UE5.8 Unreal Animation Framework 专题系列

UE5.8 UAF 专题（六）：Pose Search、Pose History 与 Motion Matching

讲 UAFPoseSearch 中 MotionMatchingTrait、HistoryCollectorTrait、PoseHistory、Trajectory、PoseSearchDatabase、交互、Warp 和结果变量写回。

UE5.8 UAF Pose Search Motion Matching Trajectory
开始阅读 专题总览

总览

UAFPoseSearch 把 UE 的 Pose Search / Motion Matching 能力包装成 UAF Trait。它不是重新实现数据库搜索，而是把历史姿态、轨迹、搜索参数、结果发布、交互和 Warping 接入 UAF 的 Update/Evaluate 流程。

UE5.8 UAF 专题（六）：Pose Search、Pose History 与 Motion Matching 配图
Motion Matching 需要历史姿态、轨迹、数据库、搜索节流和结果发布，UAF 用 Trait 把这些接到图评估里。

源码依据

重点文件：

  • UAFPoseSearch/Internal/MotionMatchingTraitData.h
  • UAFPoseSearch/Private/MotionMatchingTrait.h
  • UAFPoseSearch/Internal/HistoryCollectorTraitData.h
  • UAFPoseSearch/Public/IPoseHistory.h
  • UAFPoseSearch/Public/PoseHistoryEvaluation.h
  • UAFPoseSearch/UncookedOnly 下的 Motion Matching graph node template 和 chooser 参数

FMotionMatchingTraitSharedData 是这层的核心配置。它的字段非常多，能看出 UAF 不是只包了一个“Search Database”按钮，而是覆盖了生产 Motion Matching 的关键控制面。

MotionMatchingTrait 的数据面

关键字段可以分成几组：

分组 字段 用途
数据库 Databases 一个或多个 UPoseSearchDatabase
混合 BlendArguments、BlendProfile 切换到新结果时的混合参数
搜索控制 bShouldSearch、SearchThrottleTime、PoseReselectHistory、PoseJumpThresholdTime 控制何时搜索、避免重复选择和近距离跳转
BlendSpace XAxisSamplePoint、YAxisSamplePoint、bUpdateBlendSpaceInputs、bTrySkipBlendsForBlendSpaces 支持结果是 BlendSpace 的情况
同步 SyncMode 动画组同步模式
结果发布 MotionMatchingResultVariableName、MotionMatchingResultSystemReference、Alt 版本、AlignmentTransformVariableName 把搜索结果写回 UAF 变量
交互 Availabilities、bValidateResultAgainstAvailabilities、bKeepInteractionAlive 多角色/交互 Motion Matching
Warp bEnableWarp、bWarpUsingRootBone、旋转/位移比例和曲线名 交互结果的对齐修正

Trait 实例数据里保存 FMotionMatchingState MotionMatchingState。FMotionMatchingTrait 实现 IUpdate、IEvaluate 和 IGarbageCollection。Update 阶段做搜索状态推进和结果发布，Evaluate 阶段通过 FAnimNextMotionMatchingTask 接入 EvaluationVM。

Pose History

Motion Matching 需要历史姿态。FAnimNextHistoryCollectorTraitSharedData 提供：

  • PoseCount
  • SamplingInterval
  • CollectedBones
  • CollectedCurves
  • bResetOnBecomingRelevant
  • bStoreScales
  • Root bone recovery 参数
  • bGenerateTrajectory
  • Trajectory
  • TrajectorySpeedMultiplier
  • TrajectoryHistoryCount
  • TrajectoryPredictionCount
  • PredictionSamplingInterval
  • PoseHistoryReferenceVariable
  • TrajectoryData

如果 bGenerateTrajectory 为 false，它使用输入轨迹；如果为 true，它根据 FPoseSearchTrajectoryData 自行生成轨迹。源码注释强调轨迹样本期望在 SkeletalMeshComponent 的 world space 中。

查询与评估流程

典型流程：

  1. History Collector 在 Update/Evaluate 过程中维护历史姿态。
  2. Motion Matching Trait 读取数据库、轨迹、当前 continuing pose 和搜索控制参数。
  3. 按 throttle 和 interrupt 模式决定是否搜索。
  4. 选择结果后通过 blend 参数切到目标资产或图。
  5. 可选地发布 MotionMatchingResult 和对齐 Transform 到变量。
  6. EvaluationVM 执行 FAnimNextMotionMatchingTask，处理结果相关的 pose 和 warp。

项目落地

Motion Matching 的落地要先设计数据，而不是先连节点：

  1. 为 locomotion 建一个 schema 稳定的 PoseSearchDatabase。
  2. 只采必要骨骼，CollectedBones 过多会直接影响历史采样和查询成本。
  3. 让移动组件或运动模型提供可解释的 trajectory。
  4. SearchThrottleTime 先从 0 开始验证质量，再为大量 NPC 或低优先级角色做分帧搜索。
  5. PoseReselectHistory 默认 0.3 秒是为了防抖，不要轻易改成 0。
  6. 把结果写回变量，便于 Rewind Debugger、日志和 gameplay 联动。

配置示意：

Pose History
  PoseCount: 8
  SamplingInterval: 0.04
  CollectedBones: pelvis, thigh_l, thigh_r, foot_l, foot_r
  bGenerateTrajectory: false

Motion Matching
  Databases: DB_Locomotion
  SearchThrottleTime: 0.0
  PoseReselectHistory: 0.3
  PlayRate: [0.85, 1.15]
  MotionMatchingResultVariableName: MotionResult

使用案例：只替换地面移动层

最推荐的 Motion Matching 试点是“地面 locomotion 层替换”，不要同时替换跳跃、攻击、受击和交互。目标图可以这样拆：

AG_Hero_Locomotion
  Chooser: bIsInAir
    false -> AG_Hero_Grounded_MM
    true  -> AG_Hero_InAir_Sequence

AG_Hero_Grounded_MM
  History Collector
  Motion Matching
  Optional Strafe Warping
  Optional Offset Root Bone

资产准备步骤：

  1. 整理 locomotion 动画库，只放同骨架、同风格、同速度标定的资产。
  2. 建 PoseSearchDatabase，先只覆盖 Idle、Start、Stop、Walk、Run、Turn，不要一开始塞交互动作。
  3. 统一 trajectory 来源。CharacterMovement 项目可以先用移动组件预测轨迹，再逐步换成更精细的运动模型。
  4. History Collector 先采下肢和 pelvis，曲线只采对搜索有贡献的。
  5. Motion Matching Trait 里显式配置 MotionMatchingResultVariableName，把结果写到 MotionResult。
  6. 第一轮关闭 interaction warp，只验证搜索结果；第二轮再打开 warping 修正。

质量验收可以分三档：

指标 通过标准 失败信号
搜索质量 起步、停步、转向能选到相近 pose 原地转向总选跑步片段
稳定性 同一片段不会短时间内反复重选 PoseReselectHistory 过低导致抖动
性能 主角每帧搜索可接受，NPC 可节流 多库不同 schema 导致查询成本上升

使用案例：交互动作对齐

UAFPoseSearch 里有 Availabilities、bValidateResultAgainstAvailabilities、bKeepInteractionAlive 和 experimental warp 字段，说明它不只面向普通 locomotion，也考虑了交互 Motion Matching。比如近战处决、双人同步开门、扶起队友，可以按这个路线试：

  1. 交互系统生成候选 availability，包括参与者、交互点和期望朝向。
  2. UAF 公共变量写入目标 Transform 或交互约束。
  3. Motion Matching Trait 搜索交互数据库，并验证 result 是否仍满足 availability。
  4. 搜索通过后写 AlignmentTransform，交给 Warping 或 Root Motion provider 对齐。
  5. 交互结束后清空 availability，回到普通 locomotion 数据库。

这类功能风险高，建议和普通 locomotion 数据库分开，不要让主移动层每帧背着交互约束跑。

架构分析：数据库、轨迹和图的边界

内容 放在哪里 注意事项
动画资产集合和 feature schema PoseSearchDatabase schema 改动会影响所有查询结果
当前速度、期望方向、未来点 UAF 变量或 trajectory data 坐标空间要统一，源码注释期望 world space trajectory
选择频率、防抖、play rate Motion Matching Trait SearchThrottleTime、PoseReselectHistory 是性能和稳定性的旋钮
图切换和 fallback UAF AnimGraph / Chooser 空中、受击、剧情锁定可以切回传统图
对齐修正 Warping / Root Motion provider 先验证搜索，再开 warp

调试建议

  • 先检查 trajectory 是否跟角色移动方向一致。
  • 再检查 PoseHistory 是否采到了足够骨骼和曲线。
  • 数据库 schema 不一致时，bShouldUseCachedChannelData 的收益和风险要单独验证。
  • 如果 BlendSpace 结果抖动，检查 bTrySkipBlendsForBlendSpaces 和 MaxDeltaAssetTimeToTrySkipBlendsForBlendSpaces。
  • 交互 Motion Matching 先关闭 bEnableWarp 验证选择，再开 Warp 处理对齐。

常见坑

  • Motion Matching 不是“数据库越多越好”。多库和不同 schema 会增加查询和调试成本。
  • 不要用不稳定的 gameplay 速度直接喂 trajectory，先做滤波和坐标空间确认。
  • SearchThrottleTime 增大能省性能，但也会降低反应速度。
  • 结果变量名为空时，外部系统看不到结果；需要调试联动时应显式配置。
  • Warp 对交互很有用，但源码里也标了 Experimental 提醒，不要把它当唯一对齐方案。

源码路径索引

  • UAFPoseSearch/Source/UAFPoseSearch/Internal/MotionMatchingTraitData.h
  • UAFPoseSearch/Source/UAFPoseSearch/Private/MotionMatchingTrait.h
  • UAFPoseSearch/Source/UAFPoseSearch/Internal/HistoryCollectorTraitData.h
  • UAFPoseSearch/Source/UAFPoseSearch/Public/IPoseHistory.h