How Throwable Items Work in Bedrock
A throwable item is not actually the object flying through the air. In the Bedrock engine, the item in the player's inventory simply listens for a use input, deducts one from the item stack (unless the player is in Creative mode), and spawns a separate entity in front of the player's camera.
To make an item throwable, you must always combine two specific item components in your item JSON file: minecraft:throwable and minecraft:projectile. The first component controls how the player's arm behaves, whether the throw can be charged up, and how much velocity is imparted. The second component tells the game which entity identifier to spawn when the throw actually triggers. Without both components present on the item, nothing will launch.
Basic Instant-Throw Item Configuration
The most common pattern is an instant throw, similar to a snowball or egg, where pressing the use button immediately launches the projectile at a fixed speed. To set this up, you configure the item with launch_power_scale at its default or desired multiplier and keep do_swing_animation set to true so the player's arm visibly tosses the item.
Below is a complete, minimal item definition for a custom throwing pebble. It sets a short cooldown so players cannot spam every single tick, defines the icon, and points to a custom entity identifier that will act as the physical rock in the air.
{
"format_version": "1.20.80",
"minecraft:item": {
"description": {
"identifier": "wiki:pebble",
"menu_category": {
"category": "equipment"
}
},
"components": {
"minecraft:icon": "wiki_pebble",
"minecraft:max_stack_size": 16,
"minecraft:cooldown": {
"category": "pebble_throw",
"duration": 0.5
},
"minecraft:throwable": {
"do_swing_animation": true,
"launch_power_scale": 1.0,
"max_draw_duration": 0.0,
"min_draw_duration": 0.0,
"scale_power_by_draw_duration": false
},
"minecraft:projectile": {
"minimum_critical_power": 1.0,
"projectile_entity": "wiki:pebble_projectile"
}
}
}
}Component Reference
The properties inside minecraft:throwable and minecraft:projectile give you control over the feel and timing of the throw. If you want an item that must be held down and charged like a trident before releasing, you adjust the draw duration properties rather than firing immediately.
When configuring charge-up throws, remember that do_swing_animation can look unnatural if it plays while the player begins holding right-click; it depends on how your custom animations are set up. The table below outlines the exact fields available across both components.
| Field | What it does | Notes |
|---|---|---|
| do_swing_animation | Plays the standard player arm swing when thrown. | Boolean inside minecraft:throwable. Defaults to false. |
| launch_power_scale | Multiplier applied to the base velocity of the spawned projectile. | Float inside minecraft:throwable. Defaults to 1.0. Negative values throw backwards. |
| max_draw_duration | Maximum time in seconds the player can hold the use button to charge. | Float inside minecraft:throwable. Set to 0.0 for instant throws. |
| min_draw_duration | Minimum time in seconds the player must hold before releasing will actually fire. | Float inside minecraft:throwable. If released early, the throw cancels. |
| scale_power_by_draw_duration | Scales the launch velocity based on how long the item was charged up to max_draw_duration. | Boolean inside minecraft:throwable. Defaults to false. |
| projectile_entity | The identifier of the entity to spawn when the throw executes. | String inside minecraft:projectile. Must match a valid entity with a projectile component. |
| minimum_critical_power | Draw duration threshold required for the projectile to deal critical damage. | Float inside minecraft:projectile. Used mainly with charged throws. |
Setting Up the Projectile Entity
The item JSON only handles the player interaction; the entity referenced in projectile_entity does the actual flying and hitting. If the target entity does not exist or lacks the entity-side minecraft:projectile component, the item will either do nothing when used or drop the entity straight at the player's feet with zero velocity.
Your projectile entity needs standard collision boxes, the minecraft:physics component so it moves through space, and the entity minecraft:projectile component to define gravity, base power, and what happens on impact. Here is the matching behavior pack entity for the pebble.
{
"format_version": "1.19.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:pebble_projectile",
"is_spawnable": false,
"is_summonable": true,
"is_experimental": false,
"runtime_identifier": "minecraft:snowball"
},
"components": {
"minecraft:collision_box": {
"width": 0.25,
"height": 0.25
},
"minecraft:physics": {},
"minecraft:projectile": {
"on_hit": {
"impact_damage": {
"damage": 3,
"knockback": true
},
"remove_on_hit": {}
},
"power": 1.3,
"gravity": 0.03,
"inertia": 0.99,
"liquid_inertia": 0.6
},
"minecraft:pushable": {
"is_pushable": false,
"is_pushable_by_piston": true
}
}
}
}Intercepting Throws with the Script API
In stable versions of the @minecraft/server Script API, you can pair JSON throwable mechanics with script events to run custom logic when a throw occurs or when the projectile lands. For instant throws, itemStartUseAfterEvent fires the moment the player presses use, while projectileHitEntityAfterEvent or projectileHitBlockAfterEvent lets you run code at the point of impact.
Note that for instant-throw items (where max_draw_duration is 0.0), itemReleaseUseAfterEvent will not fire because the item is consumed and thrown immediately upon pressing the input. You should only listen for release events if your item uses a non-zero min_draw_duration.
Which versions this applies to
Applies to Bedrock Edition 1.20.50 and newer using current item format versions (such as 1.20.80 or 1.21.0). Both minecraft:throwable and minecraft:projectile are stable item components and do not require any experimental toggles enabled in the world settings.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| The player swings their arm and the item count decreases, or nothing happens at all, and no projectile appears in the world. | You included minecraft:throwable on the item, but forgot to add the minecraft:projectile item component, or the identifier in projectile_entity has a typo and does not match any entity in your behavior pack. | Ensure both minecraft:throwable and minecraft:projectile are present inside the item's components block, and verify the entity identifier string matches your entity file's description.identifier exactly. |
| The projectile entity spawns inside the player and falls straight to the ground instead of flying forward. | The spawned entity is missing the entity-side minecraft:projectile component or minecraft:physics component in its BP/entities/ file. Without the projectile component on the entity itself, the item cannot transfer launch velocity to it. | Add both "minecraft:projectile" (with a valid "power" property) and "minecraft:physics" to the components list of your projectile entity JSON. |
| Holding right-click starts an eating or drinking animation, or the item refuses to throw unless held for a specific time. | You have set min_draw_duration and max_draw_duration to values greater than 0, or accidentally combined minecraft:use_modifiers with a long use_duration alongside an instant throw. | For an instant snowball-style throw, set both min_draw_duration and max_draw_duration to 0.0. If making a chargeable item, make sure min_draw_duration is lower than max_draw_duration. |
| Content Log shows: [Item][error] wiki:pebble | minecraft:item | components | minecraft:projectile : missing required field 'projectile_entity' | You copied the entity-side minecraft:projectile component structure into the item file by mistake, or left the component object empty. | Remember that the item component and entity component share the exact same name (minecraft:projectile) but take completely different fields. On an item, it only takes projectile_entity and minimum_critical_power. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.