blender-animation

动画

执行模型位于 blender-core（其中的 references/bpy-patterns.md 包含经过验证的关键帧和驱动器代码片段）。绑定位于 blender-character-rigging。

5.x 数据模型（变更内容）

• 一个 Action 包含 slots（每个动画 ID 一个）以及 layers → strips → channelbags → F-curves。单个 action 可以通过不同的 slots 为多个对象制作动画（例如绑定和摄像机）。
• 赋值：ob.animation_data.action = act，然后确保设置了 ob.animation_data.action_slot（存在合适的 slot 时会自动选取；否则使用 act.slots.new(id_type="OBJECT", name=ob.name)）。
• F-curves：cb = anim_utils.action_ensure_channelbag_for_slot(act, slot)，然后使用 cb.fcurves.ensure(path, index=i, group_name=...)。action.fcurves 已不存在。
• 最简单的方式仍然是 pb.keyframe_insert("rotation_quaternion", frame=f)，它会创建 action、slot 和 channelbag。

工作流（关键帧动画，工作室风格）

1. Blocking（定姿）：在黄金帧（走路时的接触、下沉、经过、抬起）上为每个通道设置关键姿势（使用 CONSTANT 插值，bpy.context.preferences.edit.keyframe_new_interpolation_type）。
2. Breakdowns（过渡姿势）：添加定义弧线和间距的中间帧。
3. Spline（曲线细化）：切换到 BEZIER，在曲线编辑器中调整间距，并清理过冲。自动钳制手柄可避免过冲。
4. Polish（润色）：调整偏移和重叠（头发、尾巴、布料骨骼的跟随动作）、弧线、动态停顿（角色绝不能完全静止）以及接触稳定性（用 IK 锁定双脚）。
5. Review（检查）：使用 MCP look(mode="frames", frame_count=8) 或 Workbench 快速预览（blender-rendering）。

游戏动画规则

• 每个片段使用一个 action，命名为 <Rig>_<Clip> 或直接命名为 <Clip>，并启用伪用户以确保保存后仍保留。
• 循环：首尾帧必须相同。导出第 1..N 帧并让引擎丢弃重复帧，或排除最后一帧（UE/Unity 的“loop pose”选项）。F-curve 的 CYCLES 修改器有助于预览，但不会导出，因此需要烘焙。
• FPS：以 30（或 24）帧制作，并让引擎重新采样。导入动作捕捉前设置 scene.render.fps。
• 根运动：根骨骼负责平移（和偏航）。髋部保留上下起伏和摆动。scripts/bake_action.py --root-motion xy 会将髋部的地面运动转移到根骨骼。原地片段中，根骨骼保持在原点。
• 加成/叠加片段（瞄准偏移、呼吸）按普通片段导出，并在引擎中标记为加成动画。
• 保留引擎所需的骨骼变换通道。除非引擎支持，否则不要为骨骼制作缩放动画（Roblox 和许多移动端流程都不支持）。

将控制绑定烘焙到导出骨架

scripts/bake_action.py -- --list
scripts/bake_action.py -- --source RIG_Body --target GAME_RIG_Body [--actions Walk Run] [--root-motion xy --hips spine]

这样每个片段都会得到一个经过清理并带有伪用户的烘焙 action（GAME_RIG_Body|Walk），此外每个片段还会有一条静音 NLA 轨道（CLIP_Walk），以便 FBX（bake_anim_use_nla_strips/all actions）和 glTF（ACTIONS 模式）导出所有片段。之后会静音目标对象的约束，使其播放烘焙数据；运行 --follow 可再次实时驱动它。自行烘焙（将 IK/约束转换为同一绑定上的关键帧）：--source X --target X。

动作捕捉与重定向

• 导入：bpy.ops.import_anim.bvh(filepath=..., global_scale=0.01 if cm else 1, rotate_mode="NATIVE", update_scene_fps=True)、import_scene.fbx（Mixamo，automatic_bone_orientation=True）。
• 不使用插件进行重定向：让目标骨架与源骨架处于相同的静止姿势（T 姿势和 A 姿势的区别最重要）；为每根目标骨骼添加 COPY_ROTATION 约束（使用世界空间或带父级的局部空间），指向对应的源骨骼；再为髋部／根骨骼添加 COPY_LOCATION，并按腿长比例缩放。然后运行 bake_action.py --source TARGET --target TARGET 进行自烘焙，并删除约束。
• 清理动作捕捉数据：抽稀关键帧（graph.decimate，比例为 0.3–0.5），使用 F 曲线 SMOOTH 修改器或 Butterworth 滤波器（graph.butterworth_smooth），并通过 IK 定位点修复脚部滑动，然后烘焙。
• 生产级重定向工具：Auto-Rig Pro（付费）、Rokoko（免费）以及引擎端的重定向工具（UE IK Retargeter、Unity Humanoid）。

NLA 与姿势库

• NLA：将动作下推为片段（track.strips.new(name, start, action)），以叠加／混合剪辑（混合类型为 REPLACE／ADD／COMBINE），并使用 Tweak 模式进行编辑。当动作包含多个槽位时，必须为片段设置动作槽位（strip.action_slot）。
• 姿势库（捆绑的 pose_library）将姿势存储为资产：poselib.create_pose_asset(pose_name=...)、poselib.apply_pose_asset／blend_pose_asset。可用于手部形状、面部姿势以及 T／A 静止姿势。

形态键与其他属性

任何属性都可以设置关键帧：kb.keyframe_insert("value", frame=f)（形态键）、mat.node_tree.nodes[...].inputs[...].keyframe_insert("default_value")（材质，通常会被渲染引擎忽略）、自定义属性 ob.keyframe_insert('["prop"]')。

注意事项

• pb.matrix = ... 后接 keyframe_insert 时，必须先调用正确的 scene.frame_set(f)，否则求值过程会覆盖姿势。
• 已连接的骨骼（use_connect）无法平移。髋部／骨盆必须与根骨骼断开连接。
• 使用视觉关键帧的 bake_action 会读取求值后的姿势，因此约束、IK 和驱动器都会被捕获。（脚本会）随后停用目标自身的约束，否则这些约束会持续覆盖关键帧。
• 四元数与欧拉角：游戏骨骼应使用 QUATERNION（不会发生万向节锁，球面插值平滑）。单轴控制使用欧拉角即可。不要在不同关键帧之间混用模式。
• glTF 采样：export_force_sampling 会烘焙每一帧（安全默认值）。非线性 F 曲线修改器和驱动器只有在采样后才会导出。