物品更新策略

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

配置字段

update 是物品定义文件中的顶层字段：

字段	类型	默认值	说明
enabled	boolean	false	是否启用物品更新。
version	integer	0	物品版本号。版本号变化时才触发更新。
preserve_amount	boolean	true	更新时是否保留物品数量。
preserve_damage	boolean	true	更新时是否保留耐久损耗。
preserve_unknown_attribute_sources	boolean	true	更新时是否保留来自未知来源的属性。
triggers	object	—	更新触发器开关；未写的项默认为 true。

enabled 必须为 true 且 version >= 1 才会生效。两者缺一不可。若 enabled: true 但缺少有效 version，加载时会输出警告并按未启用处理。

更新触发时机

物品更新在以下时机触发，由物品定义的 update.triggers 控制；未显式写出的触发项默认启用：

触发器	说明
join	玩家登录时。
held_change	切换手持物品时。
inventory_click	背包点击时。
inventory_drag	背包拖拽时。
pickup	拾取物品时。
interact	交互时。
command	执行命令时。

版本机制

• 物品 PDC 中存储当前 update_version；未启用更新的物品不写该字段。
• 当物品定义中的 version 大于 PDC 中的版本时才重建物品；PDC 版本已不低于定义版本时跳过。
• 更新后 PDC 版本号同步为定义中的版本号。
• 若物品 ID 命中 id_aliases.yml 中的 alias，会先执行 alias 迁移而不是普通版本更新。

Assembly / Ledger 安全重建

如果目标物品包含 CoreLib Assembly envelope，更新服务会以最新 EmakiItem definition 重新生成基础物品，再通过 Assembly rebuild 恢复 Forge、Strengthen、Gem、Cooking 等层快照与 operation ledger，而不是直接用新基础物品覆盖整件物品。普通未组装物品仍按 preserve_amount、preserve_damage 和 preserve_unknown_attribute_sources 规则更新。

关闭个别触发器

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

只需写出要关闭的触发项；其余未写出的触发项仍为默认启用。上例中 held_change 不再触发该物品的更新，inventory_click、pickup 等仍然生效。

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

示例

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 后，玩家背包中旧版本的新手之剑会在触发时机自动更新为新定义。