物品更新策略

物品的自动更新要解决: 改过物品定义之后, 怎么让玩家手里和背包里的旧物品自动升级到新版本

物品更新系统允许在物品定义变更后, 自动把玩家已有的旧物品更新为新版本

配置字段

更新字段都写在物品定义文件的顶层 update 下:

字段	类型	必填	默认值	取值范围	说明	示例
`enabled`	boolean	否	`false`	`true` / `false`	是否启用物品更新	`true`
`version`	integer	否	`0`	`>= 0` (`>= 1` 才生效)	物品版本号. 只有版本号变化时才触发更新	`1`
`preserve_amount`	boolean	否	`true`	`true` / `false`	更新时是否保留物品数量	`true`
`preserve_damage`	boolean	否	`true`	`true` / `false`	更新时是否保留耐久损耗	`true`
`preserve_unknown_attribute_sources`	boolean	否	`true`	`true` / `false`	更新时是否保留来自未知来源的属性	`true`
`triggers`	object	否	—	子键见下表	更新触发器开关; 没写出来的项默认为 `true`	`join: true`

IMPORTANT

注意, enabled 必须为 true 且 version >= 1 才会生效. 两者缺一不可. 如果只写了 enabled: true 却没有有效的 version, 加载时会输出警告, 并按未启用处理

更新触发时机

物品更新在下面这些时机触发, 由物品定义的 update.triggers 控制; 没显式写出来的触发项默认是启用的:

触发器	类型	必填	默认值	取值范围	说明	示例
`join`	boolean	否	`true`	`true` / `false`	玩家登录时	`true`
`held_change`	boolean	否	`true`	`true` / `false`	切换手持物品时	`true`
`inventory_click`	boolean	否	`true`	`true` / `false`	背包点击时	`true`
`inventory_drag`	boolean	否	`true`	`true` / `false`	背包拖拽时	`true`
`pickup`	boolean	否	`true`	`true` / `false`	拾取物品时	`true`
`interact`	boolean	否	`true`	`true` / `false`	交互时	`true`
`command`	boolean	否	`true`	`true` / `false`	执行命令时 (也覆盖 `give` 派发路径)	`true`

版本机制

物品 PDC (插件自定义数据, 即物品身上由插件写入的隐藏字段) 中存着当前的 update_version; 没启用更新的物品不写这个字段
只有当物品定义里的 version 大于 PDC 里的版本时才重建物品; PDC 版本已经不低于定义版本时跳过
更新后, PDC 里的版本号会同步成定义里的版本号
如果物品 ID 命中 id_aliases.yml 中的 alias, 会先执行 alias 迁移, 而不是走普通版本更新

Assembly / Ledger 安全重建

已经组装过的物品不会被简单覆盖: 如果目标物品包含 CoreLib Assembly envelope, 更新服务会按最新的 EmakiItem 定义重新生成基础物品, 再通过 Assembly rebuild 恢复 Forge, Strengthen, Gem, Cooking 等层的快照与 operation ledger, 而不是直接用新的基础物品覆盖整件物品. 普通的未组装物品仍按 preserve_amount, preserve_damage 和 preserve_unknown_attribute_sources 规则更新

关闭个别触发器

yaml

update:
  enabled: true
  version: 2
  preserve_amount: true
  preserve_damage: true
  triggers:
    join: true
    held_change: false

你只需写出要关闭的触发项; 其余没写出来的触发项仍是默认启用. 上例中 held_change 不再触发这件物品的更新, inventory_click, pickup 等仍然生效

NOTE

别混淆: config.yml > set_bonus.refresh_triggers 控制的是套装状态刷新, 与物品定义的 update.triggers 是两套独立开关

示例

yaml

id: starter_sword
item:
  source: minecraft-iron_sword
  components:
    minecraft:custom_name: '<white>新手之剑'
update:
  enabled: true
  version: 3
  preserve_amount: true
  preserve_damage: true
  preserve_unknown_attribute_sources: true

把 version 从 2 改成 3 后, 玩家背包里旧版本的新手之剑就会在触发时机自动更新为新定义

物品更新策略 ​

配置字段 ​

更新触发时机 ​

版本机制 ​

Assembly / Ledger 安全重建 ​

关闭个别触发器 ​