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	—	Item-level trigger overrides.

enabled must be true and version must be at least 1.

Trigger timing

Updates can run on these triggers, controlled by global config or item-level overrides:

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.
• If the definition version is greater than the PDC version, update runs.
• After update, PDC version is set to the definition version.

Example

id: starter_sword
display_name: '<white>Starter Sword'
material: IRON_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.