Skip to content
Programming Bible

Wall Run — end-of-wall, turn gate, curve follow

Status: Locked · 2026-11-02
Scope: Continuous MOVE_TFA_WallRun persist rules — lookahead peel, max turn, curve re-stick, auto peel.
Out of scope: Carbon montage WallRunOver/On · Tic-Tac · all Vault* (FS-MOV-003 WILL NOT USE) · MOVE_Flying parkour ability · dedicated peel montages (reuse jump-off until art) · Wall Run anim / MM enter-exit handoff (see wall-run MM sibling)

Authority: FS-MOV-004 · bible docs/08-camera-input-movement.md · docs/22-demo.md · GDD Hybrid Perspective / Character Movement · Demo Mod Lab › Parkour · kanban demo-movement-input / demo-modkit
Presentation sibling: L/R cycle mid-stint; ground MM at enter/exit — 2026-11-07-wall-run-motion-matching-design.md (CMC still owns this persist spec).

Carbon reference (borrow probes only): ParkourSystem/Character/CarbonParkourComponent.cpp — WallRunTrace · WallRunValidationTrace (45° entry cone + along-wall clearance sweep). Do not ship Carbon’s detect→montage→EndAbility product model.

1. Intent

Section titled “1. Intent”

Wall Run must feel stuck to real geometry: peel before walking off a lip, peel on hard creases, and follow gentle curves without resetting the duration timer. Playtest must dial “how much curve” via Demo Mod.

2. Decisions locked

Section titled “2. Decisions locked”
Decision Lock
Fail exit Auto peel — same family as Space wall jump-off (away-from-wall impulse + air window / directional double-jump). Not soft freefall · not grace-stick
Max turn MaxWallTurnDegrees = 45 (lab default) — along-path normal delta between samples
Curves Allowed when successive normals ≤ gate; re-stick to new normal (CMC continuous)
Timer Gentle normal change does not reset WallRunMaxDuration; only successful opposite-wall dash does
DEX Scales duration + dash distance only — not turn degrees / lookahead

3. Runtime (server-sim CMC)

Section titled “3. Runtime (server-sim CMC)”

Each tick / fixed step while MOVE_TFA_WallRun:

  1. Contact probe into current wall — require TFA.World.WallRunnable. Miss → auto peel.
  2. Tangent = Cross(WallNormal, Up) oriented to run side.
  3. Lookahead — WallRunLookaheadSamples probes along tangent over WallRunLookaheadDistance.
  4. End-of-wall — no valid tagged hit → auto peel (early, before capsule falls off).
  5. Turn / crease — Angle(CurrentNormal, SampleNormal) > MaxWallTurnDegrees → auto peel.
  6. Curve follow — under threshold: update attach normal (mesh may slerp); keep velocity on new tangent.
  7. Auto peel — same exit path as Space wall jump-off (default same impulse scale).

Entry: existing sprint + Space + proximity. Shared entry cone: reject face-plant stick when Abs(Dot(Forward, Normal)) > cos(MaxWallTurnDegrees) unless playtest splits dials later.

Enter → tick → contact → lookahead → (gap|turnFail) → auto peel → air
                      ↘ ok → update normal → timer → tick

4. Lab dials (Demo Mod › Parkour)

Section titled “4. Lab dials (Demo Mod › Parkour)”
Field Default Notes
WallRunMaxDuration / WallRunMaxDurationSec 3.0 s existing · DEX-scaled
MaxWallDashDistance / MaxWallDashDistanceM 6.0 m existing · DEX-scaled
MaxWallTurnDegrees 45 crease / curve gate · not DEX-scaled
WallRunLookaheadDistance / WallRunLookaheadDistanceM 2.0 m end-of-wall early peel
WallRunLookaheadSamples 4 integer · curve fidelity
DexWallRunDurationPctPerPt 1.0 existing
DexWallDashDistancePctPerPt 0.75 existing

Export kind lab-parkour → DT_TFA_ParkourLabDefaults → parkour DA. Fixture: data/demo_mod_exports/fixtures/tfa-lab-parkour.json.

5. AC (extend AC-MOV-001)

Section titled “5. AC (extend AC-MOV-001)”
  • Flat long wall: runs until timeout or Space peel; no false peel
  • Wall ends: auto peel before falling through end
  • Hard ~90° inside corner: peels (delta > 45°)
  • Gentle cylinder / spline under 45° per sample step: stays stuck; normal updates; no timer reset
  • Lower MaxWallTurnDegrees → peels sooner on same curve; raise → holds more curve
  • Untagged / wrong tag ahead → peel
  • Opposite-wall dash unchanged (success still resets duration only)

6. Implementer notes

Section titled “6. Implementer notes”
  • Host path: MOVE_TFA_WallRun on TF CMC (FS-MOV-005) — Phase B / J absorb from Carbon WallRun* only (Vault* WILL NOT USE)
  • Never leave silent magic numbers in GA graphs — read parkour DA / Mod session overrides
  • Kanban: demo-movement-input + demo-modkit Lab › Parkour