Item modifiers

Standalone, reusable loot functions stored at data/<namespace>/item_modifier/ and applied to real item stacks with /item modify. They share the exact same function system as loot-table functions. Primary syntax targets 1.21+ (singular item_modifier/ folder).

What an item modifier is

An item modifier file is a standalone, reusable loot function — or an array of functions applied in order. Its root is either a single function object or an array of them. It uses the identical function schema as the functions lists inside loot tables, so any function documented for loot tables works here and vice-versa. The folder is singular item_modifier/ since 1.21.

Every function object has the form {"function": "minecraft:<id>", …params} and may carry an optional conditions array (loot conditions — see predicates). A bare array of functions behaves exactly like the sequence function.

Applying with /item modify

Item modifiers are applied to a real stack in the world with the /item modify command, targeting a slot on an entity or a block container:

In a function or the chat console

/item modify entity @s weapon.mainhand mypack:sharpen
/item modify block ~ ~ ~ container.0 mypack:sharpen

The modifier's own conditions can only reference loot context, so to gate application on live entity state, gate the command with a predicate instead:

/execute as @a if predicate mypack:holding_sword run item modify entity @s weapon.mainhand mypack:sharpen

set_nbt successors — set_custom_data vs set_components

The 1.20.5 component migration split the old set_nbt function into two distinct functions. Choosing the right one matters:

The copy family mirrors this split:

Function catalogue

The complete 1.21+ function set. Every function is {"function": "minecraft:<id>", …} and may carry an optional conditions array. Fields shown as "number provider" accept the shorthand and explicit forms documented for loot tables.

Worked examples

A multi-step modifier that renames, enchants, adds lore and stamps components onto whatever stack it is applied to. As an array, its four functions run in order like sequence.

data/<namespace>/item_modifier/make_masterwork.json

[
  { "function": "minecraft:set_name",
    "name": "{\"text\":\"Masterwork\",\"color\":\"aqua\",\"italic\":false}",
    "target": "item_name" },
  { "function": "minecraft:set_enchantments",
    "enchantments": { "minecraft:unbreaking": 3, "minecraft:mending": 1 }, "add": false },
  { "function": "minecraft:set_lore",
    "mode": "append",
    "lore": ["{\"text\":\"Forged by the datapack gods\",\"color\":\"gray\",\"italic\":true}"] },
  { "function": "minecraft:set_components",
    "components": { "minecraft:rarity": "epic", "minecraft:custom_data": "{masterwork:1b}" } }
]

Apply it with:

/item modify entity @s weapon.mainhand mypack:make_masterwork

A single-function modifier that writes only your pack's marker tag using the direct set_nbt successor — the right tool when you just need a private flag, not a vanilla component.

data/<namespace>/item_modifier/tag_quest_item.json

{
  "function": "minecraft:set_custom_data",
  "tag": "{quest_item:1b, quest_id:\"ember\"}"
}

A filtered modifier that only enchants swords within a mixed stack of drops — useful as a table-wide loot function that should act selectively.

data/<namespace>/item_modifier/enchant_only_swords.json

{
  "function": "minecraft:filtered",
  "item_filter": { "items": "#minecraft:swords" },
  "modifier": {
    "function": "minecraft:enchant_with_levels",
    "levels": { "min": 20, "max": 30 }
  }
}

Tricks & best practices

Sources

• Item modifier — Minecraft Wiki
• Loot table — Minecraft Wiki
• Data component predicate — Minecraft Wiki