Skip to main content

🔄 Item Updater

The item updater patches existing items in players' inventories when you change a config. Unlike client_bound_data which only updates visuals, the updater modifies the item's actual data on the server.

How It Works​

Each item carries an internal version tag (craftengine:version, default 0). When an update trigger fires, the plugin compares the item's version against the updater config and replays any steps defined above the current version.

Old item (version 0) picked up
  → Apply updater steps for version 1, 2
  → Item now at version 2
  → No further updates needed

New items skip the updater entirely. They are built from the item's data section and tagged with the latest version upfront. This means: whenever you add updater steps, you must also update the base data to match the final desired state.

Configuring an Updater​

The golden rule: data builds new items, updater patches old ones. They must agree.

items:
  default:my_sword:
    material: stone_sword              # ← new items start here
    data:
      item_name: Stone Sword
      lore:
        - "Final lore"
    updater:
      1:
        type: apply_data
        data:
          item_name: Stone Sword       # old items: rename
      2:
        - type: apply_data
          data:
            lore:
              - "Final lore"           # old items: add lore
        - type: transmute
          material: stone_sword        # old items: change material

Each key under updater is a version number — steps run when the item's version is below it. A version holds a single updater or a list. Old items replay all steps above their current version; new items get data directly and skip the updater.

danger

If you add an updater but forget to update data, old items get patched correctly while new items are stuck with the old values.

Updater Types​

apply_data​

Apply any item data using the same format as đŸ”ĸ Item Data:

type: apply_data
data:
  item_name: Updated Name
  lore:
    - "New lore line"

transmute​

Replace the base material while preserving all components and NBT:

type: transmute
material: stone_sword

reset​

Rebuild the item from scratch using the latest config, keeping only specified data:

type: reset
# 1.20.5+: components to keep
keep_components:
  - minecraft:enchantments
  - minecraft:custom_name
# Legacy (< 1.20.5): NBT paths to keep
keep_tags:
  - Enchantments
  - display.Name
caution

Anything not listed in keep_components or keep_tags is discarded. Be explicit.

Enabling Triggers​

The updater only activates during specific events, all disabled by default. Enable only what you need in config.yml:

item:
  update-triggers:
    click-in-inventory: false   # Click inside inventory (not in creative mode)
    drop: false                 # Drop an item
    pick-up: false              # Pick up an item
    attack: false               # Attack with an item

Each trigger adds overhead — the plugin checks every affected item on every event. Enable sparingly.