scenario-unreal-animation

Unreal 动画（技术动画师）

专家级意味着角色在游戏播放的每个片段中都能保持接触，针对会在输入帧改变类别的移动模型制作的移动动画，在目标平台上测得耗时毫秒数的动画，以及从源头就保持干净的数据。Agent 通过数据和模板开展工作：编写脚本创建资产、IK Rigs、重定向器、数据库和设置；复制 Epic 的 AnimBPs，而不是绘制图表；以数值测量接触，然后再查看帧。如果此处提到的相关技能不在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无人值守，请根据工具架构继续操作，并标明缺失项。

必备背景： scenario-unreal-expert（通道、审查循环、5.8 陷阱）。

状态（2026-09-24）： 尚未安装 Unreal。离线层 scripts/ue_anim.py 已通过 30 项测试（python3 tests/code/unreal-animation/run_all.py --offline）。所有编辑器内代码片段尚未在 Unreal 中运行；[verify] 项由 job_00_anim_probe.py 作答。导入方式：sys.path[:0] = ["<skills>/scenario-unreal-animation/scripts", "<skills>/scenario-unreal-expert/scripts"]; import ue_anim as A。

立场（专家经验差异）

• 先选择成本最低的转移方式，再由重定向顺序决定接触效果。 骨架相同或兼容时，使用 Copy Pose From Mesh 或 Leader Pose，优于 IK Retargeter（Greg Richardson，-8CQNaODNNA [00:02:40]-[00:06:04]）。重定向时：创建新的命名重定向姿势（切勿使用 Default），并启用自动对齐、贴合地面，膝盖和肘部略微弯曲；在顶部只缩放一次源骨架，并依据 IK 目标判断效果。出现腿部 IK 问题或脚部下沉时，使用 Blend to Source。自动导出的重定向器默认关闭 IK（Richardson [00:08:13]、[00:16:29]、[00:21:26]、[00:29:14]）。固定游戏逻辑读取的 IK 辅助骨骼（ik_foot_l/r、ik_hand_gun）；一次性修正应放在 Additive Pose 操作中，而非基础姿势中（Richardson [00:33:16]；5.8 重定向文档）。
• 先确定移动模型，再据此制作动画。 配合粗略动画调整胶囊体速度、加速度和制动，直到效果理想；导出胶囊体轨迹，在容差范围内让根骨骼与胸部（而非髋部）逐帧精确对齐；身体越过目标位置时，设置 5 帧停顿。这样可以区分动画问题和系统问题（GASP 团队、Tony，mhVp_cC9MLc [00:24:25]-[00:28:43]；Dustin DeVoe，FLDXtAV7qsw [00:06:27]-[00:08:40]）。
• 运动匹配是由设计师掌控的数据。 按移动状态拆分数据库，使用基于缓存枚举的 Chooser 选择数据库；仅当核心状态在当前帧发生变化时才中断；即使由胶囊体驱动，也要在每个移动片段中启用根运动（GASP 团队 [00:29:43]-[00:40:54]、[01:30:00]）。权重用于表达对覆盖率较低、效果不完美的候选项的偏好（Sam [00:49:01]）；权重无法修正速度或覆盖率不匹配的问题，后期调整应使用通知状态标签，而非架构权重（Jose，tNw9lD2PW3U [00:18:28]；运动匹配文档）。
• 小型动画集也能配合程序化节点投入使用。 13 个片段可提供非侧移基础，26 个可支持侧移，60 到 80 个可覆盖多种状态；每种开始、停止和转向开始动作都要包含左右脚两种情况（DeVoe [00:11:14]-[00:14:44]）；“认为必须覆盖所有情况，这种说法并不准确”（GASP [01:21:06]）。数据稀疏时，应使用 Steering、Offset Root Bone、脚部放置和网格空间叠加，而不是状态机（DeVoe [00:28:19]-[00:31:40]）。
• 让 AnimBP 脱离游戏线程运行，并为根运动分配预算。 使用线程安全更新、Property Access，并在每个节点上启用快速路径（Matthew Lake，N_suMyUuork [00:12:44]-[00:16:53]）。Root Motion from Everything 和 Montages Only 都会让 AnimGraph 在游戏线程上更新（根运动文档；Lake [00:13:18]）。选择 Montages Only 是因为胶囊体驱动的移动网络性能更好，而非为了节省线程：应为其开销预留预算；没有根运动蒙太奇的角色可以使用 No Root Motion Extraction【根据文档措辞推断，请在 Insights 中验证】。
• 从源头清理，并降低不可见内容的更新频率。 移除扭转、面部和变形轨道以及 Maya 辅助曲线后，单个片段的存储空间减少了 71%，内存减少了 90%；导入默认值应按整个项目设置，而非逐个资产设置（Lake [00:05:15]-[00:07:21]）。仅将 Tick Pose When Rendered 设为项目默认值，并使用预算分配器或 URO（二者不可同时启用），以及一个带滞后的 LOD Settings 资产（Lake [00:21:13]；AnimBP 文档）。
• Control Rig：Construction 阶段缓存，Forwards Solve 每帧执行。 转换为 C++ 前先进行性能分析（图表为 60 µs，Rig Unit 为 10 到 16 µs）；FBIK 用于调整姿势，而非生成姿势；应排除骨骼，而不是锁定它们；Backwards Solve 可让 Rig 烘焙（Stéphane Biava，XYMad1EutcA [00:10:08]；LEGO Fortnite 技术动画师，kO6pz8ADgcU [00:12:04]）。
• 切勿发布电影级 MetaHuman。 烘焙后约 800 MB，Optimized High 约 60 MB；在 PS5 级别的设备上，从 LOD 2 开始通过游戏摄像机查看各 LOD；Mac 只渲染卡片（DeVoe，tTgMafRAM7A [00:15:16]、[00:23:34]）。

首先确定

输入	影响	未明确说明时的默认值
平台、帧预算、屏幕上的角色数量	预算、LOD、分配器、运行时重定向还是离线重定向	主机级 60 fps；动画占比参考 scenario-unreal-performance
多人游戏、英雄角色保真度	胶囊体还是由根运动驱动	多人游戏：由胶囊体驱动，蒙太奇中使用根运动；单人游戏中需要原地转向的英雄角色：通过根运动属性评估由根运动驱动的方案（Jose [00:33:25]-[00:34:29]）；Mover 5.8 增加了 ChaosMover 轨迹预测，但仍处于 Experimental 阶段
移动模型：各方向速度、加速度、制动	每个动画片段的时长	重用 GASP 数据时沿用 GASP 的速度；创作前先调优
动画片段集：GASP、动作捕捉、手工关键帧、数量	动作匹配还是状态机	使用带程序化节点的动作匹配；仅在需要显式控制每个状态时，才使用状态机加扭曲（Lyra）
游戏玩法需求	侧向移动和状态会使内容量倍增（每个状态几乎都会使其翻倍，DeVoe）	面向移动方向、行走、跑步、跳跃
来自 DCC 的骨架约定	骨骼链、IK 骨骼、根骨骼	scenario-maya-rigging 的 game_skeleton_check 检查通过

工作流

1. 每种引擎只探测一次。 无头运行 job_00_anim_probe.py。门槛：probe.json 列出 IK Rig、重定向器、Pose Search、AnimPose、Interchange、MetaHuman 名称，以及是否存在 5.8 BlueprintGraphEditor。
2. 接收并审核角色。 使用 A.import_character / A.import_animations（任一导入器均显式指定选项），然后执行 A.import_audit(A.skeletal_mesh_facts(mesh))：一个根骨骼、未使用的骨骼（5.8 Bone Count Reduction）、超过 8 个的影响骨骼、单位。一次性设置项目范围的导入默认值：对旧版导入器执行 A.apply_ini_plan(cfg, A.import_defaults_plan())，对 Interchange Import Content 堆栈中的项目管线执行相应设置。门槛：无错误；在中性光照预览中检查网格体。
3. 选择转移方式。 A.transfer_method(source, target)。门槛：记录方式和原因。
4. IK Rigs。 使用 A.create_ik_rig（5.8 模板会在脚踝处拆分 Leg，并添加 Foot 链），自定义名称使用 A.biped_chain_plan。门槛：A.chain_map_check 检查通过。
5. 重定向器，构建一次，再制作模板。 A.create_retargeter；在 GUI 中设置一次操作选项，并保存为 RTG_Template；使用 A.ik_bone_pin_plan(bones, A.mannequin_bone_map(bones, parents)) 固定骨骼。门槛：A.op_stack_check(ops, proportions_differ=True, target_ik_bones=..., runtime=..., profile_ops_us=...) 检查通过；A.retarget_log_check 检查 Retarget Output Log 通过；为任何运行时重定向器设置 LOD 阈值和 Profile Ops。
6. 批量重定向并清理。 执行 A.batch_retarget(..., retain_additive=True)；使用专属重定向器处理动作捕捉（Filter Bones、Generate From Target Pelvis）；执行 A.anim_content_audit、A.ensure_root_motion、A.strip_curves。门槛：对走路、跑步、转身、蹲伏、跳跃、一个接触动作片段和一个动作捕捉片段执行 A.compare_contact；执行 A.root_motion_check；从侧面和正面检查接触帧。
7. 移动模型和制作好的动作片段。 按步态和方向调整移动组件；导出胶囊体轨迹（5.6+ 使用 Rewind Debugger > Trajectories export，否则使用 Take Recorder）到 scenario-maya-animation 或 scenario-blender-animation。门槛：A.capsule_match（根骨骼沿路径移动、胸部在容差范围内、根骨骼随胶囊体停止）和返回的动作片段上的 A.speed_parity 检查通过。
8. 移动架构。 执行 A.decide_locomotion(...)。运动匹配：迁移 GASP，执行 A.motion_matching_coverage（脚部配对、捕捉形状）、A.database_plan，复制 schemas 和 databases，然后重新映射每个 mannequin 骨骼名称： A.schema_bone_check(A.schema_facts(s)["bones"], bones, bone_map)；在 GUI 中设置 Pose History 骨骼；设置标签、通知筛选、重复保护。程序化节点：执行 A.procedural_order_check、A.offset_root_bone_modes。门槛：在 PIE 中循环每个状态时，“no database”警告为零；使用 Rewind Debugger 检查每个过渡帧；通过静止摄像机，以 0.25 倍时间缩放检查起步、停止和转向。
9. 根运动和蒙太奇。 执行 A.root_motion_mode_check(mode, multiplayer, montage_root_motion)、A.montage_blend_out_check；通过 JustTraversed database 处理穿越动作片段的尾段。门槛：混出窗口内无根速度；show collision 胶囊体与网格体保持一致；测量游戏线程。
10. 脚部 IK。 GASP 5.4 的腿部 IK 只会将脚锁定到 IK 脚骨骼，不会适应地面 [验证当前 GASP]；斜坡和楼梯需要 Foot Placement 或使用 FBIK 的 Control Rig（A.fbik_foot_defaults(mannequin_like=False) 会重新推导膝盖轴）。Sequencer 镜头：先在 mannequin 上使用 CR_GroundAlignment，然后进行重定向。门槛：捕捉楼梯和 30 度斜坡；逐帧检查脚部间隙，确保无跳变、无抖动。
11. 性能检查。 执行 A.anim_ini_plan、A.animbp_settings、A.compile_and_scan、A.allocator_config_check、A.lod_settings_check。门槛：在同一路径上分别于优化前后运行 stat anim、stat unit 和 Insights。
12. 交付：按交接要求交付，并注明未经验证的内容。

数值

数值	相对于	来源
GASP 速度：步行约 2、侧移 3.5、跑步 5 m/s	移动模型和动画片段	GASP 团队 [01:27:17]
胶囊体停止 5 帧；根节点偏移半径约 30 cm	胶囊体	GASP 团队 [00:27:38]、[01:52:15]
转向所需朝向提前 0.5 s	轨迹	Jose [00:29:50]
Notify Recency Time Out 为 0.2 s；权重示例：Pose 为 1，Trajectory 为 3	Motion Matching 节点、架构	Motion Matching 文档
最小集合包含 13、26、60 至 80 个动画片段（GASP 超过 500 个）	移动	DeVoe
a.Budget.BudgetMs 为 1.0（默认值）、1.5、2.0、2.5	游戏线程，ViewDistanceQuality 为 0 至 3	AnimBP 文档
最大骨骼影响数：8（LOD0）、4、1（最后一级）	骨骼 LOD	Lake；Biava
FBIK：骨盆刚度 0.8，膝盖首选 Z 轴角度 45，脚踝 -70..70	人形骨架关节轴	Control Rig 文档
Filter Bones：响应度 0.3 至 0.8，速度截止频率 15 至 30 Hz，低于帧率的一半	动作捕捉	重定向文档
MetaHuman 姿势驱动器在 PS5 上每个角色耗时 1.4 ms，之前为 5.6 ms，之后约为 0.4 ms	每个角色	DeVoe
接触容差为 1 至 2 cm；根节点位于胶囊体上方 2 cm；胸部 30 cm	着地帧、制作的动画片段	[新增] 默认值

没有来源给出每个角色的毫秒预算：请从 scenario-unreal-performance 中获取动画所占预算。

质量门槛

• **代码：**每个工作流门槛的 A.* 检查，由 verdict(issues) 汇总，且不得有错误。
• 引擎数值：stat anim、stat unit、Insights（动画通道、游戏线程 AnimGraph 更新）、stat group PoseSearch（5.8 个名称）、a.Budget.Debug.Enabled 1、重定向配置文件操作。
• **视觉（ue_review）：**接触帧侧面和正面、原生状态居中、0.25 倍速移动、楼梯和斜坡、远距离 LOD。使用 references/critique.md 评分。

常见错误

错误	表现形式	修复
导入动画时未指定目标骨架	动画片段无法播放；出现多余的 <Mesh>_Skeleton	始终传入骨架
腿部 IK 未启用 Blend to Source	脚部在较矮的目标上陷入地面	启用 Blend to Source；如果手部伸得过远，则调高顶部的 Scale Source
IK 辅助骨骼未固定	腿部或武器 IK 使用参考姿势骨骼	按 ik_bone_pin_plan 固定骨骼
批处理时使用自动生成的重定向器	IK 异常，忽略覆盖设置	使用手动构建的重定向器
调优移动模型前就制作动画片段	每个片段都要重新定时；动画与系统错误混杂	先调优模型，再进行 capsule_match
在自定义骨架上复制 GASP 架构	通道读取缺失的人形骨骼，选取效果不佳	使用 schema_bone_check，采用架构骨架，并重建镜像表
使用一个大型数据库并调优权重	起步效果改善，但停止动作出问题	按状态拆分，使用 Chooser，并在核心状态变化时中断
因为动画集较小而选择状态机	过渡僵硬	使用精简动画集并搭配程序化节点
键盘输入时在 Offset Root Bone 后进行 Steering，或不进行 Steering	选择频繁抖动	将 Steering 放在前面，并且仅在移动或处于空中时启用
选择 Montages Only 是为了“让图表在工作线程上运行”	未计入预算的游戏线程开销	两种模式都会在游戏线程上运行图表；设置预算，或选择 No Root Motion Extraction
Blend Out Trigger Time 为 -1，且根骨骼仍在移动	位移动作结束后仍出现行走循环帧	将触发时间设为 0，或让根运动提前结束
分配器节点未启用 a.Budget.Enabled，或同时使用分配器与 URO	没有作用，节流行为令人困惑	启用两个开关；切勿同时使用这两种系统
在墙边使用 Offset root bone	网格体穿进墙壁	在墙边缩小半径，或使用支持碰撞检测的轨迹

交接

• 接收自 scenario-maya-rigging、scenario-maya-animation、scenario-blender-rigging、scenario-blender-animation，直至 scenario-unreal-pipeline-automation： FBX 2020.2、cm、原点处的单个根节点、仅包含关节、每个文件一个片段、game_skeleton_check JSON。Blender 文件来自 scenario-blender-export 的 unreal_skeletal 预设。
• 交付给 scenario-maya-animation 或 scenario-blender-animation： 导出的胶囊体轨迹、各方向的速度、加速度和制动数据、停止规格、胸部容差、包含双脚的片段列表。
• 交付给 scenario-unreal-gameplay： 角色 Blueprint 子类（GASP 或 Lyra）、AnimBP 变量约定（步态、姿态、移动模式、旋转模式）、带有扭曲目标的蒙太奇、移动模型数值，以及备注：CMC 输入加速度需要通过 C++ 复制，才能支持多人游戏轨迹。
• 交付给 scenario-unreal-cinematics： 重定向后的片段、可烘焙的 Control Rig、CR_GroundAlignment 指南；MetaHuman Cine 仅用于预渲染镜头。
• 向 scenario-unreal-performance 索取动画预算和目标捕获数据。

UE 5.8 说明

• Retargeter：操作栈（5.6）、Override Sets 取代 Retarget Profiles、脚部定义和地面约束、Blend to Source、Scale Goals、Offset Goals 作为独立的 Run IK Rig 子操作；重新保存 5.8 之前的 Retargeter。
• Pose Search：DatabaseAnimationAssets（5.7）、Chooser 列数据库默认使用 Brute Force、...FromContext 通道获取器、重命名的统计信息、“Block Transition In”。
• unreal.BlueprintGraphEditor 是 5.8 中编辑 Blueprint 图表的方式；是否支持 AnimGraph 节点尚待[验证]：尝试使用副本，否则使用模板和计算机操作。
• Interchange：资产导入已可用于生产（5.5）、默认用于 FBX 关卡导入（5.6）、对话框已重新设计（5.8）；FBX 资产导入的默认设置尚待[验证]，因此请为两种导入器都传递选项。
• Control Rig：Construction Event、Physics Beta、Dynamics Experimental；已移除 FSmartName 和 5.0 至 5.6 的动画 API。
• MetaHuman：先运行 ConvertLegacyDNAAssets -DryRun；面部 MetaHuman Animator 仅适用于 macOS，身体仅适用于 Windows。
• 实验性功能，需准备备用方案：Animation Mixer、Direct Mesh Controls、uFBX、MetaHuman Crowd、MotionMatchMulti。Mover 仍处于 Experimental 状态。

参考资料

• references/procedures.md：每个阶段的完整代码、测试路径、状态；任何脚本化步骤执行前都要查阅。
• references/expert-notes.md：专家判断、分歧和决策条件。
• references/critique.md：自我审查标准；每个关卡都要查阅。
• references/gui-paths.md：供计算机操作 Agent 使用的编辑器、菜单和设置。
• references/sources.md：所有来源、凭据、URL、最佳时间戳和修订历史。