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	— (none yet; ancestor registered 2026-08-13, derivatives pending)

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	shipped	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

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.