animation/characters/REGISTRY.md

Character Model Registry

Naming law for characters/. Scope: newly created bodies derived from mako and lena — every such artifact from here on, wherever it is produced. A character artifact generated in another repo is still governed by this file and still belongs under characters/.

Legacy models elsewhere — game-side derived-bodies/, old intermediates, historical race-sources — keep their names and are NOT registered here.

---

The central rule: a folder is born at ship time

A character folder exists only for a body that has shipped to ariki-game. Not for a variant, not for an experiment, not for a promising candidate. Until it ships, it is lane material and it lives in characters/work/.

characters/
  originals/            immutable delivered sources — never modified, never renamed
  female/
    lena_base_v01/      SHIPPED 2026-08-10   <- frozen
    lena_base_v02/      the next one to ship
  male/
    mako_base_v01/      SHIPPED 2026-08-12   <- frozen
  work/
    lena/               the live lane: recipes + masters. Grammar-exempt.
    mako/
  rig-work/             disposable AccuRig carriers. Grammar-exempt.
  archive/              superseded SHIPPED folders only

Folder grammar

<character>_base_v<NN>

NN is the ship ordinal for that character — the 1st shipped lena is lena_base_v01, the 2nd is lena_base_v02. It counts ships, not attempts. Numbers are monotonic and never reused, even if a ship is later rolled back.

This replaces the old variant-folder scheme (lena, lena_nude, lena_elder). A nude body, an elder body and a re-sculpt are no longer three folders — they are whichever of them actually ships, numbered in the order they ship. What distinguishes them is recorded in the ship folder's README, not in its name.

File grammar inside a ship folder

<character>_base_<stage>_<format>_v<NN>.<ext>

NN is the folder's ship number, repeated — not a per-artifact counter. Every file in lena_base_v01/ ends _v01. This is the one real break from the old law (old rule 4: "version is per-artifact"), and it is deliberate: per-artifact counters are what produced ten decimated_glb_vNN files sitting next to four sculpt_glb_vNN files with no way to tell which went together. Now the version identifies the ship, and everything carrying it belongs to that ship.

All lowercase snake_case, [a-z0-9_] only. No dates, no status words, no hyphens.

Stage vocabulary (closed set — extending it is an edit to this table)

token	meaning
sculpt	unrigged full-res mesh
decimated	post-decimation, unrigged
tpose	pose-prep export for a rigging tool
accurig	AccuRig output / AccuRig-skeleton body
quatskin	65-bone Quaternius UAL game skeleton
lod<NN>	LOD at NN% of tris (appended after quatskin)

The rules

1. Originals are read-only; delivered names immutable — even misspelled (female_lena_tripo keeps its missing _v1). Identity is recorded here, never fixed on disk: renaming would fork identity against the name-synced mirror in ariki-game/assets/models/characters/race-sources/ and can break FBX-internal texture paths.
2. A ship folder is frozen on ship. Nothing inside it is ever edited, re-exported or re-graded. A change of any kind means the next _vNN folder. This is what makes the folder a truthful record of what the game actually has.
3. A ship folder holds only what the ship needs: the shipped body, the inputs that cannot be regenerated by script, a preview/ render set, and a README. Working .blend files, QA renders, probes and superseded stages do not belong here — they are lane material.
4. Exactly one stage token per filename.
5. Ancestry lives in this registry and the folder README, never in a filename.
6. Status lives in this registry, never in a filename — no _candidate, _final, _locked.
7. FBX or loose-texture models get a folder named exactly the model basename; loose textures inside are <character>_<map>.<ext> — no version chains in texture names. .fbm/ folders and Tripo UUID internals are never renamed.
8. Boundary law: snake_case = animation-repo working names; PascalCase Ariki_* = game-repo ship names. The rename happens exactly once, at import into ariki-game/assets/quaternius/derived-bodies/, and is recorded in the ship table below. Never create Ariki_* files in this repo.
9. A superseded ship folder moves to characters/archive/ — never deleted. This applies to ship folders only. Lane material is governed by .agents/rules/working-files.md and is deleted freely.
10. Every ship folder gets a row in the Ships table before its first commit.
11. characters/work/ and characters/rig-work/ are exempt from the grammar and from rule 10. They hold recipes, masters and disposable rig carriers. See .agents/rules/working-files.md and rig-work/README.md.

---

Originals

Never modified, never renamed, never resaved in place. Verify with Get-FileHash -Algorithm SHA256.

file	sha256	delivered by	tool	date	identity note
originals/male/male_base_bald_tripo_v1.fbx	f7c884bb8b8a71351b1448fa355658459a61a2537fdd48f9c72e52709693608c	Özlem	Tripo	2026-08-04	mako generation 1, unrigged A-pose ~1.9M tris
originals/male/male_base_bald_tripo_v1.glb	59df0de4b097428324f6b9048e0eeb7e8e034062aa8c8dad7e1eba1937be8aca	Özlem	Tripo	2026-08-04	mako generation 1
originals/female/female_lena_tripo.fbx	c3a7cb1bf4958b27bd81b6bf73fd132c88f7a582d045c8936992d5d22bfd4e8e	Özlem	Tripo	2026-08-04	lena generation 1 — delivered name has no _v1; treat as v1
originals/female/female_lena_tripo.glb	de17a1e7d56cefc3e07596bfb08efc65b41d04fac709c27b76500729e4fbb4b8	Özlem	Tripo	2026-08-04	lena generation 1
originals/female/female_lena_leafbikini_tripo.glb	977104ba4338ca76e04696d130dd21f0924a5614baa5f1ab8339d5c07666cf29	Özlem	Tripo	2026-08-13	lena_leafbikini generation 1 — lena wearing a sculpted-in leaf bikini
originals/female/female_lena_leafbikini_tripo_fbx/tripo_convert_9bb20cb8-9dff-4b8a-99c1-f087540d4aa4.fbx	d11693f331d144c64520ffe89b7e755ccd44e7aa0398a8808fc97664975aaf3a	Özlem	Tripo	2026-08-13	lena_leafbikini generation 1 — FBX delivery; lives in a _fbx/ folder with its .fbm/ textures, UUID name kept per rule 7

Canonical-name aliases

Byte-identical copies under grammar-conforming names, so tools can reference canonical names without touching the immutable delivered files.

file	byte-identical to	date
originals/female/lena_sculpt_fbx_v01.fbx	female_lena_tripo.fbx	2026-08-04
originals/female/lena_sculpt_glb_v01.glb	female_lena_tripo.glb	2026-08-04
originals/male/mako_sculpt_fbx_v01.fbx	male_base_bald_tripo_v1.fbx	2026-08-04
originals/male/mako_sculpt_glb_v01.glb	male_base_bald_tripo_v1.glb	2026-08-04

Characters

character	gender	parent original	ships so far
lena	female	female_lena_tripo	lena_base_v01
mako	male	male_base_bald_tripo_v1	mako_base_v01
lena_leafbikini	female	female_lena_leafbikini_tripo	lena_leafbikini_base_v01 (live lane: work/lena_leafbikini)

Spelling history for the male: game wiki "Mako", AccuRig-era typo "moka", also "moko". Canonical filename token is mako; the others are never used in new files.

---

Ships

Status vocabulary: shipped / superseded / rolled-back.

folder	character	date	status	ship name in ariki-game	sha256 (repo-side body)
female/lena_base_v01	lena	2026-08-10	superseded	Ariki_Female_QuatSkin_Nude.glb, and swapped into Ariki_Female_QuatSkin.glb	0d602accef0992a6a0dfffa5b73b1f9b702400df5258ff7517f786f11050f4d0
male/mako_base_v01	mako	2026-08-12	shipped	Ariki_Male_Mako.glb (male Ariki default, lineage MALE-MAKO-FULLHEAD-V1)	220714a2fb6283188be3834214877204533fde78de9a6ffa03ed85e1167735d3
female/lena_leafbikini_base_v01	lena_leafbikini	2026-08-13	shipped	Ariki_Female_QuatSkin.glb (female Ariki default) + Ariki_Female_QuatSkin_LowPoly_40.glb (LOD1)	bbfd8ac3919ad171cab76d62bec133d1f149ee3cf3c5d27f7408d502e99d678e

lena_base_v01 is marked superseded, not rolled-back: she was displaced from Ariki_Female_QuatSkin.glb on 2026-08-13 but her own ship name Ariki_Female_QuatSkin_Nude.glb is untouched and still in the game. Per rule 9 her folder moves to characters/archive/ only when that file goes too. Nothing about her was wrong — the game simply changed which body is the female default.

lena_base_v01 — what it is

Lena with the sculpted-in underwear removed (no bra, no briefs, breasts with volume and no nipples, featureless crotch), athletic definition in the normal map, on the 65-bone Quaternius contract. She is now the game's female base body, not a side variant — Ariki_Female_QuatSkin.glb was swapped to her on 2026-08-10, with the previous body kept as Ariki_Female_QuatSkin_PRESWAP_2026-08-10.glb.bak.

Ancestry, condensed from the 20 intermediate stages that produced her (all pruned 2026-08-11; the recipes in work/lena/ regenerate any of them from originals/female/female_lena_tripo.glb):

step	what happened
sculpt	garment membrane-removed, crotch healed with a male-GLB donor + bi-harmonic gusset, bust rescaled to match the concept turnaround approved by Can 2026-08-06 → 860,389 v
decimate	COLLAPSE 0.037728 → 31,964 v (3.72% of the sculpt)
re-atlas	Tripo's 5,870-chart UV soup replaced with 14 anatomical charts; maps resampled at 4096², normal map rotated per face into its new tangent frame
refill	breast/underwear texels re-authored by a harmonic solve with Dirichlet boundaries, so the fill equals her real skin at the mask edge — no ghost outline
despeckle	two defects, not one: 892 folded edges collapsed/dissolved (geometry) + 44k local-contrast texels inpainted (Tripo scan noise) → 31,111 v
musculature	anatomy into the NORMAL map only, geometry untouched; 3D-space gradient projected into per-texel tangent frames so the back midline seam does not tear
rig	AccuRig 1.10.1822.1, manual. 101 CC_Base_* bones. Vertex order preserved, so weights grafted index-exact, not nearest-surface — this is what avoided the mangled fingers of the July lane
quatskin	ariki-game/tools/make_lena_nude_quatskin_accurig.py → 65 joints, 1.777 m, rigid-mitt fingers

Departure from the approved concept: the turnaround Can approved is a smooth mannequin with no muscle definition. The shipped body has athletic definition (42_musculature.py strength 1.0, SPINE=0.34). Flagged here so it is a known decision rather than a drift.

mako_base_v01 — what it is

The Tripo male sculpt with the body decimated and the head untouched (158,575 tris, full scan resolution, cut at the neck at 86.5% of height): body 24k / hands 40k. First mako-geometry body ever in the game — it replaced the July graft body (Superhero_Male + Lena's head, MALE-MAKO-D-V1, kept on disk as comparison) as the male Ariki default.

step	what happened
decimate	body/hands only (work/mako/01_decimate_fullhead.py); head gated bit-identical → 222,575 tris
rig	AccuRig 1.10, manual, on a 1.700 m materials-free carrier → 101 CC_Base_* bones
graft	index-exact (122,062 verts both sides), mesh moved 0 mm (work/mako/02_graft.py)
quatskin	ariki-game/tools/make_mako_fullhead_quatskin_accurig.py HEAD_SAFE=1 → 65 joints, 1.818 m, rigid mitts, body-only weld + body-only split-normals clear

Known decisions: height 1.818 m is provisional (IB-lane taller-than-Lena convention, not eye-locked); ship name avoids the QuatSkin/QuatBody tokens because PlayerController string-gates on them; no male LOD1 yet. Details in the folder README.

lena_leafbikini_base_v01 — what it is

Lena wearing a leaf bikini sculpted into the mesh — not a garment, so there is no cloth to fit and no OutfitCatalog entry. Full-resolution Tripo scan (999,823 v after weld) at 1.777 m, the game's female default from 2026-08-13.

She is the first ship of a separate character, not a lena_base_v02: she descends from her own Tripo original and shares no geometry with the nude sculpt, which is why the Characters table has carried a lena_leafbikini row since the ancestor was registered.

step	what happened
bait	tools/rigbait_decimate.py body 24k / head 14k / hands 40k → 51,682 v, no scale, no recenter
rig	AccuRig 1.10.1822.1, manual, on the bait → 101 CC_Base_* bones
graft	nearest-surface (work/lena_leafbikini/01_graft.py) — 51,682 v carrier onto the 1,029,360 v pristine mesh; mesh moved 0 mm, 0 unweighted verts, rest-pose drift 0.000239 mm
quatskin	ariki-game/tools/make_lena_fullres_quatskin.py LENA_CLEAR_SPLIT_NORMALS=1 → 65 joints, 1.777 m, rigid mitts

First nearest-surface graft in this lane. The two earlier ships were index-exact because AccuRig had been given the shipping mesh whole; a 20:1 decimated bait makes that impossible. AccuRig's 9.346 mm offset is recovered in closed form by fitting the rigged carrier against the bait, which is index-exact with it and already in the GLB's space — so the bait is a required input to the graft, not disposable, and lives in the ship folder.

Known decisions: single-sided, unlike lena_base_v01 whose doubleSided=true was forced by inward-wound patches this mesh does not have; no Ariki_*_LeafBikini.glb companion file (the _Nude.glb precedent would have cost a duplicate 79 MB full-res body in LFS and a duplicate Godot import — the new LENA_OUT_GLB override writes the canonical name directly); LOD1 is 391,948 v, far heavier than the 14,559 v body it replaced, because make_lena_lowpoly.py protects the head at full resolution and this head alone is 103,225 v.

---

Lane artifacts (not ships)

Rule 11 exempts work/ from the folder grammar and from rule 10, so nothing below has — or needs — a Ships row. They are listed here because they are registered lane milestones: someone else must be able to find out what a heavy binary sitting in a gitignored v0N/ dir is, and why. Each is git add -f'd against characters/work/*/v0[0-9]/, exactly as that .gitignore rule anticipates.

file	sha256	date	built by	what it is
work/lena_leafbikini/v01/lena_leafbikini_leafcut_sculpt_glb_v01.glb	8aa3421e98e985b57bda222a5cee6fd87343b6b773376c740bd907ae08db8897	2026-08-13	work/lena_leafbikini/04+05	the leaf bikini cut away at its seam, holes left open

lena_leafbikini_leafcut_sculpt_glb_v01 — what it is

originals/female/female_lena_leafbikini_tripo.glb with the leaf geometry deleted along the line where it stops being Lena: 474,224 faces and 247,658 vertices removed (23.8% / 24.1%), leaving two open holes — bust and briefs. The holes are not filled, by request. It exists so the seam itself can be judged before any repair is designed.

The leaves are welded into the body — one Tripo mesh, one material, one UV map — so they are a bulge in the body surface, not a separable object. They are also real geometry, which is the opposite of the case lena_base_v01 had to solve: there the sculpted-in underwear was the skin, painted on, so deleting it opened a hole and the fix was to re-fair a rim crease (tools/make_lena_nude_body.py). Here there is a shell to remove, and the seam is found by a hue key — skin 20–40°, leaf 60–80° — repaired on the mesh over position-welded adjacency, then grown 2 rings so the cut lands just outside the rim. work/lena_leafbikini/README.md carries the full reasoning and the regeneration commands.

Unrigged, because it was authored on the pristine original. That costs nothing: the graft that produced the ship moved the mesh 0.000000 mm, so lena_leafbikini_base_v01 holds the same 1,029,360 vertices in the same order and work/lena_leafbikini/leaf_mask.npz indexes either mesh. Cutting the shipped body is the same stage 05 with a different input — and per rule 2 its result is a new ship folder, never an edit to the frozen one.