Item Update Strategy

The item update system updates existing player items automatically when an item definition changes, bringing the old items in players' hands and inventories up to the new version

Fields

All update fields live at the top level of an item definition under update:

Field	Type	Required	Default	Range	Description	Example
enabled	boolean	No	false	true / false	Whether item update is enabled	true
version	integer	No	0	>= 0 (applies at >= 1)	Item version. Updates trigger only when this increases	1
preserve_amount	boolean	No	true	true / false	Preserve stack amount	true
preserve_damage	boolean	No	true	true / false	Preserve durability damage	true
preserve_unknown_attribute_sources	boolean	No	true	true / false	Preserve attributes from unknown sources	true
triggers	object	No	—	sub-keys in the table below	Update trigger switches; any omitted entry defaults to true	join: true

Note that enabled must be true and version must be at least 1; both are required. If enabled: true but no valid version is present, a warning is logged at load time and updates stay disabled

Trigger timing

Items update on the triggers below, controlled by update.triggers in the item definition. Triggers that are not listed explicitly are enabled by default:

Trigger	Type	Required	Default	Range	Description	Example
join	boolean	No	true	true / false	Player joins	true
held_change	boolean	No	true	true / false	Held item changes	true
inventory_click	boolean	No	true	true / false	Inventory click	true
inventory_drag	boolean	No	true	true / false	Inventory drag	true
pickup	boolean	No	true	true / false	Item pickup	true
interact	boolean	No	true	true / false	Interaction	true
command	boolean	No	true	true / false	Manual command (also covers the give dispatch path)	true

Version mechanism

• Item PDC (plugin-defined data, the hidden fields a plugin writes onto an item) stores the current update_version; items without update enabled do not write this field
• The item is rebuilt only when the definition version is greater than the PDC version; if the PDC version is already at least the definition version, the update is skipped
• After update, PDC version is set to the definition version
• If the item ID matches an alias in id_aliases.yml, alias migration runs instead of a normal version update

Assembly/Ledger-safe rebuilding

Assembled items are never blindly overwritten. When an item contains the CoreLib Assembly envelope, the update service builds the latest EmakiItem base definition and then runs an Assembly rebuild to restore Forge, Strengthen, Gem, Cooking, and other layer snapshots plus the operation ledger; it does not replace the whole assembled item with a fresh base stack. Non-assembled items still follow preserve_amount, preserve_damage, and preserve_unknown_attribute_sources

Disabling individual triggers

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

You only need to list the triggers you want to disable; omitted triggers remain enabled by default. Above, held_change no longer updates this item, while inventory_click, pickup, and the rest still apply

NOTE

Do not mix them up: config.yml > set_bonus.refresh_triggers controls set state refreshing and is a separate set of switches from update.triggers in an item definition

Example

id: starter_sword
item:
  source: minecraft-iron_sword
  components:
    minecraft:custom_name: '<white>Starter Sword'
update:
  enabled: true
  version: 3
  preserve_amount: true
  preserve_damage: true
  preserve_unknown_attribute_sources: true

Change version from 2 to 3, and old starter swords in player inventories update to the new definition automatically at the next trigger