This skill teaches an agent to write CharacterBody2D controllers the way Godot expects: set velocity, call move_and_slide() once per physics tick, then read floor and wall state after the call. It covers platformer run and jump, top-down 8-direction motion in floating mode, slopes, one-way platforms and collision reactions.
A bundled GDScript test runs the controller scene headless and fails with a line per broken behaviour, such as a body that never lands or drifts. The gotchas section explains why is_on_floor() stays false, why a body falls through the floor and why 3.x movement code no longer parses.
What You Get
- A step-by-step workflow from reading the player scene to verifying behaviour
- Typed GDScript patterns for a platformer controller, top-down movement and reacting to slide collisions
- A headless test script that checks landing, jumping and running, or two-axis floating motion
- A gotcha list for crawling characters, floor detection, fall-through, jitter and slope sliding
Common Use Cases
- Building a first platformer or top-down player in Godot 4
- Debugging a controller where is_on_floor() is always false
- Fixing a character that falls through the floor or teleports through walls
- Porting Godot 3 movement code to the 4.x move_and_slide() API
What Makes It Unique
Most movement snippets stop at the controller code. This skill ships a headless behaviour test and tells the agent to run it, so each behaviour gets a pass or fail result. It also names the engine-version facts that trip people up, such as the 4.7 one-way collision direction and the argument-free move_and_slide().
Under The Hood
The agent loads the SKILL.md and, when needed, a reference of controller recipes. It then runs commands in your project: it copies a GDScript test into a tests folder, edits the action names, and starts the Godot binary headless on the player scene, plus an optional Python project checker from the godot-nodes-scenes skill. It may run an asset import first on a fresh checkout. It reads scene and project files and writes the test file; it makes no network calls. The shipped GDScript test is a file type the scanner cannot read, so what it does was not analysed and is worth a look before you run it.