> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Character movement skill for AI agents

> Player controllers for 2D and 3D, plus the standard third-person controller for Summer humanoids. A Summer Engine skill for AI agents.

`character-movement` is a skill from the [Summer skill library](/mcp/skills): 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.

| | |
| - | - |
| Status | Preview: not yet exercised in-engine by the Summer team |
| Domains | Character controllers, Gameplay, 2D art, 3D models |
| Version | `1.2.1` |
| Engine version | `>=4.6` |
| Recommended set | No, installed by `--all` or by name |

## 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:

```bash theme={null}
npx -y summer-engine@latest skills install character-movement --agent claude-code
```

Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) 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:

| File | Read when |
| - | - |
| `references/default-third-person-controller.gd` | standard playable third-person Summer humanoid package; copy this exact controller instead of rewriting it |
| `references/default-third-person-verification-probe.gd` | runtime proof for that controller; pass it unchanged as a `RunVerification` `probe_source` |
| `references/platformer-feel.md` | jump feels bad, coyote time, jump buffering, variable jump height, one-way platforms |
| `references/movement-3d.md` | FPS/third-person controllers, mouse look, sprint, crouch, spring-arm camera |

## 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:

```text theme={null}
Main (Node3D)
  Player (CharacterBody3D)               # template script
    CollisionShape3D                     # capsule
    CharacterRotationRoot (Node3D)       # only this node turns
      Character                          # imported character.tscn instance
    CameraYaw (Node3D)
      CameraPitch (Node3D)
        SpringArm3D
          Camera3D                       # current = true
  Ground / level geometry                # world siblings of Player
  DirectionalLight3D / WorldEnvironment
```

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:

```text theme={null}
[gd_scene load_steps=7 format=3]

[ext_resource type="Script" path="res://scripts/player.gd" id="1_controller"]
[ext_resource type="PackedScene" path="res://characters/imported/character.tscn" id="2_character"]

[sub_resource type="CapsuleShape3D" id="PlayerCapsule"]
radius = 0.45
height = 1.8

[sub_resource type="BoxShape3D" id="GroundShape"]
size = Vector3(20, 0.5, 20)

[sub_resource type="BoxMesh" id="GroundMesh"]
size = Vector3(20, 0.5, 20)

[sub_resource type="Environment" id="WorldEnvironment"]
background_mode = 1
background_color = Color(0.12, 0.18, 0.3, 1)
ambient_light_energy = 0.6

[node name="Main" type="Node3D"]

[node name="Player" type="CharacterBody3D" parent="."]
position = Vector3(0, 1, 0)
script = ExtResource("1_controller")
character_manifest_path = "res://characters/imported/character.json"

[node name="CollisionShape3D" type="CollisionShape3D" parent="Player"]
shape = SubResource("PlayerCapsule")

[node name="CharacterRotationRoot" type="Node3D" parent="Player"]

[node name="Character" parent="Player/CharacterRotationRoot" instance=ExtResource("2_character")]

[node name="CameraYaw" type="Node3D" parent="Player"]

[node name="CameraPitch" type="Node3D" parent="Player/CameraYaw"]
rotation = Vector3(-0.349066, 0, 0)

[node name="SpringArm3D" type="SpringArm3D" parent="Player/CameraYaw/CameraPitch"]
spring_length = 5.0

[node name="Camera3D" type="Camera3D" parent="Player/CameraYaw/CameraPitch/SpringArm3D"]
current = true

[node name="Ground" type="StaticBody3D" parent="."]
position = Vector3(0, -0.25, 0)

[node name="MeshInstance3D" type="MeshInstance3D" parent="Ground"]
mesh = SubResource("GroundMesh")

[node name="CollisionShape3D" type="CollisionShape3D" parent="Ground"]
shape = SubResource("GroundShape")

[node name="DirectionalLight3D" type="DirectionalLight3D" parent="."]
rotation_degrees = Vector3(-55, -30, 0)
shadow_enabled = true

[node name="WorldEnvironment" type="WorldEnvironment" parent="."]
environment = SubResource("WorldEnvironment")
```

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:

```
summer_batch(ops=[{"op": "RunVerification", "max_seconds": 30, "probe_source": "<the probe file, unchanged>"}])
```

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

```gdscript theme={null}
extends CharacterBody2D

@export var speed: float = 200.0
@export var jump_velocity: float = -350.0   # negative = up in 2D

var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")

func _physics_process(delta: float) -> void:
	if not is_on_floor():
		velocity.y += gravity * delta
	if Input.is_action_just_pressed("jump") and is_on_floor():
		velocity.y = jump_velocity
	var dir := Input.get_axis("move_left", "move_right")
	velocity.x = dir * speed if dir else move_toward(velocity.x, 0.0, speed)
	move_and_slide()
```

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.

```gdscript theme={null}
extends CharacterBody2D

@export var speed: float = 220.0

func _physics_process(_delta: float) -> void:
	var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
	velocity = dir * speed
	move_and_slide()
```

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):

```gdscript theme={null}
extends CharacterBody3D

@export var speed: float = 5.0
@export var jump_velocity: float = 4.5
var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")

func _physics_process(delta: float) -> void:
	if not is_on_floor():
		velocity.y -= gravity * delta
	if Input.is_action_just_pressed("jump") and is_on_floor():
		velocity.y = jump_velocity
	var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
	var direction := (transform.basis * Vector3(input_dir.x, 0.0, input_dir.y)).normalized()
	if direction:
		velocity.x = direction.x * speed
		velocity.z = direction.z * speed
	else:
		velocity.x = move_toward(velocity.x, 0.0, speed)
		velocity.z = move_toward(velocity.z, 0.0, speed)
	move_and_slide()
```

## 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.

| In this skill | Command |
| - | - |
| `assets.generate_3d` | `summer assets generate-3d` |
| `summer_docs_read` | `summer docs read` |
| `summer_add_node` | `summer engine add-node` |
| `summer_batch` | `summer engine batch` |
| `summer_get_diagnostics` | `summer engine get-diagnostics` |
| `summer_get_scene_tree` | `summer engine get-scene-tree` |
| `summer_get_script_errors` | `summer engine get-script-errors` |
| `summer_input_map_bind` | `summer engine input-map-bind` |
| `summer_play` | `summer engine play` |
| `summer_read_file` | `summer engine read-file` |
| `summer_replace_text` | `summer engine replace-text` |
| `summer_save_scene` | `summer engine save-scene` |
| `summer_set_prop` | `summer engine set-prop` |
| `summer_stop` | `summer engine stop` |
| `summer_write_file` | `summer engine write-file` |

## Files in this skill

* [`references/default-third-person-controller.gd`](/skills/character-movement/references/default-third-person-controller)
* [`references/default-third-person-verification-probe.gd`](/skills/character-movement/references/default-third-person-verification-probe)
* [`references/movement-3d.md`](/skills/character-movement/references/movement-3d)
* [`references/platformer-feel.md`](/skills/character-movement/references/platformer-feel)

## Related skills

* [`make-game`](/skills/make-game): Orchestrate 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship.
* [`camera-rigs`](/skills/camera-rigs): Camera rigs: Camera2D follow with limits, first-person head, SpringArm3D third-person, top-down, FOV.
* [`combat-basics`](/skills/combat-basics): Damage: hitbox and hurtbox Areas, a reusable Health component, damage signals, knockback, projectiles.
* [`fps-controller`](/skills/fps-controller): First-person controller: WASD, mouse look, jump, coyote time, jump buffering, air control.
* [`celeste-momentum-platforming`](/skills/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`](/skills/character-animation-wiring): Wire a rigged character end to end: real clips and bones, locomotion states, method tracks, root motion.
* [`character-model`](/skills/character-model): Generate a rigged humanoid (player, NPC, enemy, boss) from a T-pose reference, previewed before rigging.
* [`playtesting-a-feature`](/skills/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`](https://github.com/SummerEngine/summer/blob/main/library/skills/character-movement/SKILL.md), rendered from `summer-engine@4.3.0` on npm.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.