HN 系列 Wiki

主题

这页专门回答一个问题：

HNAttribute 现在如何用 HNCore ItemSpec 来定义、生成、调试标准业务道具？

如果你现在想做的是：

  • 洗练券
  • 重铸核心
  • 升级材料
  • 觉醒石
  • 其他模板化 token / material 道具

那这一页就是专门给你的。

一、先理解这页在解决什么问题 ​

过去业务模块最容易失控的一类东西，就是“大家都在自己手搓 ItemStack”。

典型问题包括：

  • 材质对了，但 PDC 没打全
  • token_id 字符串每个人写得不一样
  • 发出来的物品看起来一样，但 inspect 识别不成标准协议物品
  • 后续别的模块要认这个道具时，又开始写 material / name / lore / pdc 的散判断

当前 HNAttribute 的方向是：

模板定义交给 ItemSpec，标准协议写入交给 Attribute 工厂，识别与调试统一走 HNCore identity + inspect。

所以现在你应该把模板化业务道具理解成下面这条链：

text
items/*.yml
-> HNCore ItemSpec parser / resolver
-> HNAttribute ItemSpecService
-> Attribute 工厂
-> 标准 identity / token_id / item_type
-> inspect / matcher / API / 占位符链路可复用

二、当前放在哪些文件里 ​

当前模板化道具目录是：

text
plugins/HNAttribute/items/

默认重点看这两份：

  • items/tokens.yml
  • items/materials.yml

一句话理解：

  • tokens.yml：放券、核心、功能 token 这类业务道具
  • materials.yml：放材料、石头、可堆叠培养材料这类业务道具

三、哪些道具适合放进来 ​

推荐优先模板化的：

  • 重铸核心
  • 洗练券
  • 升级材料
  • 觉醒石
  • 其他文案、材质、lore 结构比较稳定的业务道具

暂时不建议第一批就塞进来的：

  • 动态生成的大型装备
  • 词条、成长、随机属性很多的装备
  • 强依赖运行时实时拼装的复杂奖励物品

也就是说：

先把“固定模板业务道具”模板化，不要一上来拿它替代所有动态装备。

四、一个最短心智模型 ​

现在你最应该记住的是下面三个字段：

  • item_type
  • origin
  • token_id

当前 HNAttribute 这边约定的核心语义是：

  • origin = hnattribute
  • item_type = attribute_token 或 attribute_material
  • token_id = 具体业务道具 key

例如：

  • reroll_ticket
  • reforging_core
  • upgrade_material
  • awakening_stone

这意味着：

  • 模板里负责表达“这是什么业务道具”
  • 工厂层负责把这些字段稳定写进最终物品
  • 后面 inspect、matcher、其他业务 API 都围绕这套协议工作

五、最小配置示例 ​

下面是一个适合放在 items/tokens.yml 里的最小示意：

yml
items:
  reroll_ticket:
    source: hnattribute
    id: reroll_ticket
    material: PAPER
    name: "&d洗练券"
    lore:
      - "&7用于洗练装备词条"
    identity:
      item-type: attribute_token
      origin: hnattribute
      token-id: reroll_ticket
      version: 1

一个材料示意：

yml
items:
  awakening_stone:
    source: hnattribute
    id: awakening_stone
    material: AMETHYST_SHARD
    name: "&b觉醒石"
    lore:
      - "&7用于觉醒相关培养"
    identity:
      item-type: attribute_material
      origin: hnattribute
      token-id: awakening_stone
      version: 1

你可以把它理解成两层：

1）ItemSpec 层 ​

负责：

  • 材质
  • 名称
  • lore
  • 基础模板结构

2）业务协议层 ​

负责：

  • item-type
  • origin
  • token-id
  • version

六、当前推荐怎么调试 ​

第一步：先列模板 ​

text
/hnattr item list

你应该能看到当前已加载的：

  • token key 列表
  • material key 列表

如果这里都没出现，先不要怀疑别的系统，优先确认：

  • 文件路径对不对
  • YAML 结构对不对
  • reload 后有没有重新加载

第二步：直接发一个模板道具 ​

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

第三步：立刻 inspect ​

text
/hnattr inspect

现在你应该重点看：

  • hasIdentity
  • attributeKind
  • item_type
  • origin
  • token_id
  • templateMatched
  • templateKey
  • templateCategory

如果模板链路正常，通常应该看到：

  • hasIdentity = true
  • attributeKind = attribute_token 或 attribute_material
  • templateMatched = true
  • templateKey = 你刚发的 key

七、当前有哪些直接可用的命令与 API ​

命令 ​

text
/hnattr item list
/hnattr item give [玩家] <templateKey> [amount]

用途：

  • 管理员调试模板是否加载
  • 快速发放标准业务道具
  • 验证 inspect / matcher / identity 协议

Java API ​

当前已经可以直接使用：

java
HNAttributeAPI.createReforgingCore();
HNAttributeAPI.createReforgingCore(2);
HNAttributeAPI.createRerollTicket();
HNAttributeAPI.createRerollTicket(5);
HNAttributeAPI.createUpgradeMaterial(16);
HNAttributeAPI.createAwakeningStone();

适合：

  • 奖励系统
  • GM 工具
  • 活动发放
  • 其他 HN 系列模块调用

如果你只是想发“标准属性业务道具”，优先用这些 API，不要继续在别的模块里手搓 ItemStack。

八、和 GUI ItemSpec 是什么关系 ​

现在不只是模板化道具，属性面板 GUI 里的按钮物品也已经支持：

  • 优先走 HNCore ItemSpec / Resolver
  • 旧格式回退
  • append-lore

但这两者关注点不同：

items/*.yml ​

更偏：

  • 业务道具模板
  • 发放给玩家的 token / material
  • 被 inspect 与 matcher 识别的标准物品

gui/attribute-stats.yml ​

更偏：

  • 面板里的按钮 / 摘要物品
  • 只读显示用途
  • GUI 渲染与追加说明文案

你可以理解成：

两边都能走 ItemSpec，但 items/*.yml 更偏业务物品，gui/*.yml 更偏展示物品。

九、最容易踩坑的地方 ​

1）模板 key 和 token_id 不一致 ​

建议最稳的做法是：

  • key 叫 reroll_ticket
  • token-id 也写 reroll_ticket

除非你非常明确要分离命名，否则不要给后续识别增加心智负担。

2）把复杂动态装备也强行模板化 ​

模板化道具最擅长的是“稳定模板”，不是“高动态随机装备生成器”。

3）只看材质和名字，不看 inspect ​

现在排查模板道具时，最重要的不是看像不像，而是看协议有没有写进去。

所以遇到问题时第一反应应该是：

text
/hnattr inspect

4）改了 items/*.yml 却没 reload ​

模板文件改完后，别忘了：

text
/hnattr reload

十、推荐的最短使用路径 ​

如果你现在只想把这套东西跑通，最短路径就是：

text
1. 修改 items/tokens.yml 或 items/materials.yml
2. /hnattr reload
3. /hnattr item list
4. /hnattr item give <templateKey>
5. /hnattr inspect

只要这五步都正常，你的：

  • 模板配置
  • ItemSpec 解析
  • identity 协议
  • 识别与调试链路

就已经通了。

十一、一句话结论 ​

HNAttribute 里的模板化道具，本质上是“HNCore ItemSpec 模板 + HNAttribute 标准 identity 协议 + inspect / API / matcher 可复用链路”的组合。

如果你要的是稳定、可识别、可调试、可复用的业务 token / material，道具就应该优先走这套。

HN 系列插件文档

Copyright © 2024