Skip to main content
character-movement is a skill from the Summer skill library: a guide your AI agent reads when the task matches, so it builds the good version on the first try. Player controllers for 2D and 3D, plus the standard third-person controller for Summer humanoids.

​
When your agent uses it

  • Building or fixing player movement — gravity, collision, side-scroller, top-down, or 3D walk
  • Wiring an imported Summer character package (character.tscn) as the playable third-person player
  • Walk, run, and jump animation states, facing, or mouse look for a player controller
  • The jump feels bad — coyote time, jump buffering, variable jump height, one-way platforms

​
Install

summer setup installs every skill for your agent. To add only this one:
Swap claude-code for your agent, such as codex or cursor. See Skills for every option.

​
The skill

The player controller is the first thing you build and the thing the user feels in the first 3 seconds. Ship the smallest correct controller, then tune feel. Trigger phrases: “add player movement”, “the player can’t move / falls through the floor”, “wire my imported character as the player”, “walk/run/jump animations”, “mouse look”, “make the jump feel better”. Supporting files live in this skill’s references/ folder, next to this SKILL.md. Open only the one the task needs:

​
Default playable Summer character

For a standard playable third-person Summer humanoid package, install this skill’s references/default-third-person-controller.gd unchanged as the player script. Do not rewrite or reconstruct it from the snippets below. Customize the installed file only when the user explicitly asks for different controls or behavior. Install it byte-exact:
  1. Take the full text of references/default-third-person-controller.gd from this skill’s folder, unchanged (tabs, comments and all).
  2. New destination: summer_write_file(path="res://scripts/player.gd", content=<that text>, create_only=true). Existing destination: summer_read_file(path="res://scripts/player.gd") first, then summer_write_file(path=..., content=<that text>, expected_sha256=<sha256 from the read>).
  3. Confirm the copy is exact: the write receipt’s sha256 must equal the sha256 of the source file (hash it locally when you have a shell; otherwise summer_read_file the result and compare it to the source text).
Do not edit the installed file, add roles, or add an AnimationTree merely because the user selected more package clips: choosing clips is not a request to customize controls or behavior. When the user does explicitly request different controls or behavior, install the exact canonical source first, then summer_read_file the installed project file and change it with summer_replace_text. Configure the manifest path and node paths on the scene instance. Required main-scene shape:
When authoring a new main scene as .tscn text (written whole with summer_write_file, never a hand edit of a scene open in the editor), use this exact serialization pattern. Replace only the imported package paths when they differ:
Every nested parent is the complete path from the scene root, excluding the root node’s own name. Never shorten parent="Player/CameraYaw/CameraPitch" to parent="CameraPitch". A PackedScene instance belongs in the [node ...] header and has no type; never write a typed Node3D followed by instance = ExtResource(...) in the node body. The playable body is a child of the world root. Ground, level geometry, lights, and environment remain siblings of Player, never children of it, so they do not move with the player. Set character_manifest_path to the imported package’s character.json. Bind move_left, move_right, move_forward, move_back, jump, and sprint before running, one summer_input_map_bind per action (e.g. summer_input_map_bind(name="move_forward", events=[{"type": "key", "key": "W"}])); ui_cancel is a built-in action — confirm it is still bound. The controller asserts every one of them at _ready. Do not attach this template during generic import or to an NPC unless the user explicitly asks for player-style control. The default camera has horizontal mouse orbit only. CameraPitch is set once to a modest downward angle and vertical mouse motion does not change it. The controller keeps a short floor snap plus a small downward grounded velocity so ordinary horizontal movement does not create a false airborne Jump state. It also records the spawn point and respawns after falling below respawn_below_y. A bind T/A-pose survives every static check: the AnimationPlayer is wired, the clip is named Idle, and the files on disk all read correctly. Only a running frame separates that from a character actually at rest. Runtime proof. Read this skill’s references/default-third-person-verification-probe.gd and pass its full text unchanged as the probe_source of a RunVerification op, which runs it in a hidden, disposable game instance that never touches the editor:
The probe samples the live Skeleton3D after the player reaches the floor, requires the real resting clip to be named Idle, verifies that its pose actually changes, rejects an idle whose hands remain level with the upper arms like a bind T/A-pose, saves separate idle and moving frames, verifies W moves toward world -Z, and verifies vertical mouse input leaves camera pitch unchanged. Every boolean in results must be true; open the saved idle and moving frames listed in frames before you describe them. A false is a finding to fix, not a flaky probe. If the probe cannot run (the op returns ok: false with a failure_reason such as spawn_failed, or the engine build lacks the op), the runtime question belongs to the user. Do not paste the probe into the project. Finish on the saved state: the manifest path written into the Player node, the four semantic roles present, CameraYaw at identity and CameraPitch at its fixed angle in the .tscn text, the InputMap actions bound, and clean diagnostics. Then tell the user which idle clip should be playing at rest, so it is the first thing they look at on Play. That is a complete integration handed off for a playtest, not an incomplete one.

​
Order of operations

  1. Root node must be CharacterBody2D or CharacterBody3D. move_and_slide() only exists on these. RigidBody is for physics props, not players.
  2. Give it a CollisionShape2D/3D with a real shape (CapsuleShape for 3D humans, RectangleShape/CapsuleShape2D for 2D). No shape = falls through everything.
  3. Read gravity from project settings, never hardcode it, so tuning one value fixes the whole game: ProjectSettings.get_setting("physics/2d/default_gravity").
  4. Bind input actions BEFORE the script references them (move_left, jump, …). Referencing an unbound action is a silent no-op that reads as “controls dead”.
  5. Compile-check, then run and watch it move. Feel is a user call, not a still frame.

​
2D side-scroller controller

Flip the sprite with $Sprite2D.flip_h = velocity.x < 0 only when velocity.x != 0. For real platformer feel (coyote time, jump buffer, variable height) load references/platformer-feel.md.

​
Top-down controller (RPG / twin-stick / survivors)

No gravity. 8-directional, normalize so diagonals are not faster.
Survivors-style games with 200+ agents: enemies are Area2D moved with position += dir * speed * delta, NOT physics bodies. See the make-game skill’s survivors blueprint (summer_docs_read id skill/make-game/references/2d-survivors.md). The PLAYER stays a CharacterBody2D.

​
3D controller (first + third person)

Both share the same body + gravity + Input.get_vector floor logic. The only difference is where the camera lives and how look rotation is applied. Full first-person and third-person controllers, mouse look, sprint, crouch, and spring-arm setup are in references/movement-3d.md - load it for any 3D player. Minimal 3D walk (no look yet):

​
Summer humanoid package

When the player visual is a Summer character package:
  1. Produce or import the package first — it comes from the shared character pipeline (character-model; assets.generate_3d with rig and animationNames) and carries character.tscn plus its character.json manifest. Instantiate character.tscn; for clip wiring without this controller see character-animation-wiring.
  2. Put the normalized wrapper under a CharacterBody3D; do not modify the package or scale the body.
  3. Let controller velocity and move_and_slide() own all scene translation. Idle, Walk, Run, and Jump are in-place visual clips; never add their root motion to velocity.
  4. Resolve the four clips from character.json semantic roles instead of guessing names. Require every requested role; never substitute one role for another.
  5. Select one state from physics: airborne -> Jump, stopped -> Idle, moving -> Walk, sprinting -> Run. Airborne Jump has highest priority and never falls back to Walk/Run. Change clips only when the state changes, so Jump plays once per takeoff.
  6. Rotate the visual child toward non-zero movement while preserving the normalized -Z forward axis. Turn only visual yaw; do not rotate the collision body merely to turn the mesh. Keep the third-person camera behind the visual on local +Z.
Do not put player controls into the generation pipeline or generic character importer.

​
Camera-follow basics

  • 2D: add a Camera2D as a CHILD of the player (it is active while enabled, the default), position_smoothing_enabled = true, speed 5-8. Add limit_left/right/top/bottom so it never shows past the level edge. Full rigs in the camera-rigs skill.
  • 3D first-person: camera is a child of a Head node; yaw rotates the body, pitch rotates the Head (never the body) to avoid gimbal lock.
  • 3D third-person: camera on a SpringArm3D so walls push it in. See camera-rigs.

​
Traps

  • Scaling the CharacterBody node breaks collision + velocity. Scale the MESH/Sprite child instead. In 3D, 1 unit = 1 meter; a human is ~1.0-2.0 tall.
  • is_on_floor() is only valid AFTER move_and_slide() ran once this frame.
  • Diagonal speed-up = you forgot to normalize the input vector.
  • Mouse captured with no release traps the user. Always pair Input.MOUSE_MODE_CAPTURED with a ui_cancel handler that sets it VISIBLE.

​
From a shell

No Summer MCP tools in this session? Run each one as a command; when summer --version is missing or below 4.0, use npx -y summer-engine@latest in place of summer. Fields are flags in kebab-case (--scene-path res://main.tscn) or one --input '<json>', and summer ops describe <op> prints the exact input. The summer-cli skill has the rest.

​
Files in this skill

  • make-game: Orchestrate ‘make me a game’: brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship.
  • camera-rigs: Camera rigs: Camera2D follow with limits, first-person head, SpringArm3D third-person, top-down, FOV.
  • combat-basics: Damage: hitbox and hurtbox Areas, a reusable Health component, damage signals, knockback, projectiles.
  • fps-controller: First-person controller: WASD, mouse look, jump, coyote time, jump buffering, air control.
  • celeste-momentum-platforming: Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction.
  • character-animation-wiring: Wire a rigged character end to end: real clips and bones, locomotion states, method tracks, root motion.
  • character-model: Generate a rigged humanoid (player, NPC, enemy, boss) from a T-pose reference, previewed before rigging.
  • playtesting-a-feature: Before calling a gameplay feature done, run the game and walk through it. Static checks do not count.
Source: library/skills/character-movement/SKILL.md, rendered from summer-engine@4.3.0 on npm.