用途:处理 Blender 动画关键帧与时间线操作,包括帧范围、当前帧切换、插入关键帧、检查 F 曲线、删除关键帧以及烘焙变换采样。构建骨骼请用 blender-rigging,复用骨架姿势请用 blender-pose-library。
主要能力:set_keyframe 把对象当前属性值写入指定帧的曲线,它不会移动播放头也不会重新求值场景;set_current_frame 才是会求值动画的工具。bake_animation 相反,会逐帧推进播放头并采样已求值的变换后写入关键帧。NLA 工具用于在时间线上编排多个动作:list_animation_actions、list_nla_tracks、add_nla_track / remove_nla_track、add_nla_strip、set_nla_strip(移动、裁剪、缩放、重复、混合、静音、设置影响)、remove_nla_strip、list_action_fcurves、set_action_fcurve_extrapolation。
使用方式:关键帧顺序为先摆姿势再打帧,例如 set_current_frame(frame=1) → 摆姿势 → set_keyframe(object_name=…, frame=1)。在两个不同帧为两个不同姿势打帧才会生成真实曲线;若跳过摆姿或先打帧后摆姿,两端关键帧会存相同值,结果为静帧。add_nla_strip 需要已存在的动作,须先用 set_keyframe 或 bake_animation 生成。strip 的 blend_type(REPLACE / ADD / SUBTRACT / MULTIPLY)决定其与下层轨道的合成方式,influence 缩放贡献量。strip 与 fcurve 的外推控制空隙:HOLD 重复末值,NOTHING 回退到底层值。
限制:set_nla_strip 会拒绝超出范围的 influence、scale 和 repeat,而非钳制。移除轨道或 strip 是破坏性操作,无法撤销。Blender 5.x 没有 Action.fcurves,改为分层动画(action.layers[].strips[].channelbags[].fcurves),list_action_fcurves 与 set_action_fcurve_extrapolation 在 5.x 上会返回明确的 “fcurves unavailable” 错误;NLA 轨道与 strip 工具不受影响,支持所有版本。部分细节与版本支持范围暂未提供。