Ariescar/anyCreature

Contribute to Ariescar/anyCreature development by creating an account on GitHub.

Summary

anyCreature is an open-source toolchain that turns a one-sentence order into a game-ready, skinned, animated, vertex-coloured GLB (glTF 2.0) plus an offline showroom viewer. The engine itself is a Node CLI with zero runtime dependencies; the measuring and QC tooling around it is Python. The repo defines a five-stage "card" pipeline that an AI agent runs end-to-end, with quality judged by separate context-free reader agents rather than self-graded.

What it is useful for

This is useful when an engineer needs a small, programmatic 3D creature for prototyping and does not have a 3D modelling pipeline handy. The worked example at example/wolf.json ships as 2,211 vertices and 31 joints written by the engine from a plain JSON spec, so a non-artist can read and copy it. Either you author the spec directly, or you give an agent a description like "menacing mountain giant, 1.8 m" and let the cards compile it for you.

Output satisfies a documented contract (docs/OUTPUT_CONTRACT.md): two chunks, no trailing bytes, no external textures (colour is baked into vertex colours), and semantic material and bone names. The spec is embedded in the GLB as asset.extras.source_spec, so any agent can later extract, edit, recompile, or graft parts between creatures via harness/graft.py. Useful spec knobs include smooth_angle (crease threshold, default 50°), shading (vertical colour ramp with grain), ao (per-vertex ambient occlusion), build: "rigid" for robots and crystals, and tri_budget in harness/claims.json for cheaper creatures.

How engineers can use it

The README documents this flow:

bash setup.sh                              # deps + red/green ruler calibration
node engine/cli.js example/wolf.json out/wolf.glb

setup.sh must print calibrate OK before you trust anything else; it builds one spec that has to pass and two that have to be blocked, proving the rulers separate good from bad on your machine. To run the full text-to-creature session, give your agent (Claude Code, Cursor, or any shell-running agent) the prompt in the README that tells it to read MANUAL.md, follow the cards in order, run setup.sh itself, and ask only the one clarification question card 01 defines.

To verify a finished file, run node harness/glbcheck.mjs <file.glb>. Requirements are Node 18+ and Python 3.9+; on Windows use setup.ps1 in PowerShell or setup.sh in Git Bash/WSL. Short-lived local servers used by the render tools bind to 127.0.0.1 only, and the bundled three.js (MIT) is the only third-party component in harness/assets/.

Documented limitations to be aware of: the example wolf ships only idle and move animations, not attack, so it is a syntax reference rather than a starting skeleton; part_attachment and mirror_distortion rules are new in 1.2.0 and may now block older specs; the triangle budget is calibrated only on the heaviest class, so treat it as an estimate for simpler creatures; and isolated head-only blind reads can misfire on elephants and birds, so trust the whole-body silhouette when they disagree. scipy is required for the measuring tools, because without it the legibility and boldness measures do not compute and a gate with nothing to read passes everything.