godot-2d-movement
Implement 2D kinematic character movement in Godot 4.7 with CharacterBody2D and move_and_slide(): platformer run/jump with gravity, top-down 8-direction motion, slope handling, and reading collisions. Use when coding a 2D player or enemy controller, a platformer or top-down chara
Install
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/godot/godot-2d-movement
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
git clone https://github.com/gamedev-skills/awesome-gamedev-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gamedev-skills/awesome-gamedev-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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, oris_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
CharacterBody2Dwith aCollisionShape2Dchild. It is script-driven: it does not fall or react to forces on its own. - Set the
velocityproperty, then callmove_and_slide()(no arguments in 4.x). The method readsvelocity, moves the body, slides along surfaces, and updatesvelocityto reflect what actually happened. - Do it in
_physics_process(delta)—move_and_slide()uses the physics step's delta internally, so do not multiplyvelocitybydeltayourself. - Platformer: add gravity to
velocity.yeach tick, jump by settingvelocity.ynegative whenis_on_floor(). - Top-down: build a direction from input and scale by speed; set
motion_mode = MOTION_MODE_FLOATINGso there is no "floor/wall" distinction. - Read results with
is_on_floor(),is_on_wall(),get_wall_normal(), andget_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 thevelocityproperty and callmove_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. Settingvelocity = dir * speed * deltamakes the body crawl. - Movement in
_processinstead of_physics_processcauses frame-rate-dependent, jittery motion. Always move in_physics_process. is_on_floor()always false whenup_directionis wrong (defaultVector2.UP), there is noCollisionShape2D, or you never calledmove_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 raisefloor_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), readreferences/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.
Files (awesome-gamedev-agent-skills)
-
references
-
controller-recipes.md 3.4 KB
Loading…
-
-
SKILL.md 6.1 KB
--- name: godot-2d-movement description: > Implement 2D kinematic character movement in Godot 4.7 with CharacterBody2D and move_and_slide(): platformer run/jump with gravity, top-down 8-direction motion, slope handling, and reading collisions. Use when coding a 2D player or enemy controller, a platformer or top-down character, or fixing move_and_slide()/ is_on_floor() behavior in a .tscn with a CharacterBody2D. --- # 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 1. **Use `CharacterBody2D`** with a `CollisionShape2D` child. It is script-driven: it does not fall or react to forces on its own. 2. **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. 3. **Do it in `_physics_process(delta)`** — `move_and_slide()` uses the physics step's delta internally, so do not multiply `velocity` by `delta` yourself. 4. **Platformer:** add gravity to `velocity.y` each tick, jump by setting `velocity.y` negative when `is_on_floor()`. 5. **Top-down:** build a direction from input and scale by speed; set `motion_mode = MOTION_MODE_FLOATING` so there is no "floor/wall" distinction. 6. **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) ```gdscript 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 ```gdscript 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 ```gdscript 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) ```gdscript @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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.