物品更新策略

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

配置字段

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

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

enabled 必须为 true 且 version >= 1 才会生效。两者缺一不可。

更新触发时机

物品更新可以在以下时机触发（由全局 config.yml 或物品级别 triggers 控制）：

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

版本机制

• 物品 PDC 中存储当前 update_version。
• 当物品定义中的 version 大于 PDC 中的版本时，触发更新。
• 更新后 PDC 版本号同步为定义中的版本号。

物品级别触发器覆盖

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

物品级别的 triggers 会覆盖全局配置中对应的开关。

示例

id: starter_sword
display_name: '<white>新手之剑'
material: IRON_SWORD
update:
  enabled: true
  version: 3
  preserve_amount: true
  preserve_damage: true
  preserve_unknown_attribute_sources: true

当 version 从 2 改为 3 后，玩家背包中旧版本的新手之剑会在触发时机自动更新为新定义。