Skip to content

t1k:cocos:playable:fbx-rig-animate

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
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

/t1k:cocos:playable:fbx-rig-animate

Rig & 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).

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 because bake_space_transform misbehaves with armatures; references/export-and-import.md is 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 § 7 meshCompress guidance conflicts with one measured finding here (see references/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.
#StepWhere
1Never overwrite the source; write <name>_rigged.fbx beside itDelivery rules
2Decide the size cost first (about +120-135 KB per creature)Size
3Fit the armature to the mesh (measure heads/tails off the mesh)references/worked-examples.md
4Weight: one connected mesh = skin, separate rigid parts = rigid-parent per bonereferences/weights-and-motion.md
5Author motion: 30 fps, in place, first frame == last frame, polishedreferences/weights-and-motion.md
6Export with bare take names and constant-channel dropscripts/t1k_fbx_export.py
7Verify in a FRESH Blender processscripts/t1k_fbx_verify.py, scripts/t1k_fbx_deform.py
8Render contact sheets and LOOK at them (stills cannot judge timing)scripts/t1k_fbx_contact_sheet.py
9Cocos import: copy meshCompress from the source .meta, Reimportreferences/cocos-import-and-size.md

Asset-agnostic; every name, path and threshold is a CLI argument. Run each as its own process:

Terminal window
blender -b --factory-startup --python-exit-code 1 --python scripts/<script>.py -- <args>
ScriptDoes
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 --simplifyExport with bare take names + constant-channel drop (--keep-constant to measure it)
t1k_fbx_verify.py --fbx [--src] --expect-takes --disconnectFresh re-import: tris, bounds size, weights, takes, loop seam, root travel
t1k_fbx_deform.py --blend|--fbx --actionsPer-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 --actionsN-frame x view PNG sheet per action
t1k_fbx_common.pyShared 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.

  • 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 --src requires 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 originalRigged + animatedDelta
Cow (Cocos assets total)about 22 KBabout 143 KBabout +121 KB
Chicken (Cocos assets total)about 20 KBabout 154 KBabout +134 KB
  • Skinned mesh with meshCompress copied 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.

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 the Armature| prefix; the file on disk is fine.
  • Dropping start/end keys broke loops (15 mm); drop whole constant-and-at-rest channels instead.
  • A .meta edit 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.
StepAgent
Run scripts, tabulate tris/curves/takes/bytest1k-metrics-reporter
Armature fit, weight and gait judgment, reading contact sheetsstays on a reasoning tier
Any Edit/Write on a .blend, .fbx, .fbx.metawrite-capable reasoning tier; editor-closed gate first