docs+tools: working-file policy, lane pruner, and a human MD explainer
Two pieces of work.
1. Keep milestones, not steps. Staged NN_*.py lanes were saving a full
~80 MB .blend per attempt, so Lena's lane reached 3.0 GB of which 2.2 GB
was 30 .blend files -- five snapshots to land one crotch fix, five more
for the bra. The .py recipes are the real history; the blends are cache.
- .agents/rules/working-files.md: four-tier policy (KEEP / MASTER /
SCRATCH / UNKNOWN) + how to work a lane.
- tools/prune_lane.py: classifies a lane and prunes the scratch tier.
Dry-run by default. Reads a per-lane .lanekeep manifest, flags
binaries byte-identical to a registered original (canonical name
always survives a duplicate pair), and never auto-deletes a .blend
with no step script beside it -- those cannot be rebuilt.
- .gitignore: scratch patterns can never be committed.
Dry run on characters/female/lena_nude reports 2.3 GB reclaimable.
Not applied -- that lane had a live Blender session at the time.
2. .humans/marvelous-designer.html: how we author garments in Marvelous
Designer, written for people rather than agents -- the six-step process,
what has been made, the traps that cost hours, and what is still
unsolved. Matches the .humans/ HTML convention in ariki-game.
Also committing the docs the AGENTS.md knowledge map and the new page
reference, so they are not dangling: the clothing-lane architecture page,
the marvelous-designer skill, and the two screenshots the page embeds.
characters/ is deliberately untracked and stays that way -- it holds GBs of
blends and GLBs, and .gitattributes does not LFS-track .blend.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,117 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user