The Four Pillars of Bedrock Movement
New add-on creators often drop a single movement component into their entity file and wonder why the mob remains frozen in place. Bedrock separates how fast an entity can go, how its body physically turns and steps, how it calculates a route around obstacles, and why it wants to move in the first place. If any of these four pieces is missing, the chain breaks and the entity will not walk.
First, you need the base speed attribute (`minecraft:movement`), which acts as a stat value that effects like Slowness or Speed can multiply. Second, you need a movement style component (such as `minecraft:movement.basic`) to handle body rotation and acceleration. Third, you need a navigation component (such as `minecraft:navigation.walk`) to generate paths across the terrain grid. Finally, you need at least one behavior component (like `minecraft:behavior.random_stroll`) to actually request a destination from the navigator.
{
"format_version": "1.20.80",
"minecraft:entity": {
"description": {
"identifier": "my_pack:walking_mob",
"is_spawnable": true,
"is_summonable": true
},
"components": {
"minecraft:physics": {},
"minecraft:collision_box": {
"width": 0.6,
"height": 1.8
},
"minecraft:movement": {
"value": 0.25
},
"minecraft:movement.basic": {},
"minecraft:navigation.walk": {
"can_path_over_water": true,
"avoid_water": true,
"avoid_damage_blocks": true
},
"minecraft:jump.static": {},
"minecraft:behavior.float": {
"priority": 0
},
"minecraft:behavior.random_stroll": {
"priority": 1,
"speed_multiplier": 1.0
}
}
}
}Setting Base Speed and Physics
The `minecraft:movement` component defines the raw movement speed of your entity. Standard humanoid mobs typically use values between `0.2` and `0.35`. A value of `0.25` is roughly a normal walking pace, while `0.4` and above is very fast. Note that AI goals apply their own `speed_multiplier` on top of this base value, so it is best to set `minecraft:movement` to your mob's normal walking speed and use the multipliers inside behaviors like `minecraft:behavior.panic` or `minecraft:behavior.melee_attack` to make them sprint when excited.
Alongside base speed, physical movement requires `minecraft:physics` so gravity and velocity apply, and `minecraft:collision_box` so the pathfinder knows how wide and tall the entity is when squeezing through doorways or under trees. For land mobs, you must also include `minecraft:jump.static`. Without a jump component, a walking mob cannot ascend a full one-block step, leaving it trapped in any shallow one-block pit it walks into.
Choosing a Movement Mechanic
The `minecraft:movement.*` family of components dictates the physical rules of how your entity translates pathfinding nodes into motion. You should only ever have one of these active on an entity at a time. If you are making an entity that switches between walking on land and swimming or flying, swap them out cleanly using component groups and entity events.
Most movement mechanics take a single optional parameter, `max_turn`, which defaults to `30.0` degrees per tick. Lowering `max_turn` to `5.0` or `10.0` gives large creatures, vehicles, or charging beasts a heavy, wide turning radius instead of letting them snap instantly toward their target.
| Component | What it does | Notes |
|---|---|---|
| minecraft:movement.basic | Standard ground movement with normal turning and stepping. | Used by most overworld walkers like zombies, pigs, and villagers. |
| minecraft:movement.amphibious | Allows seamless transitions between walking on land and moving underwater. | Pair with minecraft:underwater_movement to set water speed separately. |
| minecraft:movement.fly | Allows powered 3D movement through the air. | Requires a flying navigation component and flight-compatible AI goals. |
| minecraft:movement.glide | Simulates powerless gliding with forward pitch and descent rules. | Accepts start_speed and speed_when_turning to control the glide arc. |
| minecraft:movement.hover | Keeps the entity suspended in the air while moving between points. | Good for bees, drones, or floating magical constructs. |
| minecraft:movement.jump | Moves the entity exclusively through continuous hops rather than sliding steps. | Used by slimes and magma cubes; lets you customize jump_delay. |
| minecraft:movement.sway | Adds a side-to-side undulating motion while moving forward. | Designed for fish and aquatic creatures to look natural while swimming. |
Configuring Navigation and Pathfinding
While the movement mechanic moves the body, the `minecraft:navigation.*` component acts as the brain's GPS. When an AI goal picks a target block, the navigation component evaluates the blocks in between to build a valid route. Just like movement mechanics, an entity can only use one navigation component at a time.
For ground mobs, `minecraft:navigation.walk` is the standard choice. For flying mobs, use `minecraft:navigation.fly` or `minecraft:navigation.hover`. For fish or amphibians, `minecraft:navigation.generic` or `minecraft:navigation.swim` allows pathing through water volumes. Inside whichever navigation component you choose, you can pass boolean flags to teach the mob what terrain is safe and what is off-limits.
| Field | What it does | Notes |
|---|---|---|
| can_path_over_water | Allows the pathfinder to plot routes across the surface of water. | Combine with minecraft:behavior.float so the mob does not sink. |
| avoid_water | Penalizes water blocks when calculating a route. | The mob will walk around puddles and rivers if a dry path exists. |
| avoid_sun | Directs the pathfinder to prefer blocks shaded from the sky. | Essential for undead mobs or cave creatures during daytime. |
| avoid_damage_blocks | Prevents the mob from willingly walking over magma, cactus, or sweet berry bushes. | Default is false; almost always set this to true for smart mobs. |
| can_open_doors | Lets the pathfinder treat closed wooden doors as passable nodes. | Pair with a door interaction behavior if you want the door to visibly open. |
| can_pass_doors | Allows routing through open doorway spaces. | Usually set to true alongside can_open_doors for humanoid NPCs. |
| can_sink | Determines if the entity drops to the bottom of fluids. | Set to false for swimming or floating entities so paths stay near the surface. |
Aquatic and Flying Setups
When building an entity that swims or flies, simply swapping `minecraft:movement.basic` for `minecraft:movement.sway` or `minecraft:movement.fly` is not enough. Water drags down normal movement speed, so aquatic and amphibious entities need the `minecraft:underwater_movement` attribute component to define how fast they travel while submerged. They also need `minecraft:breathable` configured so they do not drown—or so they suffocate on dry land if they are strict fish.
Similarly, flying entities often fight against standard gravity. While `minecraft:movement.fly` and `minecraft:navigation.fly` handle airborne pathing, you must make sure your AI goals actually pick destinations in the air rather than only on solid ground. Using `minecraft:behavior.random_fly` or `minecraft:behavior.random_hover` instead of `minecraft:behavior.random_stroll` ensures the pathfinder looks for open air blocks above the terrain.
{
"format_version": "1.20.80",
"minecraft:entity": {
"description": {
"identifier": "my_pack:custom_fish",
"is_spawnable": true,
"is_summonable": true
},
"components": {
"minecraft:physics": {
"has_gravity": false
},
"minecraft:collision_box": {
"width": 0.5,
"height": 0.4
},
"minecraft:movement": {
"value": 0.1
},
"minecraft:underwater_movement": {
"value": 0.15
},
"minecraft:movement.sway": {
"sway_amplitude": 0.05
},
"minecraft:navigation.swim": {
"can_path_over_water": false,
"can_sink": false,
"can_walk_in_lava": false
},
"minecraft:behavior.random_swim": {
"priority": 1,
"speed_multiplier": 1.0,
"xz_dist": 16,
"y_dist": 4
}
}
}
}Which versions this applies to
Applies to all modern Bedrock versions (1.16.0 through 1.21+). All core movement, navigation, and basic AI stroll/swim/fly components are stable and do not require any experimental toggles.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| The entity spawns properly and plays its idle animation, but stands completely still and never walks around, with no errors in the Content Log. | One of the four required components is missing. Most commonly, creators remember `minecraft:movement` and `minecraft:navigation.walk`, but forget `minecraft:movement.basic` or forget to add an AI goal like `minecraft:behavior.random_stroll`. | Verify that your `components` block contains all four parts: `minecraft:movement`, a `minecraft:movement.*` mechanic, a `minecraft:navigation.*` pathfinder, and at least one movement-driving `minecraft:behavior.*`. |
| The entity walks on flat ground, but gets permanently stuck against single-block ledges or trapped in 1-block deep holes. | The entity has no jump mechanic, so even though the pathfinder plots a route up a 1-block step, the body cannot execute the vertical hop. | Add `"minecraft:jump.static": {}` to the entity's components so it can jump up standard single-block terrain steps. |
| An amphibious or swimming mob moves fine on land, but slows to a crawl or stops moving entirely the moment it enters water. | Standard `minecraft:movement` only controls land speed. Underwater speed defaults to near-zero unless explicitly defined, or the entity is sinking to the bottom without an underwater pathfinder. | Add the `minecraft:underwater_movement` component with a positive `value` (such as `0.15`), and ensure your navigation component allows underwater routing or add `minecraft:behavior.float` if the mob is supposed to swim on the surface. |
| Content Log shows `[Entities][error]-my_pack:walking_mob | failed to parse entity` or complains about duplicate movement/navigation components. | Two movement mechanics (such as `minecraft:movement.basic` and `minecraft:movement.fly`) or two navigation components are active at the same time, or a JSON syntax comma is missing between components. | Keep only one `minecraft:movement.*` and one `minecraft:navigation.*` in the base `components` list. If your mob changes movement styles dynamically, place the alternate pair inside separate `component_groups` and swap them via events. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.