Custom Projectile Entities

Every projectile is an entity at heart, meaning it starts with a standard entity file in your behavior pack. Unlike living mobs, a projectile does not need navigation, health, or AI goals. Instead, its movement and collision logic are driven almost entirely by three components: `minecraft:projectile`, `minecraft:physics`, and `minecraft:collision_box`.

The `minecraft:collision_box` on a projectile should always be kept small, typically around 0.25 blocks wide and high. If the collision box is too large, the projectile will immediately collide with the player or mob that fired it, or clip the edges of blocks when aiming around corners. You also set `is_spawnable` and `is_summonable` in the description; usually you want `is_summonable` set to true so commands and items can spawn it, and `is_spawnable` set to false so it does not generate a spawn egg in the creative menu.

{
  "format_version": "1.16.0",
  "minecraft:entity": {
    "description": {
      "identifier": "my_pack:magic_bolt",
      "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:pushable": {
        "is_pushable": false,
        "is_pushable_by_piston": true
      },
      "minecraft:projectile": {
        "on_hit": {
          "impact_damage": {
            "damage": 6,
            "knockback": true,
            "semi_random_diff_damage": false,
            "destroy_on_hit": true
          },
          "remove_on_hit": {}
        },
        "power": 1.5,
        "gravity": 0.03,
        "inertia": 0.99,
        "liquid_inertia": 0.6,
        "uncertainty_base": 1.0,
        "uncertainty_multiplier": 0.0,
        "anchor": 1,
        "offset": [0, -0.1, 0],
        "reflect_on_hit": false,
        "catch_fire": false
      }
    }
  }
}

The feel of a ranged weapon comes down to the numeric properties inside `minecraft:projectile`. By balancing velocity (`power`), drop rate (`gravity`), and air drag (`inertia`), you can simulate anything from a heavy, slow-moving boulder to a fast, completely straight laser beam.

When a projectile spawns, it inherits a base position from the shooter. The `anchor` and `offset` properties adjust this starting point so the projectile appears to leave from the shooter's hand or eyes rather than their feet. Getting these numbers right prevents the projectile from hitting the ground immediately when firing down a slope.

Everything a projectile does when it touches a block or entity is governed by the `on_hit` object inside `minecraft:projectile`. You can stack multiple sub-objects inside `on_hit` to combine effects—for example, dealing damage, applying a status effect, and spawning a particle cloud all at the same time.

If you include `remove_on_hit`, the projectile entity despawns the instant it strikes something, which is standard for snowballs and fireballs. If you omit `remove_on_hit` and instead use `stick_in_ground`, the projectile remains in the world like an arrow. Be careful when omitting `remove_on_hit` without a despawn timer: hundreds of stuck projectiles will quickly cause world lag.

For complex behaviors that the built-in impact responses cannot cover, use `definition_event`. This triggers a custom entity event on the projectile itself at the moment of impact. Inside that event, you can add an instant `minecraft:explode` component, run commands, or transform the projectile into a different entity.

{
  "format_version": "1.16.0",
  "minecraft:entity": {
    "description": {
      "identifier": "my_pack:explosive_arrow",
      "is_spawnable": false,
      "is_summonable": true
    },
    "component_groups": {
      "my_pack:exploding": {
        "minecraft:explode": {
          "fuse_length": 0.0,
          "fuse_lit": true,
          "power": 2.0,
          "causes_fire": false,
          "breaks_blocks": false
        }
      }
    },
    "components": {
      "minecraft:collision_box": {
        "width": 0.25,
        "height": 0.25
      },
      "minecraft:physics": {},
      "minecraft:projectile": {
        "on_hit": {
          "impact_damage": {
            "damage": 4,
            "knockback": true
          },
          "definition_event": {
            "affect_projectile": true,
            "event_trigger": {
              "event": "my_pack:trigger_explosion",
              "target": "self"
            }
          }
        },
        "power": 1.8,
        "gravity": 0.05
      }
    },
    "events": {
      "my_pack:trigger_explosion": {
        "add": {
          "component_groups": [
            "my_pack:exploding"
          ]
        }
      }
    }
  }
}

A projectile entity does nothing on its own until something launches it. In Bedrock, there are two main ways to launch your custom projectile: from a player-held custom item, or from a mob using a ranged attack AI goal.

To let players throw or shoot the entity from an item, give your custom item the `minecraft:shooter` or `minecraft:throwable` paired with `minecraft:projectile` item components. The item's `minecraft:projectile` component simply points to your entity identifier and defines the minimum critical power. When the player uses the item, the game spawns your projectile entity and applies the velocity defined in the entity's behavior file.

For mobs, you combine the `minecraft:behavior.ranged_attack` AI goal with the `minecraft:shooter` entity component. The `minecraft:shooter` component tells the mob which projectile entity identifier to spawn when the ranged attack goal triggers.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:magic_wand",
      "menu_category": {
        "category": "equipment"
      }
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "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": "my_pack:magic_bolt"
      }
    }
  }
}

Making a projectile face the direction it is flying can be tricky. Normal entities rotate based on their AI movement, which projectiles do not have. If you create a 3D arrow or missile model, it will fly sideways unless you animate its rotation based on its flight trajectory or use a specific runtime identifier.

For simple flat items like snowballs, shurikens, or magic orbs, the easiest approach is adding `"runtime_identifier": "minecraft:snowball"` to your behavior pack description, and using a billboard (camera-facing) geometry in your resource pack. The snowball runtime tells the engine to render the entity using the simple thrown-item pipeline and generates the standard snowball break particles on impact.

For 3D directional projectiles like arrows or spears, you must include an animation in your resource pack's client entity file that rotates the root bone using Molang queries, or use `"runtime_identifier": "minecraft:arrow"` which applies vanilla arrow hardcoding for flight pitch and yaw.

Applies to Bedrock Edition 1.16.0 and newer for entity definitions, and 1.20.50+ for the modern item component syntax. No experimental toggles are required for standard projectile entities or throwable items.

Read out of the game itself, so the ids match the version you are building for.