Item Update Strategy

The item update system can update existing player items when an item definition changes.

Fields

update is a top-level field in an item definition.

Field	Default	Description
enabled	false	Whether item update is enabled.
version	0	Item version. Updates trigger only when this increases.
preserve_amount	true	Preserve stack amount.
preserve_damage	true	Preserve durability damage.
preserve_unknown_attribute_sources	true	Preserve attributes from unknown sources.
triggers	—	Update trigger switches; any omitted entry defaults to true.

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

Trigger timing

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

Trigger	Description
join	Player joins.
held_change	Held item changes.
inventory_click	Inventory click.
inventory_drag	Inventory drag.
pickup	Item pickup.
interact	Interaction.
command	Manual command.

Version mechanism

• Item PDC 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

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

Only 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.

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

When version changes from 2 to 3, old starter swords in player inventories are updated when a configured trigger runs.