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.