The making
Parameters, not baked assets
Proportions, pose, palette and polygon budget are values in a file. That is the whole claim, and it is worth making only if the pipeline that turns those values into a validated release is honest about what it has and has not proved.
What follows is the stack, the gates, and what each gate caught — including the ones that went green while the work was visibly wrong, which is most of what this project has learned.
The stack
Five layers, and the boundaries are provenance
Every canonical manifest hashes its complete foundation source tree. Extending v1 in place would invalidate all five static releases, so v2 and v3 are separate provenance boundaries rather than newer versions of the same thing.
The gates
Green is a correctness oracle, never a quality oracle
Format, closure, topology and provenance all passed while a lifecycle shipped with the wrong-coloured egg, hidden ember vents, and 26,000 triangles of featureless charcoal. Every gate below exists because something got through the ones before it.
The appearance gate
appearance/
A gate that can fail because the model looks wrong. Twenty-six views — three rings of eight at 45° from below, level and above, plus straight up and straight down — at one radius fitted once and held for every model, so a measure reports the surface rather than the framing. Each view renders twice, on black and on white; an opaque pixel is identical in both, which gives an exact mask instead of an assumption about the palette.
Why: Every defect this collection found by looking was found from an angle nobody had rendered. Floors come from what the briefs and specs ask for, not from what the models currently score — a gate calibrated to the assets can only detect a regression, and the failure it exists for is a first build passing everything while looking wrong.
Clip checks
rigkit.clipcheck
Zeroed amplitudes, parent and child continuity, loop behaviour, the declared clip shape, and the direction the motion is supposed to go in.
Why: A loop closes only if every rate is whole, and nothing else can tell you a motion points the wrong way.
The merge test
tools/merge_check.py
Measures how far any arm vertex sits inside the torso or the head, per frame, across a whole film.
Why: It found 142 worker-frames with an arm inside a chest or a head in a cut that had already passed everything else.
Finger clearance
humanoidkit/hands.py
Measures phalanx against phalanx, and measures the rig's own rest fan and droop at every call rather than assuming fingers start straight.
Why: A finger fault is a few pixels in any other film. Thrown on a wall at 2.4 times life size by the hand's own triangles, it is the picture.
Delivery verification
store.kit.verify
Local structural checks on the shipped GLB, plus the Khronos glTF-Validator when it is available.
Why: A missing external validator is reported separately. It is not the same result as Khronos validation passing.
What is actually shipped
Release state is a vector
| layer | state | current evidence |
|---|---|---|
| v1 static | current | All five release validators pass. |
| v2 rig foundation | partial | Baby, Crystal, Eastern and Wyvern manifests are current. Western's geometry validates but its source and foundation provenance are stale. |
| v3 deformation, clips, lifecycle | partial | Four families validate but their manifests predate the current v3 source. Western has no canonical v3 static release, and its rig export still shows orphaned weights. |
Fixtures
Craft studies
Fixtures built to expose one class of defect at the size it has to survive. Every fix they produced went back into the character kit, so the stories inherit it.
The Tool Study
One person and five hand tools in eleven beats: a spade dug, thrown and shouldered; a pick struck and prised; a knife whittling; a spear planted and thrust; a wheelbarrow walked and tipped. A fixture, not a story — built so hand faults have nowhere to hide.
Shadow Puppets
Someone sitting by a candle making shadow puppets on a wall: a dog, a goose, a rabbit, a cobra, a swan. It exists to look at fingers, which the wall shows at well over life size.
Version ladders
Each version came from reading the last one cold
Not from a note, and not from a test going green. Someone looked at the delivered frames, found the thing that was wrong, measured it, and fixed the cause rather than the symptom. Every rejected cut is kept — the current one is marked, and the rest are the evidence.
The Feast
v3 solved every stance against the rig's measured 0.477 m arm; v2 had assumed 0.56 m, so no hand ever arrived at what it held. v4 traced every stance snap to a threshold inside an otherwise smooth solver. v5 rebuilt the hand fold itself — fingers that twisted as they curled, a thumb that never opposed, and a wrist oriented after the fingers were folded, which silently unfolded them. v6 made the elbow pole hand-aware, taking 142 worker-frames with an arm inside a chest or a head down to three, at most 4.2 cm in.
The Tool Study
A fixture, not a story. Hand and limb defects are a few dozen pixels in a narrative film, which is how a hand closed on the hole in the middle of a D-handle and a wheelbarrow carried with its wheel half a metre in the air both survived five versions of the feast. v2 fixed feet skating under a body solved per frame; v3 a pick swung like a shovel and a knife held into the chest; v4 re-authored every stroke from the tool's contact with the world rather than from hand positions; v5 added the merge test.
Shadow Puppets
It exists to look at fingers. Each puppet is thrown on the wall at 2.4 times life size by the hand's own triangles, so a finger that crosses its neighbour is the picture. v1's stag read as a splayed hand and its swan sat in the corner of a mostly empty frame; v2 aims each performing lens at the measured centre of that puppet's shadow and keeps the elbow at the flame's height, where its shadow lands beside the hand's.
The Farm Battle
v1's dragons appeared to spin fiercely, its defenders read as inactive, and the single casualty was not visually clear. v2 still corkscrewed and used proxy figures rather than the project's own characters. v3 routes three exact-length, nearly straight planar spines through open attack lanes, casts every defender from the production humans, and gives the casualty a dedicated insert.
One decision worth writing down
The package is not the animal
The fifth family is built by a package called babydragon. Its lore name is the Thicket Hatchling, and LORE.txt section 6 is explicit about why: “It is not a baby dragon. It is a dragon that is small, which is a different and much more unpleasant thing.”
So the site ships the lore names and the package names stay in the engineering column. It is a small thing that would have leaked into every URL, nav label and filename if nobody had looked.
The record
26 recurring failure shapes, each with measurements
LEARNINGS.md is 16,224 words of cross-system synthesis. These are its section 2 headings — the shapes that turned up more than once, in more than one subsystem, and were named so they could be recognised the next time.
- 2.1The proxy problem
- 2.2Checks that cannot fail
- 2.3Discontinuity is the artefact
- 2.4Nothing should be authored in metres
- 2.5Rigidity is the default; softness is the exception
- 2.6Fixing the shape beats fitting the deformation
- 2.7Green is a correctness oracle, never a quality oracle
- 2.8A joint rotated without its descendants is a break, not a bend
- 2.9A loop closes only if every rate is whole
- 2.10Nothing else can tell you a motion points the wrong way
- 2.11An effect is sized against the frame, not against the animal
- 2.12The effects are a third of the work and have no contract at all
- 2.13Two definitions of one envelope will drift
- 2.14Count it before you claim it
- 2.15Age is not size, and topology has to carry the anatomy
- 2.16Connectivity by vertex index is not connectivity
- 2.17Proximity is a guess about authorship
- 2.18A contact is against the surface, never against a bone plus a number
- 2.19A renderer's cost is the shape of a triangle, not the count of them
- 2.20A causal verb needs causal state
- 2.21A metric is trustworthy only after a failed witness
- 2.22Camera correctness is visibility, not collision clearance
- 2.23Representation sets the ceiling before tuning begins
- 2.24The executable artifact is the evidence
- 2.25Release state is a vector, not a boolean
- 2.26Repository cleanup is dependency and lifecycle design
Downstream
What else the foundations carry
SurfaceKit
surfacekit/
Turns the surface-scoped mesh rows in ASSETS.txt into low-poly world props using the same part validator as the dragons.
HumanoidKit
humanoidkit/
Five peoples on one shared topology. The lightweight implicit path handles silhouettes and variants; the premium path deforms one stable CC0 topology and is what the films are cast from.
Fairy
fairy/
The sixth people on its own insect-scale flight body. It stays outside HumanoidKit because entering a dragon vent is its defining anatomy.
Store
store/
Downstream packaging. Reads validated canonical outputs and writes UVs, atlases, rigged files, LODs and manifests without touching a model's canonical output directory.
Branding
branding/
The identity, generated from parameters: palette, fault, marks, surfaces, counted facts and copy written to platform limits.
| system | built | measured | note |
|---|---|---|---|
| SurfaceKit props | 321 | 101,870 tris | 73 mesh rows, 321 declared variants. Variant seeds use Python's process-randomised hash(), so geometry is not byte-deterministic across interpreter processes. |
| People models | 52 | 6 peoples | 51 HumanoidKit people and variant GLBs cover five shared-topology peoples, plus 1 separate Fairy GLB on its own insect-scale flight body. |
| Store products | 2 | -- | Eastern Lung is the complete delivery: textured static and rigged GLB, FBX, .blend, four LODs, 2048 and 4096 maps, previews, notices and a draft licence. The second product ships GLBs, maps and a manifest, and does not yet mirror that surface. |