Minecraft Wiki
Advertisement

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 from commands or functions, specifically, 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 loot conditions, of which all must pass, for this function to be applied.
      • A loot condition. The JSON structure of this tag is defined on the Predicates page.
    • Other parameters of the function, described below.

The possible resource locations for  function and associated extra contents:

  • apply_bonus—Applies a predefined bonus formula.
    •  enchantment: Enchantment ID used for level calculation.
    •  formula: 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(0; random(0..Level + 2) - 1)+1)).
    •  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—For loot table type block, copies a block entity's CustomName tag into the item's display.Name tag.
    •  source: "block_entity" - The target with the CustomName. Currently, this needs to be set to block_entity.
  • 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. Set to block_entity, this, 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 the source block entity or entity to copy NBT from. Set to block_entity for the block entity of the destroyed block, this for the entity triggering this item modifier, killer for the entity that killed the entity triggering this item modifier, or killer_player to only target the killer if they are a 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 state properties from dropped block to the item's BlockStateTag tag.
    •  block: A block ID. Function fails if the block doesn't match.
    •  properties: A list of property names to copy.
      • A block state name to copy.
  • enchant_randomly—Enchants the item with one randomly-selected enchantment. The level of the enchantment, if applicable, is random.
    •  enchantments: List of enchantment IDs to choose from. If omitted, all enchantments applicable to the item are possible.
  • exploration_map—Converts an empty map into an explorer map leading to a nearby generated structure.
    •  destination: The type of generated structure to locate. Accepts any of the StructureTypes used by the /locate command (case insensitive).
    •  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.
    •  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—For loot tables of type block, removes some items from a stack, if there was an explosion. Each item has a chance of 1/explosion radius to be lost.
  • furnace_smelt—Smelts the item as it would be in a furnace. Used in combination with the entity_properties condition to cook food from animals on death.
  • fill_player_head—Adds required item tags of a player head.
    •  entity: Specifies an entity to be used for the player head. Set to this the entity triggering this item modifier, killer for the killer, or killer_player for a killer that is a player.
  • limit_count—Limits the count of every item stack.
    •  limit: Number provider. Specifies the exact limit to use.
    •  limit: Limits the count between a minimum and maximum value. Both are not required.
  • looting_enchant—Adjusts the stack size based on the level of the Looting enchantment on the entity that killed the entity triggering this item modifier.
    •  count: 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.
  • set_attributes—Add attribute modifiers to the item.
    •  modifiers:
      • : An attribute modifier to add.
        •  name: Name of the modifier.
        •  attribute: The name 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: 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 cannot[verify] be weighted by listing the same slot multiple times.
  • set_banner_pattern—Adds or replaces banner patterns of a banner. Function fails 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: Optional. If true, the patterns will be applied on top of the banner's existing patterns.
  • set_contents - For loot tables of type block, sets the contents of a container block item to a list of entries.
    •  entries: A list of loot table entries to use as contents.
    •  type: the type to be written in BlockEntityTag.id.
  • set_count - Sets the stack size.
    •  count: Number provider. Specifies the stack size to set.
    •  add: Optional. If true, change will be relative to current count.
  • set_damage - Sets the item's damage value (durability) for tools.
    •  damage: 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.
  • set_enchantments - Modifies the item's enchantments.
    •  enchantments: Enchantments to modify.
      •  An enchantment: Key name is the enchantment ID. Value is a number provider specifying the enchantment level. Levels are clamped at a maximum of 255. Decreasing an enchantment level 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.
  • set_instrument[upcoming: JE 1.19]—Sets the item tags for instrument items to a random value from a tag.
    •  options: The resource location 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, a random seed will be used.
    •  type: the 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.
    •  entity: Specifies the entity to act as @s when referenced in the JSON text component. Set to this to use the entity that triggered the item modifier, killer for the entity that killed the this entity, or killer_player to target the killer only if they are a player.
    •  replace: Set to true to replace the existing item lore with only the lines in  lore. If false or absent, the lines are appended to the list of existing lines of lore.
  • 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. Set to this to use the entity that triggered the item modifier, killer for the entity that killed the this entity, or killer_player to target the killer only if they are a 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.
  • 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: Number provider. The duration of the effect.

History[]

Java Edition
1.1720w46aAdded item modifiers.
1.1821w39aAdded set_potion function.

Issues[]

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

Advertisement