Godot 2D Movement (4.x)
Build responsive 2D character controllers with CharacterBody2D and the argument-less
move_and_slide(). Targets Godot 4.7.
When to use
- Use when scripting a 2D player/enemy that moves and collides: platformer (gravity +
jump) or top-down (free 8-direction), slope walking, or wall/floor detection.
- Use when
move_and_slide() "does nothing", the character sinks through floors, or
is_on_floor() is always false.
When not to use: dynamic rigid bodies, areas, raycasts, collision layers →
godot-physics; tile-based levels → godot-tilemap; full platformer game template →
the platformer genre skill; engine-agnostic feel tuning → physics-tuning.
Core workflow
- Use
CharacterBody2D with a CollisionShape2D child. It is script-driven: it
does not fall or react to forces on its own.
- Set the
velocity property, then call move_and_slide() (no arguments in 4.x).
The method reads velocity, moves the body, slides along surfaces, and updates
velocity to reflect what actually happened.
- Do it in
_physics_process(delta) — move_and_slide() uses the physics step's
delta internally, so do not multiply velocity by delta yourself.
- Platformer: add gravity to
velocity.y each tick, jump by setting velocity.y
negative when is_on_floor().
- Top-down: build a direction from input and scale by speed; set
motion_mode = MOTION_MODE_FLOATING so there is no "floor/wall" distinction.
- Read results with
is_on_floor(), is_on_wall(), get_wall_normal(), and
get_slide_collision(i) after the call.
Patterns
1. Platformer controller (gravity, jump, slopes)
extends CharacterBody2D
@export var speed := 200.0
@export var jump_velocity := -400.0
@export var gravity := 1200.0 # pixels/sec^2 (tune to taste)
func _physics_process(delta: float) -> void:
# Apply gravity while airborne.
if not is_on_floor():
velocity.y += gravity * delta
# Jump only when grounded (Input action set in Project Settings > Input Map).
if Input.is_action_just_pressed("jump") and is_on_floor():
velocity.y = jump_velocity
# Horizontal input: -1, 0, or 1.
var dir := Input.get_axis("move_left", "move_right")
if dir != 0.0:
velocity.x = dir * speed
else:
velocity.x = move_toward(velocity.x, 0.0, speed) # decelerate to a stop
move_and_slide() # 4.x: no arguments; uses and updates `velocity`
A fixed gravity export keeps tuning simple. To follow the project setting
(Physics > 2D > Default Gravity) and any Area2D gravity overrides instead, use
velocity += get_gravity() * delta, as the built-in CharacterBody2D script template does.
2. Top-down 8-direction movement
extends CharacterBody2D
@export var speed := 220.0
func _ready() -> void:
motion_mode = CharacterBody2D.MOTION_MODE_FLOATING # no floor/ceiling concept
func _physics_process(_delta: float) -> void:
# get_vector returns a normalized-ish Vector2 from four input actions.
var input := Input.get_vector("move_left", "move_right", "move_up", "move_down")
velocity = input * speed
move_and_slide()
3. Reading slide collisions after moving
func _physics_process(delta: float) -> void:
# ... set velocity ...
move_and_slide()
for i in get_slide_collision_count():
var c := get_slide_collision(i)
var other := c.get_collider()
if other and other.is_in_group("enemies"):
take_damage(1) # touched an enemy while moving
4. Coyote time (forgiving jump just after leaving a ledge)
@export var coyote_time := 0.1
var _coyote := 0.0
func _physics_process(delta: float) -> void:
if not is_on_floor():
velocity.y += gravity * delta
_coyote -= delta
else:
_coyote = coyote_time
if Input.is_action_just_pressed("jump") and _coyote > 0.0:
velocity.y = jump_velocity
_coyote = 0.0
# ... horizontal input + move_and_slide() ...
Pitfalls
- 3.x signature is gone.
move_and_slide(velocity) (returning the new velocity) was
removed. In 4.x set the velocity property and call move_and_slide() with no args.
move_and_slide(velocity, Vector2.UP) will not parse.
- Multiplying velocity by delta.
move_and_slide() already accounts for the physics
delta. Setting velocity = dir * speed * delta makes the body crawl.
- Movement in
_process instead of _physics_process causes frame-rate-dependent,
jittery motion. Always move in _physics_process.
is_on_floor() always false when up_direction is wrong (default Vector2.UP),
there is no CollisionShape2D, or you never called move_and_slide() this frame.
- Sinking through floors usually means the collision shape is missing/zero-sized, the
floor body is on a layer this body's mask doesn't include, or you moved the body via
position += instead of velocity + move_and_slide().
- Slope slipping while idle: keep
floor_stop_on_slope = true (default) and raise
floor_snap_length (default 1 px) so the body sticks to downward slopes.
References
- For one-way platforms, moving platforms, jump buffering, variable jump height, and
move_and_collide() (manual collision response), read references/controller-recipes.md.
Related skills
godot-physics — collision layers/masks, areas, raycasts, rigid bodies.
godot-tilemap — building the levels this character walks on.
godot-animation — driving sprite/skeletal animation from movement state.
camera-systems — follow camera, deadzone, and look-ahead that track this character.
platformer / input-systems — full genre template and rebindable input.
1---2name: godot-2d-movement3description: >4 Implement 2D kinematic character movement in Godot 4.7 with CharacterBody2D and5 move_and_slide(): platformer run/jump with gravity, top-down 8-direction motion,6 slope handling, and reading collisions. Use when coding a 2D player or enemy7 controller, a platformer or top-down character, or fixing move_and_slide()/8 is_on_floor() behavior in a .tscn with a CharacterBody2D.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-2d-movement11---1213# Godot 2D Movement (4.x)1415Build responsive 2D character controllers with `CharacterBody2D` and the argument-less16`move_and_slide()`. Targets **Godot 4.7**.1718## When to use1920- Use when scripting a 2D player/enemy that moves and collides: platformer (gravity +21 jump) or top-down (free 8-direction), slope walking, or wall/floor detection.22- Use when `move_and_slide()` "does nothing", the character sinks through floors, or23 `is_on_floor()` is always false.2425**When *not* to use:** dynamic rigid bodies, areas, raycasts, collision layers →26`godot-physics`; tile-based levels → `godot-tilemap`; full platformer game template →27the `platformer` genre skill; engine-agnostic feel tuning → `physics-tuning`.2829## Core workflow30311. **Use `CharacterBody2D`** with a `CollisionShape2D` child. It is script-driven: it32 does not fall or react to forces on its own.332. **Set the `velocity` property, then call `move_and_slide()`** (no arguments in 4.x).34 The method reads `velocity`, moves the body, slides along surfaces, and updates35 `velocity` to reflect what actually happened.363. **Do it in `_physics_process(delta)`** — `move_and_slide()` uses the physics step's37 delta internally, so do not multiply `velocity` by `delta` yourself.384. **Platformer:** add gravity to `velocity.y` each tick, jump by setting `velocity.y`39 negative when `is_on_floor()`.405. **Top-down:** build a direction from input and scale by speed; set41 `motion_mode = MOTION_MODE_FLOATING` so there is no "floor/wall" distinction.426. **Read results** with `is_on_floor()`, `is_on_wall()`, `get_wall_normal()`, and43 `get_slide_collision(i)` after the call.4445## Patterns4647### 1. Platformer controller (gravity, jump, slopes)4849```gdscript50extends CharacterBody2D5152@export var speed := 200.053@export var jump_velocity := -400.054@export var gravity := 1200.0 # pixels/sec^2 (tune to taste)5556func _physics_process(delta: float) -> void:57 # Apply gravity while airborne.58 if not is_on_floor():59 velocity.y += gravity * delta6061 # Jump only when grounded (Input action set in Project Settings > Input Map).62 if Input.is_action_just_pressed("jump") and is_on_floor():63 velocity.y = jump_velocity6465 # Horizontal input: -1, 0, or 1.66 var dir := Input.get_axis("move_left", "move_right")67 if dir != 0.0:68 velocity.x = dir * speed69 else:70 velocity.x = move_toward(velocity.x, 0.0, speed) # decelerate to a stop7172 move_and_slide() # 4.x: no arguments; uses and updates `velocity`73```7475A fixed `gravity` export keeps tuning simple. To follow the project setting76(*Physics > 2D > Default Gravity*) and any `Area2D` gravity overrides instead, use77`velocity += get_gravity() * delta`, as the built-in CharacterBody2D script template does.7879### 2. Top-down 8-direction movement8081```gdscript82extends CharacterBody2D8384@export var speed := 220.08586func _ready() -> void:87 motion_mode = CharacterBody2D.MOTION_MODE_FLOATING # no floor/ceiling concept8889func _physics_process(_delta: float) -> void:90 # get_vector returns a normalized-ish Vector2 from four input actions.91 var input := Input.get_vector("move_left", "move_right", "move_up", "move_down")92 velocity = input * speed93 move_and_slide()94```9596### 3. Reading slide collisions after moving9798```gdscript99func _physics_process(delta: float) -> void:100 # ... set velocity ...101 move_and_slide()102 for i in get_slide_collision_count():103 var c := get_slide_collision(i)104 var other := c.get_collider()105 if other and other.is_in_group("enemies"):106 take_damage(1) # touched an enemy while moving107```108109### 4. Coyote time (forgiving jump just after leaving a ledge)110111```gdscript112@export var coyote_time := 0.1113var _coyote := 0.0114115func _physics_process(delta: float) -> void:116 if not is_on_floor():117 velocity.y += gravity * delta118 _coyote -= delta119 else:120 _coyote = coyote_time121122 if Input.is_action_just_pressed("jump") and _coyote > 0.0:123 velocity.y = jump_velocity124 _coyote = 0.0125 # ... horizontal input + move_and_slide() ...126```127128## Pitfalls129130- **3.x signature is gone.** `move_and_slide(velocity)` (returning the new velocity) was131 removed. In 4.x set the `velocity` property and call `move_and_slide()` with no args.132 `move_and_slide(velocity, Vector2.UP)` will not parse.133- **Multiplying velocity by delta.** `move_and_slide()` already accounts for the physics134 delta. Setting `velocity = dir * speed * delta` makes the body crawl.135- **Movement in `_process`** instead of `_physics_process` causes frame-rate-dependent,136 jittery motion. Always move in `_physics_process`.137- **`is_on_floor()` always false** when `up_direction` is wrong (default `Vector2.UP`),138 there is no `CollisionShape2D`, or you never called `move_and_slide()` this frame.139- **Sinking through floors** usually means the collision shape is missing/zero-sized, the140 floor body is on a layer this body's mask doesn't include, or you moved the body via141 `position +=` instead of velocity + `move_and_slide()`.142- **Slope slipping while idle:** keep `floor_stop_on_slope = true` (default) and raise143 `floor_snap_length` (default 1 px) so the body sticks to downward slopes.144145## References146147- For one-way platforms, moving platforms, jump buffering, variable jump height, and148 `move_and_collide()` (manual collision response), read `references/controller-recipes.md`.149150## Related skills151152- `godot-physics` — collision layers/masks, areas, raycasts, rigid bodies.153- `godot-tilemap` — building the levels this character walks on.154- `godot-animation` — driving sprite/skeletal animation from movement state.155- `camera-systems` — follow camera, deadzone, and look-ahead that track this character.156- `platformer` / `input-systems` — full genre template and rebindable input.