animation/.agents/wiki/architecture/clothing-lane.md

# Clothing lane — reference image → garment worn in-game

The animation lane carries **motion** to ariki-game; this is the parallel lane
that carries **clothing**. Both converge on the same 65-bone Quaternius
skeleton. Built 2026-07-30 in two halves, by two sessions, that meet at a
garment mesh.

```
reference photo ──▶ [ UPSTREAM: Marvelous Designer ] ──▶ garment mesh (FBX/OBJ)
   or concept        author · drape on game body           1–4k verts, fitted
                     texture · QC placement                 + .zprj source
                                                                 │
                                                                 ▼
                     [ DOWNSTREAM: clothing/garment_pipeline.py ]
                      census · prepare · fit · reduce · (bake) · skin · export
                                                                 │
                                                                 ▼
                              ariki-game/assets/quaternius/outfits/<set>/
                              per-slot GLB on the shared skeleton
                                      + OutfitCatalog.Register entry
```

## The two halves

| | Upstream — authoring | Downstream — game-ification |
|---|---|---|
| Question it answers | "What is this garment, and what shape is it on *our* body?" | "How does the game wear it?" |
| Tool | Marvelous Designer 2026 + `TinqsMDBridge` socket plugin | Headless Blender 5.1, deterministic, staged |
| Lives in | `tools/md_bridge*`, `tools/tailor/` | `clothing/` |
| Playbook | `.claude/skills/marvelous-designer/SKILL.md` | `clothing/README.md` |
| Driven by | Agent over a socket; **needs a human click** per session, freezes MD's UI | Agent, fully headless, no human in the loop |
| Output | Draped garment mesh + `.zprj` + QC screenshot | Per-slot skinned GLB + catalog entry |

Read each half's own doc for operating detail — this page only owns **how they
fit together**. (Repo SoT rule: no second source of truth.)

## The handoff contract

Upstream hands downstream a **garment mesh in `tools/tailor/`**
(`lena_<garment>_v<N>_garment.fbx|.obj`) plus the `.zprj` it came from.
Downstream consumes it via a per-garment config
(`clothing/configs/<garment>.json`) naming the source file, island→part mapping,
slots, and budgets — new garment = new config, not new code.

Two properties of **MD-authored** meshes change how the downstream config should
be written, and the pilot config does not yet reflect them:

- **Already at game budget.** MD-authored garments export at **1.2k–3.7k verts**.
  The pilot config was written against a *downloaded* MD dress at **2.49 M verts
  / 110 MB**, where `reduce` is the hard stage. For our own garments, set a
  generous tri budget and only decimate if the test bed complains.
- **Already fitted.** They were draped on `Ariki_Female_QuatSkin.glb` itself, so
  alignment/scale work is largely moot; the `fit` stage still earns its keep for
  the +4 mm clearance shell that prevents poke-through.

The `clothing/README.md` independently reached the same conclusion from research:
prefer re-exporting from MD over fighting reduction downstream. Our upstream
makes that the default rather than the exception.

## Why this shape

- **Why MD for authoring:** it is the only tool in the stack that turns flat
  panels into cloth physically draped on *our* body. Garments come out
  pre-fitted, low-poly, and reproducible from a `.zprj`.
- **Why not Character Creator:** the CC5/Reallusion clothing lane was
  investigated and **rejected** — CC5 provably refuses clothing tools on AccuRig
  "Humanoid" characters (verified via its Python API *and* GUI). See
  `clothing/README.md`.
- **Why not MD's own EveryWear** (its auto retopo/rig/GLB toolkit, which would in
  principle replace the whole downstream half): it is **GUI-only, absent from the
  scripting API**, so it cannot be driven agentically. Revisit only if
  Reallusion/CLO exposes it.
- **Why the halves are separate processes:** MD can't run headless and freezes
  during a bridge session; Blender can and doesn't. Splitting keeps everything
  after the garment mesh fully automatable.

## Body and rig facts

- Target body: `ariki-game/assets/quaternius/derived-bodies/Ariki_Female_QuatSkin.glb`
  (32.7k verts, 65 bones, 1.777 m).
- MD needs it as **FBX**: `tools/tailor/avatar/Lena_QuatSkin_Avatar.fbx`
  (leaf bones stripped, stray meshes dropped) — regenerate with the converter
  described in the marvelous-designer skill.
- Measurements: `tools/tailor/lena_measurements.json` — she is stylized
  (108-67-109 cm, 72 cm thighs, 178 cm), so standard size charts don't fit.
- The skeleton is the same hub the animation lane targets — see `../ARCHITECTURE.md`.

## Status (2026-07-31)

**Proven upstream:** image → decomposition → drafted panels → sewn → draped →
textured → QC'd → exported, end to end. Shipped: tee, A-line skirt, and a kapa
haka set (tāniko pari + piupiu) matched to a reference photo, all with repo
screenshots in `tools/tailor/screenshots/`.

**Proven downstream:** the dress pilot ran through to an in-game render
(`clothing/dress_ingame_2026-07-30.png`).

**The seam is CROSSED (2026-07-31).** The kapa haka set — MD-authored on our own
body — went through `garment_pipeline.py` (`configs/pari.json`,
`configs/piupiu.json`) to `Female_Kapahaka_{Body,Legs}.gltf`, and both render on
Lena in the game's clothing test bed with the tāniko pattern and piupiu stripes
intact. None of the feared surprises materialised: MD's material naming, island
splitting, and UV/texture carry-through all worked first time. The predictions on
MD-authored meshes above held — both garments arrived at game budget already
(4k/8k tri ceilings never bit) and needed no alignment work beyond a z-nudge.

**What the in-game pass exposed instead** was pose-dependent, not authoring:
the bodice neckline opens over the sternum and the piupiu lets a thigh through
once the skeleton leaves the rest pose. Both are invisible to the pipeline's own
QA, which only ever renders the **rest pose** — the pose the garment was fitted
in, i.e. the one pose that cannot fail. Judging cloth in motion is the test bed's
job, and until 2026-07-31 the bed could not do it either (its Idle/Walk/Dance
buttons were overridden by the AnimationTree; fixed in `ClothingTestBed.PlayClip`).

**Known gaps:** trousers/shorts don't drape (see the skill's failure catalogue);
placement QC's pixel classifier is crude; no skirt bones, so deep leg swings
compress hems; garments are flat-coloured until textures are authored.