Consumables and Food
Making an item edible requires a combination of two distinct components: one to define the nutritional payoff and another to control the physical action of eating. The `minecraft:food` component dictates how much hunger the item restores and how much saturation it provides, while `minecraft:use_modifiers` governs how long the player must hold the use button and how fast they move while doing so.
If you include `minecraft:food` without `minecraft:use_modifiers`, the item will not be consumable in-game because the engine defaults the use duration to zero. You also need to provide a `minecraft:use_animation` component so the game knows whether to play the eating or drinking animation and sound effects.
| Field | What it does | Notes |
|---|---|---|
| nutrition | Restores hunger points upon consumption. | Integer value. One hunger icon on the HUD equals 2 points. |
| saturation_modifier | Calculates hidden saturation restored based on nutrition. | Float value. Higher values delay hunger depletion longer. |
| can_always_eat | Allows consumption even when the hunger bar is full. | Boolean. Useful for items meant to give buffs or convert items. |
| using_converts_to | Replaces the consumed item with another item identifier. | String. Commonly used to return bowls or empty bottles. |
| use_duration | Time in seconds required to finish using the item. | Lives inside `minecraft:use_modifiers`. Standard food is 1.6. |
| movement_modifier | Multiplier for player movement speed while using the item. | Lives inside `minecraft:use_modifiers`. Range is 0.0 to 1.0. |
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "my_pack:spiced_apple",
"menu_category": {
"category": "equipment",
"group": "itemGroup.name.miscFood"
}
},
"components": {
"minecraft:icon": {
"textures": {
"default": "spiced_apple"
}
},
"minecraft:use_animation": "eat",
"minecraft:use_modifiers": {
"use_duration": 1.6,
"movement_modifier": 0.35
},
"minecraft:food": {
"nutrition": 6,
"saturation_modifier": 0.6,
"can_always_eat": true,
"using_converts_to": "minecraft:stick"
}
}
}
}Placing Blocks and Entities
Items that place objects into the world rely on `minecraft:block_placer` and `minecraft:entity_placer`. The `minecraft:block_placer` component allows an item to place a specified block when used against a valid surface. This is particularly useful when you want an item in the inventory to have a flat 2D sprite (like seeds, doors, or cakes) rather than rendering the 3D block model, or when one item should replace the standard auto-generated item of a custom block.
Similarly, `minecraft:entity_placer` turns your custom item into a functional equivalent of a spawn egg or a boat item. You define the target entity identifier, and you can optionally restrict which blocks the player is allowed to tap to spawn the entity, as well as which Monster Spawner blocks the item is allowed to overwrite.
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "my_pack:golem_totem"
},
"components": {
"minecraft:icon": {
"textures": {
"default": "golem_totem"
}
},
"minecraft:max_stack_size": 16,
"minecraft:entity_placer": {
"entity": "minecraft:iron_golem",
"use_on": [
"minecraft:grass_block",
"minecraft:dirt",
"minecraft:stone"
],
"dispense_on": [
"minecraft:grass_block",
"minecraft:stone"
]
}
}
}
}Ranged Weapons and Projectiles
For items that can be thrown immediately (like snowballs or ender pearls) or charged and fired (like bows), Bedrock provides `minecraft:throwable` and `minecraft:shooter`. A throwable item acts as the trigger to spawn a separate projectile entity, which means you must also pair `minecraft:throwable` with `minecraft:projectile` on the item so the engine knows which entity identifier to summon when the throw occurs.
The `minecraft:shooter` component handles weapons that consume ammunition from the player's inventory. You define an array of valid ammunition items and the projectile entity each one spawns when fired. If you want the weapon to require charging before release, enable `charge_on_draw` and configure `minecraft:use_modifiers` with a long enough duration so the player can hold the draw before releasing.
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "my_pack:pebble"
},
"components": {
"minecraft:icon": {
"textures": {
"default": "pebble"
}
},
"minecraft:projectile": {
"projectile_entity": "minecraft:snowball",
"minimum_critical_power": 1.0
},
"minecraft:throwable": {
"do_swing_animation": true,
"launch_power_scale": 1.2,
"max_draw_duration": 0.0,
"scale_power_by_draw_duration": false
}
}
}
}Passive Usage: Fuel, Repair, and Cooldowns
Not all usage components happen in the player's hand during gameplay; several govern how the item is used inside block interfaces or how often an action can be repeated. The `minecraft:fuel` component allows an item to be placed into the fuel slot of furnaces, blast furnaces, and smokers. Its single `duration` property is measured in seconds of burn time, where a standard piece of coal burns for 80.0 seconds and smelts eight items.
To restrict how fast a player can spam a throwable, shooter, or consumable item, attach `minecraft:cooldown`. This component applies a visual recharging overlay to the item slot on the hotbar—identical to throwing an ender pearl. By assigning a shared `category` string across multiple custom items, using one item will trigger the cooldown timer for every item in that same category simultaneously.
Finally, `minecraft:repairable` defines how a damaged item can be restored inside an anvil interface. It accepts an array of repair entries, letting you list which raw materials (or copies of the tool itself) are valid inputs and how much durability each material restores via simple numeric values or Molang expressions.
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "my_pack:charred_root"
},
"components": {
"minecraft:icon": {
"textures": {
"default": "charred_root"
}
},
"minecraft:fuel": {
"duration": 20.0
},
"minecraft:cooldown": {
"category": "my_pack:root_items",
"duration": 3.5
}
}
}
}Handling Complex Usage Without Events
In older format versions, items relied on `minecraft:on_use` and `minecraft:on_use_on` to trigger JSON item events inside the same file. Those event components were removed from modern format versions starting in 1.20.40 and 1.20.50. The components documented on this page cover the vast majority of standard vanilla mechanics that previously required workarounds.
If your item requires custom logic that these vanilla usage components cannot express—such as teleporting the player, applying status effects on consumption, or running conditional commands when tapping a block—you must now combine `minecraft:use_modifiers` (if the item is held/charged) with the `@minecraft/server` Scripting API's `itemComponentRegistry` and `minecraft:custom_components`.
Which versions this applies to
Applies to format_version 1.20.50 and newer. All components shown here are stable and do not require any experimental toggles.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| Player holds right-click with a custom food item, the eating animation starts, but the item never finishes being eaten and no hunger is restored. | The item has `minecraft:food` defined, but is missing `minecraft:use_modifiers` or has `use_duration` set to 0. | Add `minecraft:use_modifiers` to your component list and set `use_duration` to a positive float such as 1.6. |
| Content Log Error: [Item][error]-my_pack:pebble | minecraft:throwable requires a projectile item component to be defined in order to launch a projectile. | `minecraft:throwable` only handles the player input and throwing physics; it does not know which entity to summon. | Add the `minecraft:projectile` component alongside `minecraft:throwable` and specify a valid `projectile_entity` identifier. |
| Custom block vanishes from the Creative inventory after adding a custom item with `minecraft:block_placer` pointing to that block. | By default, `minecraft:block_placer` replaces the target block's auto-generated block item unless configured otherwise, or the item itself lacks a `menu_category`. | Ensure your custom item has a valid `menu_category` inside its `description` block so it appears in the Creative menu in place of the raw block. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.