You can now generate creatures directly within your project. Drop the open-source into your Agent, and start prompting what you want.
Spec JSON — the whole language on one page
{
"height": 1.85, // real-world metres, ground to crown — the engine verifies ±15%
"palette": { "skin_torso": {"color":"#8a8a80","rough":0.95}, ... }, // one material PER PART
"sections": { "flute": [[1,0],[0.6,0.4],...] }, // named 2D outlines, CONCAVE allowed (bark, crescents)
"smooth_angle": 50, // default: faces meeting at a vertex average when their normals sit within
// this many degrees; the vertex splits only at a REAL crease. Override per
// volume and per part. "faceted":true == smooth_angle 0.
"shading": { // THE L1-L8 STACK. Every field below is optional and every
// default is the settled value — you normally write NOTHING
// here except `pattern.color`, which is a MID decision.
"pattern": {"color":"#ffffff","sharpness":0.45,"amount":1.0,"scale":0.06},
// L2. Omit `color` and there is no pattern. Flesh only.
"ramp": {"bottom":"#001370","mid":"#cfcfcf","top":"#fffcf0","pm":0.31,"wm":0.08},
// L3. Top-to-bottom, multiplied over everything but features.
"boost": {"y0":0.00,"y1":0.40,"gamma":0.30,"dL":0.03,"dC":1.50},
// L4. Brighter AND more saturated up top, EXACTLY nothing below
// y0 (identity, not "almost"). Chroma walks back to the sRGB
// edge instead of clamping — clamping turns the hue.
"bleed": {"radius":0.025,"sharpness":0.35,"amount":0.45}, // L5 hardware into flesh
"hardsh": {"amount":0.54,"gamma":0.70}, // L6 shadow on hardware
"bodysh": {"lights":4,"rot":4,"elev":17,"amount":0.20,"gamma":1.95}, // L7 on flesh
"normals":{"flesh":0.90}, // L8 — the ONLY layer that leaves COLOR_0 and goes into
// the file's NORMAL, so the user's lighting reacts to it.
"stack": true }, // false = the 1.2.0 ramp-and-grain instead (gradient/noise below)
// legacy, only read when stack:false:
// "gradient":{"top":0.30,"bottom":-0.88}, "noise":{"size":0.018,"amount":0.26}
// noise.size = FRACTION OF THE MODEL DIAGONAL, not metres.
"build": "rigid", // robots/constructs/golems/vehicles ONLY — lifts the faceted_body BLOCK
"joints": {
"Hips": [0, 0.9, 0], // absolute [x,y,z], y up, z forward
"Chest": {"from":"Hips","fwd":0.1,"up":0.5}, // relational: fwd=+z up=+y side=+x
"TailTip": {"from":"Tail2","dir":[0,-1,-0.4],"len":0.3},
"LToe": {"from":"LKnee","fwd":0.1,"ground":0.03} // ground = absolute Y (feet)
},
"joints_R": { "RElbow": {"from":"Chest","side":-0.3,"up":0.25} },
// optional: reposition auto-mirrored R* joints — pairs GROW symmetric but the
// bind POSE staggers (raised right arm); the mirrored skin follows its joints.
// A FEW CENTIMETRES ONLY. The twin's mesh is grown on the LEFT bone path and
// then dragged onto the right joints by translation, so a large offset shears
// the volume instead of posing it: past ~10% of the limb's length it starts
// squashing, past ~35% the right thigh comes out 40% of the left's depth with
// its width untouched. mirror_distortion BLOCKs that. For a genuinely
// different pose, take the limb OUT of "mirror" and author it as its own chain.
"chains": { "torso":["Hips","Spine","Chest"], "LArm":[...], ... },
"attach": { "LArm":"Chest", "head":"Neck" }, // every non-root chain → its host joint
"mirror": ["LArm","LLeg"], // auto right-side twins (joints, meshes, anims)
"touch": [["torso","tail"]], // declared connections MUST overlap or BLOCK
"volumes": [{
"chain":"torso", "material":"skin_torso", "sides":14, "frame":"up",
"profile":[[0,0.3,0.35], [0.6,0.42,0.5,{"bias":-0.1,"sharp":true}], [1,0.2,0.22]],
// rows [t, half-width, half-height, opts]; exp 2.5-4=boxy slab; bias<0 belly-full;
// sharp = hard SILHOUETTE break, and it only bites when the radius STEPS
// across it (>=15%). The flag between two rings of the same radius is a
// no-op. It changes nothing.
"smooth_angle": 30, // per-volume override, and the SHADING lever. The wall
// angle is 360/sides; smooth_angle welds every edge under it, so 9 sides
// (40 deg) or 16 sides (22 deg) at the default 50 is welded perfectly
// smooth. A volume that can break NOWHERE — no facets, no radius step —
// is a bean, and the engine BLOCKs it (soft_mass). Lowering it hardens the
// shading and leaves the outline untouched.
"soft": true, // OPT-OUT for soft_mass: this mass really is meant to be
// a smooth organic lump (a slug, a bladder, a droplet). Deliberate, not default.
"shade": "flesh", // OPTIONAL. flesh | hard | fx — which shading
// class this piece belongs to. The default is right almost always: volumes, hands and paws
// are flesh; spikes, curves, membranes and fins are hard; eyes are fx (no layer, no shadow).
// Write it when the default is wrong for THIS creature: a trunk is a `curve` that is flesh;
// an armour plate grown as a volume is a volume that is hard. The build prints which pieces
// landed in which class ("info: shade class ..."), so check that line rather than guessing.
// "faceted":true on a VOLUME is a BLOCK (faceted_body) — an 800-tri torso becomes 800 shards
// and AO bakes the mess into COLOR_0. Break a body with "sharp" rows or a lower smooth_angle.
"caps":["dome","dome"], "ring_step":0.05,
"colors": { "arcs":[{"from":0,"to":52,"color":"#57513f"}] } // 0°=spine 180°=belly
// arcs ONLY — colors.gradient / colors.noise are ignored (info: line); see "shading" above
}],
"parts": [
{ "type":"curve", "host":"Head", "material":"tusk", "mirrored":true, // CURVED horn/tusk/trunk
"join":"insert", // how it meets the body: insert (base buried, verified) /
// extrude (grows out of the skin) / snap (rides an anchor) /
// place (deliberately free) — undeclared floating roots warn
"offset":[0.06,0,0.1], "dir":[0.3,-0.6,0.7], "sides":8,
"segments":[ {"len":0.1,"r":0.035,"ahead":20}, {"len":0.1,"r":0.028,"rise":35},
{"len":0.08,"r":0.015,"rise":30,"taper":true} ] },
// steering is per-segment and ADDS UP down the chain. rise/fall/ahead/behind
// pull the heading that many degrees toward that world axis; coil swings it in
// the carried plane (rings, spirals); taper pinches the far end.
// Four mild segments can finish somewhere you did not predict — the compiler
// reports the accumulated total (info: ... accumulated to 123°). Read that line.
{ "type":"membrane", "name":"wing", "material":"wing_skin", "mirrored":true, // skin between rib chains
"cusp":0.25, "along":8, "across":3,
"ribs":[ {"chain":"LArm"}, {"chain":"LFing2"}, {"chain":"LFing3"}, {"chain":"LTrail"} ] },
// along = samples down each rib · across = columns between neighbouring ribs
// cusp = how deeply the trailing edge scoops · per-rib "shorten":0.2 pulls one rib in
// Ribs run leading→trailing and the LAST one has to come back to the body.
// Leave it out at the far end and the silhouette never encloses — it reads as
// spread fingers, not one sheet. The compiler measures the root gap and warns.
{ "type":"fin", "host":"Skull", "material":"plate", "thickness":0.02, "mirrored":true,
"anchor":{"chain":"head","t":0.4,"around":60}, // around: 0=spine 90=side 180=belly
// ⚠ that mapping is the BODY chain's frame. `around` is read in the host
// SECTION's frame, so on a chain running vertically (a leg) the same numbers
// point elsewhere: 0=inner, 90=FRONT, 180=OUTER, 270=back. Aiming a plate at
// the outside of a thigh with 90 lands it on the front. The compiler prints
// the world direction each anchored part actually faces — read that line,
// do not reason from this comment.
"udir":[0,0,1], "vdir":[0,1,0], "points":[[0,0],[0.1,0.02],[0.05,0.15]],
"faceted":true }, // PARTS may face freely (or set "smooth_angle") — only VOLUMES are blocked
// by default the host surface wins: an anchored part is snapped flat onto the
// surface normal, and the direction you wrote survives only as a reported
// difference. Set "conform":false when that written direction was the point.
{ "type":"eye", "host":"Brow", "material":"eye", "size":0.028,
"anchor":{"chain":"head","t":0.4,"around":62} }, // both eyes from one entry; side of head ≈55-70
{ "type":"hand", "host":"LWrist", "material":"skin_hand", "mirrored":true, // palm + 4 fingers + OPPOSABLE thumb
"size":0.17, // palm length — the whole hand scales from it
"dir":[0.1,-0.9,0.35], "up":[0,0,1], // dir = where the knuckles point; up = back of the hand
"curl":0.35, "spread":0.5, // relaxed curl / finger fan; "fist":true = folded, thumb wrapped
"join":"extrude" },
{ "type":"paw", "toes":3, "host":"LToe", "material":"skin_fist", "size":[0.3,0.25,0.2], "mirrored":true }
],
"animations": {
"move": { "duration":0.95, "loop":true, "mirror_phase":0.5,
"tracks": { "LFrontRoot": {"rx":[[0,-26],[0.5,28],[1,-26]]} } }, // rx..tz keys [fraction,deg|m]
"attack": { "duration":0.7, "loop":false, "tracks": { ... } }
// attack must COMMIT FORWARD — either route passes (attack_reach):
// REACH: something ends ≥15% of the body span past the bind front, or
// SWING: some part travels forward ≥45% of ITS OWN length.
// You do NOT have to lunge. Planted on the spot, winding a limb, tail or
// weapon BACK and sweeping it FORWARD counts. A sideways sweep does not —
// the strike has to commit at the space in front of the body.
},
"style": "heavy", // ONLY if 1:1 segment rhythm is the design (relaxes the 50:50 gate)
"ao": false, // debug only — vertex AO bakes automatically otherwise
"embed_spec": false, // opt OUT of the embedded birth certificate (default: the GLB carries its own spec)
"keep_uv": true, // opt-in UV atlas (TEXCOORD_0) for downstream texture bakes
"qa_isolate": true // MID part-isolation builds only: skips whole-body checks
}
BLOCK: = build refused (fix, costs no round) · warn: = a measure, you judge ·
info: = the compiler telling you what actually happened — always read them.
Shipped GLBs auto-merge primitives per material and export public bone names
(LArm1Sh convention) — internal spec names never leak.
function — what each chain is FOR (1.3.2)
"function": {
"body": "axis", // the load-bearing spine of the creature
"LArm": "locomotion", // what moves it: legs, wings, fins, wheels
"RArm": "locomotion",
"LLeg": "effector", // the end that reaches out and contacts the world
"case": "ornament" // carried, not load-bearing, does no work
}
Keys are chain names. A chain listed in mirror covers its twin automatically.
A part bolted onto a chain inherits that chain's function, so "neck": "effector"
covers the blade mounted on the neck; naming the part directly also works.
Five words, all manufacturing vocabulary. Nothing here says how hard a thing hits or what it is worth in a fight — that is the receiving system's business.
A declaration is not a label; it is a claim the engine checks:
| check | what the declaration has to pay for |
|---|---|
effector_leads |
at the frame the attack reaches furthest, the effector is the frontmost mesh |
attack_windup |
the effector winds back 5% of its travel, or swings 15% out to the side |
gait_footfall |
a locomotion chain that touches ground lands in FRONT of where it lifts |
self_clip |
nothing that starts far apart ends up inside something else |
clip_closes |
a non-looping clip returns to its first frame |
ground_clip |
nothing goes below the plane the creature stands on |
harness/autofix.mjs fixes the arithmetic ones before a round is spent — the ground
offset, the loop closure, and the compensation of joints that must hold their own aim
while the body turns for some other purpose. It never touches the decisions: which way
a leg swings, what the creature attacks with, how far it lunges.
joint_range — how far each joint turns (1.3.2)
"joint_range": {
"LKnee": { "rx": [-130, 10] }, // a knee is a hinge, one way
"LSh": { "rx": [-50, 90], "ry": [-60, 60], "rz": [-70, 70] },
"Beak": { "rx": [-10, 40] }, // opens, does not close past shut
"BallTop":{ "rx": [-35, 35], "ry": "free" } // hangs on a chain, spins freely
}
Degrees, per axis, in the joint's own frame — the same frame and the same axis
names (rx/ry/rz) the animation tracks use, so a limit and a track compare
directly.
- An axis you leave out is LOCKED at 0, not free. A table with holes in it is a
table that checks nothing, and one axis per joint is the common case anyway.
"free"opts an axis out on purpose — a rotor, a wheel, a weight on a chain. - Declare the L side only. The R twin is generated:
ryandrznegate, which swaps the ends of the interval, so[-10, 90]becomes[-90, 10]. Writing both sides by hand is how mirrored limbs get broken. WritingR…explicitly overrides, for a body that really is asymmetric. - Write what the ANIMAL can do, not what your clip happens to use. A limit is a fact about the body; a track is one use of it. If they are the same numbers, the declaration is not saying anything.
What the declaration has to pay for:
| failure | what it means | the fix |
|---|---|---|
| undeclared | a clip turns a joint with no entry | write the entry |
| overrun | a track leaves its own declared interval | fix the track, or the number — one of them, not both |
| unreachable | the body collides before the declared limit | tighten the number to the angle the engine reports |
unreachable is the one worth understanding. You know a gorilla's shoulder swings 60°
back; you do not know that THIS gorilla has a wrecking ball hanging off a crane on its
back, so its arm stops at 53°. The engine sweeps every declared bound against the actual
geometry and reports the last angle that clears. Authored knowledge, checked arithmetic —
neither one alone is enough.
name on every part — the identity channel (1.3.2)
"parts": [
{ "name": "nose_leaf", "type": "fin", "host": "Muzzle", "material": "paw" },
{ "name": "foot_claws", "type": "paw", "host": "LToe", "material": "paw", "mirrored": true },
{ "name": "left_tusk", "type": "curve", "host": "Muzzle", "material": "tusk" }
]
Required, and unique within the creature. It may not reuse a chain name, because volumes are identified by their chain.
Why it is not optional, and why the material cannot do the job. A material is a
CLASS — "this is horn", "this is brass pipe". Many parts share one on purpose, and the
GLB merges primitives one per material so a body with forty plates does not ship forty
draw calls. That makes a material name structurally unable to answer which part is
this: above, paw names both a foot pad and a nose-leaf, and anything that groups by
material adds the two together. Naming is the fix, and it costs nothing — you already
know what you are building at the moment you write the part.
Name the THING, not its type and host. spike@Skull is a description of where you put
something, and two spikes on one skull share it; left_horn and right_horn are names.
The engine writes each name into the file as asset.extras.part_spans, with the exact
vertex range that part owns — so a checker, the Arena importer or graft.py can point
at one piece of geometry without a single extra material.