animation/docs/characters/head-features-contract.md

# Hair fit — what Ozan's system needs, why it is wrong on both ship bodies, and the pipeline fix

**Written 2026-08-12.** Measurements in §2 were taken today with
[`tools/measure_head_shell.py`](../../tools/measure_head_shell.py) against the currently
shipped GLBs. Eyebrows and eye colour are covered briefly in §6 — hair is the subject.

Game-side sources: `src/Character/OutfitSystem.cs`,
`src/Character/HeadAccessoryBindMath.cs`, `src/Data/CharacterBuildData.cs`,
`src/Viewer/PlayerController.cs`,
`assets/quaternius/derived-bodies/hair_fit_quatskin_female.json`.

---

## 1. How the hair system actually works

Sixteen Quaternius pieces — 6 female styles, 7 male styles, 3 facial-hair — live in
`assets/quaternius/source-hair/`. Each is a small mesh — **466 to 3,501 verts** — and every
one is **100 % rigidly weighted to the single `Head` bone**. Verified across six styles:
one joint, weight 1.0, no blending anywhere.

That single fact governs everything below. A hairstyle is not a skinned garment. It is a
rigid prop parented to one bone, authored in the rest-pose world space of the **stock
Quaternius body** — female styles on `Superhero_Female` (Head pivot Y 1.5496), male styles
on `Superhero_Male` (Head pivot Y 1.5998).

At runtime `PlayerController` attaches the style to whatever body loaded and corrects it with
three constants from `CharacterBuildData.HeadFit`:

| constant | effect |
|---|---|
| `HeadScale` | diagonal scale of the binds **about the Head rest pivot** |
| `HairOffset` | bind-space translation |
| `HairPitchDeg` | pitch about the same pivot |

Colour is `ApplyHairColor` → `StandardMaterial3D.AlbedoColor = swatch`, i.e. a **multiply**
against the hair card.

So the entire per-body fit is a 3-parameter diagonal scale plus a translate, hand-tuned in
`head_test_bed`, stored as C# constants.

---

## 2. Measured: both ship bodies are wrong, in opposite directions

Cranium band = Head-weighted verts within 8 cm of the skull top — the surface a cap actually
sits on. (The *full* Head-weighted shell, which is the measure quoted in `MakoHeadFit`'s
comment, is inflated several cm by jaw/ear/neck weight bleed. Use the band.)

| body | Head pivot Y | cranium w | cranium d | skull top above pivot | pivot above chin |
|---|---|---|---|---|---|
| stock `Superhero_Female` *(female hair authoring rig)* | 1.5496 | 14.84 | 20.11 | **21.69** | 1.2 |
| stock `Superhero_Male` *(male hair authoring rig)* | 1.5998 | 14.79 | 19.91 | **21.02** | 2.3 |
| `Ariki_Female_QuatSkin.glb` (Lena, ship) | 1.5687 | 21.44 | 25.96 | **20.83** | 12.8 |
| `Ariki_Male_Mako.glb` (Mako, ship) | 1.5687 | 18.79 | 24.03 | **24.93** | 7.3 |

Ratio the cranium against the same gender's authoring rig, and compare to the constant each
body actually carries:

| | needed | carried | error |
|---|---|---|---|
| Lena X | 1.445 | 1.545 | +7 % |
| Lena Y | **0.960** | **1.431** | **+49 %** |
| Lena Z | 1.291 | 1.426 | +10 % |
| Mako X | 1.270 | 1.316 | +4 % |
| Mako Y | 1.186 | 1.346 | +13 % |
| Mako Z | 1.207 | 1.327 | +10 % |

Push a scalp-hugging style through the real runtime chain
(`HeadAccessoryBindMath.RestToWorldStepwise`) and the consequence is concrete:

```
Hair_BuzzedFemale  authored crown 22.13 cm above its pivot
  on Lena, scale 1.431 / offset -0.060  ->  lands Y 1.8254   her skull top 1.7770
  crown vs skull  +4.84 cm   FLOATING

Hair_Buzzed (male) authored crown 21.37 cm above its pivot
  on Mako, scale 1.346 / offset -0.057  ->  lands Y 1.7994   his skull top 1.8180
  crown vs skull  -1.87 cm   BURIED
```

**A buzz cut floating ~5 cm over Lena's head, and one sunk ~2 cm into Mako's.** Both from
the same three constants.

Neither is a mystery. The code says so itself. Lena's constants carry a stale-marker: they
were tuned against the pre-swap body, whose skull top was **26.5 cm** above the pivot where
the AccuRig body that replaced it on 2026-08-11 measures **20.83 cm**. Her vertical
correction should now be ≈ identity; she is carrying a 43 % stretch plus a 6 cm drop that
were fitted to a skull 5.7 cm taller. Mako's were never bed-tuned at all — the comment calls
them "STARTING VALUES", derived by ratio off the inflated full-shell measure.

**Not yet eye-verified in `head_test_bed`.** These are rest-pose numbers from the bind chain;
someone should confirm the look before acting on them. But the direction and rough magnitude
are arithmetic, not opinion.

---

## 2b. The constants are derivable, not bed-guessable

A scale-about-pivot plus a translate has exactly two degrees of freedom per axis, so **two
matched cranium landmarks determine both constants outright** — no bed session. Take the
crown and the widest cranium slice (the temple/ear line) on the stock authoring rig and on the
ship body, solve, done. That is `measure_head_shell.py --fit`.

Scored against each style's *authored* clearance on its own stock rig — the correct test, since
a mohawk stands proud and a beard hangs at the chin by design:

| body | constants | worst error | mean error |
|---|---|---|---|
| Mako, 10 styles | carried `(1.316,1.346,1.327)` / `−0.057` | 8.04 cm | 3.17 cm |
| Mako, 10 styles | **derived `(1.363,1.000,1.322)` / `+0.0388,+0.0242`** | **0.00 cm** | **0.00 cm** |
| Lena, 6 styles | carried `(1.545,1.431,1.426)` / `−0.060` | 7.29 cm | 5.09 cm |
| Lena, 6 styles | **derived `(1.613,1.148,1.311)` / `−0.0411,−0.0094`** | 1.04 cm | **0.29 cm** |

Mako lands *exactly* because his fit comes out as a pure translate (Y scale 1.000), which
preserves every relative distance. Lena's residual is `Hair_LongDreads`, whose crown is far
from both fit landmarks.

This changes the calculus in §3. "Retuning goes stale on the next rebake" stops being an
argument once retuning is one command — so **re-derive in the ship gate** and it can never go
stale silently again.

What the fit still cannot do is the reason §4 survives: it fixes crown height, not shape.
Lena's cranium needs **1.613 in X but 1.311 in Z** — a 23 % anisotropy that visibly stretches
an authored cap sideways, and moves ear cutouts along a diagonal rather than onto her actual
ears. That is Ozan's logged residual, and no 3-constant fit reaches it.

**Verification status:** rest-pose arithmetic on the crown only. X/Z placement — the ear
cutout, the forehead line — is untested by this metric, and nothing here has been looked at in
`head_test_bed`.

---

## 3. Why retuning the constants is not the whole fix

Look at the last column of the table in §2: **the Head pivot lands at a different anatomical
place on every body.** On the stock rig it sits at the jaw line, 1–2 cm above the chin. On
Lena it sits 12.8 cm above her chin — mid-face. On Mako, 7.3 cm.

A diagonal scale about that pivot therefore scales about a different landmark per body. It
can be made to fit the crown, or the ear cutouts, or the forehead line — not all three. That
is exactly the residual Ozan logged in the canonical fit record:

> "Buzzed-style ear cutout still slightly off vs her ear position (ear sits further back+lower
> than stock). Translation gets close, not perfect — **a true fix is a Blender-authored hair
> fit pass**."

He named the fix. It is a Blender geometry pass — which is this repo's lane, not the game's.

And the tuning loop has a structural flaw: the constants are C# literals validated by eye
against one body build. Every rebake invalidates them silently. It has already happened once
(Lena, 2026-08-11) and shipped once un-noticed (Mako, 2026-08-12). Lena's v02/v03 rebake will
do it a third time. Retuning now buys a few weeks and re-enters the same loop.

---

## 4. The fix: bake a per-body hair set in our lane

Because hair is 100 % rigid to one bone, refitting it is a **pure geometry problem with no
rigging component**. Deform the verts once, offline, and the runtime needs no constants at
all.

**Proposed stage — `characters/hair/hair_refit.py`**

Inputs: a shipped body GLB, its gender's stock authoring body, that gender's style files.

1. Extract the scalp surface of both heads (Head-weighted, above the brow line).
2. Build a smooth displacement field *stock scalp → ship scalp*, anchored on a handful of
   landmarks — skull top, ear centres, temples, brow centre, nape — then relaxed. A few
   hundred correspondences under a thin-plate/RBF fit is ample. **Full NRICP is unnecessary**:
   hair sits *outside* the surface, so millimetre face accuracy is irrelevant. (The NRICP
   head-standardization lane proved the harder version of this registration; it was never
   wired into `tools/`, and we do not need it here.)
3. Per hair vert: closest point on the stock scalp → (surface point, signed normal distance).
   Reconstruct as *warped surface point + the same normal distance along the ship normal*, so
   a cap authored 4 mm off the stock scalp stays 4 mm off ours. Verts outside the scalp
   region — ponytails, dreads, beard fringes — fall off to the rigid part of the field and
   keep their authored shape while riding the new skull.
4. Recompute normals. **Topology, UVs, materials and the single Head weight are untouched** —
   that is what makes this safe to ship.
5. Export `Hair_<style>.<bodyid>.glb` as a per-body set.

**QC gates** (the lane already works this way — gate it or it ships wrong again):

- **penetration** — no cap-region vert inside the ship scalp.
- **clearance** — cap-region verts within the stock clearance distribution (roughly 1–8 mm).
- **ear cutout** — for Buzzed/Bob, cutout rim to ear landmark within tolerance. This is the
  residual Ozan logged, and it becomes a measurable gate rather than an eyeball call.
- **crown** — the §2 prediction, run per style per body, must read `ok`.
- silhouette renders per style per body, into `preview/` like every other ship artifact.

**Game-side change is small.** `GetHairPath(hairId, gender)` → `GetHairPath(hairId, bodyId)`
with fallback to the stock path when no baked variant exists; `HeadScale` / `HairOffset` /
`HairPitchDeg` go to identity for bodies that have a baked set. Slots, catalogue, colour and
the builder are untouched. Nothing gets deleted until a baked style is accepted.

**Cost:** 6 baked styles for Lena, 10 for Mako — 16 GLBs of 466–3,501 verts, a few hundred KB
each. Noise next to an 8.5 MB body.

---

## 5. Hair colour — the "real fix" is 16 PNGs

`ApplyHairColor` sets `AlbedoColor`, which Godot multiplies against the card texture. The card
is ~0.55 neutral grey, so dark swatches land near-black. `DefaultHairSwatches[7]` stores
`target / 0.55` to work around it — the wiki correctly calls that "a hack on one swatch, not a
system", and lists authored per-colour textures as the real fix.

That fix is far cheaper than it sounds. **The entire hair set — all 13 styles, the stock
eyebrow meshes and all three facial-hair pieces — uses exactly two base textures**,
`T_Hair_1_BaseColor.png` and `T_Hair_2_BaseColor.png`.

So "authored per-colour hair textures" is **2 textures × 8 swatches = 16 PNGs**, generated
once with the luminance-preserving retint this lane already runs on skin
(`SkinToneTransform` / the `21_tone.py` texture-space tone engine). Then `ApplyHairColor`
swaps a texture instead of multiplying a tint, dark colours land as themselves, and the
`/0.55` swatch hack goes away.

Cheap, ours to produce, Ozan's to accept.

---

## 6. Eyebrows and eye colour, in brief

Both are downstream of the same root cause — our bodies ship as **one mesh, one primitive,
one material** (`MI_Body_Lena`, `MI_Body_Mako`), so no facial feature is individually
addressable.

- **Eyebrows.** Lena's ship path deletes painted brows from the albedo and attaches a
  generated skinned surface built from a *locked UV-space mask*
  (`tools/generate_lena_brow_surface.py`), coloured by the hair swatch. The mask, the browless
  albedo and the surface JSON are **atlas-bound** — Lena's v02 re-atlas invalidates all three
  at once, and they must be regenerated in the same stage that finalizes the atlas.
  There is also a live-but-superseded mask-tint path (`shaders/character_brow.gdshader`) that
  recolors a painted brow in place — 72 % replace, not a multiply. That one generalizes to a
  scanned face; the cover path does not, because you cannot erase raised scan geometry with a
  texture. Mako has `AttachFacialFeatures = false` and therefore no brow colour at all.
- **Eye colour.** `ApplyEyeColorByIndex` swaps the whole albedo of the `OutfitSlot.Eyes` mesh
  between six baked iris PNGs. It needs a **separate mesh or primitive** — there is no other
  mechanism. Lena only has one because stock Quaternius eye spheres are laid over her painted
  face. Mako has none, so the builder's eye swatches are dead for the male default.
  The pipeline answer is one line of the export stage: emit the iris shells (real geometry on
  both Mako's scan and Lena's v02 transplanted head) as their own primitive instead of welding
  them into the body. One extra draw call; retires `quat_eyes.glb`.

---

## 7. Suggested order

| # | Change | Where | Note |
|---|---|---|---|
| 1 | Land Mako's derived fit `(1.363, 1.000, 1.322)` / `(0, +0.0388, +0.0242)` | game-side C# | His own comment calls the current values "STARTING VALUES for a head-bed pass" — unlocked. He is the **shipped male default with hair sunk into his skull**. Verify in `head_test_bed` before baking |
| 2 | Lena's derived fit `(1.613, 1.148, 1.311)` / `(0, −0.0411, −0.0094)` | **Ozan's call** | Do NOT edit unilaterally: `HeadTestBed` carries an explicit hair-fit LOCK, a warning label hardcoding `1.545,1.431,1.426`, and a documented "1.37 incident". Take the §2b table to him |
| 3 | `--fit` re-derivation added to the body ship gate | this repo | Makes staleness structurally impossible; both bodies shipped wrong because nothing re-checked |
| 4 | `hair_refit.py` + QC gates, baked per body | this repo | The part a 3-constant fit cannot reach: ear cutouts, the 23 % X/Z anisotropy, forehead line |
| 5 | 16 per-colour hair PNGs | this repo | Kills the `/0.55` swatch hack |
| 6 | Iris primitive split at export | this repo | Gives Mako eye colour |
| 7 | Regenerate brow mask/browless/surface at atlas-final | Lena v02 lane | Or v02 ships with brows mismatched to her atlas |

Note the duplicated literal: `HeadAccessoryBindMath.ArikiHeadScale` carries its own copy of
Lena's numbers marked "keep in sync with CharacterBuildData". Any change to hers must touch
both, and `MaleCandidateBed` (`ArikiHeadScale * 1.08f`) and `BodyProportionTestBed` read it too.