Updating items

Updating items refers to the tools Matcha Flavoured provides for bringing items from older versions of the pack up to date, chiefly the /trigger update_item command added in 1.12.2.

Background

Datapacks cannot add items, so every custom item is a vanilla item with extra data components (name, model, lore, enchantments, attributes). An item keeps the components it was created with, so when a new version changes an item's stats, textures or name, old copies stay as they were and often no longer stack with new ones. In 1.12.2 almost all models and data moved from the minecraft and main namespaces to matcha, which made many old items appear broken.

/trigger update_item

Hold the item in the main hand and run /trigger update_item. Any player can use it without cheats. The function:

1. Reads the translation key of the held item's name. An item without one is rejected with "The held item cannot be updated because it is missing a translation key."
2. Looks the key up in a table of 247 current item definitions, generated from the pack's crafting, smithing and food recipes and its villager trades. Since 1.12.8-beta the 14 old "bronze" keys (item.kleispack.bronze_axe and so on) are in the table too and give the matching hepatizon item. For 15 items whose only change is the item model (Amber, Opal, Ruby, Topaz, the fox pelt, the clay statues (cheerful and mournful), tallow, the ofuda, a recipe page, the classic porkchop, the two classic roses, and since 1.12.8-beta the blessings and the Overgrown Abbey map), a small item modifier is applied to the held stack instead, which sets the new model and leaves everything else alone. These items have no table entry, so the command then still reports "The held item cannot be updated.", although the model has changed. Since 1.12.8-beta the beacon kindling and the bedrock buster also get a model modifier, but they have table entries as well, so they are rebuilt from the table as before. An item whose key is in neither list is reported as "The held item cannot be updated."
3. Builds the current version of the item, and carries over the stack size and custom name. Durability damage is kept as a proportion of the new maximum.
4. Merges the old item's enchantments, armor trim and lodestone compass target onto the new one; where both have an enchantment, the higher level is kept. Vanilla Fortune is then capped at level I, the pack's maximum.
5. Removes the held item and drops the new one at the player's feet with no pickup delay, then reports "The held item has been successfully updated."

The table is generated by the script generate_update_item_mcfunction.py in the repository.

Limitations

Only items whose name carries a translation key can be updated, so an item renamed with an anvil keeps its custom name but must still have the original key underneath. In 1.12.2 the function also looked items up by their item ID, which rebuilt any item on one of those vanilla IDs as the table entry (any splash potion became a pickled warped fungus), lost armor trims and lodestone compass targets, and had no entries for items only villagers sell. Since 1.12.3 the ID table is gone, villager-trade items are covered and trims and compass targets are kept. Since 1.12.8-beta a held blessing is given the plain enchanted book model, so it loses its own texture (see Known bugs).

Automatic updates

• Since 1.12.4, most of the pack's items update themselves. Whenever the player's inventory changes, an item in the main hand, the off hand or an armor slot that matches one of 415 pack items but lacks the current version tag (the custom data version: 1, or version: 2 for milk bottles since 1.12.8-beta, which the updater itself never writes; see Known bugs) has its components rewritten to the current definition. Items made in 1.12.4 carry the tag and are left alone. The functions for enchanted equipment are also meant to raise its enchantments to at least the current levels, but that step does nothing (see Known bugs). The files are generated by the script generate_item_update_files.py from item_updater_db.json.
• The sacred texts (The Avesta, The Book of Enoch, The Divine Comedy, The Lesser Key of Solomon, Paradise Lost, The Quran and The Tanakh) and the "Golden" music disc are replaced automatically when picked up, outside Creative mode.
• Vanilla water bottles and unenchanted vanilla elytra are converted into the pack's versions. In 1.12.2 vanilla apples, sweet berries and turtle scutes were converted as well; the 1.12.3 pack no longer does this.
• When a player joins after an update, their recipe unlocks are reset, so that new recipes can unlock. Since 1.12.6-alpha their progression and reward advancements are kept; earlier versions also revoked progression and reward advancements so they could be earned again (nearly the whole tutorial tab in 1.12.2, a shorter list in 1.12.3 to 1.12.5). Since 1.12.7-beta the update also sets the player's experience level to 10,000; see Anvil#Experience. See Advancements#Revocation on update.

Other methods

• /loot give @s loot matcha:... gives a fresh copy of many items, for example matcha:treasure/divine_comedy.
• For a sentimental item the trigger cannot rebuild, the 1.12.3 release notes suggest throwing it on the ground and running /data merge entity @n[type=item] {Item:{components:{"item_model":"matcha:XXX"}}}, where XXX is the item's model name from the English language file (for example oarfish or mournful_clay_statue).
• Loading the previous resource pack below the new one hides broken textures, although enchantments stay broken.
• The weaponsmith (grindstone villager) melts alloyed equipment into its components, and an amnestic resets a villager's trades (after the 1.12.3 changes, villagers need one to unlock the new trades). Both were added in 1.10.

History

1.10	Added version tracking, recipe unlock resets, weaponsmith melting and the amnestic.
1.12.1-alpha	Automatic replacement of moved books and the "Golden" disc.
1.12.2	Added /trigger update_item, by FloofShade.
1.12.3	/trigger update_item no longer identifies items by ID, reports items without a translation key, supports villager-trade items, and keeps armor trims and lodestone compass targets (FloofShade). Fewer tutorial advancements are revoked on update.
1.12.4	Items in the hands and armor slots update themselves when the inventory changes, using a version tag in their custom data.
1.12.5	A plain book, shield or bow is no longer turned into the Angler's Almanac, the warding shield or the compound bow on its own: in 1.12.4 the updater's checks for these three accepted the base item in either hand. They still accept it in the main hand while another plain one of the same kind is in the off hand, so that one is still converted (see Known bugs).
1.12.6-alpha	Updating no longer revokes any advancements other than recipe unlocks, and no longer resets minimum hearts to 10. Apples, carrots, chorus fruit, sweet berries, glow berries, tomatoes, enchanted golden apples, braised warped fungus and the two Overgrown Abbey maps no longer update themselves, and fish bones, raw diamonds, clear mushroom soup and the classic porkchop now do. The functions that restore enchantments now exist under matcha_item:enchants/, but still don't work in Minecraft 26.3.
1.12.8-beta October 23, 2026	A plain bone, raw porkchop or brush held in either hand is no longer turned into fish bones, the classic porkchop or the archeologist's brush; the brush check had accepted any brush since 1.12.4, the other two since 1.12.6-alpha. Updated milk bottles take 0.8 seconds to drink instead of 1.6, and updated ice cream no longer leaves a bowl, matching the crafted items. /trigger update_item also accepts the old "bronze" equipment keys and gained model-only updates for blessings and the Overgrown Abbey map.
1.12.9 October 31, 2026	A red bundle held in either hand is no longer turned into a full Geothermal Bundle: since 1.12.6-alpha every red bundle without the version tag was, replacing whatever it held. The updater now recognizes the Geothermal Bundle by its name.
1.12.9 October 31, 2026	Apples, baked apples, carrots, chorus fruit, cooked chicken, glow berries, melon slices and sweet berries from the pack's food loot tables carry the version tag (version: 1). Baked apples, cooked chicken and melon slices now stack with copies the updater has rewritten; the other five, which the updater no longer touches, don't stack with copies obtained before 1.12.9.