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 |

### 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` |

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.