--- name: animated-asset description: Create a fully rigged, animated voxel creature from a one-line idea — fal text-to-image → Hunyuan-3D → C++ voxelizer → headless Blender rig + 13 animation clips → glTF. Use when asked to add, generate or create a new creature, animal, animated asset or voxel model (e.g. "add a corgi", "make a wolf", "generate a new animal"). --- # Animated asset pipeline Turns a one-line idea ("a cheerful corgi") into a rigged voxel creature with 13 animation clips, exported as glTF. Four stages, each with a QA gate. Run them in order; never skip a gate — a bad early artifact wastes every later stage. Exactly ONE gate is a manual user pick — present the material, then stop and wait: 1. concept selection (stage 1): the user picks one of four generated concept images. Every other gate is automated; ask the user only when one fails twice in a row. ## Layout ``` assets// (PascalCase name, e.g. Corgi) concept/candidate_{1..4}.png stage 1 candidates + concept_sheet.png + concept.json (CDN urls) _mesh.glb stage 2: Hunyuan-3D output .vox stage 3: MagicaVoxel voxels, 5 cm cells, facing -Y previews/_vox_{front,side,top}.png layout.json, _rules.py stage 4: derived body plan + voxel->bone rules _rigged.blend stage 4: the rig, all clips stashed in the NLA _animated.glb stage 4: EXPORT — every clip as a glTF animation report.json, run.log guards, timings, everything that was run ``` Tools live in this repo: `tools/pipeline/concept.py`, `tools/pipeline/run_creature.py`, `tools/voxelizer/` (build once with CMake), `tools/rig/` (Blender scripts + clip modules). Requirements: Blender 5.2 LTS on PATH (or `BLENDER=/path`), a fal API key (`FAL_KEY` or `~/.fal/key`), Python 3.10+ with Pillow for the contact sheets. ## Stage 1 — concept image (fal text-to-image) Model: `bytedance/seedream/v5/pro/text-to-image`. Use the `fal-ai` MCP tools (`run_model` / `submit_job` + `check_job`) when that server is connected; otherwise run ``` python tools/pipeline/concept.py --idea "a cheerful corgi" --len-m 0.9 \ --anatomy "<2-3 sentences of BLOCKY anatomy>" --colors "" ``` Prompt rules (the template is in `concept.py` and [references/fal-generation.md](references/fal-generation.md)): depict the animal AS voxel art ("large chunky visible cubes, MagicaVoxel style, roughly N cubes long"), side three-quarter view, legs clearly separated from each other and the ground, plain light-grey background, whole model in frame. Thin parts (tails, whiskers, antler tines) must be thickened into slabs or omitted — they shred at 5 cm. `--len-m` is the real-world length; cube counts in the prompt follow from it (1 cube = 10 cm in the prompt, 5 cm in the voxels). **Auto QA first:** view each candidate. Reject any that are not blocky axis-aligned cubes, lack a plain background, crop the body, fuse the limbs, or grow thin appendages. Fewer than 2 survivors → regenerate before involving the user. **USER PICK (mandatory):** show `concept_sheet.png` and STOP until they choose. Keep the picked candidate's fal CDN URL — stage 2 takes it directly. ## Stage 2 — image to 3D (Hunyuan-3D), Stage 3 — voxelize, Stage 4 — rig + animate One command runs all three and writes the report: ``` python tools/pipeline/run_creature.py --image-url --len-m 0.9 ``` What it does, and the gates it applies: - **Mesh** — `fal-ai/hunyuan-3d/v3.1/pro/image-to-3d`, `generate_type: Normal`, PBR on, `face_count: 100000` (plenty for voxels, 4x smaller download). ~2.5 min. If the rear comes out wrong (Hunyuan hallucinates unseen views), pass a back-view image via `back_image_url`. - **Voxelize** — `tools/voxelizer` cuts the mesh at 5 cm cells (`--long-axis` = 2 x metres x 10). Facing is detected from the voxel grid (the taller end is the head) and the yaw is swept automatically. **Check `previews/_vox_side.png`: the head must be at the image LEFT.** The heuristic fails on animals whose rump is higher than the head (rhino, boar) or whose tail is raised (skunk); fix those by re-running the voxelizer with `--yaw` and passing `--vox`. - **Rig** — `tools/rig/voxrig.py` derives the body plan from the grid (leg zone = bottom layers still split into separate blobs, tail = narrow trailing slices, head = whatever rises at the front) and writes `_rules.py` (voxel -> bone). `generic_quad_build.py` builds a 14-bone quadruped rig with rigid per-bone weights, authors Idle / Walk / Gallop / Graze / Alert, then exec's every module in `tools/rig/clips/` (Trot, Jump, Sit, Sleep, Shake, Stretch, LookAround, Rear) and exports the glTF. Gaits are scaled by leg length; the same maths runs on a fox and a hippo. **QA gate (numeric, never visual):** `report.json` → `stages.rig.guards`. `DIRECTION GUARD: OK` means every planted foot sweeps tailward and touches the ground in the Walk; `suspension: YES` means the Gallop has an airborne frame (legs one voxel tall can't — the clip still exports). Every extra clip prints its own `EXTRA CLIP : N frames | guard: OK ...`. Read [references/rigging-traps.md](references/rigging-traps.md) before touching any rig code — it is the accumulated list of things that silently produce wrong animation, including why vision-model judges cannot be trusted to tell a forward walk from a backward one. Optional: add `--video` to render a 3/4-view preview MP4 per clip into `previews/`. ## Stage 5 — use it `_animated.glb` imports into Godot, Unity, Unreal and three.js with all clips as named animations (`Idle`, `Walk`, `Gallop`, ... same names on every animal, so a state machine can key on them). The `.blend` keeps the rig editable. (tiny-voxel additionally bakes the clips into its own rigid-part runtime format; that baker is engine-specific and not part of this repo.) ## Wrap up Report one line per stage: model used, voxel dims and count, clips exported, and any gate that needed a retry. Leave the unpicked candidates in `concept/` — never delete. ## Scope Quadrupeds only. The rig is one body plan with derived proportions; bipeds, birds, snakes and anything with a moving tail need their own build script. Blocky voxel animals are the easy case for both meshing and weights — nothing here claims organic characters.