character-controller

name: character-controller description: >- Architecture blueprint for first-person and third-person character controllers: kinematic collide-and-slide, movement states, slopes, steps, jumping, stamina, abilities, animation handoff, FPS momentum, vehicles, networking, feel, and accessibility. Use when designing or diagnosing player movement, locomotion, climbing, swimming, gliding, jump feel, FPS movement, motion matching, jitter, slope bugs, floaty controls, nausea, or netcode desync.

Character Controller

Build the movement layer of a game — third-person AND first-person, from a kinematic adventure controller to a momentum FPS. This skill is the engine-agnostic architecture blueprint: the solver, the movement state machine, feel numbers, FPS/momentum movement, locomotion animation, build order, and failure modes. Engine tooling specifics live in the engine mapping section and the dedicated engine skills (unity6-aaa-best-practices, ue5-aaa-best-practices).

The default stance: kinematic

Use a kinematic collide-and-slide controller for player characters. This is the AAA consensus (Unity CharacterController/KCC, UE CMC, PhysX CCT): exact designer-authored response, instant stops, no mass/friction leakage into feel, stable on slopes and steps, deterministic and replayable for networking. A force-driven character can't express "stop exactly here" or "ignore this push" without fighting the solver.

Rigidbody-driven is the justified exception: physics-as-gameplay (Human: Fall Flat), vehicles/boards, or momentum-trading designs — typically built as a floating capsule (ground spring holding a hover height, force toward target velocity, torsional upright spring; Genshin ships a steered variant of this hybrid).

The one-directional pipeline

input → intent → state machine → movement solver → collision → animation

• The state machine decides what the character does.
• The solver decides where it ends up.
• Collision decides what's legal.
• Animation only visualizes — it never writes position during locomotion (root motion is a scoped exception, see solver-states.md).

Keeping these one-directional is what allows per-state tuning without regressions. Never let the animation or the camera write into the capsule.

Reference map

Build order (4 shippable tiers)

Tier 1 — Walking skeleton
- [ ] Capsule + collide-and-slide solver (or engine-native equivalent)
- [ ] Grounded/Airborne states; jump parametrized by height + time-to-apex
- [ ] Ground detection by shape cast (not a single ray); slope limit
- [ ] Camera-relative input -> intent vector
Tier 2 — Production feel
- [ ] Coyote time + jump buffering (buffer = intent + timestamp, revalidated)
- [ ] Asymmetric gravity (fall multiplier), variable jump, apex hang
- [ ] Step-up/step-down + ground snapping (no bunny-hop downhill)
- [ ] Fixed-timestep simulation + visual interpolation (test 30/60/144 fps)
- [ ] Squash/stretch, dust, camera assists (feel without touching physics)
Tier 3 — Traversal states
- [ ] Moving platforms (basing: delta-transform, velocity imparted on exit)
- [ ] Climb / swim (surface + underwater) / glide as HSM states
- [ ] Stamina economy as the traversal governor (drain/regen/exhaustion)
- [ ] Animation interface: publish state + velocity; root motion as
      proposed-velocity only
Tier 4 — Scale & robustness
- [ ] Modular movement verbs (composition over transition edges)
- [ ] Network-ready structure (see below)
- [ ] Rigidbody interaction (capped push impulses, crush handling)
- [ ] World-streaming guards (no simulation over missing collision)

Feel numbers (starting points — tune by playtest)

Jump math: pick height h and time-to-apex t, derive g = 2h/t², v0 = 2h/t (Pittman, GDC). Designers tune what they feel; constants fall out. Full sourced tables in solver-states.md; FPS/ momentum movement in fps-movement.md; animation/feel/ accessibility in animation-feel.md.

Network-ready structure (3 decisions, day one)

Even a solo game should structure these three things — retrofitting is a rewrite:

1. Deterministic tick: simulate(state, input, fixed_dt) as a pure step — fixed timestep, no reads from real time or render state.
2. Input → intent separation: the simulation consumes an intent struct (move vector, action flags), never raw device input.
3. Snapshotable state: controller state (position, velocity, state id, timers) serializable in one struct.

Prediction/rollback/reconciliation are covered at architecture level in coop-session; UE's CMC gives them free if you respect its saved-move cycle.

Engine mapping

Failure modes

The 14 classic movement bugs (slope/stair jitter, tunneling, edge sticking, capsule sliding off ledges, moving-platform desyncs, slope exploits, state deadlocks, root motion conflicts, frame-rate dependence, water/climb boundary oscillation, physics desync/crush, buffered-input misfires, first-person camera nausea, and networked movement desync/speedhacks) are cataloged in pitfalls.md with symptom → root cause → prevention.

Related skills

• traversal-system — the layer above: world traversability data, the verb catalog, and the stamina economy driving these movement states.
• combat-system — the attack graph plugs into this movement HSM as the combat state's content.
• camera-system — the one-clock interpolation contract (the #1 jitter source) and camera-relative input.
• coop-session — prediction/reconciliation and the anti-cheat re-simulation behind fast-movement netcode (fps-movement.md), built on the deterministic tick + intent + snapshot structure above.
• open-world-streaming — the controller side of streaming (never simulate over missing collision) is covered there and in pitfalls.md.
• game-architecture-patterns — State (HSM), Component, Update Method theory.
• unity6-aaa-best-practices / ue5-aaa-best-practices — engine-wide practices this skill assumes.