animation/.claude/skills/marvelous-designer/SKILL.md

name, description

name

description

marvelous-designer

Authoring garments in Marvelous Designer agentically — driving MD's Python API over the TinqsMDBridge socket plugin, drafting patterns from a reference image and Lena's measurements, draping/QC-ing them on the game body, and exporting meshes for the clothing pipeline. Use for any "make/adjust a garment", "match this clothing photo", or "drive Marvelous Designer" task, and read before touching tools/md_bridge* or tools/tailor/.

Marvelous Designer — agentic garment authoring

The upstream half of the clothing lane: reference image (or a description) → sewn, draped, textured garment mesh fitted to the game body. The downstream half (garment mesh → game-ready skinned GLB) is clothing/ — see .agents/wiki/architecture/clothing-lane.md for how they meet.

Everything here was learned by doing it on 2026-07-30 (tee, skirt, kapa haka pari + piupiu). The API facts are verified against MD 2026 Personal, not docs — Reallusion/CLO's published API docs are thin and several signatures in them are wrong.

The 60-second model

• MD is driven through tools/md_bridge.py → a socket plugin running inside MD (tools/md_bridge/TinqsMDBridge.py). Full protocol: docs/md-bridge.md.
• A garment = flat 2D panels (CreatePatternWithPoints) + seams (AddSeamlinePairGroup) + arrangement points on the avatar (SetArrangement), then simulate (utility_api.Simulate(frames)) to drape cloth onto the body.
• You see results by rendering the viewport to PNG (ExportSnapshot3D) and reading the image back. This vision loop is the whole method — draft, drape, look, measure, adjust, repeat.
• Which call for which job, and why: references/tooling.md. Read it before any QC or diagnostic work — it carries the verified signatures, the render/measure toolkit, the seam-pairing decision table, and the harness patterns.
• Garment identity for traditional wear is mostly textiles, not tailoring. Kapa haka / Mexica / Pacific garments are rectangles + blocks; the design lives in generated texture maps. Model the shape simply, spend effort on the pattern.

Session protocol (read first — MD's UI freezes)

MD's embedded Python does not run background threads, so the bridge owns the main thread while it serves. Consequences:

1. A human must click Plugin → TinqsMDBridge to start a session. You cannot start one yourself. Ask, then wait.
2. MD's UI is frozen for the whole session ("Not Responding" is normal).
3. End with python tools/md_bridge.py --stop — works from the terminal even though the UI is dead. Idle timeout is 4 h (was 300 s; raised so one click lasts a work session).
4. Pause the session whenever Jeremy wants to look at the model. He inspects in MD's viewport; he can't while you hold the thread. Default to stopping when you hand back a result, unless he said to stay in.

python tools/md_bridge.py --ping                       # verify + see mode/api modules
python tools/md_bridge.py --exec "result = pattern_api.GetPatternCount()"
python tools/md_bridge.py --file tools/tailor/md_pari.py --timeout 500
python tools/md_bridge.py --stop                       # give the UI back

Long Simulate() calls need a raised client --timeout (~1 min per 300 frames). The exec namespace persists within a session, not across; MD api modules (pattern_api, import_api, export_api, fabric_api, utility_api, ApiTypes) plus a BRIDGE info dict are pre-seeded.

Introspect, don't trust docs. Full surface dump lives at tools/md_bridge/api_surface.json (688 functions) and harvested docstrings at tools/md_bridge/api_docs.json. Overloaded pybind11 functions break inspect.signature() — read __doc__ instead.

API facts that cost hours to find

Fact	Consequence
2D pattern y+ maps to UP in 3D	Panels drafted y-down drape upside-down over the head and tangle. Symptom looks like a seam bug; it isn't. Hem at y=0, neckline at high y.
Units are mm; gravity −9800	A "500" square is 50 cm.
Blender-exported FBX avatars import 10× small	Import with op.scale = 10.0.
ImportAvatar() is .avt only — returns False on FBX	Use import_api.ImportFBX(path, op) for the game body.
op.bAddArrangementPoints = True	Auto-generates ~98 named arrangement points on a custom avatar. Without it you have nowhere to hang cloth.
SetArrangement() only assigns; utility_api.ResetClothArrangement() applies it	Skipping the apply = nothing moves. (ReDrape3DArrangement only materializes not-yet-draped cloth.)
Arrangement indices regenerate per avatar import	Always look up by name from GetArrangementList(); never hardcode an index. Offsets aren't stable either — verify with a 0-frame snapshot.
Avatar getters live in export_api (GetAvatarCount, GetAvatarNameList)	Not utility_api, where you'd look.
utility_api.NewProject() deletes the avatar	Re-import after.
SetBaseTextureMapImageGivenFilePath(path, fabricIdx) — path is arg0	Reversed args throw a TypeError that reads like a missing overload.
PNG DPI sets a texture's physical size in MD	1024 px at 54.2 dpi = 480 mm of cloth. Control tiling by setting dpi in PIL, not by scaling the image.
fabric_api.AddFabric() needs a .zfab file path	A name string silently fails. Stock presets: C:\Users\Public\Documents\MarvelousDesigner\New Assets\Fabric\.
Fabric index 0 is the shared default	Coloring it dyes every garment in the scene. Always AddFabric a new one.
AssignFabricToPattern() returns False for every arg order tried	Use pattern_api.SetPatternPieceFabricIndex(pattern, fabric).
SetViewPoint() does nothing; SetCamViewPoint(2) = front view	Call before every QC snapshot so shots are comparable.
SetCamViewPoint has NO REAR VIEW (0 bottom, 1/3 front ¾, 2 front, 4/6/7 sides, 5 top)	ExportSnapshot3D cannot show the back of a garment at all. Use export_api.ExportTurntableImages(4) — index 2 is the back. It ignores its path arg and writes into MD's own output folder, so the return value is the only way to find the files. This blind spot shipped four separate defects.
SetArrangementPosition takes 4 ints	A float raises TypeError. The correct x depends on the arrangement family: Body_*_Center_1 needs the two panels to match (a 50/0 split folds one shoulder); Leg_Skirt_* needs them to differ (50/50 drops the skirt on the floor). Sweep with a control before changing it. See references/tooling.md §5.
ExportOBJ writes mm; the FBX→census path reads decimetres	The two exporters disagree. Metres = OBJ × 0.001, FBX census × 0.1 (that's what align.scale_z is for).
GetClothPositions() is an out-param that stays empty from Python	No mesh introspection. Export a throwaway OBJ and parse its v lines — exact, and the only option for gappy/strand garments, where qc_placement.py's pixel classifier fails outright.
No SaveProjectFile; no glTF export; no EveryWear in the API	Save = export_api.ExportZPrj. Exits: ExportFBX / ExportOBJ / ExportZPac. EveryWear is GUI-only.

Construction doctrine

Take the reference apart before drafting anything. The tailor's method — image → slot split → anchoring → placement targets → ease table → piece plan — is references/deconstruction.md. Its output is a worksheet of numbers, and every downstream value (panel dims, expect.bands, sim recipe) traces to a row of it. Skipping this step is how garments shipped 4–14 cm off target.

Draft from measurements, not guesses. Lena's card: tools/tailor/lena_measurements.json (regenerate for any body with tools/tailor/measure_body.py, a headless-Blender mesh slicer). She is stylized — 108-67-109 cm with 72 cm thighs on 178 cm — so real-world size charts produce clothes that don't fit.

Build from blocks, not freehand. The blocks are parametric now — tools/tailor/blocks.py turns worksheet numbers into a runnable config skeleton (python tools/tailor/blocks.py fitted_top --name x --band-top-z 1.31 --hem-z 1.05 --ease 17), with the seam parity, arrangement-x rules, bodice taper, and tension waists baked in (--selftest proves it regenerates the shipped garments). Prefer generate-then-edit over hand-typing point lists. The original per-garment recipes remain as provenance:

Block	Generator	Legacy recipe	Notes
Fitted top / tank / bodice	blocks.fitted_top	md_tee_v1.py, md_pari.py	Front+back panels, shoulder+side seams, neck gap and armholes cut into the outline. Straps hold height reliably. Legacy recipes predate the §3.3 seam-parity and §5 arrangement-x discoveries — the generator has the fixes.
A-line skirt	blocks.aline_skirt	md_skirt_v1.py, md_piupiu.py	2 panels, side seams only. The most forgiving garment; start here.
Strand/fringe skirt	blocks.strand_skirt	—	Comb outline (teeth, never partial seams), symmetric half-gaps, elastic mid-settle.
Trousers/shorts	unsolved — see failure catalogue

Seams: whole-edge only. Pair the same line index on mirrored front/back panels with (False, False) — mirrored is load-bearing. Most recipes here draft both panels from the identical point list offset by dx, which is NOT mirrored, and those need (True, True) on the side seams or the panel twists and turns partly inside out. Full decision table in references/tooling.md §3.3; cross-pairing every seam makes the garment slide off the shoulders. Build neck gaps and armholes as extra points in the outline, not as partial seams. Fingerprint line indices by length via GetLineLength(pattern, line).

Straps beat tubes. A strapless tube slides down to the narrowest catch (underbust). If a reference garment is strapless, add straps anyway when the target body has baked-in underwear to cover — it fixes placement and coverage at once. It's also what made the pari read correctly.

Bottoms stay up by tension, not elastic. Cut the waist smaller than the hips and let fabric stretch hold it.

Drape recipe (the sequence that works)

pattern_api.SetPatternStrengthen(p, True)      # stiffen so cloth wraps, not crumples
utility_api.ResetClothArrangement()            # apply arrangement
utility_api.Simulate(250)                      # main settle, still stiff
# skirts: enable waist elastic HERE, mid-settle, then Simulate(80) more
pattern_api.SetPatternStrengthen(p, False)
utility_api.Simulate(50)                       # relax into natural folds

• Strengthen through the whole settle, relax only at the end. Soft fabric from frame 0 rolls into a bunch at the waist. This is the anti-bunching fix — but only for garments whose sides are fully sewn. On a bodice sewn only over its lower half with 90 mm straps, strengthening flattens the back and rotates the whole garment, giving an uneven hem and exposed skin. Where it can't be used, remove the surplus cloth instead.
• Elastic mid-settle, never from the start. Elastic applied before the cloth has wrapped cinches the garment off one hip. Drape first, cinch second — that is what finally locked the piupiu waistband at the waist.
• Skirts arrange on Leg_Skirt_Front / Leg_Skirt_Back, not the body-waist points, with SetArrangementPosition(p, x, 92, 50).
• One garment per scene. A second garment — even frozen — grabs and inverts the new one. Game exports are per-garment anyway. Assemble outfits only at the end, by reloading finished pieces (below).
• Outfit assembly: ImportZprj(base) + ImportZpac(other, op.bAdd=True). Textures survive only if you don't re-fabric or re-simulate after merging — a merge renumbers patterns and fabrics unpredictably. Assemble, shoot, done.

QC — the part that was missing and matters most

Early drapes were accepted because they "looked like clothing". They were bunched around the middle. Fit is judged by numbers against the reference:

1. Extract placement targets from the reference photo — where each edge sits relative to body landmarks, as a table with tolerances. Example (kapa haka): pari top 1.31 m ±3 cm (above bust), pari hem / piupiu waist 1.05 m ±3 cm, piupiu hem 0.45 m ±4 cm (below knee).
2. Measure every drape: python tools/tailor/qc_placement.py <snapshot.png> classifies background/skin/garment pixels, calibrates px→m off Lena's known 1.777 m height, and reports each garment band's top/bottom in metres against the nearest landmark. Iterate until inside tolerance.
3. Snapshot with SetCamViewPoint(2) so every shot is comparable.
4. Save a screenshot into the repo for every shipped garment — tools/tailor/screenshots/<garment>.png. Required, not optional: it's how Jeremy reviews without opening MD.

The diagnostic that unsticks everything: snapshot after ResetClothArrangement() with zero simulation frames. That shows where the panels actually start, before physics muddies it. Seven "seam bug" iterations were really an upside-down garment; one pre-sim snapshot would have caught it immediately. Reach for it the moment a drape misbehaves.

qc_placement.py is honest but crude: it counts the body's baked-in underwear and floor shadow as garment. Tighten it with per-garment colour masks when precision matters.

Textures

Generate procedurally with PIL and set physical scale via DPI — tools/tailor/textures/ holds taniko.png (concentric woven diamonds) and piupiu.png (flax strands with geometric banding), both derived from a reference photo. Pattern-generation scripts are worth keeping when a motif will recur.

Workflow: AddFabric(<.zfab>) → SetBaseTextureMapImageGivenFilePath(png, fab) → SetPatternPieceFabricIndex(pattern, fab). Set the PNG's dpi so the design spans the garment exactly once (dpi = px / (mm/25.4)).

Handing off downstream

Export three ways per garment, into tools/tailor/:

export_api.ExportZPrj(".../lena_<garment>_v<N>.zprj")           # editable source of truth
op = ApiTypes.ImportExportOption(); op.bExportGarment = True; op.bExportAvatar = False
export_api.ExportFBX(".../lena_<garment>_v<N>_garment.fbx", op) # for clothing/
export_api.ExportOBJ(".../lena_<garment>_v<N>_garment.obj", op)
export_api.ExportZPac(".../lena_<garment>_v<N>.zpac")           # for outfit assembly

Then the garment goes through clothing/garment_pipeline.py (fit → reduce → skin → export) to become a game outfit part. Two advantages MD-authored garments have over downloaded ones, worth exploiting in the config:

• They're already game budget. These export at 1.2k–3.7k verts; the downloaded MD dress the clothing pipeline was piloted on is 2.49 M verts / 110 MB. The brutal reduce stage is mostly unnecessary — start with a high tri budget and only decimate if the test bed complains.
• They're already fitted, having been draped on the actual game body, so align/fit needs little more than the clearance shell.

Keep the .zprj — regenerating a variant beats re-authoring, and the clothing README explicitly prefers re-exporting from MD over fighting reduction.

Failure catalogue (don't rediscover these)

• Shorts / trousers are unsolved. Two-panel crotch-notch construction twists every time — fabric can't thread between Lena's touching thighs, and all seam parities were tried. Next approach: 4 panels arranged on the per-leg points (Leg_Front_L/R, Leg_Back_L/R) so cloth starts wrapped around each thigh.
• Upside-down panels (y-down drafting) — see the y+ = UP rule.
• Elastic-first drapes slide off a hip; soft-from-frame-0 drapes bunch.
• Co-draping two garments inverts one.
• A textured render hides folds and winding. Judge shape with the texture OFF: cloth is white on its front face, grey on its back, so a panel showing grey from outside is inside out and a white streak is a fold. A busy motif conceals both.
• A sweep without a control case teaches you something false. If the control (known-good settings) also fails, the harness is broken, not the geometry.
• A light garment does not slide into place. MD materialises cloth at the arrangement point and does not simulate donning, so for anything light the arrangement height is the placement.
• Retexturing after a scene merge silently repaints the wrong garment.
• Threaded/background socket servers inside MD never answer — the bridge must own the main thread. Don't "fix" the frozen UI by re-threading it; that was tried and the design is deliberate.
• MD 2026's AI Image Generator / EveryWear are GUI-only — not scriptable.

File map

Path	What
tools/md_bridge.py	Terminal client (--ping/--exec/--file/--stop)
tools/md_bridge/TinqsMDBridge.py	The plugin (register once via Plug-in Manager; referenced in place, so edits go live on next click)
tools/md_bridge/api_surface.json, api_docs.json	Introspected API truth
docs/md-bridge.md	Protocol, install, threading rationale
tools/tailor/measure_body.py, lena_measurements.json	Body measurement tool + Lena's card
tools/tailor/blocks.py	Parametric blocks: worksheet numbers → config skeleton (--selftest)
tools/tailor/draft_garment.py	Config md block → bridge script (the four recipes, templated)
tools/tailor/md_*.py	Per-garment recipes (each header carries its own lessons)
references/deconstruction.md	The tailor's method: taking a reference image apart into pieces
tools/tailor/qc_placement.py	Placement QC measurement
tools/tailor/textures/	Generated fabric maps
tools/tailor/screenshots/	Required per-garment review renders (front and back — see tooling.md §0)
references/tooling.md	Which API call for which job, verified signatures, decision tables
tools/tailor/avatar/Lena_QuatSkin_Avatar.fbx	Game body as an MD avatar (from the GLB, leaf bones stripped)
tools/tailor/lena_*_v*.{zprj,fbx,obj,zpac}	Shipped garments