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** |
| `work/lena_leafbikini/v02/lena_leafbikini_crotchfill_sculpt_glb_v02.glb` | `de7b713e03fc9b8611b83cafdb6d24e1ad71eedc7045fea51e54eb166d632951` | 2026-08-14 | `work/lena_leafbikini/04`+`07` | the briefs leaves **melted into a smooth Barbie-doll crotch**; bust holes still 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.

### `lena_leafbikini_crotchfill_sculpt_glb_v02` — what it is

The same original with the briefs-band leaves **melted into a smooth featureless
"Barbie doll" crotch** (bi-harmonic membrane over the leaf shell's own topology — the rims
supply position, the collar supplies slope) with a pure-Laplacian flow finish. The bust
holes remain open from v01. Requested target: Barbie doll anatomy — no cleft, no features,
belly flowing into thighs; the geometry now does exactly that.

Known consequences, documented in the lane README (not defects to chase):
- **two mild shelf bulges at the hip sides** where the vine crossed the inguinal crease —
  there was never skin under the vine, and every rim-anchored fill spans its anchors by
  construction; removing them means sculpting the crease, a separate decision;
- **the fill is one flat donor texel** and leaf paint survives on skin just outside the
  melt — the albedo re-author is its own later stage (the atlas is Tripo chart soup).

Unrigged and vertex-compatible with the ship for the same reason as v01. The recipe
(`07_fill_crotch.py`) carries the ten-run autopsy of every approach that failed first —
worth reading before attempting any similar repair.