Items 1.16+

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 format version items. If you would like to learn about stable items, you can do so here.

Item Events

Using Events

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

Event Functions

swing

Plays the item swinging animation.

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

shoot

Shoots a projectile when triggered.

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 damage to a specified target.

Copy
{
	"example:damage_event": {
		"damage": {
			"type": "magic", // Can also be any entity-accepted damage source
			"amount": 4
		}
	}
}
1
2
3
4
5
6
7
8

decrement_stack

Decrements the stack by one.

Copy
{
	"example:remove_one": {
		"decrement_stack": {}
	}
}
1
2
3
4
5

add_mob_effect

Adds a mob effect when triggered.

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 event functions.

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.

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.

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

Broken/Nonfunctional Features

  • Components
    • minecraft:mining_speed - Currently has no function.
    • minecraft:shooter - Currently broken.
    • minecraft:digger - use_efficiency - Parameter currently has no function.
  • Event Functions
    • transform_item - Crashes the game.

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.

Contributors

SirLichSmokeyStackMedicalJewel105yanasakanaPavelDobCZ23