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.

Item Events

| Using Events

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

Copy
{
	"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
31
32

| 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
{
	"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 ones projectile - to use as an entity to 'shoot'.

Copy
{
	"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
{
	"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 gamemodes.
Copy
{
	"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
{
	"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
{
	"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
{
	"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
{
	"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
{
	"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
{
	"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
{
	"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
{
	"minecraft:ignores_permission": true
}
1
2
3
  • minecraft:mining_speed
Copy
{
	"minecraft:mining_speed": 1
}
1
2
3
  • minecraft:damage
Copy
{
	"minecraft:damage": 5
}
1
2
3
  • minecraft:can_destroy_in_creative
Copy
{
	"minecraft:can_destroy_in_creative": true
}
1
2
3
  • minecraft:dye_powder
Copy
{
	"minecraft:dye_powder": {
		"color": 4
	}
}
1
2
3
4
5
  • minecraft:mirrored_art
Copy
{
	"minecraft:mirrored_art": true
}
1
2
3
  • minecraft:explodable
Copy
{
	"minecraft:explodable": true
}
1
2
3
  • minecraft:should_despawn
Copy
{
	"minecraft:should_despawn": true
}
1
2
3
  • minecraft:liquid_clipped
Copy
{
	"minecraft:liquid_clipped": true
}
1
2
3
  • minecraft:allow_off_hand
Copy
{
	"minecraft:allow_off_hand": true // Disables most functionality
}
1
2
3
  • minecraft:projectile
Copy
{
	"minecraft:projectile": {
		"projectile_entity": "minecraft:arrow",
		"minimum_critical_power": 0.5
	}
}
1
2
3
4
5
6
  • minecraft:block_placer
Copy
{
	"minecraft:block_placer": {
		"block": "minecraft:grass",
		"use_block_description": true
	}
}
1
2
3
4
5
6
  • minecraft:entity_placer
Copy
{
	"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
{
	"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
{
	"minecraft:on_use": {
		"on_use": {
			"event": "example:item_event",
			"target": "self"
		}
	}
}
1
2
3
4
5
6
7
8
  • minecraft:knockback_resistance
Copy
{
	"minecraft:knockback_resistance": {
		"protection": 0.4
	}
}
1
2
3
4
5
  • minecraft:enchantable
Copy
{
	"minecraft:enchantable": {
		"slot": "bow", // Can be any of the enchant slot listed below
		"value": 10
	}
}
1
2
3
4
5
6

Enchantable Slots

Slot Name
bow
armor_feet
armor_torso
armor_head
armor_legs
hoe
axe
pickaxe
shovel
sword
elytra
fishing_rod
flintsteel
shears
cosmetic_head
  • minecraft:shooter
Copy
{
	"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
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  • minecraft:durability
Copy
{
	"minecraft:durability": {
		"max_durability": 100,
		"damage_chance": {
			"min": 5,
			"max": 10
		}
	}
}
1
2
3
4
5
6
7
8
9
  • minecraft:armor
Copy
{
	"minecraft:armor": {
		"protection": 4
	}
}
1
2
3
4
5
  • minecraft:wearable
Copy
{
	"minecraft:wearable": {
		"slot": "slot.armor.feet" // Can be slot listed in the '/replaceitem' command
	}
}
1
2
3
4
5
  • minecraft:weapon
Copy
{
	"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
{
	"minecraft:record": {
		"sound_event": "cat", // Currently restricted to strings listed below
		"comparator_signal": 8
	}
}
1
2
3
4
5
6

Allowed Sound Events

Slot Name
11
13
cat
chirp
blocks
far
mall
mellohi
pigstep
stall
strad
wait
ward
  • minecraft:repairable
Copy
{
	"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"
				}
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
  • minecraft:cooldown
Copy
{
	"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
{
	"minecraft:use_duration": 1.6 // Use duration in seconds of the item
}
1
2
3
  • minecraft:digger
Copy
{
	"minecraft:digger": {
		"use_efficiency": true,
		"destroy_speeds": [
			{
				"block": {
					"tags": "query.any_tag('stone', 'metal')" // Note that not all blocks have tags; listing many blocks may be necessary
				},
				"speed": 6
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
  • minecraft:fertilizer
Copy
{
	"minecraft:fertilizer": {
		"type": "bonemeal" // Can also be "rapid"
	}
}
1
2
3
4
5
  • minecraft:fuel
Copy
{
	"minecraft:fuel": {
		"duration": 20
	}
}
1
2
3
4
5
  • minecraft:throwable
Copy
{
	"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
{
	"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
  • minecraft:creative_category
Copy
{
	"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
{
	"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",
		"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
{
	"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:renderoffsets _New Syntax
Copy
{
	"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
{
	"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:

  • query.any_tag
  • query.all_tags
  • query.equipped_item_all_tags
  • query.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
{
    "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:shooter - Currently broken.
    • 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