HN 系列 Wiki

主题

这页的目标不是把所有概念都讲完，而是带你 按步骤跑通一条最短可验证链路：

  1. 插件能启动
  2. 一件 Lore 装备能被识别
  3. 一个模板化道具能被发放并通过 inspect 验证协议
  4. 一个 Buff 能被施加
  5. 一个周期实例能创建、查看、调试

只要这五步都通了，后面你继续配战斗、Buff、DOT / HOT、模板道具，效率会高很多。

第 0 步：准备插件 ​

必需依赖 ​

  • HNCore
  • HNAttribute

可选依赖 ​

  • PlaceholderAPI
  • MythicMobs

如果你当前只是想先把属性、Buff、周期效果跑通，不装 MythicMobs 也没问题。

如果你后面准备验证跨服同步，记得那部分现在统一依赖 HNCore 的 ClusterBus，而不是 HNAttribute 自己单独维护 Redis 通道。

第 1 步：首次启动后先确认文件 ​

启动服务器后，确认 plugins/HNAttribute/ 下已生成以下目录结构：

text
plugins/HNAttribute/
├── config.yml                      # 主配置文件
├── display.yml                     # 显示配置
├── mythicmobs.yml                  # MythicMobs 集成
├── vanilla.yml                     # 原版属性映射
├── equipment/                      # 装备相关配置
│   ├── read-patterns.yml           # 属性读取模式
│   └── slot.yml                    # 装备槽位配置
├── attributes/                     # 属性定义目录
│   ├── base.yml
│   ├── combat.yml
│   └── ...
├── damage_types/                   # 伤害类型定义
│   └── ...
├── stages/                         # 战斗管线阶段定义
│   └── ...
├── pipelines/                      # 战斗管线编排
│   └── ...
├── buffs/                          # Buff 定义
│   └── ...
├── gui/                            # GUI 界面配置
│   └── ...
├── items/                          # 物品配置
│   └── ...
└── storage/                        # 数据存储目录
    └── player-runtime.db           # 玩家运行时数据

如果这些核心文件都没生成，先不要继续配内容，优先确认插件是否完整加载。

核心配置文件说明 ​

路径作用
config.yml全局开关、Lore/NBT 读取、血量压缩、原版护甲/横扫行为、Groovy 公式、条件系统
equipment/read-patterns.ymlLore 正则读取规则
equipment/slot.yml槽位与 source 名称映射
display.yml伤害显示(BossBar / ActionBar / 全息)
vanilla.yml自定义属性同步到原版属性的规则
mythicmobs.ymlMythic 标签、Mechanic 说明与联动配置
periodic/settings.yml周期系统全局设置，负责 combat-timeout 与 debug 等全局项
periodic/*.yml周期效果定义，负责 direct / instance / DOT / HOT 类配置
buffs/default.yml默认 Buff 模板示例
attributes/*.yml属性注册表
stages/*.ymlStage 定义（独立计算步骤、公式与终止语义）
pipelines/*.yml管线定义（按攻击方式编排 Stage 执行顺序）
damage_types/*.yml伤害类型显示配置与可选减伤公式
gui/attribute-stats.yml属性面板 GUI 配置
items/tokens.yml模板化道具 token 定义
items/materials.yml模板化道具 material 定义
storage/player-runtime.db玩家运行时数据（SQLite 数据库）

第 2 步：先做一件最简单的测试装备 ​

先用 Lore 测试，因为这是最容易肉眼确认的入口。

做一件武器或护甲，给它写上下面几行 Lore：

text
攻击力: 120
火焰伤害: 25
最大生命值: 60
生命恢复: 5

这几行分别对应默认属性：

  • attack_damage
  • fire_damage
  • max_health
  • health_regen

为什么推荐这四条 ​

  • 攻击力：方便后面测伤害
  • 火焰伤害：方便确认元素通道
  • 最大生命值：方便确认原版属性同步
  • 生命恢复：方便确认默认周期回血

第 3 步：装备后先用命令验证 ​

1）检查物品到底读到了什么 ​

text
/hnattr inspect

如果你想指定槽位：

text
/hnattr inspect mainhand
/hnattr inspect helmet

你应该重点看：

  • Lore 原文是不是你写的那几行
  • 解析结果里有没有 attack_damage / fire_damage / max_health / health_regen
  • attributeKind 是否显示为标准属性装备
  • 物品 identity 信息是否合理

2）看最终属性值 ​

text
/hnattr lookup

3）先看运行时总览 ​

text
/hnattr stats

你可以在面板里快速确认：

  • 当前分组是否正常显示
  • 属性有没有明显异常
  • Buff / 周期页当前是否有内容

4）看来源是否进系统 ​

text
/hnattr source

你应该能看到类似：

text
equipment:mainhand

5）只追一个属性 ​

text
/hnattr trace attack_damage
/hnattr trace max_health

到这一步，如果 inspect / lookup / stats / source / trace 都能对上，你的“属性读取层”和“运行时观察层”就已经通了。

第 3.5 步：顺手验证模板化道具链路 ​

如果你想系统理解 items/tokens.yml / items/materials.yml 应该怎么写，建议配合阅读：

现在 HNAttribute 已经接入模板化 token / material 协议，你可以直接先确认默认模板是否加载成功：

text
/hnattr item list

然后给自己发一张洗练券：

text
/hnattr item give reroll_ticket

如果你想指定玩家或数量：

text
/hnattr item give Steve reroll_ticket 2
/hnattr item give Steve awakening_stone 8

发完之后立刻再用：

text
/hnattr inspect

你应该重点看：

  • attributeKind 是否显示为 attribute_token 或 attribute_material
  • item_type / origin / token_id 是否正确
  • templateMatched 是否为 true
  • templateKey 是否是你刚发的模板 key

到这一步，你的“模板道具配置层 + 标准 identity 协议层 + inspect 调试层”就已经通了。

第 4 步：顺手验证 Buff 系统 ​

默认 buffs/default.yml 会带示例 Buff。

1）先看模板是否真的加载成功 ​

text
/hnattr buff list

至少应该能看到默认示例，例如：

  • 力量提升
  • 钢铁护体

2）给自己施加一个 Buff ​

text
/hnattr buff apply 力量提升 100 1

含义：

  • Buff key = 力量提升
  • 持续时间 = 100 tick
  • 等级 = 1

3）看自己身上当前 Buff ​

text
/hnattr buffs

4）再看来源与属性变化 ​

text
/hnattr source
/hnattr trace attack_damage

如果一切正常，你会看到类似：

text
buff:力量提升

这样的来源。

到这一步，你的“Buff 运行时层”就通了。

第 5 步：验证默认周期回血 ​

当前版本默认的周期回血已经不走旧单文件，而是走 periodic/regen.yml 里的 玩家脱战回血。

默认逻辑大意是：

  • 只对玩家生效
  • 每 20 tick 扫描一次
  • 脱战后才恢复
  • 目标必须血量未满
  • health_regen > 0 才会真的回血

你可以这样测试 ​

  1. 装备上带 生命恢复: 5 的装备
  2. 自己受一点伤
  3. 离开战斗状态
  4. 等几秒观察血量是否开始回升

如果没回，先检查：

  • 你的装备里是否真的有 生命恢复
  • /hnattr trace health_regen 是否有值
  • 当前是否仍在战斗中
  • periodic/regen.yml 里的 玩家脱战回血.enabled 是否为 true

到这一步，你的“direct 周期层”就通了。

第 6 步：手动创建一个最简单的实例周期效果 ​

接下来我们验证 instance 模式，也就是统一 DOT / HOT runtime。

新建或打开：

text
plugins/HNAttribute/periodic/tutorial.yml

在文件顶层新增一个测试项（也可以放在 effects: 节点下）：

yml
tutorial-self-poison:
  enabled: true
  mode: instance
  selector: players
  interval: 40
  tags: [tutorial, poison]
  condition:
    mode: expression
    script: target_health > 4
  instance:
    source: self
    interval: 20
    duration: 60
    reapply-mode: refresh
    tick-condition:
      mode: expression
      script: target_health > 1
    fail-policy: cancel
  actions:
    - type: damage
      amount: 1

这段配置的含义 ​

  • 每 40 tick 扫描一次玩家
  • 命中后给玩家自己挂一个实例
  • 这个实例每 20 tick 掉 1 点血
  • 持续 60 tick
  • 如果血量已经太低，就直接取消实例

保存后重载 ​

text
/hnattr reload

第 7 步：用周期调试命令看实例是否真的在跑 ​

1）查看实例列表 ​

text
/hnattr periodic list

2）查看实例详情 ​

text
/hnattr periodic inspect tutorial-self-poison

3）打开周期 debug 日志 ​

text
/hnattr periodic debug detail tutorial-self-poison

然后你可以在后台看到类似事件：

  • prepare
  • apply
  • tick
  • skip
  • cancel
  • expire

4）查看 debug 状态 ​

text
/hnattr periodic debug status

5）恢复为配置文件控制 ​

text
/hnattr periodic debug reset

到这一步，你的“instance 周期运行时层”也通了。

第 8 步：如果装了 MythicMobs，再试一个最短 DOT/HOT ​

如果你的服已经装了 MythicMobs，那么现在还能顺手验证：

  • hna-dot
  • hna-hot

一个最短示例思路是：

text
hna-dot{amount=2;duration=60;interval=20;mode=refresh;key="tutorial-dot"} @target
hna-dot{a=2;d=60;i=20;m=refresh;k="tutorial-dot"} @target

或者：

text
hna-hot{amount=2;duration=60;interval=20;mode=refresh;key="tutorial-hot"} @target
hna-hot{a=2;d=60;i=20;m=refresh;k="tutorial-hot"} @target

然后继续用：

text
/hnattr periodic list
/hnattr periodic inspect tutorial-dot
/hnattr periodic debug detail tutorial-dot

去确认 Mythic 技能是不是已经接进统一周期系统。

第 9 步：最推荐的新手排查顺序 ​

装备属性没生效 ​

按这个顺序查：

text
/hnattr inspect
/hnattr lookup
/hnattr source
/hnattr trace <属性ID>

Buff 没生效 ​

按这个顺序查：

text
/hnattr buff list
/hnattr buff apply <buffKey> 100 1
/hnattr buffs
/hnattr source
/hnattr trace <属性ID>

周期效果没生效 ​

按这个顺序查：

text
/hnattr reload
/hnattr periodic list
/hnattr periodic inspect <key>
/hnattr periodic debug detail <key>

第 10 步：下一步该看哪页 ​

如果你已经完成这页，推荐继续读：

  1. 命令说明
  2. 属性读取与来源
  3. 周期效果与实例系统

如果你现在最关心的是：

  • 怎么写 DOT / HOT
  • 怎么做 tick-condition
  • 怎么查运行中的实例

那下一页就直接去看：

HN 系列插件文档

Copyright © 2024