Motion Matching — Demo + Full (UE 5.8 Lyra · Pose Search)

Status: Active full tutorial · 2026-11-02 (merged concrete Lyra 5.8 wire steps)
Products: Ladder Demo · Full game (Lyra 5.8 host family)
Authority: FS-FX-002 · motion-matching design · look-vs-body (22-demo.md · 08) · hit auth FS-ARCH-013
Howto: Demo 26 · Full 25
Kanban: Demo demo-motion-matching · Full combat (loco) + melee (strike choosers)
Host rule: Do not fork LyraGame / edit stock ABP_Mannequin_Base in place — duplicate AnimBP + Linked Layers into TF content (02-gfp-cookbook.md)

Alias: demo-motion-matching-lyra.md → this file.

Not this doc: Cinematic Benchmark standalone — 29 · Sequencer cinematic feet (Foot Placement + Mixer, no MM) — sequencer-foot-placement-cinematic.md · Melee Drive combat — melee-drive-guns-singularity.md (deferred).

Refs (Epic / community pattern): UE 5.8 Game Animation Sample · Lyra GAS / abilities docs · Lyra upper/lower Linked Layer practice. Steps below adapt that pattern to Terra Firma locks.

---

0. Goal

Replace Lyra’s lower-body locomotion provider with Pose Search / Motion Matching while leaving upper-body weapon / GAS overlays on Linked Anim Layers + Layered Blend Per Bone. Future aim offsets hook after the spine split (Mesh Space).

Product	Loco MM	Strike / Melee Drive MM	Exit
Demo	Shall — lower only	Not this card’s exit	demo-motion-matching
Full	Shall — same + richer DBs	Shall when family DA enables (TFAMelee)	combat / melee

Hard locks

• MM = presentation + clip choice — never HP / Flow / CMC authority

• Look = mouse / RS; MM never writes control rotation

• Remotes: TPP AnimInstance; local TrueFPP = same mesh bone-hide + TPP OwnerNoSee only (FS-CAM-002) — no arms-only asset

• AnimBP / Pose Search assets in Blueprints; thin C++ only for CMC/tag glue in GFP

• No ambient melee magnet

---

1. Architectural overview

        [Character Trajectory Component]
                       │
                       ▼
        [Motion Matching]  ◄── Pose History
               │              ◄── Active Tags (weapon stance)
               ▼
        [Orientation Warping]   (stride / facing fix)
               │
               ▼
        [Layered Blend Per Bone · spine_01]
           Base  = MM + warp (lower)
           Blend0 = Lyra / TF weapon overlay (ABP_ItemAnimLayers / Linked Layers)
               │                    ▲
               │                    └── GAS / stance tags
               ▼
        [FUTURE: Aim Offset · torso/arms · Mesh Space]
               │
               ▼
        [Final pose] → [Post-Process AnimBP · Foot IK / Control Rig]

Lyra isolates loco in a Linked Anim Layer (e.g. FullBody_Locomotion). Replace the default CycleState / blend-space loco there — do not smash the whole AnimGraph into one full-body MM node.

---

2. Plugins

Edit → Plugins (then restart):

Plugin	Role
Pose Search	Motion Matching / databases / schema
Motion Trajectory	Character Trajectory component + prediction
Animation Warping	Orientation Warping (stride fix)
Keep	Motion Warping (melee/vault) · Animation Locomotion Library

Also enable PoseSearch on the .uproject cook path. GFP Runtime (TFACombat typical): add "PoseSearch" (and trajectory modules if used from C++) to Build.cs — never LyraGame.Build.cs.

---

3. Content ownership (TF first)

1. Duplicate Lyra hero TPP AnimBP + Linked Layer interfaces + item anim layer BPs into TF content.
2. Point Demo / Full Experience pawn data at your copies.
3. Optional gate: bTFA_UsePoseSearchLoco (or Gameplay Tag) — default off until AC green.
4. Inventory stock Lyra: note FullBody_Locomotion, spine_01 layered blend, ABP_ItemAnimLayers (or TF equivalent), Post-Process Foot IK.

---

4. Animation assets + schema + database

4.1 Bulk-edit locomotion clips

Select loco sequences (unarmed / rifle / pistol walks, jogs, starts, stops, pivots — TF or Lyra feed):

1. Asset Actions → Bulk Edit via Property Matrix
2. Enable Root Motion = True
3. Force Root Lock = True
4. Save

4.2 Pose Search Schema — PSS_TFA_Loco (or PSS_LyraBase lab name)

Create: Content Browser → Animation → Motion Matching → Pose Search Schema · assign TF / Lyra skeleton.

Channels (recommended baseline):

Channel	Notes
Position + Velocity Trajectory	Sample past/future (e.g. −0.2s, 0, +0.2s, +0.5s, +1.0s)
Bone foot_l	Position + Velocity
Bone foot_r	Position + Velocity
Bone pelvis or spine_01	Weight low (e.g. ~0.1) — registers lean without letting upper weapon postures hijack foot selection

4.3 Pose Search Database — PSD_TFA_Loco

1. Create Pose Search Database · assign schema.
2. Drop locomotion sequences in.
3. Continuization / mirroring per Epic Pose Search practice.
4. Tag by stance (Lyra Cosmetic tags or TF equivalents — map to your equipment flow):

Clip group	Example tag
Rifle loco	Cosmetic.WeaponStance.Rifle (or TF stance tag)
Pistol / 1H gun loco	Cosmetic.WeaponStance.Pistol (or TF)
Unarmed / melee-stance lower	Empty or TF default / melee stance tag

Demo may ship a capped set; Full expands gaits / armor feel without changing underarmor scale (FS-FX-004).

---

5. Character Trajectory + movement settings

On the TF hero BP (derived from Lyra hero — not a LyraGame fork):

1. Add Component → Character Trajectory.
2. Character Movement Component:
   • Orient Rotation to Movement = False
   • Use Controller Desired Rotation = True
3. This matches look-vs-body: Look owns control rotation; MM follows trajectory, does not steal aim.

---

6. Inject MM into Lyra’s locomotion layer

Work only on the TF duplicate of the mannequin / hero AnimBP.

6.1 Event Graph

1. From Pawn → Get Component by Class (Character Trajectory) → cache TrajectoryComponent.
2. Maintain an ActiveStanceTags (Gameplay Tag Container) updated from Lyra / TF equipment / loadout (same source that drives weapon Linked Layers).

6.2 FullBody_Locomotion Linked Layer

1. Open the FullBody_Locomotion interface implementation.
2. Disconnect / remove default CycleState (or equivalent loco state machine / blend spaces).
3. Rebuild:

ActiveStanceTags ──► Motion Matching.Active Tags
TrajectoryComp   ──► Motion Matching.Trajectory
Pose History     ──► Motion Matching.Pose History
                         │
                         ▼
                  Orientation Warping
                         │
                         ▼
                  (layer output / cache Lyra expects)

4. Assign PSD_TFA_Loco on the Motion Matching node.
5. Do not rebuild upper weapon graphs inside this layer.

6.3 UE 5.8 — Pose Match Column (optional polish)

If weapon swaps mid-run hitch, use 5.8 Pose Match Column inside the loco layer to smooth database sections across stance tags (Game Animation Sample pattern). Full cause/fix list for snap vs skate: §8.

6.4 Alternate: multi-database Select (from community “stances” tutorials)

Some UE tutorials (e.g. Unreal Made Easy — Quick & Easy Guide to Motion Matching (Stances)) use one PSD per stance and switch them in the AnimGraph:

InAir? ──► Blend poses bool ──► Jump PSD MM
Crouch? ──► Blend poses bool ──► Crouch PSD MM
WeaponMode (int) ──► Select ──► Base / Pistol / Rifle PSD MM
         + Pose History + Trajectory

When to prefer that: lab / Third Person prototype, or if Active Tags filtering on one fat DB is unstable in your engine build.

TF default stays §6.2 (one tagged DB + GAS / equipment tags) so Lyra equipment flow owns stance — not keyboard ints. If you use multi-DB Select, drive the Select index / chooser from the same equipment tag source that feeds Linked weapon layers (map tag → index), never a parallel debug key path in shipping Demo/Full.

Do not copy from that video into TF:

Video habit	TF lock
Fresh Third Person AnimBP, full-body MM	Inject only into FullBody_Locomotion Linked Layer on TF duplicate
Delete pivots / 180s “to keep DB clean”	Keep starts/stops/pivots — skating without them
Integer WeaponMode + C-key crouch as authority	GAS / equipment tags + CMC crouch already in Lyra
No spine split / Orientation Warping / Foot IK	Keep §§7–9
Migrate Lyra loco into Third Person and strip ABPs	Host is Lyra 5.8; migrate clips into TF content only

Normalization Set (PSNS_*) from that workflow is optional polish — create one shared set and assign to every PSD if search costs feel uneven across stances.

---

7. Protect upper body + future aim offsets

Downstream in the main AnimGraph (where Lyra caches FullBody_Locomotion output):

1. MM + Orientation Warping → Base Pose of Layered Blend Per Bone.
2. Branch: Bone spine_01 · Blend Depth 1 · Mesh Space Rotation Blend = True
   • Mesh Space matters so later aim offsets conform to world look, not local axes from the loco DB.
3. Blend Pose 0 ← Lyra / TF weapon overlay (ABP_ItemAnimLayers / Linked weapon layers driven by GAS tags).
4. Montages on UpperBody / additive slots (reload, fire) continue to override torso/arms while legs stay on MM velocity.
5. Future hook: Aim Offset node on torso/arms after this split, before final output.

Confirm stock Lyra already layered at spine_01; if so, ensure your MM output feeds the base of that blend, not a parallel full-body path that bypasses it.

Expect rifle↔pistol mid-stride hitch even with a correct lower-only split — that is §8 (tag cliff), not proof Mesh Space is wrong. Do not turn Mesh Space off to “fix” swaps.

---

8. Weapon-switch snap / skate (stance tag cliff)

Lower-body-only MM does not remove weapon-swap glitches. Stance tags change the eligible pose pool instantly while feet and capsule velocity are mid-cycle. Treat snap / skate on rifle↔pistol (or TF stance tags) as a known structural risk, not a broken upper/lower split.

8.1 Why it happens

Cause	What changes	Visible fail
A. Tag-filter cliff	Equipment / Lyra cosmetic stance tag flips (e.g. Cosmetic.WeaponStance.Rifle → …Pistol or TF equivalents). MM Active Tags (or multi-PSD Select) drops the old pool and queries the new one on the next search.	Mid-stride foot phase in rifle may have no near neighbor in pistol → snap (blend too short) or skate (blend too long across mismatched foot velocities).
B. Stance velocity / chassis mismatch	Rifle lower clips = wider / lower combat chassis; pistol / unarmed = narrower / upright. Root and foot speeds in the new DB may not match capsule speed.	Skating until search settles on a stable loop.
C. Mesh Space tug-of-war	Upper overlay jumps spine/shoulder weights while pelvis parents spine_01. Mesh Space Rotation Blend (required for aim offsets) transmits a sudden rotational counter into the hierarchy.	Momentary foot-plant break / skip while MM and Foot IK re-lock — keep Mesh Space on; fix with blend / bridge clips / mirror parity below.

[stance tag flip] ──► Active Tags / PSD pool swap ──► new foot phase vs old
        │
        ├── short Blend Time  → snap
        ├── long Blend Time   → skate (velocity lerp)
        └── Mesh Space upper jump → hierarchy tug on plant

8.2 Fixes (UE 5.8 · apply in order)

1. Motion Matching Blend Time on tag transitions
   On the MM node Details, raise Blend Time for stance swaps (lab start ~0.2 → 0.35–0.4). Gives Pose History / search time to interpolate feet across pools. Too high = ice-skate; tune per product feel. Optional: drive a slightly longer blend only while equipment stance is changing (short window), then return to normal.

2. Stance-bridge / dual-tag clips in the loco DB
   If snap stays harsh, add neutral or dual-tagged transition clips to PSD_TFA_Loco (both rifle + pistol tags, or a short untagged bridge the search can land on). Softens the cliff without full-body MM.

3. Mirror / foot-phase parity across stance sets
   Rifle and pistol (and unarmed) loco sets must mirror the same way and prefer the same lead foot on matched gaits. Opposite lead mid-stride forces an immediate leg swap on tag flip.

4. Also use (already in this tutorial)

   • §6.3 Pose Match Column for mid-run weapon swaps
   • §4 low spine/pelvis schema weight so upper hold poses do not hijack foot choice
   • Shared Normalization Set if rifle vs pistol search costs feel uneven
   • §9 Foot IK after overlays so plant recovers post-tug

8.3 What not to do

Don’t	Why
Disable Mesh Space Rotation Blend	Breaks future aim offsets; tug is managed, not deleted
Instant tag flip with Blend Time ≈ 0	Guarantees snap on any foot-phase mismatch
Different mirror rules per stance DB	Built-in mid-stride leg snap
Blame upper Linked Layers and rip them out	Layers are correct; pool cliff is the loco-tag problem

8.4 Demo / Full AC note

Stance AC is not only “correct DB while holding rifle.” Also PIE swap mid-jog (and mid-strafe): no hard foot teleport; skate window short enough to read as a blend, not ice.

---

9. Post-process Foot IK

Keep Foot IK / Control Rig in the Post-Process AnimBP (after weapon layers + future aim offsets). MM chooses frames from ideal ground; uneven terrain must resolve last or feet float when upper weight is added. After a stance tag flip (§8), IK is the last recovery for plant — it cannot fix a 0-blend pool cliff by itself.

---

10. Part A — Demo wire order

Kanban: demo-motion-matching.

1. PIE baseline: ADS + run (upper/lower) before MM.
2. bTFA_UsePoseSearchLoco off.
3. Plugins + Trajectory component + CMC rotation flags.
4. Schema + DB + root-motion bulk edit.
5. TF AnimBP: replace FullBody_Locomotion CycleState with MM graph (§6).
6. Spine_01 layered blend + item overlays (§7).
7. PIE: walk/run/start/stop/pivot · ADS+move · mid-jog stance swap (§8 Blend Time / bridge / mirror).
8. Net smoke: listen + 2 clients — TPP remotes; FPP local only.
9. Gate on → Demo Experience when §13 Demo AC green.

Demo card does not require Melee Drive strike Pose Search.

---

11. Part B — Full wire order

Kanban: combat · melee.

11.1 Loco

Promote/share Demo PSS_* / PSD_* / AnimBP pattern into Full Experience; expand DB; PoseSearch on Full Experiences. Re-check §8 mid-swap AC after DB expansion.

11.2 Melee Drive strike choosers (TFAMelee · after Melee foundation)

1. Family DA enables strike MM.
2. Separate strike DB — every clip has hit Anim Notify windows.
3. Attack press → stick/cone score (no magnet) → optional Motion Warp → chooser → notify → capsule / optional bUseSocketSweep → server GE.
4. Implementer detail: melee-drive-guns-singularity.md.

11.3 Parkour (Wall Run — MM at enter/exit only)

Lock: 2026-11-07-wall-run-motion-matching-design.md.

Wall Run mid-stint is one authored L/R cycle — not a wall Pose Search database.

1. CMC publishes FWallRunAnimQuery + tags TFA.Move.WallRunning · TFA.Move.WallRun.Left / .Right.
2. Enter: blend / short enter clip out of ground PSD_TFA_Loco (when bTFA_UsePoseSearchLoco) → WallRun_L_Cycle / WallRun_R_Cycle.
3. While stuck: play that cycle; Orientation Warp → RunTangent; suspend lower Pose Search.
4. Exit / peel / land: clear wall tags → resume PSD_TFA_Loco (or legacy if ground gate off).

Do not author PSS_TFA_WallRun / PSD_TFA_WallRun for v1. No bTFA_UsePoseSearchWallRun gate.

Wire order: CMC wall mode + L/R cycles → AnimBP override while tagged → enter/exit blends against ground MM → design §8 AC.

Parkour Vault is WILL NOT USE (FS-MOV-003) — do not author vault montage or vault Pose Search overrides.

---

12. Net and anti-cheat

Do	Don’t
Client predict MM	Second full pose stream as authority
CMC server owns move	Anim-driven teleport
Hits: rewind + notify geometry	MM clip proves HP
Remotes: movement + TPP anim	Trust client trajectory for damage

AI bots: same AnimBP; server owns bot CMC; TFAAI ≠ damage.

---

13. Acceptance

Demo

AC	Pass
Upper/lower	ADS/fire/reload overlays while moving
Loco	Start/stop/pivot via Pose Search
Stance tags	Correct pool while held and mid-jog swap without hard foot teleport (§8)
Look-vs-body	CMC flags + no control rotation from MM
Foot IK	Post-process after layers
Packing	PoseSearch + Motion Trajectory; no LyraGame fork
Auth	No GE from MM
Wall Run edges	Mid-stint L/R cycle (no wall PSD); enter/exit handoff to ground MM; look 180° keeps tangent (wall-run MM design §8)

Full

AC	Pass
Loco	Demo AC + Full DB coverage + §8 swap quality
Strike MM (DA on)	Chooser → notify → server GE; no magnet
Socket sweep	Optional polish; same auth
Aim-offset hook	Mesh Space spine split ready (keep Mesh Space; do not disable for swap polish)

---

14. Blueprint vs C++

Blueprints	Thin C++ (GFP)
Schema, DB, MM graph, Orientation Warping, Linked Layers, Trajectory component setup	Stance tag push if equipment is C++; rare trajectory helpers
Art iteration	Never full AnimInstance loco rewrite “for net”

---

15. Anti-patterns

Don’t	Do
Edit stock ABP_Mannequin_Base in place	TF duplicate
Full-body MM wiping Linked Layers	MM in FullBody_Locomotion only
High weight on spine in schema	Low pelvis/spine weight (~0.1)
Orient Rotation to Movement = True (strafe FPS)	Controller desired rotation + free Look
Skip Foot IK post-process	IK after weapon + aim layers
PoseSearch deps in LyraGame	TFACombat / owning GFP
Turn off Mesh Space to kill swap skate	§8 Blend Time / bridge / mirror parity
Blend Time ≈ 0 on stance tag flip	0.35–0.4 lab start; tune

---

16. Troubleshooting

Symptom	Check
Foot skate on turn	Orientation Warping after MM; trajectory samples
Snap / skate on rifle↔pistol	§8 — Blend Time, bridge clips, mirror parity; also Active Tags + Pose Match Column (§6.3)
Upper aim broken	Spine_01 blend; Mesh Space Rotation Blend; overlays still on Blend Pose 0
Floating feet on slopes	Post-Process IK after all layers (§9)
Look follows mesh	Orient Rotation to Movement must stay False
Remotes invisible / wrong	TPP OwnerNoSee only (never SetHiddenInGame for FPP); montages on TPP; same-mesh bone-hide local only

---

17. Related docs

Doc	Role
2026-11-02-motion-matching-full-design.md	Design lock
2026-11-07-wall-run-motion-matching-design.md	Wall Run L/R cycle + MM enter/exit edges
26 / 25	How-to
melee-drive-guns-singularity.md	Melee Warp / Counter
2026-11-02-melee-hit-registration-design.md	Hit auth
Kanban	?project=demo · ?project=full-game