Item modifier

This feature is exclusive to Java Edition.

Item modifiers are technical JSON files that can be created inside data packs and are used to add loot functions into existing items using the command /item.

This page describes how item modifiers are defined and invoked. It also shows the JSON structure of a loot function, the primary JSON structure within an item modifier.

Definition[]

An item modifier is an item function or an array of item functions to apply to the item. They are defined using the JSON format.

Item modifiers belong in the following folder of a data pack's structure, highlighted below:

(data pack name)
- pack.mcmeta
- pack.png
- data
  - (namespace)
    - advancements
      - (advancement).json
    - functions
      - (function).mcfunction
    - item_modifiers
      - (modifier).json
    - loot_tables
      - (loot table).json
    - predicates
      - (predicate).json
    - Further folders…

The root element of an item modifier can be either an object, following the structure of an item function below, or an array, containing multiple item functions.

Invocation[]

Item modifiers can only be invoked with the /item command. When doing so, it is required to specify a target slot to invoke the modifier upon, either an item inside a container block's contents, or inside an entity's inventory.

There are two variations of this command: /item modify invokes a modifier alone upon the target slot, /item replace replaces the item in the target slot with another and subsequently invokes a modifier upon it.

item modify (block <pos> | entity <targets>) <slot> <modifier>
item replace (block <pos> | entity <targets>) <slot> from (block <pos> | entity <targets>) [<modifier>]

Although item modifiers are only invokable using commands, item functions (the underlying structure) can be entered into other files such as Loot tables.

Item function JSON format[]

This section describes the JSON format of a single item function. Multiple item functions may be entered into one item modifier by placing them into a JSON array.

The root tag of the item function.
- function: Resource location of the function to apply. Valid functions are described below.
- conditions: A list of predicates, of which all must pass, for this function to be applied.
  - A predicate. The JSON structure of this tag is defined on the Predicates page.
- Other parameters of the function, described below.

The possible resource locations (namespace minecraft: is omitted) for function and associated extra contents:

apply_bonus—Applies a predefined bonus formula to the count of the item stack.
- enchantment: ID of an enchantment on the tool provided by loot context used for level calculation.
- formula: A resource location. Can be binomial_with_bonus_count for a binomial distribution (with n=level + extra, p=probability), uniform_bonus_count for uniform distribution (from 0 to level * bonusMultiplier), or ore_drops for a special function used for ore drops in the vanilla game (Count *= (max(1; randomInt(0(inclusive) .. (Level + 2)(exclusive))))).
- parameters: Values required for the formula.
  - extra: For formula 'binomial_with_bonus_count', the extra value.
  - probability: For formula 'binomial_with_bonus_count', the probability.
  - bonusMultiplier: For formula 'uniform_bonus_count', the bonus multiplier.

copy_name—Copies an entity's or a block entity's name tag into the item's display.Name tag.
- source - The target whose name will be copied. Specifies an entity or block entity from loot context. Can be block_entity, this, killer, or killer_player (cannot be direct_killer).

copy_nbt—Copies NBT values from a specified block entity or entity, or from command storage to the item's tag tag.
- source: Shorthand form of source below with type set to context. Specifies an entity or block entity from loot context. Can be block_entity, this, killer, direct_killer, or killer_player.
- source: Information of the block entity, entity or storage to copy NBT from.
  - type: Set to context to use a block entity or an entity as the source, or storage to use a command storage as the source.
  - target: Included only if type is set to context. Specifies an entity or block entity from loot context to copy NBT from. Can be block_entity, this, killer, direct_killer, or killer_player.
  - source: Included only if type is set to storage. A resource location specifying the storage ID to copy NBT from.
- ops: A list of copy operations.
  - An NBT operation.
    - source: The NBT path to copy from.
    - target: The NBT path to copy to, starting from the item's tag tag.
    - op: Set to replace to replace any existing contents of the target NBT path, append to append to a list or array, or merge to merge into a compound tag.

copy_state—Copies block state properties provided by loot context to the item's BlockStateTag tag.
- block: A block ID. Function fails if the block doesn't match the properties list.
- properties: A list of properties to copy.
  - The name of a block state to copy.

enchant_randomly—Enchants the item with one randomly-selected enchantment. The power of the enchantment, if applicable, is random. A book will convert to an enchanted book when enchanted.
- enchantments: Optional. List of enchantment IDs to choose from. If omitted, all discoverable enchantments (currently only Soul speed and Swift Sneak are undiscoverable) applicable to the item are possible.

enchant_with_levels—Enchants the item, with the specified enchantment level (roughly equivalent to using an enchantment table at that level). A book will convert to an enchanted book.
- treasure: Determines whether treasure enchantments are allowed on this item. Defaults to false.
- levels: Number provider. Specifies the enchantment level to use.

exploration_map—If the origin is provided by loot context, converts an empty map into an explorer map leading to a nearby generated structure.
- destination: A tag of structure to locate. Defaults to on_treasure_maps.
- decoration: The icon used to mark the destination on the map. Accepts any of the map icon text IDs (case insensitive). If mansion or monument is used, the color of the lines on the item texture changes to match the corresponding explorer map. Defaults to mansion.
- zoom: The zoom level of the resulting map. Defaults to 2.
- search_radius: The size, in chunks, of the area to search for structures. The area checked is square, not circular. Radius 0 causes only the current chunk to be searched, radius 1 causes the current chunk and eight adjacent chunks to be searched, and so on. Defaults to 50.
- skip_existing_chunks: Don't search in chunks that have already been generated. Defaults to true.

explosion_decay—Removes some items from a stack, if the explosion ratius is provided by loot context. Each item in the item stack has a chance of 1/explosion radius to be lost.

fill_player_head—Adds required item tags of a player head.
- entity: Specifies a player to be used for the player head. Specifies an entity from loot context. Can be this, killer, direct_killer, or killer_player.

furnace_smelt—Smelts the item as it would be in a furnace without changing its count.

limit_count—Limits the count of every item stack.
- limit: An integer to specify the exact limit to use.
- limit: Limits the count between a minimum and maximum value.
  - min: Optional. A number provider. Minimum limit to use.
  - max: Optional. A number provider. Maximum limit to use.

looting_enchant—Adjusts the stack size based on the level of the Looting enchantment on the killer entity provided by loot context.
- count: A number provider. Specifies the number of additional items per level of looting. Note the number may be fractional, rounded after multiplying by the looting level.
- limit: Specifies the maximum amount of items in the stack after the looting calculation. If the value is 0, no limit is applied. Defaults to 0.

reference—Call sub-functions
- name: Location of function to call.

set_attributes—Add attribute modifiers to the item.
- modifiers:
  - : An attribute modifier to add.
    - name: Name of the modifier.
    - attribute: The resource location of the attribute this modifier is to act upon.
    - operation: The operation of this attribute modifier. One of addition, multiply_base, or multiply_total.
    - amount: A number provider. Specifies the amount of the modifier.
    - id: Optional. UUID to assign the modifier, in hyphenated hexadecimal format. If none specified, a new random UUID is generated.
    - slot: Sets the slots the item must be in for the modifier to take effect. One of: mainhand, offhand, feet, legs, chest, head.
    - slot: To choose randomly from a set of possible slots. List contains strings of one of the above slot choices, to choose randomly from. The random selection can be weighted by listing the same slot multiple times.

set_banner_pattern - Adds or replaces banner patterns of a banner. Function successfully adds patterns into NBT tag even if invoked on a non-banner.
- patterns: List of patterns to add or replace with.
  - : A pattern.
    - pattern: The pattern type. For example, square_bottom_left.
    - color: The color for this pattern. One of white, orange, magenta, light_blue, yellow, lime, pink, gray, light_gray, cyan, purple, blue, brown, green, red, black.
- append: Required. If true, the patterns will be applied on top of the banner's existing patterns.

set_contents - Sets the contents of a container block item to a list of entries.
- entries: A list of loot table entry producer to provide item stacks.
- type: the block entity type to be written in BlockEntityTag.id.

set_count - Sets the stack size.
- count: A number provider. Specifies the stack size to set.
- add: Optional. If true, change will be relative to current count. Defaults to false.

set_damage - Sets the item's damage value (durability).
- damage: A number provider. Specifies the damage fraction to set (1.0 is undamaged, 0.0 is zero durability left).
- add: Optional. If true, change will be relative to current damage. Defaults to false.

set_enchantments - Modifies the item's enchantments. A book will convert to an enchanted book.
- enchantments: Enchantments to modify.
  - An enchantment: Key name is the enchantment ID. Value is a number provider specifying the enchantment power. Powers are clamped at a maximum of 255. Decreasing an enchantment power below 1 will remove the enchantment, through a relative negative add or through a direct value assignemnt.
- add: Optional. If true, change will be relative to current level. A nonexistent enchantment will be presumed to start at 0. Defaults to false.

set_instrument - Sets the item tags for instrument items to a random value from a tag.
- options: The resource location started with # of an instrument tag, one of the listings is selected randomly.

set_loot_table - Sets the loot table for a container block when placed and opened.
- name: Specifies the resource location of the loot table to be used.
- seed: Optional. Specifies the loot table seed. If absent or set to 0, the seed won't be put into the NBT, and a random seed will be used when opening the continer.
- type: the block entity type to be written in BlockEntityTag.id.

set_lore - Adds or changes the item's lore.
- lore: List of lines to append or replace on the item's lore.
  - A line of item lore, following the Raw JSON text format. Components requiring resolution are resolved only if entity successfully targets an entity.
- entity: Specifies the entity to act as @s when referenced in the JSON text component. Specifies an entity from loot context. Can be this, killer, direct_killer, or killer_player.
- replace: Optional. Set to true to replace the existing item lore with only the lines in lore. If false, the lines are appended to the list of existing lines of lore. Defaults to false.

set_name—Adds or changes the item's custom name.
- name: A JSON text component, overwriting the previous custom name on the item. Components requiring resolution are resolved only if entity successfully targets an entity.
- entity: Specifies the entity to act as @s when referenced in the JSON text component. Specifies an entity from loot context. Can be this, killer, direct_killer, or killer_player.

set_nbt—Adds or changes NBT data of the item.
- tag: The NBT to merge onto the item's tag tag, within a JSON string. The outer braces { } of the NBT must be present within this JSON string. Additional care is required when the NBT contains quotation marks ", as they must be escaped from the JSON syntax with a backslash \.

set_potion—Sets the Potion tag of an item.
- id: The potion ID. Set to empty to remove the Potion tag.

set_stew_effect—Sets the status effects for suspicious stew. Fails if invoked on an item that is not suspicious stew.
- effects: The effects to apply.
  - An effect.
    - type: The effect ID.
    - duration: A number provider. The duration of the effect.

History[]

Java Edition
1.17	20w46a	Added item modifiers.
1.18	21w39a	Added `set_potion` function.
?	?	Added `set_instrument` function.
1.20	23w14a	Added `reference` function.

Issues[]

Issues relating to "Item modifier" are maintained on the bug tracker. Report issues there.