Index of every page on this site: llms.txt
All skills
gamedev-skills avatar

/godot-2d-movement

@c6ca6c4
Run it yourself

Godot 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`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/godot-2d-movement

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈102 tokens for metadata: the name and description. ≈1.7k when used: this file. ≈787 more on demand in 1 file.

Description uses 5.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈409 characters, or 5.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Read the scene first. Open the player .tscn: the root should be a CharacterBody2D with a CollisionShape2D/CollisionPolygon2D child, and the action names the script uses must exist under [input] in project.godot.
  2. Pick the motion mode. Platformers keep the default MOTION_MODE_GROUNDED; top-down games set MOTION_MODE_FLOATING, which has no floor, wall or ceiling.
  3. Set velocity, then call move_and_slide() once per _physics_process(). It takes no arguments, applies the physics delta itself, and writes back the velocity after collisions.
  4. Read results after the call: is_on_floor(), is_on_wall(), get_wall_normal(), get_slide_collision(i). They describe the last move_and_slide(), not the current frame.
  5. 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).
  6. Verify before you finish (paths are relative to this skill's folder):
    • If godot-nodes-scenes is installed, run python3 ../godot-nodes-scenes/scripts/check_godot_project.py <project> after adding or moving scenes and scripts; fix every ERROR.
    • Copy assets/test_character_controller.gd to res://tests/, set the action names at the top to the project's, and run godot --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); each FAIL line names the behaviour that broke. On a fresh checkout run godot --headless --path <project> --import first. To keep it in CI, use godot-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.

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 → velocity was multiplied by delta. move_and_slide() already scales by the physics step; only move_and_collide() takes a per-frame motion.
  • is_on_floor() is always false → the body is in MOTION_MODE_FLOATING, up_direction is not Vector2.UP, there is no collision shape, the floor's layer is not in this body's mask, or move_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 += or global_position =, which skips collision. Move through velocity only; 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 on physics/common/physics_interpolation rather than moving the body in _process().
  • Sliding down slopes while idle → keep floor_stop_on_slope on (default) and raise floor_snap_length (default 1 px) so the body sticks when walking downhill. Slopes steeper than floor_max_angle (default 45°) count as walls.
  • 3.x code will not parse → move_and_slide(velocity, Vector2.UP) is gone; set velocity and up_direction as properties and call move_and_slide() with no arguments.
  • The InputMap action "jump" doesn't exist in the log, and the character ignores input → the action is missing from project.godot. The bundled test adds blank actions it cannot find and prints a note: line, so it can pass while the game fails; read the notes and fix the Input Map.

References

  • Read references/controller-recipes.md for one-way platforms (including the 4.7 one_way_collision_direction), moving platforms, move_and_collide() bounces, acceleration ramps and the main CharacterBody2D properties.
  • assets/test_character_controller.gd is 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 from velocity and 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_direction is new in 4.7 (default Vector2(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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The skill provides templates and headless testing procedures for Godot 4.7 character movement. It uses standard development tools and engine commands as expected for game development tasks.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/godot-2d-movement