Item modifier

From Minecraft Wiki
Jump to: navigation, search
Information icon.svg
This feature is exclusive to Java Edition.
Grass Block JE7 BE6.png
This page describes content that may be included in a future update to Java Edition.
These features have appeared in Java Edition development versions, but the full update containing them has not been released for Java Edition yet.

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

Usage[edit]

An item modifier is a loot table function or an array of functions to apply at the item. They can be applied using the command /item.

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

JSON structure[edit]

Item modifiers are defined using the JSON format. Below are a list of tags used.

  • The root tag
    •  function: Namespaced ID of the function to apply.
    • Other parts of the function, specified below.

The possible values 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" - Needs to be set to 'block_entity'.

  • copy_nbt - Copies nbt to the item's tag tag.
    •  source: Specifies the source. Set to block_entity for the block entity of the destroyed block, this to use the entity that died or the player that gained the advancement, opened the container or broke the block, killer for the killer, or killer_player for a killer that is a player.
    •  source:
      •  type: Nbt provider type. One of context, storage.
        • If type is context:
          •  target: Same as source above.
        • If type is storage:
    •  ops: A list of copy operations.
      • An operation
        •  source: The nbt path to copy from.
        •  target: The nbt path to copy to, starting from the item's tag tag.
        •  op: Can be replace to replace any existing contents of the target, append to append to a list, 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 to use the entity that died or the player that gained the advancement, opened the container or broke the block, 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 killer entity.
    •  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:
      • : A modifier.
        •  name: Name of the modifier.
        •  attribute: The name of the attribute this modifier is to act upon.
        •  operation: Must be either "addition", "multiply_base" or "multiply_total".
        •  amount: Number provider. Specifies the amount of the modifier.
        •  id: Optional : UUID of the modifier following. If none specified, a new UUID is generated.
        •  slot: Slots the item must be in for the modifier to take effect, this value can be one of the following : "mainhand", "offhand", "feet", "legs", "chest", or "head".
        •  slot: One of the listed slots is chosen randomly.

  • set_banner_pattern[upcoming: JE 1.17] - Sets tags needed for banner patterns.
    •  patterns: List of patterns.
      • :
        •  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, new patterns will be appended to existing ones.

  • set_contents - For loot tables of type 'block', sets the contents of a container block item to a list of entries.
    •  entries: The entries to use as contents.

  • set_count - Sets the stack size.
    •  count: Number provider. Specifies the stack size to set.
    •  add[upcoming: JE 1.17]: 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[upcoming: JE 1.17]: Optional. If true, change will be relative to current damage.

  • set_enchantments[upcoming: JE 1.17] - Sets the item's enchantments.
    •  enchantments: Enchantments to add.
    •  add: Optional. If true, change will be relative to current level.

  • set_loot_table - Sets the loot table for a container (chest etc.).
    •  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.

  • set_lore - Adds lore to the item
    •  lore: List of JSON text components. Each list entry represents one line of the lore.
    •  entity: Specifies the entity to act as the source @s in the JSON text component. Set to this to use the entity that died or the player that gained the advancement, opened the container or broke the block, killer for the killer, or killer_player for a killer that is a player.
    •  replace: If true, replaces all existing lines of lore, if false appends the list.

  • set_name - Adds display name of the item.
    •  name: A JSON text component name, allowing color, translations, etc.
    •  entity: Specifies an entity to act as source @s in the JSON text component. Set to this to use the entity that died or the player that gained the advancement, opened the container or broke the block, killer for the killer, or killer_player for a killer that is a player.

  • set_nbt - Adds NBT data to the item.
    •  tag: Tag string to add, similar to those used by commands. Note that the first bracket is required and quotation marks need to be escaped using a backslash (\).

  • set_stew_effect - Sets the status effects for suspicious stew.
    •  effects: The effects to apply.
      • An effect.
        •  type: The effect ID.
        •  duration: Number provider. The duration of the effect.

Data packs[edit]

Main article: data packs

Custom data packs can add new item modifiers. This is the file structure:

  • world save folder
    • datapacks
      • data pack
        • data
          • custom_namespace
            • item_modifiers
              • item modifier name.json

The JSON files go in this folder. Item modifiers are namespaced. To create an item modifier, first create a new folder for the custom namespace, and then create item modifiers within following a similar structure. Then, use /item ... modify with the name of the directory and file (without the .json extension) as the <modifier>, such as /item entity @s weapon.mainhand modify custom_namespace:path/to/modifier.

History[edit]

Java Edition
1.1720w46aAdded item modifiers.

Issues[edit]

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