gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-2d-movement
godot-2d-movement
VerifiedGodot 4.7 CharacterBody2D movement in GDScript: platformer run and jump, top-down 8-direction motion, slopes and one-way platforms, with a headless landing test. Use when a 2D controller will not move, falls through the floor or is_on_floor() is always false. Not for coyote time and jump feel (`platformer`), RigidBody2D, raycasts or 3D (`godot-physics`) or tile levels (`godot-tilemap`).
Godot 2D Movement (4.x)
Write CharacterBody2D controllers that land, run, jump and slide the way the engine expects,
then prove it with a headless test. Targets Godot 4.7; check config/features in
project.godot and keep an older project on its own version.
Workflow
- Read the scene first. Open the player
.tscn: the root should be aCharacterBody2Dwith aCollisionShape2D/CollisionPolygon2Dchild, and the action names the script uses must exist under[input]inproject.godot. - Pick the motion mode. Platformers keep the default
MOTION_MODE_GROUNDED; top-down games setMOTION_MODE_FLOATING, which has no floor, wall or ceiling. - Set
velocity, then callmove_and_slide()once per_physics_process(). It takes no arguments, applies the physics delta itself, and writes back the velocity after collisions. - Read results after the call:
is_on_floor(),is_on_wall(),get_wall_normal(),get_slide_collision(i). They describe the lastmove_and_slide(), not the current frame. - Hand off feel. Coyote time, jump buffering, variable jump height and apex tuning belong
to
platformer; this skill supplies the Godot hooks they read (is_on_floor(),velocity). - Verify before you finish (paths are relative to this skill's folder):
- If
godot-nodes-scenesis installed, runpython3 ../godot-nodes-scenes/scripts/check_godot_project.py <project>after adding or moving scenes and scripts; fix everyERROR. - Copy
assets/test_character_controller.gdtores://tests/, set the action names at the top to the project's, and rungodot --headless --path <project> --script res://tests/test_character_controller.gd -- res://player.tscn. Exit 0 means the body landed, jumped and ran (or, floating, moved on both axes without drifting); eachFAILline names the behaviour that broke. On a fresh checkout rungodot --headless --path <project> --importfirst. To keep it in CI, usegodot-gdscript-headless-testing. - If the user wants feel signed off, ask them to play and report jump height and how fast the character stops; the test only proves the mechanics.
- If
Patterns
1. Platformer controller
extends CharacterBody2D
@export var speed := 200.0
@export var jump_velocity := -400.0
func _physics_process(delta: float) -> void:
if not is_on_floor():
velocity += get_gravity() * delta # project gravity plus any Area2D override
if Input.is_action_just_pressed("jump") and is_on_floor():
velocity.y = jump_velocity
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) # stops within one tick
move_and_slide()
For a tunable fall speed that ignores the project setting, replace get_gravity() with an
exported Vector2(0, gravity). For weight, ramp with move_toward(velocity.x, dir * speed, accel * delta); the reference has the full version.
2. Top-down 8-direction movement
extends CharacterBody2D
@export var speed := 220.0
func _ready() -> void:
motion_mode = CharacterBody2D.MOTION_MODE_FLOATING
func _physics_process(_delta: float) -> void:
# get_vector applies the action deadzones and caps the length at 1.
velocity = Input.get_vector("move_left", "move_right", "move_up", "move_down") * speed
move_and_slide()
3. React to what the body touched
func _physics_process(delta: float) -> void:
# ... set velocity ...
move_and_slide()
for i in get_slide_collision_count():
var other := get_slide_collision(i).get_collider()
if other and other.is_in_group("enemies"):
take_damage(1)
Gotchas
- The character crawls →
velocitywas multiplied bydelta.move_and_slide()already scales by the physics step; onlymove_and_collide()takes a per-frame motion. is_on_floor()is always false → the body is inMOTION_MODE_FLOATING,up_directionis notVector2.UP, there is no collision shape, the floor's layer is not in this body's mask, ormove_and_slide()has not run yet this tick (it reports the last call).- It falls through the floor or teleports → code moves it with
position +=orglobal_position =, which skips collision. Move throughvelocityonly; teleport only for respawns. - Motion jitters or depends on frame rate → movement runs in
_process(). Use_physics_process(); for smooth visuals at high refresh rates turn onphysics/common/physics_interpolationrather than moving the body in_process(). - Sliding down slopes while idle → keep
floor_stop_on_slopeon (default) and raisefloor_snap_length(default 1 px) so the body sticks when walking downhill. Slopes steeper thanfloor_max_angle(default 45°) count as walls. - 3.x code will not parse →
move_and_slide(velocity, Vector2.UP)is gone; setvelocityandup_directionas properties and callmove_and_slide()with no arguments. The InputMap action "jump" doesn't existin the log, and the character ignores input → the action is missing fromproject.godot. The bundled test adds blank actions it cannot find and prints anote:line, so it can pass while the game fails; read the notes and fix the Input Map.
References
- Read
references/controller-recipes.mdfor one-way platforms (including the 4.7one_way_collision_direction), moving platforms,move_and_collide()bounces, acceleration ramps and the mainCharacterBody2Dproperties. assets/test_character_controller.gdis the headless behaviour test used in step 6.
Related skills
platformer: coyote time, jump buffering, variable jump and jump feel on top of Pattern 1.godot-physics: collision layers and masks, areas, raycasts, rigid bodies, 3D characters.physics-tuning: engine-neutral tunnelling and jitter diagnosis.godot-animation: driving sprites and state machines fromvelocityand floor state.camera-systems: a follow camera for this character.godot-gdscript-headless-testing: running the controller test in CI.
Version notes
Last verified: 2026-11-11 against the Godot 4.7.2 class reference and a 4.7.2 headless run.
- Godot 4.7.2 (August 2026) is the current stable release; 4.8 is in beta.
CollisionShape2D/CollisionPolygon2D.one_way_collision_directionis new in 4.7 (defaultVector2(0, 1)); earlier versions always block from the shape's local up side.get_gravity()on physics bodies exists since 4.3.- Sources: Godot releases, CharacterBody2D, Using CharacterBody2D.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |