t1k:cocos:playable:fbx-rig-animate
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: animate fbx, armature, blender rig, bone weights, fbx animation, idle animation, in-place loop, rig fbx, rigging, skin weights, skinned mesh, take name, walk cycle
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:fbx-rig-animateRig & Animate a Static FBX for a Cocos Playable
Section titled “Rig & Animate a Static FBX for a Cocos Playable”Take an unrigged FBX, rig it in headless Blender, author polished in-place looping clips, export an FBX whose clips Cocos imports under the names you chose, and weigh the result against the playable size budget. Proven on a low-poly cow (Idle, Walk) and chicken (Idle, Walk, Peck): Blender 5.2.1 headless, Cocos Creator 3.8.7. Every number below was measured on those two creatures.
NOT this skill: engine-module/build-config size work (t1k-cocos-playable-build-size), runtime
playback (t1k-cocos-playable-animation-core, -animation-presets), editor .meta mutation
(t1k-cocos-playable-editor-tools, t1k-cocos-playable-tooling-gotchas).
Reuse verdict
Section titled “Reuse verdict”Searched this kit’s skills (.claude/modules/*/skills) and the art skills listed below; no indexed
knowledge-retrieval sweep was run for this skill.
t1k-art-base-headless-pipeline: REUSE for headless-Blender process discipline; this skill adds the rigged-FBX recipe.t1k-art-base-engine-coordinates: REUSE for axes/units theory. It says rigged assets need their own, still-unmeasured recipe becausebake_space_transformmisbehaves with armatures;references/export-and-import.mdis that recipe (bake_space_transform=False, measured on two round trips).t1k-art-cocos-playable-export: REUSE for static GLB/Draco/KTX2 export; it does not cover skinning or FBX clips.t1k-cocos-playable-build-size: EXTEND. Its § 7meshCompressguidance conflicts with one measured finding here (seereferences/cocos-import-and-size.md).t1k-cocos-playable-animation-core: runtime tween/flying animation; no overlap with authoring skinned clips.- Armature fitting, skin weights, keyframed locomotion: KEEP (new); no skill in the searched set does it.
Pipeline
Section titled “Pipeline”| # | Step | Where |
|---|---|---|
| 1 | Never overwrite the source; write <name>_rigged.fbx beside it | Delivery rules |
| 2 | Decide the size cost first (about +120-135 KB per creature) | Size |
| 3 | Fit the armature to the mesh (measure heads/tails off the mesh) | references/worked-examples.md |
| 4 | Weight: one connected mesh = skin, separate rigid parts = rigid-parent per bone | references/weights-and-motion.md |
| 5 | Author motion: 30 fps, in place, first frame == last frame, polished | references/weights-and-motion.md |
| 6 | Export with bare take names and constant-channel drop | scripts/t1k_fbx_export.py |
| 7 | Verify in a FRESH Blender process | scripts/t1k_fbx_verify.py, scripts/t1k_fbx_deform.py |
| 8 | Render contact sheets and LOOK at them (stills cannot judge timing) | scripts/t1k_fbx_contact_sheet.py |
| 9 | Cocos import: copy meshCompress from the source .meta, Reimport | references/cocos-import-and-size.md |
Scripts
Section titled “Scripts”Asset-agnostic; every name, path and threshold is a CLI argument. Run each as its own process:
blender -b --factory-startup --python-exit-code 1 --python scripts/<script>.py -- <args>| Script | Does |
|---|---|
t1k_fbx_stats.py <fbx>... | Raw FBX read, no importer: byte size, curve/key counts, take names, frame ranges |
t1k_fbx_export.py --blend --out --expect-takes --simplify | Export with bare take names + constant-channel drop (--keep-constant to measure it) |
t1k_fbx_verify.py --fbx [--src] --expect-takes --disconnect | Fresh re-import: tris, bounds size, weights, takes, loop seam, root travel |
t1k_fbx_deform.py --blend|--fbx --actions | Per-frame edge stretch vs bind pose |
t1k_fbx_prune.py --blend --out [--dry-run] | Drop flat-at-rest f-curves in the .blend, proving per-frame vertex deviation |
t1k_fbx_contact_sheet.py --fbx|--blend --out --actions | N-frame x view PNG sheet per action |
t1k_fbx_common.py | Shared helpers |
Exit codes: 0 check passed, 1 the check ran and FAILED, 2 usage error or could not run (never a
pass, never a red result). A script without a bare -- argument prints its usage and exits 2.
A verifier must run in a separate Blender process from the one that built the file.
Smoke-run on the example FBXs (Blender 5.2.1): stats, verify, deform, contact_sheet on
cow_rigged.fbx / chicken_rigged.fbx, and export + prune --dry-run on a .blend imported from
the cow, all exit 0; verify exits 1 on a missing take and 2 on a missing file.
Delivery rules
Section titled “Delivery rules”- Never overwrite the source FBX. A skinned mesh is a different Cocos sub-asset than the static one; old prefabs reference the old mesh. Instantiate the NEW FBX’s own scene prefab (skeleton + clips).
- The source node can carry a huge translation (~44 m on the chicken). Drop it, root at the origin, and tell the user to reposition the node. Reapply a prefab node scale the old prefab had (chicken: 15.925).
t1k_fbx_verify.py --srcrequires triangle count equal to the source and bounding-box SIZE equal; the absolute position legitimately moves when the translation is dropped.
Size (MEASURED, Cocos library .bin after Reimport)
Section titled “Size (MEASURED, Cocos library .bin after Reimport)”| Static original | Rigged + animated | Delta | |
|---|---|---|---|
| Cow (Cocos assets total) | about 22 KB | about 143 KB | about +121 KB |
| Chicken (Cocos assets total) | about 20 KB | about 154 KB | about +134 KB |
- Skinned mesh with
meshCompresscopied from the source meta: 75 to 43 KB (cow), 64 to 37 KB (chicken), about 42 %. - Quantize is NOT applied to skinned meshes in 3.8.7 (vertex stride stays 72: float32 position/normal/tangent + joints/weights). The static original quantized to 15.6 KB (stride 24).
- Dropping constant channels shrinks the FBX on disk (cow 422 to 178 KB, curves 342 to 79; chicken 359 to 193 KB, curves 432 to 117) but did NOT shrink the Cocos clips (cow Idle 34.7 to 34.1 KB, Walk 30.2 to 30.2; chicken Idle 33.7 to 33.8, Peck 25.0 to 25.1, Walk 22.4 to 22.5): the converter resamples every animated bone per frame.
- UNVERIFIED levers (lower clip sample rate, fewer bones, dropping tangents, any 3.8.7 animation compression): how to measure each is in
references/cocos-import-and-size.md.
Budget rule: a rig costs about +120-135 KB per creature. Decide early; tweens are the zero-cost alternative.
Hard rules
Section titled “Hard rules”Mechanisms in references/weights-and-motion.md and references/export-and-import.md.
- Auto weights can fail silently (chicken: tail took 138 verts, body 0). Check, then region-seed + diffuse.
- Hard-fixed head weights sheared the neck; use soft diffused weights, then check stretch with
t1k_fbx_deform.py. - A child of a scaling bone (breathing chest) needs
inherit_scale = NONE. - Blender writes takes as
Armature|Idle; the export script patches the name in-process. - Blender re-import marks bones connected and ignores their translation keys: pass
--disconnect(Cocos is unaffected). The importer also re-adds theArmature|prefix; the file on disk is fine. - Dropping start/end keys broke loops (15 mm); drop whole constant-and-at-rest channels instead.
- A
.metaedit may be ignored while the editor is open: Reimport Asset. - Consuming an EXISTING rig (a decoded Unity port) is a different job: scale tracks on rigid clips, a bad idle, per-controller clip tables, hysteresis and idle-on-spawn are in
t1k-cocos-base-apk-port/references/animation-import.md.
Executed by
Section titled “Executed by”| Step | Agent |
|---|---|
| Run scripts, tabulate tris/curves/takes/bytes | t1k-metrics-reporter |
| Armature fit, weight and gait judgment, reading contact sheets | stays on a reasoning tier |
Any Edit/Write on a .blend, .fbx, .fbx.meta | write-capable reasoning tier; editor-closed gate first |