How Components Are Applied
Every entity behavior file has two main places where components live: the base `components` object and the `component_groups` object. Components placed in the base `components` block are active the moment the entity spawns and remain active unless explicitly overridden by a group that contains the exact same component identifier.
Components placed inside `component_groups` are dormant until an event adds that group to the entity. This separation is how Bedrock handles state changes. For example, a passive mob might keep its movement and physics in the base `components` block, while keeping `minecraft:behavior.melee_attack` inside an angry component group that only activates when the mob takes damage.
Core Attributes and Physics
Before an entity can think or act, it needs a physical presence in the world. Attribute and physics components define the entity's bounding box, how fast it moves, how much damage it can absorb, and whether gravity pulls it down. Without these, your entity may fall through the floor, be impossible to hit, or fail to move even when AI goals are running.
A common point of confusion is the split between movement capability and movement speed. `minecraft:movement` only acts as the attribute storing the speed value. You must pair it with a movement mechanic component like `minecraft:movement.basic` and a pathfinding component like `minecraft:navigation.walk` for the entity to actually translate that speed value into footsteps.
| Component | What it does | Notes |
|---|---|---|
| minecraft:type_family | Assigns classification tags like 'monster' or 'mob'. | Used heavily by target selectors and filters to identify what kind of entity this is. |
| minecraft:collision_box | Sets the physical width and height of the entity. | Controls both the hitbox for attacks and physical block collisions. |
| minecraft:physics | Enables gravity and standard block collision. | Set `has_gravity` to false for floating entities if not using flying navigation. |
| minecraft:health | Sets current and maximum health points. | 1 heart equals 2 health points. A standard zombie has a max of 20. |
| minecraft:movement | Defines the base movement speed attribute. | A normal walking speed for a humanoid mob is usually between 0.2 and 0.35. |
| minecraft:attack | Defines base melee attack damage. | Required if the entity uses `minecraft:behavior.melee_attack`. |
Movement and Navigation
Navigation components calculate the path from point A to point B, while movement mechanic components control how the entity's body physically follows that path. You should only ever have one active navigation component and one active movement mechanic component at any given time. If you are making an amphibious mob that switches between walking on land and swimming in water, put the land components in one component group and the water components in another.
For standard land mobs, `minecraft:movement.basic` paired with `minecraft:navigation.walk` and `minecraft:jump.static` is the standard setup. The jump component is necessary even if your mob does not randomly hop around, because the pathfinder relies on it to step up full blocks.
{
"format_version": "1.20.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:custom_guard",
"is_spawnable": true,
"is_summonable": true
},
"components": {
"minecraft:type_family": {
"family": [ "guard", "mob" ]
},
"minecraft:collision_box": {
"width": 0.6,
"height": 1.9
},
"minecraft:health": {
"value": 30,
"max": 30
},
"minecraft:movement": {
"value": 0.28
},
"minecraft:movement.basic": {},
"minecraft:jump.static": {},
"minecraft:navigation.walk": {
"can_path_over_water": true,
"avoid_water": true,
"can_open_doors": true
},
"minecraft:physics": {},
"minecraft:pushable": {
"is_pushable": true,
"is_pushable_by_piston": true
}
}
}
}AI Behavior Goals
Components prefixed with `minecraft:behavior.` are AI goals. Unlike regular components that just set rules or stats, behavior components actively compete for control over the entity. This competition is managed by the `priority` field inside every behavior component.
In Bedrock, lower numbers mean higher priority. A behavior with `priority: 0` will override a behavior with `priority: 1`. Typically, emergency actions like `minecraft:behavior.float` (which keeps mobs from drowning) are given priority 0 or 1. Combat behaviors sit around 2 or 3, wandering sits around 6 or 7, and idle behaviors like looking at nearby players sit at the bottom around 8 or 9.
| Component | What it does | Notes |
|---|---|---|
| minecraft:behavior.float | Causes the entity to swim upwards when in water. | Without this, most land mobs will sink to the bottom of rivers and drown. |
| minecraft:behavior.Random_stroll | Makes the entity pick random nearby points and walk to them. | Spell the identifier in all lowercase: `minecraft:behavior.random_stroll`. |
| minecraft:behavior.look_at_player | Rotates the head to look at nearby players. | Purely cosmetic, usually given a very low priority (high number). |
| minecraft:behavior.melee_attack | Paths toward the current target and swings when in range. | Does nothing unless another behavior actually assigns a target to the entity. |
| minecraft:behavior.nearest_attackable_target | Scans for nearby entities matching a filter and sets them as the combat target. | Pairs with attack behaviors to create hostile mobs. |
| minecraft:behavior.hurt_by_target | Sets the combat target to whatever entity last damaged this mob. | Used for neutral mobs that only fight back when provoked. |
World and Player Interaction
Interaction components bridge the gap between a passive AI wandering the world and a mob the player can actually utilize. Components like `minecraft:interact` allow you to define custom right-click or tap interactions, such as feeding a mob an item to heal it, shearing it, or triggering a custom event.
Other specialized components handle classic vanilla mechanics. `minecraft:tameable` handles item-based taming probabilities, `minecraft:breedable` sets up love mode and offspring generation, and `minecraft:rideable` defines seat positions and allows players or other mobs to mount the entity. When using `minecraft:rideable`, remember that if you want the player to steer the mob using standard movement keys without holding a carrot on a stick, you also need to add `minecraft:input_ground_controlled`.
{
"format_version": "1.20.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:tameable_beast",
"is_spawnable": true,
"is_summonable": true
},
"component_groups": {
"wiki:tamed": {
"minecraft:is_tamed": {},
"minecraft:rideable": {
"seat_count": 1,
"family_types": [ "player" ],
"interact_text": "action.interact.ride.horse",
"seats": {
"position": [ 0.0, 1.1, -0.2 ]
}
},
"minecraft:input_ground_controlled": {}
}
},
"components": {
"minecraft:type_family": {
"family": [ "beast", "mob" ]
},
"minecraft:health": {
"value": 20,
"max": 20
},
"minecraft:movement": {
"value": 0.25
},
"minecraft:movement.basic": {},
"minecraft:jump.static": {},
"minecraft:navigation.walk": {},
"minecraft:physics": {},
"minecraft:tameable": {
"probability": 0.33,
"tame_items": "minecraft:beef",
"tame_event": {
"event": "minecraft:on_tame",
"target": "self"
}
},
"minecraft:behavior.random_stroll": {
"priority": 6,
"speed_multiplier": 1.0
},
"minecraft:behavior.look_at_player": {
"priority": 7,
"look_distance": 6.0
}
},
"events": {
"minecraft:on_tame": {
"add": {
"component_groups": [ "wiki:tamed" ]
}
}
}
}
}Marker and Tag Components
As you read through vanilla entity files, you will frequently see empty components like `minecraft:is_baby`, `minecraft:is_tamed`, `minecraft:is_saddled`, or `minecraft:is_sheared`. These do not add behavior on their own. Instead, they act as state flags that can be queried by Molang expressions on the client side or by entity filters on the server side.
For example, adding `minecraft:is_saddled` in a behavior pack component group does not automatically draw a saddle on the mob. What it actually does is turn the Molang query `query.is_saddled` from 0.0 to 1.0. Your resource pack render controller can then read `query.is_saddled` to make the saddle geometry bone visible. Using these built-in marker components is often cleaner than setting up custom entity properties when your custom mob mirrors a standard vanilla state.
Which versions this applies to
Applies to all modern Bedrock versions (1.16.0 through 1.21+). The core components listed here are completely stable and do not require any experimental toggles.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| The entity spawns and rotates its head to look at players, but never walks around despite having `minecraft:behavior.random_stroll`. | The entity is missing one of the three pillars required for walking: the speed attribute (`minecraft:movement`), the movement controller (`minecraft:movement.basic`), or the pathfinder (`minecraft:navigation.walk`). | Ensure all three components are present in your entity's active components list, and verify `minecraft:movement` has a `value` greater than 0.0. |
| A hostile mob walks directly up to the player and pushes them around, but never deals any damage. | `minecraft:behavior.melee_attack` is running, which handles the pathing and the swing timer, but the entity lacks the `minecraft:attack` attribute component to define how much damage the swing actually does. | Add `"minecraft:attack": { "damage": 4 }` (or your desired damage amount) alongside your melee attack behavior. |
| Content Log shows `[Entities][error]-wiki:custom_mob | minecraft:entity | components | child 'minecraft:behavior.melee_attack' is not valid here` or the mob simply ignores the component. | You accidentally placed a component directly inside `minecraft:entity` or inside `events`, rather than nesting it inside `components` or a named group under `component_groups`. | Check your JSON hierarchy and make sure every `minecraft:*` component key is a direct child of either `components` or a specific group inside `component_groups`. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.