animation/characters/REGISTRY.md

# Character Model Registry

Naming law for `characters/`. **Scope: this system applies only to newly created
variants derived from mako and lena** — every such artifact from here on, *wherever
it is produced*. (This clause used to read "anything born in this folder", which let
the AccuRig rig baits get built into `ariki-game/assets/models/characters/rig-work/`
and slip the net entirely; they were moved here 2026-08-06. 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; they will eventually be
replaced by files that follow this system.

Modeled on the dance registry (`.agents/wiki/dances/REGISTRY.md`): numbers are never
reused, superseded files are archived, never deleted.

## Filename grammar

```
<character>[_<variant>...]_<stage>_<format>_v<NN>.<ext>
```

- **character** — registered name from the Characters table below (`lena`, `mako`).
  New characters get a row here before their first file exists.
- **variant** — optional sculpt-level descriptors (`elder`, `muscular`). A new
  variant is a new folder and a new Characters-table row.
- **stage** — exactly one token from the closed vocabulary below.
- **format** — file format tag matching the extension (`fbx`, `glb`).
- **v\<NN\>** — mandatory two-digit version, per-artifact.

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 (sculpt-level alteration) |
| `decimated` | post-decimation, unrigged |
| `tpose` | pose-prep export for a rigging tool |
| `accurig` | AccuRig output, CC_Base_* skeleton |
| `mixamo` | Mixamo-rigged (legacy lane) |
| `quatskin` | 65-bone Quaternius UAL game skeleton |
| `lod<NN>` | LOD at NN% of tris (appended after `quatskin`) |
| `toned` | skin-tone pass (appended after `quatskin`) |

## The rules

1. **Originals are read-only; delivered names immutable** — even misspelled or
   inconsistent (`female_lena_tripo` keeps its missing `_v1`). Identity is recorded
   in this registry, never fixed on disk. Renaming would fork identity vs the
   name-synced mirror in `ariki-game/assets/models/characters/race-sources/` and
   risk breaking FBX-internal texture paths.
2. Every new derived file matches the grammar above and starts with a registered
   character name. Canonical male spelling is **`mako`** — the AccuRig-era `moka`
   typo and `moko` are never used in new files.
3. Exactly one stage token per filename.
4. Version is per-artifact; **ancestry lives in this registry, never in the name**
   (a `quatskin_v01` built from `decimated_v03` does not encode the parent's version).
5. **Status lives in this registry, never in a filename** — no `_candidate`,
   `_final`, `_locked`.
6. New geometry identity = new character-variant folder (e.g. `female/lena_elder/`);
   re-run of the same recipe = version bump. Test: "would the game treat it as a
   different character/body?" → new variant; "a better attempt at the same thing?"
   → bump. Numbers never reused.
7. FBX or loose-texture models get a folder named exactly the model basename
   (e.g. `mako_accurig_fbx_v01/`); loose textures inside are `<character>_<map>.<ext>`
   (`mako_basecolor.jpg`) — 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-name
   column below. Never create `Ariki_*` files in this repo.
9. Superseded files move to `characters/archive/` — never deleted, never renamed.
10. Every new file under `characters/` (outside `archive/`) gets a row in the
    Derived artifacts table before its first commit.
11. **`characters/rig-work/` is exempt from the grammar and from rule 10** — it
    holds disposable AccuRig rig carriers ("baits"): decimated FBX copies whose
    only job is to carry a skeleton out of AccuRig and back. They are never
    shipped and never contribute geometry to a registered artifact (the graft
    takes geometry from the GLB parent and only the skeleton from the bait), so
    they get no row of their own — instead the grafted body's **notes** column
    names the bait it got its skeleton from. Keeping their tool-era names is
    deliberate: they must stay recognisable as throwaway. See that folder's
    `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 (copied from ariki-game race-sources) | mako generation 1, unrigged A-pose ~1.9M tris |
| `originals/male/male_base_bald_tripo_v1.glb` | `59df0de4b097428324f6b9048e0eeb7e8e034062aa8c8dad7e1eba1937be8aca` | Özlem | Tripo | 2026-08-04 (copied from ariki-game race-sources) | mako generation 1 |
| `originals/female/female_lena_tripo.fbx` | `c3a7cb1bf4958b27bd81b6bf73fd132c88f7a582d045c8936992d5d22bfd4e8e` | Özlem | Tripo | 2026-08-04 (copied from ariki-game race-sources) | lena generation 1 — delivered name has no `_v1`; treat as v1 |
| `originals/female/female_lena_tripo.glb` | `de17a1e7d56cefc3e07596bfb08efc65b41d04fac709c27b76500729e4fbb4b8` | Özlem | Tripo | 2026-08-04 (copied from ariki-game race-sources) | lena generation 1 |
| `originals/female/female_lena_leafbikini_tripo.glb` | `977104ba4338ca76e04696d130dd21f0924a5614baa5f1ab8339d5c07666cf29` | Özlem | Tripo | 2026-08-13 (copied from ariki-game race-sources) | 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 (copied from ariki-game race-sources) | 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 of the originals under grammar-conforming names, so tools can
reference canonical names without touching the immutable delivered files. Same
read-only guard, same checksums as their sources above.

| 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 | description | status |
|---|---|---|---|---|
| `mako` | male | `male_base_bald_tripo_v1` | bald base male, Tripo sculpt. Spelling history: game wiki "Mako", AccuRig-era typo "moka" — canonical filename token is `mako` | active |
| `lena` | female | `female_lena_tripo` | base female, Tripo sculpt | active |
| `lena_nude` | female | `female_lena_tripo` | lena with the sculpted-in underwear removed: no bra, no briefs, breasts with volume and no nipples, featureless crotch. Separate variant rather than a version of `lena` because the game selects it as a different body (rule 6) | active |
| `lena_leafbikini` | female | `female_lena_leafbikini_tripo` | lena wearing a sculpted-in leaf bikini garment, Tripo sculpt. Separate variant rather than a version of `lena` because the game selects it as a distinct clothed body (rule 6) | active |

## Derived artifacts

Status vocabulary: `wip / candidate / approved / shipped / archived / rejected`.

| name | character | parent file | stage | tool/script | date | status | ship name | notes |
|---|---|---|---|---|---|---|---|---|
| `female/lena_nude/lena_nude_quatskin_glb_v01.glb` | `lena_nude` | game-side `Ariki_Female_QuatSkin.glb` (+ `Ariki_Female_QuatSkin_ChestV1.glb` as breast-shape donor) | `quatskin` | `tools/make_lena_nude_body.py` (`--size 1.0`) | 2026-08-04 | candidate | `Ariki_Female_QuatSkin_Nude.glb` (not yet released) | sha256 `931c0948a3b0201dbfbdd4d2671c3ae41688afc592a29e332bc2bab234aa1ad3`. Texture embedded, internal image name `lena_nude_basecolor` (no ship name baked inside a WIP asset). 31,670 v / 65 joints / 1.777 m; passes `tools/verify_body_variant.py` against the canonical body. Vertex count is below stock by design — the base mesh's open slits are welded shut, since the painted underwear had been hiding them. `--size` is breast volume; a different size is a version bump, not a new variant |
| `female/lena_nude/lena_nude_basecolor.png` | `lena_nude` | game-side `Ariki_Female_QuatSkin_Lena_Body_Toned.png` | — (texture) | `tools/_bake_nude_body_texture.py` | 2026-08-04 | candidate | `Ariki_Female_QuatSkin_Nude_Lena_Body_Toned_nude.png` (not yet released) | sha256 `576fcf614cfcb19befd5bd4fb57210b526db2754f7d35468b21252f31528c9f2`. 4096² albedo with bra and briefs inpainted out to uniform skin, no tan line. Loose copy for iteration; the shipped GLB embeds it. Unversioned per rule 7 |
| `female/lena_nude/lena_nude_sculpt_glb_v01.glb` | `lena_nude` | `originals/female/female_lena_tripo.glb` (hires, pre-decimation) + game-side `Ariki_Male_QuatBody_D_RigCandidate.glb` (crotch donor) | `sculpt` | `female/lena_nude/hires_claude/` pipeline (00 weld → 03 sculpt → 06 crotch+membrane → 05/05b texture+grade → 08 export); reference `female/lena_nude/reference_breasts.jpg` | 2026-08-05 | candidate | — (game asset derives via decimation later) | sha256 `cb781cf376dc046b108d1c00e2368e0ed7e74fde5a783bedc6fc435818e4b2c7`. 953,966 v / 1,907,931 tris / 0.9792 units tall, unrigged. Full-density nude: garment membrane-removed, C-cup round breasts (apex projection 0.040 units, cleavage gap 7 mm), no nipples; crotch = male-GLB donor + bi-harmonic gusset heal (featureless). Basecolor + normal + rm embedded; fabric repainted by 3D-nearest skin fill, rosy chest V graded out to uniform skin. Masters: `hires_claude/06_final.blend` (geometry), `07_polished.blend` (textured) |
| `female/lena_nude/lena_nude_sculpt_glb_v02.glb` | `lena_nude` | v01 geometry + `originals/female/female_lena_tripo.glb` textures | `sculpt` | `hires_claude/05_texture.py` in `patch` mode (garment texels only, mirror-averaged fill from her own skin) + `06f` fold melt; master `hires_claude/10_patch.blend` | 2026-08-05 | candidate | — | sha256 `4a8c811305352a5fc60a58f6146c6797de03131da56dbd4073f90580d2e59e9b`. Same nude geometry as v01 but ORIGINAL skin everywhere (rosy chest V, arm/leg tones kept); only the bra/briefs/strap/crotch texels are refilled. Jeremy's preference after v01's global tone grade changed too much of her look |
| `female/lena_nude/lena_nude_sculpt_glb_v04.glb` | `lena_nude` | `lena_nude_sculpt_glb_v03.glb` (master `hires_claude/29b_final.blend`) | `sculpt` | `hires_claude/33_bust_variants.py` (size study) → `34_apply_bust.py --k 0.5`; master `hires_claude/34_v04.blend` | 2026-08-06 | candidate | — | sha256 `88931098f27915f5a498a1bccc014e800af7e8fff3e1d43faf8b97616c307910`. 860,389 v / 1,721,805 tris, geometry identical to v03 except the bust. **Guided by the approved concept turnaround** (`exchange/INBOX/lena-base-turnaround`, GPT Image 2, approved by Can 2026-08-06): `32_ref_measure.py` compared reference silhouette against mesh and found proportions already agree — 6.43 vs 6.08 heads, waist/hip 0.504 vs 0.505, widths within 5% — with the bust the one real gap. Breast forms rescaled to 50% of their projection off a bi-harmonic chest wall, taking bust projection +0.0210 → **+0.0155 H against the reference's +0.0156**. 68,781 verts moved (max 27.8 mm, median 5.5 mm in-region), zero movement outside the chest region, height unchanged. Texture/UVs untouched from v03. Caveats: the projection metric saturates below k≈0.5 (k=0.35 also reads +0.0154) and the reference reading may be inflated by the T-pose arm crossing the chest in the side view, so 0.5 is a floor rather than a midpoint; front renders cannot distinguish sizes (frontal key light flattens the chest) — judge from the side |
| `female/lena_nude/lena_nude_decimated_glb_v01.glb` | `lena_nude` | `lena_nude_sculpt_glb_v03.glb` (master `hires_claude/29b_final.blend`) | `decimated` | `hires_claude/30_decimate.py` (COLLAPSE ratio **0.037728**, bisected to hit the vertex target) + `30b_fix_winding.py` | 2026-08-06 | candidate | — | sha256 `b11940bb46732ae0a60e1624e88e76fa48dcc3e3af49a6363348521bb7c52cc8`. 31,964 v / 64,957 tris in Blender (46,810 / 64,957 as exported, UV seams split verts) — 3.72% of the sculpt, matched to `lena_nude_quatskin_glb_v01.glb`'s 31,670 v at Jeremy's request. Unrigged, no skins, transforms applied; basecolor + normal + rm embedded. Height preserved to +0.12 mm, bbox unchanged. **Built as input for the re-atlas lane** (`24_seams.py`): collapse destroys Tripo's 5,870-chart UV layout, so the carried TEXCOORD_0 smears badly and is expected to be replaced, not reused. Residual: 25 backfacing tris of 64,957 (down from 61; the remainder sit in non-manifold knots where consistent-orientation oscillates), plus the sculpt's inherited 835 boundary / 1649 non-manifold edges |
| `female/lena_nude/lena_nude_sculpt_glb_v03.glb` | `lena_nude` | v02 chain head `hires_claude/10_welded.blend` | `sculpt` | `hires_claude/` 17 line heal → 26 median despeckle + cleavage fillet → 25 flipped-face repair → 29 on-body tone levelling → 08 export; masters `27_clean.blend` (geometry), `29b_final.blend` (textured) | 2026-08-06 | candidate | — | sha256 `7a8fe4c45d3af6acb7b39c2fac5fcc2aadf910f8d61a4a7d046911125a6e8baa`. 860,389 v / 1,721,805 tris. Jeremy's three v02 notes: (1) cut lines — reduced, not gone: shading kinks >12° 9704 → ~6900, ribcage/thigh lines gone frontally, waistband + underbust still legible under raking light; (2) discolouration — the pale bra/briefs panels are gone, on-body tone gap patch-vs-skin 0.0102 → 0.0068 luma; (3) cleavage — sternum fillet radius 9.5 mm → no sharp sample, notch depth 44 → 31 mm. Also 1511 → 10 flipped faces (the black dashes). Still open: 1649 non-manifold + 830 boundary edges (every fill refused them). See the lane README for the four dead ends this version ruled out |
| `female/lena_nude/lena_nude_decimated_glb_v02.glb` | `lena_nude` | `lena_nude_decimated_glb_v01.glb` (geometry byte-for-byte unchanged) | `decimated` | `hires_claude/24_seams.py` (anatomical seams + minimum-stretch unwrap) then `hires_claude/31_reatlas.py` (map resample) | 2026-08-06 | candidate | — | sha256 `cd3d53550470ae5a1958dc473ce11793f746b13f78ac911e6d426b6f7b9f5825`. **Re-atlas only — same 31,964 v / 64,957 tris, same shape, same material, unrigged.** Replaces Tripo's 5,870-chart atlas with 14 anatomical charts (torso, head, 2 arms, 2 legs, 2 hands ×2, 2 feet ×2): coverage 62.0→68.6%, texel density spread 1.8x→1.00x, per-triangle area-scale p95 2.55→1.77 / p99 4.25→2.27. Exported vertex count drops 46,810→42,980 because the new layout has far fewer UV seams. Maps resampled into the new layout at 4096², normal map rotated per face into its new tangent frame (p50 81°). Renders identical to v01: mean pixel \|Δ\| 0.0012, p99 0.0118 over five views (`hires_claude/33_ab.py`). Version bump, not a new variant, per rule 6 — same body, better atlas |