animation/dev/glm-task-kapahaka-outfit.md

TASK: put the approved kapa haka outfit through the clothing pipeline into the game

You are working in C:/Users/Jeremy/tinqs/animation (Git Bash, Windows). Blender is:

BLENDER="/c/Program Files/Blender Foundation/Blender 5.1/blender.exe"

Goal

Two Marvelous-Designer-authored garments have been approved. Turn them into game-ready outfit parts on the shared 65-bone Quaternius skeleton, using the existing staged Blender pipeline clothing/garment_pipeline.py.

Garment	Source file (already exported, do not re-author)	Outfit slot
Tāniko bodice ("pari")	tools/tailor/lena_pari_v3_garment.fbx	Body
Flax skirt ("piupiu")	tools/tailor/lena_piupiu_v2_garment.fbx	Legs

Target body / rig (the fit target and weight donor): C:/Users/Jeremy/tinqs/ariki-game/assets/quaternius/derived-bodies/Ariki_Female_QuatSkin.glb

Export destination: C:/Users/Jeremy/tinqs/ariki-game/assets/quaternius/outfits/kapahaka/ Set id Kapahaka, gender Female, so the pipeline should produce Female_Kapahaka_Body.gltf and Female_Kapahaka_Legs.gltf (+ .bin), matching the naming pattern of the earlier pilot in ../outfits/mddress/.

Read these first (they are the source of truth — do not guess)

1. clothing/README.md — the pipeline's stages, design rationale, usage, and the config schema explanation. Read it fully before writing any config.
2. clothing/configs/dress.json — a working config to model yours on.
3. .claude/skills/marvelous-designer/SKILL.md — how these garments were made (section "Handing off downstream" is the relevant part).

What is DIFFERENT about these garments (important — the pilot config misleads)

The pilot config (dress.json) was written for a downloaded MD dress of 2.49 million verts with 12 materials, where aggressive reduction was the hard problem. These garments are nothing like that:

• They are tiny: pari ≈ 1.9k verts / 3.6k faces; piupiu ≈ 3.7k verts / 7.1k faces. They are ALREADY at game budget. Do not fight to decimate them. Set generous tri budgets; only reduce if something is genuinely over budget.
• They were draped directly on this exact body in Marvelous Designer, so they are ALREADY fitted and correctly scaled/positioned. Expect alignment to be near-identity (scale 1.0, no nudge) — verify rather than assuming the pilot's scale_xy: 1.18 / scale_z: 0.95 values, which were corrections for a foreign garment.
• The fit stage is still worth running for its +4mm clearance shell (poke-through defence), but it should barely move anything.
• Each garment is one simple part — no junk materials, no topstitch soup, no multi-island jacket. Expect a small number of islands.

Already-established facts (verified — do not spend steps re-deriving)

• The body/rig imports clean: 65 bones, Quaternius names, body z-range -0.011 .. 1.766 m, pelvis z = 0.932, neck_01 z = 1.413.
• The MD garment FBX exports are 10× oversized and offset in Z. Measured pari z-range is 10.546 .. 14.613 against a body of 0 .. 1.77. This is the mirror of how they were authored (the avatar was imported into Marvelous Designer at scale=10 to work in MD's millimetre space, so garments come back in that same space). Expect to need roughly 0.1 uniform scale, then a Z placement correction — derive the exact numbers from the measured bounds rather than trusting this estimate. Sanity check after aligning: the pari should span roughly z 1.05–1.40 m (waist to shoulder) and the piupiu roughly z 0.45–1.05 m (below knee to waist).

CRITICAL: placement. A previous run exported a garment 10 cm too low.

You cannot see the QA renders. Confirming a PNG exists proves nothing about whether the garment is in the right place. Placement must be verified numerically, and it is the single most likely thing to go wrong.

Why the pipeline mis-places these garments

stage_prepare auto-aligns by moving the garment so its top meets the align.top_bone head: dz = (b_top - garment_top_after_scale) + z_nudge. That is correct for a foreign garment of unknown position. It is wrong for these garments, which were draped on this exact body and are therefore already in the correct world position — only 10× too large. Any bone-align drags them off their authored placement. On the last run this applied dz = -0.0970 and pushed the pari's straps below the shoulder and its hem down to the hip.

The rule

A garment's correct final world position is exactly its raw census z-range divided by 10. Nothing else. Use z_nudge purely to cancel the pipeline's auto-align so the net placement lands there.

The procedure (repeat per garment)

1. From the census log, note the raw island z-range [z0, z1]. Target world range is [z0/10, z1/10]. (pari measured [10.546, 14.613] → target [1.055, 1.461].)

2. Run prepare, then measure what you actually got — load the checkpoint and print the garment's world-space Z bounds, e.g.

   "$BLENDER" --background clothing/work/<name>/10_prepare.blend --python-expr "import bpy; o=[x for x in bpy.data.objects if x.name.startswith('GARM_')][0]; zs=[(o.matrix_world@v.co).z for v in o.data.vertices]; print('ZRANGE', min(zs), max(zs))"
   

3. If the measured top differs from the target top by more than 0.02 m, adjust: z_nudge += (target_top - measured_top), re-run prepare, measure again. Two iterations should converge.

4. Only proceed to fit once the measured range is within 2 cm of target at both ends. State the final measured range in your DONE report.

Cross-check against the body (a gross error should be obvious): pari ≈ waist to just above shoulder; piupiu ≈ below-knee to waist. Body landmarks: hem/ankle 0.11, knee 0.52, hip 0.95, waist 1.09, bust 1.26, shoulder 1.40, neck 1.41.

The pari currently in the export folder is WRONG and must be redone — delete Female_Kapahaka_Body.* and rebuild it with correct placement before moving on.

Method

Work one garment at a time; get the pari (Body) fully through first, then the piupiu (Legs). Suggested sequence per garment:

1. census stage — see what islands/materials actually exist. Read the printed stats and clothing/work/<name>/census.json. Let the data drive the config.
2. Write/adjust clothing/configs/<name>.json accordingly.
3. Run prepare → fit → reduce → skin → export. Skip bake (it is optional, Cycles-slow, and these have no high-poly detail worth baking).
4. After each stage, verify numerically (you cannot see the QA renders — their existence proves nothing). Print vert/tri counts and world-space bounds from the checkpoint .blend and check them against expectations. If a stage errors, read the traceback and adapt the config.

The pipeline is data-driven: prefer fixing the config over editing garment_pipeline.py. If you find a genuine bug or a missing capability in the pipeline, you may make a small, surgical, well-commented edit — but say so clearly in your DONE summary.

The skirt (piupiu, Legs slot) is the harder one: read the README's notes on skirt handling (weights: dress pelvis-gradient, cone proxy, why skirts are not decimated) and apply what fits. It is a straight A-line skirt, not pleated.

Success criteria (all must hold)

1. Female_Kapahaka_Body.gltf and Female_Kapahaka_Legs.gltf exist in the export dir above (with their .bin companions).
2. Each exported file contains a mesh skinned to a 65-bone armature with Quaternius bone names (the pipeline prints verification info — capture it).
3. Vert/tri counts are sane (roughly the input magnitudes, not zero, not millions).
4. The QA renders show a garment that still looks like a garment (not shredded, not collapsed, not inside-out).

Verify claims with commands; do not assert success you have not checked.

Rules

• Do not run git commit/push, do not install packages, do not touch .env.
• Do not modify anything under tools/tailor/ — those are approved source assets. Read them only.
• Do not re-run Marvelous Designer; it is not scriptable from here and its UI is not available to you.
• Work in small verifiable steps. One command per turn.
• Blender runs are slow (a stage can take minutes). That is normal — run them with a single command and wait for the output.
• If you get truly blocked, emit DONE: with a precise description of the blocker, what you tried, and what you recommend. A clear failure report is far more useful than silent thrashing.

Report

When finished, emit DONE: with:

• which files were produced and where,
• the final config(s) you settled on and any notable parameter choices,
• verification output proving the bone count / vert counts,
• anything that looks wrong or needs a human eye,
• any edit you made to garment_pipeline.py.