Wall Run — Motion Matching (enter / exit edges only)

Status: Locked · 2026-11-07 (amended same day — edges only; no mid-stint wall Pose Search)
Scope: How Pose Search relates to Wall Run presentation.
Out of scope: MM owning stick / peel / dash / duration · continuous wall-space Pose Search DB · full-body MM · Vault* / Tic-Tac MM

Authority: FS-MOV-004 · FS-MOV-005 · FS-FX-002 · FS-CAM-006 · wall persist 2026-11-02-wall-run-curve-end-design.md · wall move/look 2026-11-02-wall-run-camera-move-design.md · MM parent 2026-11-02-motion-matching-full-design.md · tutorial motion-matching-demo-and-full.md §11.3

Kanban: demo-movement-input (CMC + wall anim) · ground MM demo-motion-matching (enter/exit handoff). No separate wall Pose Search card required for v1.

---

1. Intent

Wall Run is one authored loop per side (Left / Right) while stuck. Motion Matching is not needed for the mid-stint cycle. Pose Search matters at the edges: leave ground MM cleanly on enter, and resume ground MM (PSD_TFA_Loco) on peel / land so feet don’t pop.

CMC still owns geometry; animation never decides stick/peel.

---

2. Decisions locked

Topic	Lock
Authority	CMC MOVE_TFA_WallRun owns contact, lookahead, turn gate, duration, dash, peel
Mid-stint presentation	Authored WallRun_L_Cycle / WallRun_R_Cycle (montage or AnimBP cycle state) — not Pose Search
Enter	Short enter clip and/or blend out of ground Pose Search → wall cycle
Exit / peel / land	Blend / peel clip → back into ground Pose Search (PSD_TFA_Loco) when bTFA_UsePoseSearchLoco on
Wall Pose Search DB	Shall not ship for v1 — no PSD_TFA_WallRun / PSS_TFA_WallRun requirement
Gate	No bTFA_UsePoseSearchWallRun. Wall presentation always uses L/R cycle (+ enter/peel clips)
Body vs look	Mesh faces RunTangent; never write control rotation
Layer	Lower body override during wall; upper Linked Layers unchanged
Lab dials	Unchanged (duration / dash / turn / lookahead)
Vault	WILL NOT USE (FS-MOV-003) — no vault MM
Future polish	Multi-clip wall Pose Search only if art later needs many wall variants — not locked now

WallNormal convention (stick once): normal points from wall surface into free space. RunTangent = Orient(Cross(WallNormal, Up), RunSide).

---

3. Runtime sketch

Ground: Pose Search (PSD_TFA_Loco)     [if bTFA_UsePoseSearchLoco]
        │
        ▼ enter (Sprint + Space + WallRunnable)
MOVE_TFA_WallRun (CMC)
        │
        ├─ tags: TFA.Move.WallRunning + Left|Right
        ├─ publish FWallRunAnimQuery (facing / side for mesh)
        │
        ▼
Enter clip (optional) → WallRun_L/R_Cycle loop
        │  Orientation toward RunTangent; Look free
        │
 peel / jump-off / timeout / dash-air …
        ▼
Clear wall tags → resume PSD_TFA_Loco (or legacy loco if ground gate off)

---

4. Runtime contract: FWallRunAnimQuery

Still published by CMC while attached so AnimBP can face the wall and pick L vs R without Pose Search. AnimBP does not re-trace walls for clip choice.

Field	Type	Meaning
bActive	bool	True while MOVE_TFA_WallRun attached
Side	Left | Right	Selects WallRun_L_* vs WallRun_R_*
WallNormal	Vector	Into free space
RunTangent	Vector	Mesh / warp forward while stuck
SpeedAlongTangent	float	Optional cycle play-rate bias
VerticalSpeed	float	Optional
bPeeling	bool	Peel blend window
bDashTransfer	bool	Opposite-wall dash airborne

---

5. Assets (v1 minimum)

Asset	Role
WallRun_L_Cycle / WallRun_R_Cycle	Looped mid-stint run (required)
WallRun_L_Enter / WallRun_R_Enter	Short enter (optional; blend OK)
WallRun_Peel (shared / mirrored OK)	Jump-off / auto peel (optional; reuse jump-off until art)
Dash-air	Reuse jump/air or one WallDash_Air
PSD_TFA_Loco	Ground MM — resume on exit

Do not author PSS_TFA_WallRun / PSD_TFA_WallRun for v1.

Content ownership: TF AnimBP / parkour anims under TFACombat / ADDON lab copies — not forked LyraGame.

---

6. Pseudocode (implementer contract)

6.1 CMC (authority — peel rules unchanged)

function TickWallRun(Delta):   // CMC movement update — not Actor Tick
  if not ContactProbe(WallRunnable): AutoPeel(); return
  Tangent = OrientTangent(Cross(WallNormal, Up), RunSide)
  for sample in Lookahead(Tangent, Dist, Samples):
    if not ValidWall(sample): AutoPeel(); return
    if Angle(WallNormal, sample.Normal) > MaxWallTurnDegrees: AutoPeel(); return
    WallNormal = sample.Normal
    Tangent = OrientTangent(Cross(WallNormal, Up), RunSide)

  ApplyVelocity(Tangent * DesiredSpeed + lateral lean)
  TickDuration(Delta); if expired: AutoPeel(); return

  AnimQuery.bActive = true
  AnimQuery.Side = RunSide
  AnimQuery.WallNormal = WallNormal
  AnimQuery.RunTangent = Tangent
  AnimQuery.SpeedAlongTangent = Vel · Tangent
  PushGameplayTags(WallRunning + SideTag)

6.2 AnimGraph — wall overrides MM; edges hand off

function UpdateLowerLoco():
  Q = Movement.GetWallRunAnimQuery()

  if Q.bActive:
    // Suspend ground Pose Search contribution on lower body
    PauseOrBypassPoseSearchLoco()
    if Q.bPeeling:
      PlayPeelOrBlendOut(Q.Side)
    else if JustEntered:
      PlayEnterThenLoop(Q.Side)   // Enter → WallRun_L/R_Cycle
    else:
      PlayCycle(WallRun_L_Cycle or WallRun_R_Cycle by Q.Side)
    OrientationWarp.TargetForward = Q.RunTangent
    return

  // Not on wall — ground MM (or legacy)
  if bUseGroundMM:
    ResumePoseSearch(PSD_TFA_Loco)
    PoseSearch.SetTrajectory(BuildGroundTrajectory())
    OrientationWarp.TargetForward = GroundFacingFromMove()
  else:
    LegacyBlendSpaces()

6.3 Enter / peel

OnEnterWallRun:
  // CMC set mode + tags; AnimBP blends out of PSD_TFA_Loco → enter/cycle

OnAutoPeel or OnWallJumpOff:
  AnimQuery.bPeeling = true for PeelBlendWindow
  ClearTags(WallRunning); AnimQuery.bActive = false
  // AnimBP resumes PSD_TFA_Loco with current pose/trajectory

---

7. Prerequisite order

1. CMC Wall Run (FS-MOV-004) + L/R cycle anims + tags / FWallRunAnimQuery.
2. Ground Pose Search (bTFA_UsePoseSearchLoco) for clean exit handoff (enter handoff too when gate on).
3. No wall Pose Search DB.

---

8. AC (sandbox)

AC	Pass
Mid-stint	Single L or R cycle plays while attached; no wall Pose Search database in use
Enter	From ground MM (gate on): no hard foot teleport into wall cycle
Exit	Peel / land resumes PSD_TFA_Loco (gate on) within one blend window; trajectory continues
Look free	Hold W, spin look 180° — mesh keeps wall tangent; look alone does not peel
Curve / lip	CMC persist/peel unchanged; anim stays on cycle until peel
Opposite dash	Air clip then far-wall L/R cycle; no wall PSD
Authority	Anim never moves capsule, never writes control rotation, never applies HP/Flow

Extends AC-MOV-001 feel; does not replace peel/lookahead physics AC.

---

9. Explicit non-goals

• Mid-stint PSD_TFA_WallRun / wall-space trajectory Pose Search (v1)
• MM deciding peel, dash range, or duration
• Full-body Pose Search wiping upper Linked Layers
• Vault / Tic-Tac MM

---

10. Related docs

Doc	Role
2026-11-02-wall-run-curve-end-design.md	CMC persist / peel
2026-11-02-wall-run-camera-move-design.md	Wall-locked move + free look
2026-11-02-motion-matching-full-design.md	Parent MM lock
motion-matching-demo-and-full.md	Wire tutorial §11.3
08-camera-input-movement.md	Keymapping / Wall Run bible
22-demo.md	Demo inventory