EL4CTEO/blender-skills / skills/blender-animation
blender-animation
VerifiedAnimation in Blender 5.3 - slotted/layered actions and the channelbag API, Python keyframing, F-curves, game loops with pop/hitch checks, NLA clips, pose library, mocap/BVH/Mixamo retargeting with auto bone maps, baking control rigs to export skeletons, root motion, per-clip export. Use for any keyframe, action, NLA, mocap, or animation-export task.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.1 KB |
| scripts/_bpyx.py | script | 4.4 KB |
| scripts/bake_action.py | script | 6.8 KB |
| scripts/loop_check.py | script | 5.9 KB |
| scripts/retarget.py | script | 9.4 KB |
scripts/loop_check.py
View on GitHub"""Check that a cycle loops: the pose at the last frame equals the first (no pop), and the motion
across the seam keeps its speed (no hitch). --fix keys every F-curve's first-frame value onto the
last frame. Root-motion clips: --root-motion BONE ignores that bone's X/Y travel.
Compares evaluated poses (constraints, drivers included) per bone in armature space; works on
plain objects too (object transform). Engines drop the duplicate last frame on import ("loop pose").
Usage:
blender -b f.blend -P loop_check.py -- --object GAME_RIG [--action Walk] [--frames 1 25]
[--tol-deg 0.5] [--tol-m 0.001] [--root-motion root] [--fix] [--save out.blend]
MCP: import loop_check; print(loop_check.run(object="GAME_RIG", action="Walk", fix=True))
"""
import math
import os
import sys
import bpy
from bpy_extras import anim_utils
from mathutils import Matrix, Vector
sys.path.insert(0, os.path.dirname(__file__))
import _bpyx as bx # noqa: E402
def _poses(ob, f, root=None):
bpy.context.scene.frame_set(f)
if ob.type != "ARMATURE":
return {"<object>": ob.matrix_world.copy()}
pose = {pb.name: pb.matrix.copy() for pb in ob.pose.bones}
if root in pose: # remove the root's ground travel from it and its children (they inherit it)
t = pose[root].translation.copy()
t.z = 0.0
off = Matrix.Translation(-t)
moved = {root, *(c.name for c in ob.pose.bones[root].children_recursive)}
pose = {k: (off @ m if k in moved else m) for k, m in pose.items()}
return pose
def _diff(a, b):
rot = math.degrees(a.to_quaternion().rotation_difference(b.to_quaternion()).angle)
return min(rot, 360.0 - rot), (a.translation - b.translation).length
def _w(a, b):
"""Signed angular velocity a -> b (deg, as a vector) so direction reversals are visible."""
q = a.to_quaternion().rotation_difference(b.to_quaternion())
if q.w < 0:
q.negate()
return Vector(q.to_exponential_map()) * (180.0 / math.pi)
def _check(ob, f0, f1, tol_deg, tol_m, root):
p0, p1 = _poses(ob, f0, root), _poses(ob, f1, root)
n0, n1 = _poses(ob, f0 + 1, root), _poses(ob, f1 - 1, root)
m0, m1 = _poses(ob, f0 + 2, root), _poses(ob, f1 - 2, root)
pops, hitch = [], []
for k in p0:
r, t = _diff(p0[k], p1[k])
if r > tol_deg or t > tol_m:
pops.append({"bone": k, "rot_deg": round(r, 3), "loc_m": round(t, 5)})
# velocities over the 4 frame steps around the seam (f1-2 .. f1 == f0 .. f0+2)
v1, v2, v3, v4 = _w(m1[k], n1[k]), _w(n1[k], p1[k]), _w(p0[k], n0[k]), _w(n0[k], m0[k])
a_before, a_seam, a_after = v2 - v1, v3 - v2, v4 - v3
jerk = (a_seam - (a_before + a_after) / 2).length # seam accel unlike its neighbours
kink = jerk > tol_deg and jerk > max(a_before.length, a_after.length)
# ease-out/ease-in at the seam: speed dips without the motion reversing
same_dir = v1.dot(v2) > 0 and v2.dot(v3) > 0 and v3.dot(v4) > 0
lo, hi = min(v2.length, v3.length), min(v1.length, v4.length)
dip = same_dir and hi - lo > tol_deg and lo < 0.5 * hi
if kink or dip:
hitch.append({"bone": k, "deg_per_frame_in": round(v2.length, 3),
"deg_per_frame_out": round(v3.length, 3), "kind": "kink" if kink else "dip"})
pops.sort(key=lambda x: -x["rot_deg"] - 100 * x["loc_m"])
hitch.sort(key=lambda x: -abs(x["deg_per_frame_in"] - x["deg_per_frame_out"]))
return pops, hitch
def run(object=None, action=None, frames=None, tol_deg=0.5, tol_m=0.001, root_motion=None, fix=False, **_):
if not object:
raise ValueError("--object is required")
ob = bpy.data.objects[object]
ad = ob.animation_data
if action:
ob.animation_data_create()
ob.animation_data.action = bpy.data.actions[action]
ad = ob.animation_data
if ad.action_slot is None:
ad.action_slot = next(iter(ad.action_suitable_slots), None)
if ad is None or ad.action is None:
raise ValueError(f"{object} has no action")
act = ad.action
f0, f1 = (int(frames[0]), int(frames[1])) if frames else (int(round(v)) for v in act.frame_range)
pops, hitch = _check(ob, f0, f1, tol_deg, tol_m, root_motion)
res = {"ok": True, "object": ob.name, "action": act.name, "frames": [f0, f1], "loops": not pops,
"pops": pops[:10], "hitches": hitch[:10]}
if fix and pops:
cb = anim_utils.action_get_channelbag_for_slot(act, ad.action_slot)
ground = set()
if root_motion and ob.type == "ARMATURE": # local location axes that point along the ground
ml = ob.data.bones[root_motion].matrix_local.to_3x3()
ground = {i for i in range(3) if abs(ml.col[i].normalized().z) < 0.5}
n = 0
for fc in cb.fcurves:
if fc.data_path == f'pose.bones["{root_motion}"].location' and fc.array_index in ground:
continue # root travel is the point of a root-motion clip
fc.keyframe_points.insert(f1, fc.evaluate(f0), options={"REPLACE", "FAST"})
fc.update()
n += 1
pops2, hitch2 = _check(ob, f0, f1, tol_deg, tol_m, root_motion)
res.update(fixed_curves=n, loops=not pops2, pops=pops2[:10], hitches=hitch2[:10])
if res["hitches"]:
res["note"] = "speed changes across the seam: match the tangents (Graph Editor, auto-clamped/cyclic) or re-pose frame 2/N-1"
bpy.context.scene.frame_set(f0)
return res
if __name__ == "__main__":
p = bx.parser(__doc__)
p.add_argument("--object", required=True)
p.add_argument("--action", default=None)
p.add_argument("--frames", type=int, nargs=2, default=None)
p.add_argument("--tol-deg", type=float, default=0.5)
p.add_argument("--tol-m", type=float, default=0.001)
p.add_argument("--root-motion", default=None, help="bone whose X/Y travel is ignored")
p.add_argument("--fix", action="store_true")
p.add_argument("--save", default=None)
bx.cli(run, p)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |