unreal-motion-matching

Unreal 5.8 Motion Matching

Build and debug motion-matched animation

---
name: unreal-motion-matching
description: Select, build, tune, optimize, and debug Motion Matching and Pose Search animation systems in Unreal Engine 5.8. Use for Pose Search schemas and databases, trajectory queries, Pose History, channels and weights, Choosers, database filtering, starts/stops/pivots, root-motion locomotion, cost bias, pose thrashing, foot sliding, animation coverage, warping, Rewind Debugger, or the Game Animation Sample.
---

# Unreal 5.8 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`](../unreal-animation-blending/SKILL.md), movement trajectory and network
authority to [`unreal-character-movement`](../unreal-character-movement/SKILL.md), and retargeting or
post-selection IK/contact correction to [`unreal-control-rig-ik`](../unreal-control-rig-ik/SKILL.md).

## Decide whether it fits

Read [`references/system-selector.md`](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/schema-and-database.md)
- [`references/trajectory-and-pose-history.md`](references/trajectory-and-pose-history.md)
- [`references/filtering-and-choosers.md`](references/filtering-and-choosers.md)
- [`references/selection-tuning.md`](references/selection-tuning.md)
- [`references/coverage-warping-and-contact.md`](references/coverage-warping-and-contact.md)
- [`references/debugging-and-performance.md`](references/debugging-and-performance.md)
- [`references/implementation-patterns.md`](references/implementation-patterns.md)

## Required answer format

Return:

1. **Motion Matching fitness decision** and rejected alternative.
2. **Movement/root-motion/data assumptions** and coverage gaps.
3. **Schema channels/samples and why each changes selection**.
4. **Database partition and Chooser/filter rules**.
5. **AnimGraph order, trajectory source, Pose History, and overlays**.
6. **Selection-tuning changes tied to Rewind evidence**.
7. **Memory/search/LOD/network consequences and acceptance maneuvers**.

## 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`](references/sources.md) for the UE 5.8 source trail.

## Ownership boundary

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

## Decide whether it fits

Read [`references/system-selector.md`](/unreal/unreal-motion-matching/system-selector/).

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`](/unreal/unreal-motion-matching/schema-and-database/)
- [`references/trajectory-and-pose-history.md`](/unreal/unreal-motion-matching/trajectory-and-pose-history/)
- [`references/filtering-and-choosers.md`](/unreal/unreal-motion-matching/filtering-and-choosers/)
- [`references/selection-tuning.md`](/unreal/unreal-motion-matching/selection-tuning/)
- [`references/coverage-warping-and-contact.md`](/unreal/unreal-motion-matching/coverage-warping-and-contact/)
- [`references/debugging-and-performance.md`](/unreal/unreal-motion-matching/debugging-and-performance/)
- [`references/implementation-patterns.md`](/unreal/unreal-motion-matching/implementation-patterns/)

## Required answer format

Return:

1. **Motion Matching fitness decision** and rejected alternative.
2. **Movement/root-motion/data assumptions** and coverage gaps.
3. **Schema channels/samples and why each changes selection**.
4. **Database partition and Chooser/filter rules**.
5. **AnimGraph order, trajectory source, Pose History, and overlays**.
6. **Selection-tuning changes tied to Rewind evidence**.
7. **Memory/search/LOD/network consequences and acceptance maneuvers**.

## 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`](/unreal/unreal-motion-matching/sources/) for the UE 5.8 source trail.

unreal 5.8 motion matching select, build, tune, optimize, and debug motion matching and pose search animation systems in unreal engine 5.8. use for pose search schemas and databases, trajectory queries, pose history, channels and weights, choosers, database filtering, starts/stops/pivots, root-motion locomotion, cost bias, pose thrashing, foot sliding, animation coverage, warping, rewind debugger, or the game animation sample. coverage, warping, and contact coverage, warping, and contact coverage matrix inventory animation data across: - gait/speed bands and direction; - stationary starts and moving accelerations; - decelerations/stops by lead foot; - pivots and turn angles; - sustained loops and curved paths; - slopes/stairs/crouch/carry/weapon states as required; - interruption and transition poses. compare the root-motion speed distribution with the movement model. when gameplay moves faster than the fastest data, the database can repeatedly choose its maximum-speed pose; reducing that pose's weight hides the real mismatch. procedural correction use orientation, stride, and related animation-warping nodes to extend nearby data, not replace whole missing movement categories. establish a correct selected pose/root trajectory first, then add one warp and test its maximum acceptable deviation. layer leg/foot ik after the base locomotion and warping result. foot sliding checks: 1. root-motion clip speed versus capsule/trajectory speed; 2. chosen frame and phase continuity; 3. blend duration/profile; 4. stride/orientation warp scale; 5. ground-contact ik and moving-base handling. for duplicate footsteps caused by rapid adjacent pose selections, use anim notify filtering on the notify. it does not apply to notify states. do not let a cosmetic footstep notify drive authoritative gameplay. debugging and performance debugging and performance rewind debugger enable pose search and animation insights, then open tools -> debug -> rewind debugger and rewind debugger details. record the shortest gameplay segment that shows the defect. select the character, expand animation blueprint -> pose search, and inspect: - active pose; - continuing pose; - pose candidates and their color-coded feature costs; - database searched and candidates excluded; - selected clip/time, blend, trajectory, and current gameplay context. green cost cells are more favorable, red less favorable, and gray ignored. diagnose why the expected candidate lost rather than blindly raising its category weight. symptom matrix | symptom | first check | |---|---| | wrong gait/stance | chooser/database filtering | | thrashes between clips | continuing bias, reselect history, noisy trajectory | | stays in one loop | missing candidates, negative continuing/loop bias | | bad start/stop | coverage and future trajectory | | pops at selection | selectable ranges, pose continuity, blend profile | | feet slide | data/movement speed, root motion, phase, warping | | high runtime cost | search set size, channels/samples, search mode/frequency | | high memory | database density, pruning, principal components, lod | profile representative characters and databases on target hardware. compare brute force for quality diagnosis, then optimized search. reduce invalid search breadth before lowering quality. use database lod/density policies deliberately; verify that sparse tiers still preserve starts, stops, pivots, and readability. database filtering and choosers database filtering and choosers high-level context should remove invalid candidates before low-level pose cost ranks valid ones. pattern 1. convert gameplay state into stable animation-facing enums/tags/booleans: locomotion mode, stance, gait, airborne, carried-object class, injury, or traversal context. 2. evaluate a chooser in the motion matching node update function. 3. return only the pose search databases valid for that context. 4. feed the returned database array to the motion matching node. 5. optionally cache the selected database/tags in a post-selection function for downstream presentation. the game animation sample uses this pattern to prevent, for example, run data from competing while the player intends to walk. it also prevents a pivot from being interrupted by misclassifying its second half as a new start. use database partition/filtering for categorical differences. use schema weights to rank continuous differences inside a valid candidate set. use per-segment cost bias for a small preference, not to override a contradictory gameplay category. keep chooser inputs thread-safe and animation-facing. gameplay owns authoritative state; the animbp copies the minimal values it needs. define a fallback database when context is unknown and log empty search sets during development. implementation patterns implementation patterns locomotion base gameplay movement -> animation-facing state/trajectory -> chooser -> valid databases -> motion matching -> pose history -> orientation/stride warping -> leg ik -> upper-body/action slots. validate: idle-to-walk/run, stop both feet, 45/90/180-degree pivots, analog direction changes, acceleration/braking extremes, slopes, low frame rate, network correction, and animation lod. traversal entry selection gameplay detects and validates the obstacle. pose search chooses a compatible authored entry from a bounded traversal set using relative obstacle/character features. the action system then owns the committed traversal, collision/movement, interruption, and exit. do not let pose selection decide whether gameplay traversal is legal. discrete action alongside motion matching keep locomotion motion matching active as the base. play attack/reload/interact through a montage slot and layer by body region when appropriate. for full-body actions, intentionally suppress or replace base motion and define root-motion ownership. see unreal-animation-montages. retargeted database retarget clips first, verify root motion and contact across the complete dataset, then index the target data. a correct reference pose is insufficient: test starts, stops, pivots, extremes, and curves/notifies. see unreal-control-rig-ik for retarget diagnostics. network boundary replicate gameplay movement/state; let each client select cosmetic locomotion poses from equivalent data. do not replicate pose-search candidates every frame. ensure discrete authoritative actions use their own replicated gameplay contract. schema and database schema and database schema create via content browser -> add -> animation -> motion matching -> pose search schema, then assign the character skeleton. for basic locomotion begin with: - trajectory channel: a few past/future samples of position/facing/velocity that distinguish continue, start, stop, and turn intent. - pose channel: bones whose position/velocity distinguish phase and continuity, commonly feet for locomotion or hands for climbing. every channel and sample increases feature dimensionality and search work. add one only when a recorded failure cannot be separated by existing features. component stripping can ignore irrelevant axes; character-space values help localized motion comparisons. database create via add -> animation -> motion matching -> pose search database and assign the schema. 1. add compatible sequences, composites, or blend spaces needed for the bounded state. 2. for documented locomotion, ensure clips contain root motion and enable root motion is set. 3. trim/exclude unusable entry/exit ranges; preserve frames needed to blend. 4. use pose search notify states to block branch-in, exclude ranges, or bias specific intervals. 5. inspect every indexed clip in the database editor. partition by gameplay meaning—walk/run, stance, carried object, injury, traversal type—when only a subset is valid at once. a normalization set can compare related databases consistently; a chooser can select the context-valid set at runtime. prefer pcakdtree for an optimized search after verifying quality against brute force. vptree is experimental in ue 5.8. higher principal-component counts can improve represented variance while increasing memory and cost; tune with evidence. selection tuning selection tuning tune in this order: 1. candidate validity and database coverage. 2. trajectory accuracy relative to real movement. 3. bad selectable ranges and branch-in rules. 4. schema channels/samples. 5. channel and per-sample weights. 6. cost bias and reselection behavior. 7. blend time/profile and procedural warping. controls - channel/sample weight: raises that feature's influence. weights are normalized unless the schema data processor disables normalization. - continuing pose cost bias: negative favors staying; positive encourages leaving. - looping cost bias: negative favors loops; positive penalizes them. - pose reselect history: blocks recently chosen poses for the specified history window. - search throttle time: controls how often a new search occurs; higher values reduce search frequency but can delay response. - blend time/profile/mode: changes visual transition, not candidate correctness. avoid tuning by appearance alone. record the bad moment and compare active pose, continuing pose, and pose candidates. if the desired clip is absent, fix filtering/data. if present but expensive, inspect the exact feature costs. if selected but visually poor, inspect clip ranges, blend, pose continuity, root motion, warping, and ik. use pose search: override base cost bias or override continuing pose cost bias notify states for bounded clip regions. negative is a bonus; positive is a penalty. change one variable and replay the same maneuver. ue 5.8 primary sources ue 5.8 primary sources - motion matching - motion matching debugging - game animation sample project - motion match blueprint api - motion trajectory api - root motion pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, search modes, channel availability, and sample-project architecture after an engine upgrade. system selector system selector | situation | prefer | reason | |---|---|---| | large realistic locomotion set with dense transitions | motion matching | search scales with compatible data coverage | | small/stylized moveset with deliberate states | state machine/blend space | lower data/tooling cost, direct control | | one-off attack, dodge, interaction, reload | montage | explicit action lifecycle/sections/notifies | | traversal entry needs contextual pose selection | pose search/motion match query plus action system | choose a compatible entry, then own the action | | missing directional/speed coverage | author/retarget data first | weights cannot select absent motion | adoption gates: - the animation set covers the movement model's speed and direction envelope. - starts, stops, pivots, loops, and transitions have valid selectable ranges. - the team can curate schemas/databases and use rewind debugger. - memory and runtime search cost fit target platforms. - root-motion versus capsule-driven intent is explicit. start with one locomotion mode and a representative test map. do not migrate every character state before the first database proves better than the existing system under real input. trajectory and pose history trajectory and pose history minimal animgraph 1. add a motion matching node and assign its searchable database(s). 2. feed its pose through a pose history node to output pose. 3. on pose history, enable generate trajectory for the simplest documented setup, or supply the project's explicit query trajectory. 4. add every schema-sampled bone to collected bones. 5. compile, then visualize current and predicted trajectory during pie. pose history caches prior pose samples and supplies trajectory/query history used by pose search. if the schema asks for a bone that pose history does not collect, the query contract is incomplete. trajectory contract past samples describe actual recent motion; future samples describe movement intent/model prediction. positive sample offsets look forward and negative offsets look backward. build prediction from the same acceleration, braking, facing, and movement constraints the character will actually obey. symptom mapping: - starts selected too late -> future trajectory does not anticipate acceleration/input. - stops never selected -> prediction continues motion too long or stop data is filtered out. - wrong turn direction -> facing basis/coordinate space or future heading is wrong. - correct query but wrong pose -> database coverage, schema weights, bias, or candidate filtering. - query jumps after teleport -> reset history/state when the node becomes newly relevant or movement discontinuity invalidates previous samples. do not smooth trajectory until it looks plausible but sluggish. compare raw intent, predicted path, capsule movement, and selected animation in the same recording.

Coverage, warping, and contact

# Coverage, warping, and contact

## Coverage matrix

Inventory animation data across:

- gait/speed bands and direction;
- stationary starts and moving accelerations;
- decelerations/stops by lead foot;
- pivots and turn angles;
- sustained loops and curved paths;
- slopes/stairs/crouch/carry/weapon states as required;
- interruption and transition poses.

Compare the root-motion speed distribution with the movement model. When gameplay moves faster than
the fastest data, the database can repeatedly choose its maximum-speed pose; reducing that pose's
weight hides the real mismatch.

## Procedural correction

Use Orientation, Stride, and related animation-warping nodes to extend nearby data, not replace whole
missing movement categories. Establish a correct selected pose/root trajectory first, then add one
warp and test its maximum acceptable deviation. Layer leg/foot IK after the base locomotion and
warping result.

Foot sliding checks:

1. root-motion clip speed versus capsule/trajectory speed;
2. chosen frame and phase continuity;
3. blend duration/profile;
4. stride/orientation warp scale;
5. ground-contact IK and moving-base handling.

For duplicate footsteps caused by rapid adjacent pose selections, use Anim Notify filtering on the
Notify. It does not apply to Notify States. Do not let a cosmetic footstep Notify drive authoritative
gameplay.

Debugging and performance

# Debugging and performance

## Rewind Debugger

Enable Pose Search and Animation Insights, then open Tools -> Debug -> Rewind Debugger and Rewind
Debugger Details. Record the shortest gameplay segment that shows the defect. Select the character,
expand Animation Blueprint -> Pose Search, and inspect:

- Active Pose;
- Continuing Pose;
- Pose Candidates and their color-coded feature costs;
- database searched and candidates excluded;
- selected clip/time, blend, trajectory, and current gameplay context.

Green cost cells are more favorable, red less favorable, and gray ignored. Diagnose why the expected
candidate lost rather than blindly raising its category weight.

## Symptom matrix

| Symptom | First check |
|---|---|
| Wrong gait/stance | Chooser/database filtering |
| Thrashes between clips | continuing bias, reselect history, noisy trajectory |
| Stays in one loop | missing candidates, negative continuing/loop bias |
| Bad start/stop | coverage and future trajectory |
| Pops at selection | selectable ranges, pose continuity, blend profile |
| Feet slide | data/movement speed, root motion, phase, warping |
| High runtime cost | search set size, channels/samples, search mode/frequency |
| High memory | database density, pruning, principal components, LOD |

Profile representative characters and databases on target hardware. Compare Brute Force for quality
diagnosis, then optimized search. Reduce invalid search breadth before lowering quality. Use database
LOD/density policies deliberately; verify that sparse tiers still preserve starts, stops, pivots, and
readability.

Database filtering and Choosers

# Database filtering and Choosers

High-level context should remove invalid candidates before low-level pose cost ranks valid ones.

## Pattern

1. Convert gameplay state into stable animation-facing enums/tags/booleans: locomotion mode, stance,
   gait, airborne, carried-object class, injury, or traversal context.
2. Evaluate a Chooser in the Motion Matching node update function.
3. Return only the Pose Search Databases valid for that context.
4. Feed the returned database array to the Motion Matching node.
5. Optionally cache the selected database/tags in a post-selection function for downstream presentation.

The Game Animation Sample uses this pattern to prevent, for example, run data from competing while
the player intends to walk. It also prevents a pivot from being interrupted by misclassifying its
second half as a new start.

Use database partition/filtering for categorical differences. Use schema weights to rank continuous
differences inside a valid candidate set. Use per-segment cost bias for a small preference, not to
override a contradictory gameplay category.

Keep chooser inputs thread-safe and animation-facing. Gameplay owns authoritative state; the AnimBP
copies the minimal values it needs. Define a fallback database when context is unknown and log empty
search sets during development.

Implementation patterns

# Implementation patterns

## Locomotion base

Gameplay movement -> animation-facing state/trajectory -> Chooser -> valid databases -> Motion
Matching -> Pose History -> orientation/stride warping -> leg IK -> upper-body/action Slots.

Validate: idle-to-walk/run, stop both feet, 45/90/180-degree pivots, analog direction changes,
acceleration/braking extremes, slopes, low frame rate, network correction, and animation LOD.

## Traversal entry selection

Gameplay detects and validates the obstacle. Pose Search chooses a compatible authored entry from a
bounded traversal set using relative obstacle/character features. The action system then owns the
committed traversal, collision/movement, interruption, and exit. Do not let pose selection decide
whether gameplay traversal is legal.

## Discrete action alongside Motion Matching

Keep locomotion Motion Matching active as the base. Play attack/reload/interact through a Montage
Slot and layer by body region when appropriate. For full-body actions, intentionally suppress or
replace base motion and define root-motion ownership. See `unreal-animation-montages`.

## Retargeted database

Retarget clips first, verify root motion and contact across the complete dataset, then index the
target data. A correct reference pose is insufficient: test starts, stops, pivots, extremes, and
curves/notifies. See `unreal-control-rig-ik` for retarget diagnostics.

## Network boundary

Replicate gameplay movement/state; let each client select cosmetic locomotion poses from equivalent
data. Do not replicate pose-search candidates every frame. Ensure discrete authoritative actions use
their own replicated gameplay contract.

Schema and database

# Schema and database

## Schema

Create via Content Browser -> Add -> Animation -> Motion Matching -> Pose Search Schema, then assign
the character Skeleton. For basic locomotion begin with:

- **Trajectory channel**: a few past/future samples of position/facing/velocity that distinguish
  continue, start, stop, and turn intent.
- **Pose channel**: bones whose position/velocity distinguish phase and continuity, commonly feet
  for locomotion or hands for climbing.

Every channel and sample increases feature dimensionality and search work. Add one only when a
recorded failure cannot be separated by existing features. Component stripping can ignore irrelevant
axes; character-space values help localized motion comparisons.

## Database

Create via Add -> Animation -> Motion Matching -> Pose Search Database and assign the Schema.

1. Add compatible Sequences, Composites, or Blend Spaces needed for the bounded state.
2. For documented locomotion, ensure clips contain root motion and Enable Root Motion is set.
3. Trim/exclude unusable entry/exit ranges; preserve frames needed to blend.
4. Use Pose Search notify states to block branch-in, exclude ranges, or bias specific intervals.
5. Inspect every indexed clip in the database editor.

Partition by gameplay meaning—walk/run, stance, carried object, injury, traversal type—when only a
subset is valid at once. A Normalization Set can compare related databases consistently; a Chooser can
select the context-valid set at runtime.

Prefer PCAKDTree for an optimized search after verifying quality against Brute Force. VPTree is
Experimental in UE 5.8. Higher principal-component counts can improve represented variance while
increasing memory and cost; tune with evidence.

Selection tuning

# Selection tuning

Tune in this order:

1. Candidate validity and database coverage.
2. Trajectory accuracy relative to real movement.
3. Bad selectable ranges and branch-in rules.
4. Schema channels/samples.
5. Channel and per-sample weights.
6. Cost bias and reselection behavior.
7. Blend time/profile and procedural warping.

## Controls

- **Channel/sample weight**: raises that feature's influence. Weights are normalized unless the
  schema Data Processor disables normalization.
- **Continuing Pose Cost Bias**: negative favors staying; positive encourages leaving.
- **Looping Cost Bias**: negative favors loops; positive penalizes them.
- **Pose Reselect History**: blocks recently chosen poses for the specified history window.
- **Search Throttle Time**: controls how often a new search occurs; higher values reduce search
  frequency but can delay response.
- **Blend Time/Profile/Mode**: changes visual transition, not candidate correctness.

Avoid tuning by appearance alone. Record the bad moment and compare Active Pose, Continuing Pose,
and Pose Candidates. If the desired clip is absent, fix filtering/data. If present but expensive,
inspect the exact feature costs. If selected but visually poor, inspect clip ranges, blend, pose
continuity, root motion, warping, and IK.

Use `Pose Search: Override Base Cost Bias` or `Override Continuing Pose Cost Bias` notify states for
bounded clip regions. Negative is a bonus; positive is a penalty. Change one variable and replay the
same maneuver.

UE 5.8 primary sources

# UE 5.8 primary sources

- [Motion Matching](https://dev.epicgames.com/documentation/en-us/unreal-engine/motion-matching-in-unreal-engine)
- [Motion Matching Debugging](https://dev.epicgames.com/documentation/en-us/unreal-engine/motion-matching-debugging-in-unreal-engine)
- [Game Animation Sample Project](https://dev.epicgames.com/documentation/en-us/unreal-engine/game-animation-sample-project-in-unreal-engine)
- [Motion Match Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Animation/PoseSearch/MotionMatch)
- [Motion Trajectory API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/MotionTrajectory)
- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)

Pages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,
search modes, channel availability, and sample-project architecture after an engine upgrade.

System selector

# System selector

| Situation | Prefer | Reason |
|---|---|---|
| Large realistic locomotion set with dense transitions | Motion Matching | search scales with compatible data coverage |
| Small/stylized moveset with deliberate states | State Machine/Blend Space | lower data/tooling cost, direct control |
| One-off attack, dodge, interaction, reload | Montage | explicit action lifecycle/sections/notifies |
| Traversal entry needs contextual pose selection | Pose Search/Motion Match query plus action system | choose a compatible entry, then own the action |
| Missing directional/speed coverage | Author/retarget data first | weights cannot select absent motion |

Adoption gates:

- The animation set covers the movement model's speed and direction envelope.
- Starts, stops, pivots, loops, and transitions have valid selectable ranges.
- The team can curate schemas/databases and use Rewind Debugger.
- Memory and runtime search cost fit target platforms.
- Root-motion versus capsule-driven intent is explicit.

Start with one locomotion mode and a representative test map. Do not migrate every character state
before the first database proves better than the existing system under real input.

Trajectory and Pose History

# Trajectory and Pose History

## Minimal AnimGraph

1. Add a Motion Matching node and assign its searchable Database(s).
2. Feed its pose through a Pose History node to Output Pose.
3. On Pose History, enable Generate Trajectory for the simplest documented setup, or supply the
   project's explicit query trajectory.
4. Add every schema-sampled bone to Collected Bones.
5. Compile, then visualize current and predicted trajectory during PIE.

Pose History caches prior pose samples and supplies trajectory/query history used by Pose Search.
If the schema asks for a bone that Pose History does not collect, the query contract is incomplete.

## Trajectory contract

Past samples describe actual recent motion; future samples describe movement intent/model prediction.
Positive sample offsets look forward and negative offsets look backward. Build prediction from the
same acceleration, braking, facing, and movement constraints the character will actually obey.

Symptom mapping:

- Starts selected too late -> future trajectory does not anticipate acceleration/input.
- Stops never selected -> prediction continues motion too long or stop data is filtered out.
- Wrong turn direction -> facing basis/coordinate space or future heading is wrong.
- Correct query but wrong pose -> database coverage, schema weights, bias, or candidate filtering.
- Query jumps after teleport -> reset history/state when the node becomes newly relevant or movement
  discontinuity invalidates previous samples.

Do not smooth trajectory until it looks plausible but sluggish. Compare raw intent, predicted path,
capsule movement, and selected animation in the same recording.