blender-animation

blender-animation

Blender animation keyframe and timeline skill. Use it for frame ranges, current-frame changes, inserting keys, inspecting f-curves, deleting keyframes, and baking transform samples. Prefer blender-rigging for rig construction and blender-pose-library for reusable armature poses.

Keyframing: pose first, then key

set_keyframe writes the object's current property values into the curve at the requested frame. It never moves the playhead and never re-evaluates the scene, so the order is always: move the playhead (optional), pose the object, then key it:

1. set_current_frame(frame=1) → pose → set_keyframe(object_name=…, frame=1)
2. set_current_frame(frame=49) → pose → set_keyframe(object_name=…, frame=49)

Keying two different poses at two different frames produces a real curve. If you skip the pose (or key before posing), both keys store the same value and the render is a still frame even though get_keyframes reports keys at both ends. To inspect another frame, call set_current_frame — that is the tool that evaluates the animation; set_keyframe leaves frame_current where it was.

bake_animation is the opposite: it does step the playhead, because it samples the evaluated transform at each frame and keys that value.

NLA: arranging actions over time

The keyframe tools work on one action at a time. The NLA tools arrange several actions on a timeline: an NLA track is a layer, and a strip places an action on that layer at a frame.

Tool	Description
list_animation_actions	List actions in the file, or one object's active and NLA actions
list_nla_tracks	List an object's tracks and the strips each one holds
add_nla_track / remove_nla_track	Create or remove a track (removing a track drops its strips)
add_nla_strip	Place an existing action on a track at a frame
set_nla_strip	Move, trim, scale, repeat, blend, mute, or set influence on a strip
remove_nla_strip	Remove one strip
list_action_fcurves	List the fcurves in an action with their key ranges
set_action_fcurve_extrapolation	Control behaviour before the first and after the last key

Notes that matter in practice:

• add_nla_strip needs an action that already exists; it does not create one. Use set_keyframe or bake_animation to produce an action first.
• A strip named for a missing action fails, and nothing is created. Pass track_name to target a specific track; without it the first track is used, and one is created if the object has none.
• blend_type (REPLACE / ADD / SUBTRACT / MULTIPLY) decides how a strip combines with the tracks below it; influence scales the contribution.
• Extrapolation on both strips and fcurves controls the gaps: HOLD repeats the end value, NOTHING falls back to the underlying value.
• set_nla_strip rejects out-of-range influence, scale, and repeat rather than clamping: Blender would silently clamp them, and reporting success while giving a different value is worse than refusing.
• Removing a track or strip is destructive and cannot be undone.

Blender 5.x has no Action.fcurves. It was replaced by layered animation (action.layers[].strips[].channelbags[].fcurves). list_action_fcurves and set_action_fcurve_extrapolation return an explicit "fcurves unavailable" error on 5.x instead of reporting an action with no curves. The NLA track and strip tools are unaffected and work across every supported version.