Minecraft:Item modifier

Template:Exclusive Item modifiers (also known as loot modifiers) can be used to apply modifications to item stacks, such as adjusting the stack size or adding enchantments. They can be defined in Minecraft:datapacks as Minecraft:JSON files, or used in Minecraft:loot tables. The Template:Cmd command also accepts item modifiers in Minecraft:SNBT format.

A single modification in item modifiers is called item function or loot function.

Definition

An item modifier is a single loot function or an array of loot functions to apply to the item. The root element of an item modifier can be either an Template:Nbt, following the structure of a loot function below, or an Template:Nbt, containing multiple loot functions.

Item modifiers are defined using the Minecraft:JSON format in Minecraft:data packs, or the Minecraft:SNBT format in Template:Cmd command.

Item modifiers defined in data packs in the following directory structure, highlighted below: Template:Data pack directory

Usage

Commands

Item modifiers can be invoked with the Template:Cmd 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: Template:Cmd invokes a modifier alone upon the target slot, Template:Cmd replaces the item in the target slot with another and subsequently invokes a modifier upon it.

• Template:Cmd
• Template:Cmd

Loot tables

In Minecraft:loot tables, item modifiers can be defined without the need for a separate file; however, separate files can also be explicitly referenced using the reference function.

Format

The format of a single item modifier is:

• Template:Nbt Root object
  • Template:Nbt: Minecraft:Resource location of the loot function type to apply. Valid function types are described below.
  • Template:Nbt: A list of Minecraft:predicates, of which all must pass, for this function to be applied.
    • Template:Nbt A predicate. The structure is described on the Minecraft:Predicates page.
  • Other parameters of the function, described below.

Multiple modifiers may be bundled into one by placing them into a JSON array or an NBT list. In this case, all listed modifiers are applied in sequence, similar to the sequence modifier type.

• Template:Nbt The root, a list in this case
  • Template:Nbt An item modifier.

Function types

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

• apply_bonus—Applies a predefined bonus formula to the count of the item stack.
  • Template:Nbt: ID of an enchantment on the tool provided by Minecraft:loot context used for level calculation.
  • Template:Nbt: A Minecraft:resource location. Can be binomial_with_bonus_count for 1 bonus item plus bonus determined by binomial distribution with n=level + extra, p=probability. Can be 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))))).
  • Template:Nbt: Values required for the formula.
    • Template:Nbt: For formula 'binomial_with_bonus_count', the extra value.
    • Template:Nbt: For formula 'binomial_with_bonus_count', the probability.
    • Template:Nbt: For formula 'uniform_bonus_count', the bonus multiplier.

• copy_components—Copies components from a specified source onto an item.
  • Template:Nbt: Source type to pull from. Specifies an entity or block entity from Minecraft:loot context. Can be Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd
  • Template:Nbt: Optional. A list of components to include. If omitted, all components are copied.
    • Template:Nbt: A component
  • Template:Nbt: Optional. A list of components to exclude.
    • Template:Nbt: A component

• copy_custom_data—Copies Minecraft:NBT values from an entity, block entity, or storage to the item's minecraft:custom_data component.
  • Template:Nbt: Shorthand form of Template:Nbt below with Template:Nbt set to context. Specifies an entity or block entity from Minecraft:loot context. Can be Template:Cd, Template:Loot entity target.
  • Template:Nbt: Information of the block entity, entity or storage to copy NBT from.
    • Template:Nbt: Set to context to use a block entity or an entity as the source, or storage to use a command storage as the source.
    • Template:Nbt: Included only if type is set to context. Specifies an entity or block entity from Minecraft:loot context to copy NBT from. Can be Template:Cd, Template:Loot entity target.
    • Template:Nbt: Included only if type is set to storage. A Minecraft:resource location specifying the storage ID to copy NBT from.
  • Template:Nbt: A list of copy operations.
    • Template:Nbt An NBT operation.
      • Template:Nbt: The NBT path to copy from.
      • Template:Nbt: The NBT path to copy to, starting from the item's minecraft:custom_data component.
      • Template:Nbt: 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_name—Copies an entity or block entity's name tag into the item's minecraft:custom_name component.
  • Template:Nbt - The target whose name is to be copied. Specifies an entity or block entity from Minecraft:loot context. Can be Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd or Template:Cd.

• copy_state—Copies block state properties provided by Minecraft:loot context to the item's minecraft:block_state component.
  • Template:Nbt: A block ID. Function fails if the block doesn't match the Template:Nbt list.
  • Template:Nbt: A list of properties to copy.
    • Template:Nbt The name of a block state to copy.

• discard—Removes the item stack.

• enchant_randomly—Enchants the item with one randomly-selected enchantment. The level of the enchantment, if applicable, is random. A book converts to an Minecraft:enchanted book when enchanted.
  • Template:NbtTemplate:Nbt: Optional. Template:Json ref/enchantment. List of enchantments to choose from. If omitted, all enchantments are possible.
  • Template:Nbt: Optional, defaults to Template:Cd. Whether only enchantments that are compatible with the item should be chosen (i.e. the item is listed in the enchantments Template:Cd). Books are always considered compatible.
  • Template:Nbt. Optional, defaults to Template:Cd. Whether to add a Template:Cd component to the item. The value is calculated as Template:Cd where Template:Cd is the level of the enchantment applied.

• enchant_with_levels—Enchants the item, with the specified enchantment level (roughly equivalent to using an Minecraft:enchanting table at that level). A book converts to an Minecraft:enchanted book.
  • Template:NbtTemplate:Nbt: Number provider. Specifies the enchantment level to use.
  • Template:NbtTemplate:Nbt: Optional. Template:Json ref/enchantment. List of enchantments to choose from. If omitted, all enchantments are possible.
  • Template:Nbt. Optional, defaults to Template:Cd. Whether to add a Template:Cd component to the item. The value is equal to the value determined by Template:NbtTemplate:Nbt.

• enchanted_count_increase—Adjusts the stack size based on the level of the specified enchantment on the Template:Cd entity provided by Minecraft:loot context.
  • Template:NbtTemplate:Nbt: A number provider. Specifies the number of additional items per level of the enchantment. Note the number may be fractional, rounded after multiplying by the enchantment level.
  • Template:Nbt: Specifies the maximum amount of items in the stack after the enchantment calculation. If the value is 0, no limit is applied. Defaults to 0.
  • Template:Nbt: Template:Json ref/enchantment. The enchantment whose levels should be used to calculate the count.

• exploration_map—If the origin is provided by Minecraft:loot context, converts an empty map into an Minecraft:explorer map leading to a nearby generated structure.
  • Template:Nbt: A Minecraft:tag of Minecraft:structure to locate. Defaults to on_treasure_maps.
  • Template:Nbt: 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.
  • Template:Nbt: The zoom level of the resulting map. Defaults to 2.
  • Template:Nbt: 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.
  • Template:Nbt: Don't search in chunks that have already been generated. Defaults to true.

• explosion_decay—Removes some items from a stack, if the explosion radius is provided by Minecraft: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.
  • Template:Nbt: Specifies a player to be used for the player head. Specifies an entity from Minecraft:loot context. Can be Template:Loot entity target.

• filtered—Applies an Item Predicate to the target item, and runs modifiers according to whether the predicate passes or fails.
  • Template:Nbt: An Item Predicate
    • Template:Nbt inherit/conditions/item
  • Template:NbtTemplate:Nbt: (Optional) Modifier or list of modifiers to apply to items that match the filter
  • Template:NbtTemplate:Nbt: (Optional) Modifier or list of modifiers to apply to items that do NOT match the filter

• 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.
  • Template:Nbt: An integer to specify the exact limit to use.
  • Template:Nbt: Limits the count between a minimum and maximum value.
    • Template:NbtTemplate:Nbt: Optional. A number provider. Minimum limit to use.
    • Template:NbtTemplate:Nbt: Optional. A number provider. Maximum limit to use.

• modify_contents—Applies a function to every item inside an inventory component. If such a component does not exist, it is not added.
  • Template:Nbt: A target component. Allowed values are bundle_contents, charged_projectiles, container}}.
  • Template:NbtTemplate:Nbt: Function or list of functions to be applied to every item inside the container.

• reference—Call sub-functions
  • Template:NbtTemplate:Nbt: Location of function to call.

• sequence—Applies a list of functions. Doesn't check Template:Nbt (all functions always run)<ref>Template:Bug

Template:Bug</ref>

• • Template:Nbt: Location of function to call.
    • Template:Nbt An item modifier. The same JSON structure as described on this page.

• set_attributes—Add attribute modifiers to the item.
  • Template:Nbt:
    • Template:Nbt: An attribute modifier to add.
      • Template:Nbt: The Minecraft:resource location of the attribute this modifier is to act upon.
      • Template:Nbt: The operation of this attribute modifier. One of add_value, add_multiplied_base, or add_multiplied_total.
      • Template:NbtTemplate:Nbt: A number provider. Specifies the amount of the modifier.
      • Template:Nbt: Minecraft:Resource location to assign the modifier.
      • Template:Nbt: Sets the slots the item must be in for the modifier to take effect. One of: mainhand, offhand, feet, legs, chest, head.
      • Template:Nbt: 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.
  • Template:Nbt: Optional. Set to true to replace the existing item attributes with the attributes in Template:Nbt. If false, the lines are appended to the list of existing attributes. Defaults to true.

• 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.
  • Template:Nbt: List of patterns to add or replace with.
    • Template:Nbt: A pattern.
      • Template:Nbt: The pattern type. For example, square_bottom_left.
      • Template:Nbt: 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.
  • Template:Nbt: Required. If true, the patterns are applied on top of the banner's existing patterns.

• set_book_cover—Sets the cover details of the minecraft:written_book_content component. If present, any pages in the book are left untouched.
  • Template:Nbt: Optional. Sets the author of the book. If omitted, the original author is kept (or an empty string is used if there was no component).
  • Template:Nbt: Optional. Sets the generation value of the book (original, copy, etc.). Allowed values are 0 to 3. If omitted, the original generation is kept (or 0 is used if there was no component).
  • Template:NbtTemplate:NbtTemplate:Nbt: Optional. Sets the title of the book as a Minecraft:raw JSON text component. If omitted, the original title is kept (or an empty string is used if there was no component).

• set_components—Sets components of an item.
  • Template:Nbt: A map of components ID to component value. Components with a ! prefix (e.g. "!minecraft:damage": {}) causes this component to be removed.

• set_contents - Sets the contents of a container block item to a list of entries.
  • Template:Nbt: A list of loot table entry producer to provide item stacks.
  • Template:Nbt: The target component to be filled with items. Existing contents are replaced. Allowed values: container, bundle_contents, and charged_projectiles. Both bundle_contents and charged_projectiles ignore empty stacks.<ref>Template:Mcnet</ref>

• set_count - Sets the stack size.
  • Template:NbtTemplate:Nbt: A number provider. Specifies the stack size to set.
  • Template:Nbt: Optional. If true, change is relative to current count. Defaults to false.

• set_custom_data—Sets the minecraft:custom_data component.
  • Template:NbtTemplate:Nbt: The data to merge onto the item's minecraft:custom_data component, either within a JSON string or as unflattened tags. That means that {"tag": "{a:1}"} and {"tag": {"a":1}} are equivalent. When using the string representation, additional care is required: the outer braces { } of the component must still be present and if the NBT contains quotation marks ", they must be escaped with a backslash \.

• set_custom_model_data—Sets minecraft:custom_model_data component.
  • Template:Nbt: Optional. Specifies floats for the Minecraft:custom model data.
    • Template:Nbt: A list of number providers.
    • Template:Nbt: Determines how existing values should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
    • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace values from. Defaults to 0
    • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.
  • Template:Nbt: Optional. Specifies flags for the custom model data.
    • Template:Nbt: A list of Template:Nbt values.
    • Template:Nbt: Determines how existing values should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
    • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace values from. Defaults to 0
    • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.
  • Template:Nbt: Optional. Specifies strings for the custom model data.
    • Template:Nbt: A list of Template:Nbt.
    • Template:Nbt: Determines how existing values should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
    • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace values from. Defaults to 0
    • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.
  • Template:Nbt: Optional. Specifies colors for the custom model data.
    • Template:Nbt: A list of RGB values.
      • Template:NbtTemplate:Nbt: A number provider specifying an RGB value as a decimal.
      • Template:Nbt: A list containing 3 individual red, green, and blue values that is automatically converted to a decimal. Template:More info needed
    • Template:Nbt: Determines how existing values should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
    • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace values from. Defaults to 0
    • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.

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

• set_enchantments - Modifies the item's enchantments. A book converts to an Minecraft:enchanted book.
  • Template:Nbt: Enchantments to modify.
    • Template:NbtTemplate:Nbt: 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 remove the enchantment, through a relative negative add or through a direct value assignemnt.
  • Template:Nbt: Optional. If true, change is relative to current level. A nonexistent enchantment is presumed to start at 0. Defaults to false.

• set_fireworks—Sets minecraft:fireworks component.
  • Template:Nbt: Optional. Specifies firework explosions.
    • Template:Nbt: List of firework explosion data.
      • Template:Nbt: The shape of the explosion. Can be Template:Cd.
      • Template:Nbt: The colors of the initial particles of the explosion, randomly selected from.
      • Template:Nbt: The colors of the fading particles of the explosion, randomly selected from.
      • Template:Nbt: Whether or not the explosion has a trail effect (diamond).
      • Template:Nbt: Whether or not the explosion has a twinkle effect (glowstone dust).
    • Template:Nbt: Determines how existing fireworks component should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
    • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace explosions from. Defaults to 0
    • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.
  • Template:Nbt: Optional, allowed values are 0 to 255. Determines flight duration measured in number of gunpowder. If omitted, the flight duration of the item is left untouched (or set to 0 if the component did not exist before).

• set_firework_explosion—Sets minecraft:firework_explosion component.
  • Template:Nbt: The shape of the explosion. Can be Template:Cd.
  • Template:Nbt: The colors of the initial particles of the explosion, randomly selected from.
  • Template:Nbt: The colors of the fading particles of the explosion, randomly selected from.
  • Template:Nbt: Whether or not the explosion has a trail effect (diamond).
  • Template:Nbt: Whether or not the explosion has a twinkle effect (glowstone dust).

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

• set_item—Replaces item type without changing count or components.
  • Template:Nbt: An item ID.

• set_loot_table - Sets the loot table for a container block when placed and opened.
  • Template:Nbt: Specifies the Minecraft:resource location of the loot table to be used.
  • Template:Nbt: 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 is used when opening the container.
  • Template:Nbt: the block entity type to be written in BlockEntityTag.id.

• set_lore - Adds or changes the item's lore.
  • Template:Nbt: List of lines to append or replace on the item's lore.
    • Template:NbtTemplate:NbtTemplate:Nbt A line of item lore, following the Minecraft:Raw JSON text format. Components requiring resolution are resolved only if entity successfully targets an entity.
  • Template:Nbt: Specifies the entity to act as @s when referenced in the JSON text component. Specifies an entity from Minecraft:loot context. Can be Template:Loot entity target.
  • Template:Nbt: Required. Determines how existing lore component should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
  • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace lines of lore from. Defaults to 0
  • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.

• set_name—Adds or changes the item's custom name.
  • Template:NbtTemplate:NbtTemplate:Nbt: A JSON text component, overwriting the previous custom name on the item. Components requiring resolution are resolved only if entity successfully targets an entity.
  • Template:Nbt: Specifies the entity to act as @s when referenced in the JSON text component. Specifies an entity from Minecraft:loot context. Can be Template:Loot entity target.
  • Template:Nbt: Optional. Allowed values are custom_name or item_name, corresponding with the component to be set. Defaults to custom_name.

• set_ominous_bottle_amplifier—Sets the ominous_bottle_amplifier component of an item.
  • Template:Nbt: a number provider used to generate the ominous_bottle_amplifier component.

• set_potion—Sets the potion_contents component of an item.
  • Template:Nbt: The potion ID. Set to empty to remove the Potion tag.

• set_random_dyes—Sets the dyed_color component of an item.
  • Template:NbtTemplate:Nbt: A Minecraft:number provider. The amount of random dyes to select and add to the item. The same dye can be selected multiple times.

• set_random_potion—Sets the potion_contents component of an item randomly.
  • Template:NbtTemplate:Nbt: Optional. Template:Json ref. If omitted, all potions are possible.

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

• set_writable_book_pages—Manipulates the pages of the minecraft:writable_book_content component.
  • Template:Nbt: A list of pages as filterable strings.
    • Template:Nbt: A single page.
      • Template:Nbt: The plain text content of the page.
      • Template:Nbt: The filtered text of the page. Optional. Shown only to players with chat filter enabled, instead of Template:Nbt

      Alternatively, a single page can be represented as follows:

    • Template:Nbt: The plain text content of a page.
  • Template:Nbt: Determines how existing pages should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
  • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace pages from. Defaults to 0
  • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.

• set_written_book_pages—Manipulates the pages of the minecraft:written_book_content component.
  • Template:Nbt: A list of pages as filterable Minecraft:text components.
    • Template:Nbt: A single page.
      • Template:NbtTemplate:NbtTemplate:Nbt: A text component.
      • Template:NbtTemplate:NbtTemplate:Nbt: A text component. Optional. Shown only to players with chat filter enabled, instead of Template:NbtTemplate:NbtTemplate:Nbt

      Alternatively, a single page can be represented as follows:

    • Template:NbtTemplate:NbtTemplate:Nbt: A text component.
  • Template:Nbt: Determines how existing pages should be modified. Allowed values are "append", "insert", "replace_all", "replace_section".
  • Template:Nbt: Used only if Template:Nbt is set to "insert" or "replace_section". Specifies index to insert or replace pages from. Defaults to 0
  • Template:Nbt: Used only if Template:Nbt is set to "replace_section". Specifies the size of the range to be replaced. If omitted, the size of Template:Nbt field is used.

• toggle_tooltips—Toggles which tooltips are visible.
  • Template:Nbt: A map of supported item components to modify. All fields are optional.
    • Template:Nbt: Changes the visibility of the tooltip displaying the item's attribute modifiers.
    • Template:Nbt: Changes the visibility of the tooltip displaying the blocks the item can break in Minecraft:Adventure mode.
    • Template:Nbt: Changes the visibility of the tooltip displaying the blocks the item can placed on in Minecraft:Adventure mode.
    • Template:Nbt: Changes the visibility of the tooltip displaying dyed Minecraft:armor color.
    • Template:Nbt: Changes the visibility of the tooltip displaying the item's enchantments.
    • Template:Nbt: Changes the visibility of the tooltip displaying the item's stored enchantments (for Minecraft:enchanted books).
    • Template:Nbt: Changes the visibility of the tooltip displaying the item's armor trim.
    • Template:Nbt: Changes the visibility of the tooltip displaying the item's unbreakable status. Setting this to any value does not change whether the item is unbreakable.

External links

• Item Modifier Generator on misode.github.io