blender-animation 是一套关于在 Blender 5.2 中制作动画的技能资料，内容涉及分层与分槽 Action、channelbag API、Python 关键帧、F-curve、游戏循环、NLA 片段、姿态库，以及 mocap/BVH 等主题。其执行模型位于 blender-core，参考资料 references/bpy-patterns.md 中提供了已验证的关键帧与驱动器代码片段；骨骼绑定部分位于 blender-character-rigging。
一、5.x 数据模型变化 在 Blender 5.x 中，一个 Action 包含 slots（每个被动画化的 ID 一个）与 layers → strips → channelbags → F-curves 的层级。单个 action 可以通过不同的 slot 同时动画化多个对象，例如一个绑定及其摄像机。 分配方式是：先执行 ob.animation_data.action = act，然后确保 ob.animation_data.action_slot 已设置；当存在合适 slot 时会被自动选取，否则使用 act.slots.new(id_type="OBJECT", name=ob.name)。 操作 F-curve 时，先 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。
二、关键帧动画工作流（工作室风格）
- 阻塞（Blocking）：在每个通道上打关键姿势，使用 CONSTANT 插值（bpy.context.preferences.edit.keyframe_new_interpolation_type），并在黄金帧（行走动画中的接触、下落、经过、上升）上设置。
- 分解（Breakdowns）：加入定义弧线与间距的中间帧。
- 样条（Spline）：切换到 BEZIER，在图编辑器中修正间距，并清理过冲；自动钳制手柄可避免过冲。
- 润色（Polish）：处理偏移/重叠（头发、尾巴、布料骨骼的跟随动作）、弧线、移动保持（角色绝不完美冻结）以及接触稳定性（用 IK 锁定脚部）。
- 复核（Review）：使用 MCP look(mode="frames", frame_count=8) 或 Workbench playblast（blender-rendering）。
三、游戏动画规则 每个片段使用一个 action，命名为 <Rig>_<Clip> 或直接 <Clip>，并设置假用户（fake user）以便保存后不丢失。 循环：首尾帧完全一致。导出第 1..N 帧，让引擎丢弃重复帧，或排除最后一帧（UE/Unity 的“loop pose”选项）。F-curve 的 CYCLES 修改器有助于预览但不会导出，因此需要烘焙。 FPS：以 30（或 24）制作，让引擎重采样；导入 mocap 前先设置 scene.render.fps。 根运动（Root motion）：由根骨骼承载位移（及偏航），髋部保留上下起伏/摆动。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。
五、Mocap 与重定向 导入：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 自烘焙，并删除约束。 清理 mocap：抽稀关键帧（graph.decimate，比例 0.3–0.5），使用 F-curve SMOOTH 修改器或 Butterworth 滤波（graph.butterworth_smooth），并用 IK 锁定修正脚部滑动后烘焙。 生产级重定向工具：Auto-Rig Pro（付费）、Rokoko（免费），以及引擎侧重定向器（UE IK Retargeter、Unity Humanoid）。
六、NLA 与姿态库 NLA：将 action 下推为 strip（track.strips.new(name, start, action)）以分层/混合片段（混合类型 REPLACE/ADD/COMBINE），并使用 Tweak 模式编辑。当 action 有多个 slot 时，strip 需要设置 action slot（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 使用 visual keying 时会读取求值后的姿势，因此约束、IK 与驱动器都会被捕获。之后要静音目标自身的约束（脚本会处理），否则它们会持续覆盖关键帧。 四元数 vs 欧拉：游戏骨骼应使用 QUATERNION（无万向节锁，slerp 平滑）。欧拉适合单轴控制。不要在关键帧之间混用模式。 glTF 采样：export_force_sampling 会逐帧烘焙（安全默认值）。非线性 F-curve 修改器与驱动器只有在采样时才会导出。