animation/clothing/skirt_gait_spike/NOTES.md

# Baked-skirt-gait spike — design note

**Status: SPIKE, not production.** Ozan 2026-08-20: prove that an offline cloth
sim of a skirt against the run cycle can be baked onto the `skirt_*` strand ring
and shipped as a layered animation clip. Script: `bake_skirt_gait.py` (this dir).

## What it does

1. Loads `Regular_Female_SkirtRig24.glb` (24 strands × 5 segments) and the long
   tapa skirt `Female_Tapa_Skirt_Regular.gltf`, re-pointing the garment's skin at
   the body rig.
2. Loads `Jog_Fwd_Loop` from `UAL1.glb` — this is the game's actual `run` clip
   (`PlayerController.cs`: UAL1 `Jog_Fwd_Loop` → alias `run`). The pack's other
   119 actions and its mannequin are discarded in-memory. A CYCLES fmodifier
   loops it; scene fps is set to 30 *before* import so seconds map to frames.
3. Cloth-sims the garment against the animated body, reusing
   `build_pugu_tifi.py`'s idioms (pin group at the waistband, body as collider
   8 mm outer, tension/compression 8, shear 4, bending 0.06, 6 mm contact).
   One addition the drape-only pipeline didn't need: **the waistband pin group is
   pelvis-weighted and the Armature modifier sits above Cloth**, so the pinned
   edge *rides the animated hip* instead of being nailed to world space.
   20 settle frames + 3 looped cycles; the last cycle is captured.
4. Bakes cloth → bones (mapping below), blends the loop seam, writes a
   skirt-bones-only action, renders sim-vs-bake proof frames, and exports one GLB
   containing one animation with **only `skirt_*` rotation tracks**.

## The cloth→bone mapping

- **Rest-pose binning.** Each garment vertex is assigned once, from its rest
  position, to a (strand, boundary-knot) cell: strand by azimuth around the
  pelvis axis, knot by nearest of the strand's 6 boundary heights (5 segment
  heads + hem tail). Same conventions as `skirt_garment_weights.py` — azimuth
  and ring heights read off the rig, never bone-name order.
- **Per-frame targets.** For each simulated frame, a cell's world-space centroid
  becomes the target position of that strand's boundary knot (in armature
  space). ~12 verts/cell on this garment; empty cells fall back to "hang
  straight down from the parent joint".
- **Chain fit, rotation-only.** Per strand, per frame: the root head stays glued
  to the pelvis-carried rest position (the waistband is pinned there — the cloth
  top *is* pelvis motion). Each segment takes the minimal rotation from its
  parent-propagated rest orientation that aims head→tail at its target centroid;
  twist is inherited down the chain so strands don't spin. The pose-space basis
  quaternion comes out analytically
  (`basis = (parent_pose @ parent_rest⁻¹ @ rest)⁻¹ @ M_desired`) — no
  constraints, no `bake_action`, no per-bone depsgraph updates.
- **No bone scale, no bone translation.** Bone lengths are fixed; cloth
  compression shows up as segment curl, never stretch. This keeps the clip
  compatible with anything that assumes rigid strand segments (the spring rig's
  collision particles included).
- **Loop seam.** Quat sign continuity is enforced per bone, then the last 6
  frames of the cycle are slerp-blended toward frame 0. The game wraps last
  key → first (`LoopMode.Linear`), so the seam is smooth by construction.

## Runtime integration options (for the game side to pick)

1. **Override per gait (recommended starting point).** When the locomotion state
   machine enters run/walk, `SkirtSpringRig` stops simulating and the skeleton
   plays the baked `skirt_*` clip on the same bones, synced to (or just
   cross-faded with) the body clip. Cheapest possible runtime cost (zero sim),
   deterministic silhouette, and the clip loops with the gait. Cost: a crossfade
   pop unless blended; no reaction to collisions while overridden.
2. **Additive/under-layer.** Keep the spring sim running but feed the baked pose
   as its rest/target (or as a low-weight animated base under the springs).
   Keeps collision response, regains baked flair. More machinery: spring sim
   needs a "goal pose" input it doesn't currently have.
3. **Replace the sim during gaits only** (hybrid of 1): sim for idle/dance (low
   amplitude, collision matters), baked for run/walk/sprint (high amplitude,
   where the sim visibly struggles). This matches how the industry uses baked
   cloth and is option 1 with a state gate.

Not evaluated: retargeting one baked clip across bodies. The bake is
body-specific (ring radii are measured per body; the cloth is fitted per body) —
per-body bakes are the honest answer, same doctrine as the garment generator.

## What breaks / changes with the 16×4 male ring

Nothing structural — strand/segment counts are read off the rig at runtime, so
the same script bakes 16×4. Three real differences:

- **Fewer, longer segments** (4 vs 5, non-uniform fracs) → each segment spans
  more cloth column; the centroid fit smooths out more fold detail. Expect
  slightly stiffer-looking hem on the male ring.
- **Wider strand spacing** (16 vs 24 around the ring) → each strand owns a wider
  azimuth wedge; lateral fold corners between strands get more visible. The
  `AZ_SPREAD` raised-cosine weighting that fixed piecewise-linear hem folds in
  `skirt_garment_weights.py` is the analogous fix on the *weights* side; the
  bake itself doesn't care.
- The male long tapa sits on different bodies (Superhero's quads) — the cloth
  sim, not the bake, owns that problem.

## Verified / not verified

**Verified (run 5, `run5.log`, `renders/`):** the sim holds together at run
amplitude (20 settle + 3 cycles, waistband riding the pelvis, legs pushing the
cloth — `sim_f01`/`sim_f15` show two genuinely different phases, cloth flaring
and lifting over the advancing thigh), and the bake tracks the sim's gross
motion phase-for-phase (`baked_f01` vs `sim_f01` is the same silhouette; the
skirt visibly rides and flares through the cycle, `baked_f01..f28` × 3 views).
No gross leg poke-through in any rendered phase. Exported
`out/SkirtJogFwd.glb`: one animation named `SkirtJogFwd`, 120 channels,
**rotation-only, all `skirt_*` targets**, 0.933 s (one gait cycle), 225 KB.

**Bake fidelity:** the 24×5 rotation-only centroid fit smooths fine folds — the
baked skirt is lumpier than the raw sim and the hem reads slightly ragged at
peak lift (`baked_f14`). Crumple near the front waistband is the *sim's* own
behavior at the pinned edge, not a bake artifact (visible in `sim_f01` too).

**Not verified:** in-game playback (the game side has no loader for this yet —
that is integration, out of spike scope); gait transitions; the 16×4 male ring
(same code path, never executed); walk/sprint clips; other garments.

As-built lessons from the spike runs (full log: `run5.log`):

- **The shipped garment GLTF has per-face vertices** (flat-shaded; every quad is
  its own island). A cloth sim on it shreds into confetti — the script
  `remove_doubles`-welds the imported mesh before anything else touches it.
- **Pin per island, not per mesh.** The rope ring's back-rise sits ~5 cm above
  the tapa tube's top row; one pin line off the mesh top leaves the tube
  unpinned and the whole skirt falls to the floor. Pinning is computed per
  connected island (rope island fully pinned, tube top band pinned).
- **Pinned verts must be pelvis-only.** The garment's inherited pelvis/thigh
  blend would drag the pinned waistband with the stride; the script zeroes all
  other groups on pinned verts.
- **glTF export with `export_force_sampling=True` (the default) exports TRS for
  all 185 bones**, not just the animated ones — 555 tracks including the body.
  `export_force_sampling=False` + `ACTIVE_ACTIONS` yields exactly 120 tracks,
  all `skirt_*` rotations. The exporter also won't name the animation on this
  path; the script renames it in the GLB JSON post-export.
- **Blender 5.1 has no `Action.fcurves`** — slotted actions only
  (`slots.new` → `layers.new` → `strips.new(type="KEYFRAME")` →
  `channelbags.new(slot=...)` → `bag.fcurves.new(..., group_name=...)`), and the
  object must bind `action_slot` (same for NLA strips).
- **Never `scene.frame_set` backward into a cached cloth range** to grab a
  still — it re-evaluates stale state (run 4 produced two byte-identical
  "different phase" sim renders). Sim stills are shot inside the capture loop.

## Open problems / unknowns

- **Sync contract.** The clip is one gait cycle keyed 1:1 with the body clip's
  cycle. If the game ever plays `run` at a scaled speed, the skirt layer must
  scale identically or the cloth will fight the legs.
- **Gait transitions.** Run→walk→idle crossfades of the skirt layer are
  unproven; a naive crossfade of two phase-locked clips can momentarily halve
  the flare amplitude.
- **Collision deafness during override.** With the spring sim off, nothing
  pushes the skirt off world geometry (stairs, sitting). The bake only knows
  the legs.
- **Multi-garment.** One clip per (body, garment, gait) — the tapa long/short
  and piupiu each need their own bake. Matrix is small today; worth a driver
  config if it grows.
- **Wind/idle sway.** Baked clips are dead when the character stands still;
  the spring sim (or a third, subtle idle bake) still owns that.