Items 1.16.100+

experimental

Better documentation on the new item format introduced in the 1.16.100.56 Minecraft beta.

WARNING

This document covers experimental features, for 1.16.100+ format version items. If you would like to learn about stable items, you can do so here.

You can learn more about experimental toggles here.

Item Events

Using Events

Events in items are used most exactly as they are in entities.

Copy
json
{
	"format_version": "1.16.100",
	"minecraft:item": {
		"description": {
			"identifier": "example:food_item",
			"category": "items"
		},
		"components": {
			"minecraft:use_duration": 1.6,
			"minecraft:food": {
				"nutrition": 4,
				"saturation_modifier": "low",
				"can_always_eat": true,
				"on_consume": {
					"event": "on_consume",
					"target": "self"
				}
			},
			"minecraft:use_animation": "eat"
		},
		"events": {
			"on_consume": {
				"remove_mob_effect": {
					"effect": "nausea",
					"target": "holder"
				}
			}
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

Event Functions

Items do, however, have a slightly different set of event functions that they use.

swing

Plays the item swinging animation. (As if to hit.)

Copy
json
{
	"example:swing_event": {
		"swing": {}
	}
}
1
2
3
4
5

shoot

Shoots a projectile when triggered.

  • Properties:

    • "angle_offset" - Does nothing. (Broken)

    • "launch_power" - The launch power to be multiplied over the base power of the projectile entity. Accepts Molang values.

    • "projectile" - Takes an identifier of an entity - any entity, not just projectile ones - to use as an entity to 'shoot'.

Copy
json
{
	"example:shoot_event": {
		"shoot": {
			"projectile": "minecraft:snowball",
			"launch_power": 5,
			"angle_offset": 20
		}
	}
}
1
2
3
4
5
6
7
8
9

damage

Applies a damage to a specified target.

  • Properties:

    • "type" - The type of damage to administer to the target. Standard entity damage types apply, with contextual exceptions.

    • "target" - The target which receives the damage.

    • "amount" - Amount of damage points to apply.

Copy
json
{
	"example:damage_event": {
		"damage": {
			"type": "magic",
			"target": "other",
			"amount": 4
		}
	}
}
1
2
3
4
5
6
7
8
9

decrement_stack

Decrements the stack by one.

  • Properties:

    • "ignore_game_mode" - When false (as is set by default) will not decrement in Creative gamemode.
Copy
json
{
	"example:remove_one": {
		"decrement_stack": {
			"ignore_game_mode": false
		}
	}
}
1
2
3
4
5
6
7

add_mob_effect

Adds a mob effect when triggered.

  • Properties:

    • "ignore_game_mode" - When false (as is set by default) will not decrement in Creative gamemodes.
Copy
json
{
	"example:effect_event": {
		"add_mob_effect": {
			"effect": "poison",
			"target": "holder",
			"duration": 8,
			"amplifier": 3
		}
	}
}
1
2
3
4
5
6
7
8
9
10

remove_mob_effect

Removes a mob effect when triggered.

Copy
json
{
	"example:remove_effect_event": {
		"remove_mob_effect": {
			"effect": "poison",
			"target": "holder"
		}
	}
}
1
2
3
4
5
6
7
8

transform_item

Transforms the item into the item specified.

Copy
json
{
	"example:transform_event": {
		"transform_item": {
			"transform": "minecraft:apple"
		}
	}
}
1
2
3
4
5
6
7

teleport

Teleports the target to a random location in the specified range.

Copy
json
{
	"example:teleport_event": {
		"teleport": {
			"target": "holder",
			"max_range": [8, 8, 8]
		}
	}
}
1
2
3
4
5
6
7
8

sequence

Used to sequence multiple event functions. Works just as in entities.

Copy
json
{
	"example:sequence_event": {
		"sequence": [
			{
				"add_mob_effect": {
					"effect": "poison",
					"target": "holder",
					"duration": 8,
					"amplifier": 3
				}
			},
			{
				"transform_item": {
					"transform": "minecraft:apple"
				}
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

randomize

Used to randomize event functions. Works just as in entities.

Copy
json
{
	"example:randomize_events": {
		"randomize": [
			{
				"weight": 1,
				"transform_item": {
					"transform": "minecraft:apple"
				}
			},
			{
				"weight": 2,
				"add_mob_effect": {
					"effect": "weakness",
					"target": "holder",
					"duration": 8,
					"amplifier": 3
				}
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

run_command

Used to execute commands. Works just as in entities.

Copy
json
{
	"example:execute_command_event": {
		"run_command": {
			"command": ["say hi"],
			"target": "other"
		}
	}
}
1
2
3
4
5
6
7
8

Behaviour Item Components

List of all new item components, with usage examples

minecraft:ignores_permission

Copy
json
{
	"minecraft:ignores_permission": true
}
1
2
3

minecraft:mining_speed

Copy
json
{
	"minecraft:mining_speed": 1
}
1
2
3

minecraft:damage

This component controls the amount of additional attack damgage taht the item does. The value property is a 32-bit integer. This value may also be negative.

Copy
json
{
	"minecraft:damage": 5
}
1
2
3

minecraft:can_destroy_in_creative

This component controls whether or not you can break bocks with this item while you are in creative mode.

Copy
json
{
	"minecraft:can_destroy_in_creative": true
}
1
2
3

minecraft:dye_powder

Copy
json
{
	"minecraft:dye_powder": {
		"color": 4
	}
}
1
2
3
4
5

minecraft:mirrored_art

Copy
json
{
	"minecraft:mirrored_art": true
}
1
2
3

minecraft:explodable

This component controls whether or not this item can be blown up by explosions such as tnt or a creeper.

Copy
json
{
	"minecraft:explodable": true
}
1
2
3

minecraft:should_despawn

This component controls whether or not this item will despawn.

Copy
json
{
	"minecraft:should_despawn": true
}
1
2
3

minecraft:liquid_clipped

This component allows an item to be used on a liquid block to trigger the "minecraft:on_use_on" component, when set to false (default) "minecraft:on_use_on" will not activate when using the item on a liquid block, but when set to true then it will activate.

Copy
json
{
	"minecraft:liquid_clipped": true
}
1
2
3

minecraft:allow_off_hand

Copy
json
{
	"minecraft:allow_off_hand": true // Disables most functionality while the item is in the off hand. 
}
1
2
3

minecraft:projectile

Copy
json
{
	"minecraft:projectile": {
		"projectile_entity": "minecraft:arrow",
		"minimum_critical_power": 0.5
	}
}
1
2
3
4
5
6

minecraft:block_placer

Copy
json
{
	"minecraft:block_placer": {
		"block": "minecraft:grass",
		"use_block_description": true
	}
}
1
2
3
4
5
6

minecraft:interact_button

Copy
json
{
	"minecraft:interact_button": "Use This Custom Item" // Can be a string or a boolean value. 
}
1
2
3

minecraft:hand_equipped

Copy
json
{
	"minecraft:hand_equipped": true
}
1
2
3

minecraft:stacked_by_data

Copy
json
{
	"minecraft:stacked_by_data": true
}
1
2
3

minecraft:chargeable

Copy
json
{
	"minecraft:chargeable": {
		"movement_modifier": 0.0,
		"on_complete": {
			"event": "example:example_event",
			"target": "holder" // Can also be 'self' to trigger an item event"
		}
	}
}
1
2
3
4
5
6
7
8
9

minecraft:hover_text_color

Copy
json
{
	"minecraft:hover_text_color": "green"
}
1
2
3

minecraft:entity_placer

Copy
json
{
	"minecraft:entity_placer": {
		"entity": "minecraft:zombie",
		"use_on": ["minecraft:grass", "minecraft:sand"],
		"dispense_on": ["minecraft:stone", "minecraft:gold_ore"]
	}
}
1
2
3
4
5
6
7

minecraft:on_use_on

Copy
json
{
	"minecraft:on_use_on": {
		"on_use_on": {
			"event": "example:block_event",
			"target": "block"
		}
	}
}
1
2
3
4
5
6
7
8

minecraft:on_use

Copy
json
{
	"minecraft:on_use": {
		"on_use": {
			"event": "example:item_event",
			"target": "self"
		}
	}
}
1
2
3
4
5
6
7
8

minecraft:knockback_resistance

Copy
json
{
	"minecraft:knockback_resistance": {
		"protection": 0.4
	}
}
1
2
3
4
5

minecraft:enchantable

The value property is a 32-bit integer.

Copy
json
{
	"minecraft:enchantable": {
		"slot": "bow", // Can be any of the enchant slot listed below
		"value": 10
	}
}
1
2
3
4
5
6

Enchantable Slots

Note: The "all" enchantable slot allows you to apply any enchantment that you want to the item, just like anh enchanted book.

Slot Name
armor_feet
armor_torso
armor_head
armor_legs
axe
bow
cosmetic_head
crossbow
elytra
fishing_rod
flintsteel
hoe
pickaxe
shears
shield
shovel
sword
all

minecraft:shooter

Copy
json
{
	"minecraft:shooter": {
		"max_draw_duration": 1,
		"charge_on_draw": false,
		"scale_power_by_draw_duration": true,
		"ammunition": [
			{
				"item": "minecraft:arrow",
				"use_offhand": true,
				"search_inventory": true,
				"use_in_creative": true
			},
			{
				"item": "minecraft:fireworks_rocket",
				"use_offhand": true,
				"search_inventory": true,
				"use_in_creative": true
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

minecraft:durability

Copy
json
{
	"minecraft:durability": {
		"max_durability": 100,
		"damage_chance": {
			"min": 5,
			"max": 10
		}
	}
}
1
2
3
4
5
6
7
8
9

minecraft:armor

This component allows you to put the item into the armor slot specified by the minecraft:wearable component. It also stops attatchables from working on the item while it is in a hand slot or while the player is in first person mode. If you want a piece of armor that can still be seen while in first person then don't include this component, and instead include only the minecraft:wearable component, then it will be visible in first person mode too, the side effect of this are that you can't put on the armor directly from the inventory, but instead you have to use the item to put it on, another side effect is that the armor cannot provide any protection values.

Copy
json
{
	"minecraft:armor": {
		"protection": 4,
		"texture_type" : "none"
	}
}
1
2
3
4
5
6

minecraft:wearable

Allows the item to be worn in the specified inventory slot type.

Copy
json
{
	"minecraft:wearable": {
		"dispensable" : true,
		"slot": "slot.armor.feet" // Can be slot listed in the '/replaceitem' command
	}
}
1
2
3
4
5
6

minecraft:weapon

Copy
json
{
	"minecraft:weapon": {
		"on_hurt_entity": {
			"event": "example_event",
			"target": "holder" // Can also be 'self' to trigger an item event"
		}
	}
}
1
2
3
4
5
6
7
8

minecraft:record

Copy
json
{
	"minecraft:record": {
		"sound_event": "cat", // Currently restricted to strings listed below
		"duration": 5,
		"comparator_signal": 8
	}
}
1
2
3
4
5
6
7

Allowed Sound Events

Slot Name
11
13
cat
chirp
blocks
far
mall
mellohi
pigstep
stall
strad
wait
ward

minecraft:repairable

Copy
json
{
	"minecraft:repairable": {
		"repair_items": [
			{
				"items": ["minecraft:iron_ingot", "minecraft:gold_ingot"],
				"repair_amount": 10, // Can also be molang expression
				"on_repaired": {
					"event": "example_event",
					"target": "holder" // Can also be 'self' to trigger an item event"
				}
			},
			{
				"items": ["minecraft:diamond:2", "minecraft:netherite_ingot"], // Putting a second colon and a number after the item identifier allows you to specify a data value for the item, for example minecraft:diamond:2 will not allow the item to be repaired with normal diamonds, but it will allow it to be repaired with diamonds that have a data value of 2. 
				"repair_amount": 100, // Can also be molang expression
				"on_repaired": {
					"event": "example_item_event",
					"target": "self"
				}
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

minecraft:cooldown

Copy
json
{
	"minecraft:cooldown": {
		"category": "ender_pearl", // May be a custom string, as to disable the large, white cooldown bar on multiple cooldown items
		"duration": 1
	}
}
1
2
3
4
5
6

minecraft:use_duration

Copy
json
{
	"minecraft:use_duration": 1.6 // Use duration in seconds of the item
}
1
2
3

minecraft:digger

Copy
json
{
	"minecraft:digger": {
		"use_efficiency": true,
		"destroy_speeds": [
			{
				"block": {
					"tags": "q.any_tag('stone', 'metal')" // Note that not all blocks have tags; listing many blocks may be necessary
				},
				"speed": 6,
				"on_dig": {
                    "event": "on_dig"
                }
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

minecraft:fertilizer

Copy
json
{
	"minecraft:fertilizer": {
		"type": "bonemeal" // Can also be "rapid"
	}
}
1
2
3
4
5

minecraft:fuel

Copy
json
{
	"minecraft:fuel": {
		"duration": 20
	}
}
1
2
3
4
5

minecraft:throwable

Throws the item as the projectile entity type specified in the "minecraft:projectile" component.

Copy
json
{
	"minecraft:throwable": {
		"do_swing_animation": true,
		"max_draw_duration": 2,
		"scale_power_by_draw_duration": true
	}
}
1
2
3
4
5
6
7

minecraft:icon

Copy
json
{
	"minecraft:icon": {
		"frame": 0, // Texture's array entry to use, defaults to 0
		"texture": "tool.Kama" // Texture referenced in 'item_texture.json'
	}
}
1
2
3
4
5
6

Frame field no longer works. First texture of an array will be applied. :::

minecraft:creative_category

Copy
json
{
	"minecraft:creative_category": {
		"parent": "itemGroup.name.nature" // Can be any creative category
	}
}
1
2
3
4
5

Full list of categories can be found here

minecraft:food

_New Syntax_
Copy
json
{
	"minecraft:food": {
		"on_consume": {
			"event": "example_event",
			"target": "holder" // Can also be 'self' to trigger an item event
		},
		"nutrition": 3,
		"can_always_eat": true,
		"saturation_modifier": "normal", // Can also be a float value. 
		"using_converts_to": "minecraft:apple" // Changes the food or drink into another item when consumed. It can be changed to any item.
	}
}
1
2
3
4
5
6
7
8
9
10
11
12

minecraft:use_animation

Copy
json
{
	"minecraft:use_animation": "eat" // Adds the animation and sound when eating a food item. It can also be changed to "drink".
}
1
2
3

minecraft:render_offsets

_New Syntax_
Copy
json
{
	"minecraft:render_offsets": {
		"main_hand": {
			"first_person": {
				"position": [1, 1, 1],
				"rotation": [1, 1, 1],
				"scale": [1, 1, 1]
			},
			"third_person": {
				"position": [1, 1, 1],
				"rotation": [1, 1, 1],
				"scale": [1, 1, 1]
			}
		},
		"off_hand": {
			"first_person": {
				"position": [1, 1, 1],
				"rotation": [1, 1, 1],
				"scale": [1, 1, 1]
			},
			"third_person": {
				"position": [1, 1, 1],
				"rotation": [1, 1, 1],
				"scale": [1, 1, 1]
			}
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Item Tags

Item tags work the same as block tags and can be applied like this:

Copy
json
{
	"format_version": "1.16.100",
	"minecraft:item": {
		"description": {
			"identifier": "example:my_item"
		},
		"components": {
			"tag:example:my_tag": {}
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11

They can then be queried with:

  • q.any_tag
  • q.all_tags
  • q.equipped_item_all_tags
  • q.equipped_item_any_tag

Breaking changes

If your item isn't showing up, these changes might have broken your item.

  • Item behavior files now require a "category" to show up in the /give command and creative inventory. Example:
Copy
json
{
    "format_version": "1.16.100",
    "minecraft:item": {
        "description": {
            "identifier": "example:item",
            "category" : "items"     // This line is required
        },
        "components": {...},
        "events": {...}
    }
}
1
2
3
4
5
6
7
8
9
10
11
  • RP item files are no longer used, minecraft:icon and all other RP components should be used in the BP item file.

  • Refer to the Troubleshooting Guide for more information, found here

Additional Notes

Niche Features

  • Components
    • minecraft:icon - Property "frame" may take in Molang values.

Broken/Nonfunctional Features

  • Components
    • minecraft:mining_speed - Currently has no known function.
    • minecraft:dye_powder - Currently has no known function.
    • minecraft:frame_count - Currently has no known function.
    • minecraft:animates_in_toolbar - Currently has no known function.
    • minecraft:mirrored_art - Currently has no known function.
    • minecraft:requires_interact - Currently has no known function.
    • minecraft:ignores_permission - Currently has no known function.
    • minecraft:map - Currently has no known function.
    • "saddle" - Currently has no known function.
    • minecraft:shears - Currently has no known function.
    • minecraft:bucket - Currently has no known function.
    • minecraft:digger - use_efficiency - Parameter Currently has no known function.

Current Limitations

  • Vanilla Items are hardcoded; you may not override or access them, using the new format.
  • minecraft:record - May not add a custom sound_event.
  • Items aliases currently do not work.

Contributors