Motion Matching

Ownership boundary

This skill owns Pose Search data, filtering, query construction, and selection cost. Route final AnimGraph layering/transitions to unreal-animation-blending, movement trajectory and network authority to unreal-character-movement, and retargeting or post-selection IK/contact correction to unreal-control-rig-ik.

Decide whether it fits

Read references/system-selector.md.

Use Motion Matching when a sufficiently broad, coherent animation set should drive responsive locomotion or traversal through runtime pose selection. Keep a State Machine/Blend Space when the moveset is small, stylized, intentionally discrete, or lacks the data coverage to justify search.

Motion Matching does not manufacture missing motion. Coverage, trajectory quality, database filtering, and movement-model agreement matter before weight tuning.

Execute

1. Define movement states, required transitions, target skeleton, and root-motion contract.
2. Audit clips for speeds, directions, starts, stops, pivots, loops, contacts, and bad frames.
3. Enable Pose Search and create the smallest useful Schema.
4. Build focused Databases with compatible Schema and correctly prepared animation assets.
5. Add Motion Matching and Pose History to the AnimGraph; generate or supply trajectory.
6. Use gameplay context and Choosers to restrict which databases can be searched.
7. Diagnose selection in Rewind Debugger before changing weights or adding warping.
8. Add bias, notifies, warping, IK, and performance tuning one measured need at a time.

Load only what applies:

• references/schema-and-database.md
• references/trajectory-and-pose-history.md
• references/filtering-and-choosers.md
• references/selection-tuning.md
• references/coverage-warping-and-contact.md
• references/debugging-and-performance.md
• references/implementation-patterns.md

Hard rules

• Enable the Pose Search plugin and use compatible skeleton/schema/database assets.
• UE's documented locomotion setup expects root-motion animation with Root Motion enabled.
• Use the fewest trajectory and pose samples that distinguish the required motions.
• Search only context-valid databases; do not use weights to make impossible states compete.
• Negative cost bias makes a pose/category more likely; positive bias penalizes it.
• Fix data coverage or movement-speed disagreement before suppressing symptoms with weights.
• Use Pose Search notify states to exclude invalid ranges or control branch-in eligibility.
• Anim Notify filtering can suppress repeat Notifies but does not filter Notify States.
• Diagnose with Rewind Debugger selection candidates/costs before changing several variables.
• Treat VPTree, Permutation Time, Crashing Legs, and Character Blueprint montage selection according to their Experimental UE 5.8 status.
• Keep discrete gameplay actions in unreal-animation-montages; layer final IK after the base pose.

See references/sources.md for the UE 5.8 source trail.