animation/plans/seated-sway-idle-plan-2026-07-21.md

# Plan v3: seated hearth dance (nd_02) — seated pose + salsa upper-body sway

**Status:** reviewed (independent Opus pass, GLM-4.6 API pass, Fable self-review),
awaiting Jeremy's go/route-confirmation · **Author + PC executor:** Fable 5 session 2026-07-21 (via
TinqsBridge) · **Mac-side steps:** later session

## Goal

A looping dance for a **hearth ceremony** — villagers seated around the hearth,
**seated the entire time** (lower body pinned to Jeremy's seated pose), **upper body
swaying through 4 Mixamo salsa clips**. Registry id: provisional **nd_02** (pack
`nd_02`, clip `ND02`, loop pair `nd_02_pp`/`ND02PP`); ceremony adoption is Jeremy's
call later (no hearth slot exists in the DanceType enum — closest candidate is
`fire_dance_01`, NOT assumed).

## §0 Inputs (confirmed by Jeremy 2026-07-21)

1. **Seated pose:** `A:\Reallusion Content\Reallusion Custom\Animation\Motion\External Motion\Male_Sitting_Pose.rlMotion` (39 KB — likely a single-frame pose; see Phase 1.2).
   ⚠ Provenance check at first eyeball: hearth circle implies **ground-seated**; if this
   pose is chair-height the pelvis will float in-game.
2. **Sway sources:** the 4 Mixamo FBX in `C:\Users\Jeremy\Downloads\`:
   `Salsa Dancing.fbx` (1.05 MB), `Salsa Dancing (1).fbx` (2.62 MB),
   `Salsa Dancing (2).fbx` (1.84 MB), `Salsa Dancing (3).fbx` (0.55 MB).
3. **Avatar (for the seated export only):** any stock CC male.
4. **Length target:** 20–30 s @ 60 fps overall; ~5–7 s per salsa segment.

## Route decision (changed in v2 after review)

**Primary is now Route B**: retarget the salsa FBX directly with the pipeline's own
`mixamo_retarget.py` (purpose-built, proven on `northern_soul`/`run_to_dive`) and
combine with the seated pose via the game-side **upper/lower mask composite**,
pre-baked to a GLB. iClone's role shrinks to its one irreplaceable contribution:
exporting Jeremy's seated pose as a clip (via the bridge).

Why (review consensus): Route A put two **unprobed** RLPy behaviors on its critical
path (`LoadMotion`-with-FBX — which even if it loads may skip Mixamo→CC
characterization and produce garbage — and `ExportFbxFile` option coverage), added a
lossy Mixamo→CC→game double-retarget plus the A-pose-bind risk, and then threw away
its own lower body at bake time. Route B is one proven retarget per source, iterates
via hot-reload JSON in the test bed (~0.5 s) instead of a full PC→Mac round-trip, and
gets beat-quantized transitions for free. Route A survives as fallback (§Route A) if
the salsa arm styling retargets badly onto the game skeleton.

**The lower-body guarantee moves into the composite bake itself** — the baked clip's
lower-mask tracks come from the seated clip and nowhere else. The separate
`lock_lower_body.py` from plan v1 is **dropped** (it only existed to repair Route A's
full-body take).

## Route B (primary)

### Phase 0 — salsa files into the repo (me, PC, now)
1. **Move** (not copy) the 4 FBX from Downloads into **`exchange/INBOX/`** (the repo's
   existing external-input drop, alongside `lena_tpose_legs5_input.fbx`), renamed
   `Salsa_Dancing_01.fbx` … `Salsa_Dancing_04.fbx`.
   *Note:* plan v1 sent these to the Reallusion content folder on A:; review blocker —
   the Mac retarget step can only see files that are **in the repo**. `.fbx` is
   LFS-tracked here, so a normal commit + `tinqs push` carries them.
2. Commit (explicit paths only, co-author line
   `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`), `tinqs push`.

### Phase 1 — seated clip out of iClone (me, PC, via bridge)
1. Launch check: `--ping`; if iClone is closed, start
   `A:\Program Files (x86)\iClone 8\Bin64\iClone.exe`, poll ping (~60–90 s).
   Load a stock CC male (`RLPy.RFileIO.LoadFile`), apply
   `LoadMotion(Male_Sitting_Pose.rlMotion, t=0, avatar)` — **check the returned
   RStatus** (don't assume success), and verify a clip landed on the motion track.
2. **Ground-seat precheck (GLM review):** after applying the pose, read the pelvis/hip
   world Y via the bridge and log it. Chair-height ≫ ground-height — if it reads like
   a chair sit, stop and show Jeremy before wasting the export.
3. **Hold the pose ≥300 frames** (5 s @60): set the play range so the export is a real
   take. Verified against code: `cc_retarget.py:104` rejects only `<5`-frame
   `*TempMotion` takes (frame count, not motion content) — a 300-frame static hold
   passes. Extend by re-placing the pose key at the range end (or Jeremy sets the clip
   length in the timeline — one drag).
3. Export FBX → `exchange/incoming-fbx/seatbase1.fbx`. Probe
   `RLPy.RFileIO.ExportFbxFile(*args)` for: Target Tool Preset **Blender**, 60 fps,
   Range = All, **Include Motion ON**, Preserve Bone Names. This is the only
   ExportFbxFile use left in the primary route — if the API can't reach the options,
   **Jeremy clicks the export dialog once** and the route loses nothing.
4. Sanity: file is multi-MB-ish and ≥300 frames. Commit + `tinqs push` (etiquette as
   Phase 0.2).
5. RTime/RFps handling: build times with RTime constructors from the stub; get numeric
   fps via RFps methods, never repr.

### Phase 2 — Mac side: retarget everything (later session / handoff)
0. *Cheap check first (Path 1):* scan kevin/UAL packs for an existing ground-seated
   idle — if one matches Jeremy's intended look better than the iClone export, offer
   the swap at eyeball time; Jeremy's pose remains the default.
1. `mixamo_retarget.py` on the 4 salsa FBX →
   `assets/quaternius/mixamo/salsa.glb` (clips `Salsa01..04` — batch mode per the
   kevin precedent). **Read back the GLB's `animations[].name` immediately** and use
   those exact strings in every later JSON/bake reference — don't assume the intended
   names survived the batch tool (GLM review).
2. `cc_retarget.py` on `seatbase1.fbx` → `exchange/converted-glb/seatbase1.glb`, clip
   `SeatBase1`. First-export QA: **A-pose arm check** in the showcase.
3. Copy `salsa.glb` into ariki-game (`assets/quaternius/mixamo/`), `seatbase1.glb` →
   `dancegen/`.

### Phase 3 — Mac side: composite, bake, loop, QC
1. **Iterate live first**: `nd_02.json` in `assets/dances/` with 4 chained moves, each
   `{layers: [{mask:"upper", clip:"salsa/SalsaNN"}, {mask:"lower", clip:"seatbase1/SeatBase1"}]}`
   — hot-reloads in the dance test bed (**ask Jeremy before launching the game**).
   Tune segment order/durations/bpm here where a change costs 0.5 s.
2. **Pre-bake the approved composite to a GLB** (registry requires a baked pair):
   generalize `tools/bake_run_punch.mjs` into a parameterized composite baker
   (`tools/bake_composite.mjs`): inputs = ordered (upper-clip, duration) list + lower
   clip; mask predicate **verbatim** from `bake_run_punch.mjs:103`
   (`root || pelvis || /thigh|calf|foot|ball/i`); output `exchange/converted-glb/nd_02.glb`
   clip `ND02`. **Verify gate built in:** assert every lower-mask bone track in the
   output matches the seated clip's pose within an epsilon (per-channel max deviation,
   e.g. 1e-3 — resampling/quantization makes strict equality false-fail; GLM review)
   — exit nonzero otherwise (lesson from the boat prop: agent-authored gates must
   assert what the eyeball would catch).
3. Loop pair: `pingpong_bake.py` → `nd_02_pp`/`ND02PP`. **Caveat (GLM review):**
   ping-ponging a 4-segment composite plays A→B→C→D→D→C→B→A — the reversal is exposed
   across *distinct* segments, not one homogeneous sway; it may read oddly even with a
   clean seam. Mitigations, judged at the test-bed eyeball: bookend the bake with short
   seated-base (arms-quiet) segments so `loop_fix.py`'s natural-loop trim becomes
   viable, or reorder segments so the reversal lands on the most symmetric one. Both
   variants must pass `loop_qc.py` (exit 0); nd_01 set the 0.00-seam bar.
4. Ship: GLBs + `.import` sidecars into ariki-game, final `nd_02.json` pointing at the
   baked `nd_02/ND02` (+`_pp`), `game.sh import`, verify GLB `animations[].name ==
   "ND02"`, registry row: origin "seated hearth sway — upper Mixamo salsa ×4, lower
   iClone Male_Sitting_Pose (seatbase1)". ariki-game commits stay local.

## Route A (fallback only — if salsa retargets badly onto the game skeleton)

Assemble in iClone instead: import the salsa FBX **via the UI with the Mixamo
characterization profile** (the route that produced `Talking_mixamo_com.rlMotion`;
`LoadMotion(fbx)` may be probed as an optimization but is NOT assumed — loading
without characterization would splat raw `mixamorig:` tracks onto the CC rig), place
seated base + salsa segments + seated base on the timeline, Jeremy eyeballs, export
one take → `cc_retarget.py` → then a lower-body lock IS needed again: same §Phase 3.2
baker degenerates to it (upper = the take itself, lower = seatbase1) — no separate
tool. Known extra risks: transition hard-cuts via API placement, double-retarget
quality, A-pose bind.

## Acceptance

- `nd_02` and `nd_02_pp` pass `loop_qc.py` (exit 0).
- Bake verify gate proves lower-mask tracks constant == seated pose.
- Upper body visibly cycles all 4 salsa flavors without harsh cuts (test-bed eyeball).
- Ground-seat height looks right at the hearth (pose-provenance check §0.1).
- Registry row added; salsa sources + seatbase committed in this repo via LFS;
  ariki-game not pushed.

## Review trail

- v1 reviewed 2026-07-21 by independent fresh-context Opus agent (GLM unavailable on
  this PC): 1 blocker (Route B files never reach the Mac), 4 major (lock-script unspec'd;
  frame-0 lock could freeze a standing pose; Route A's critical path rested on two
  unprobed RLPy behaviors; Route A discards most of its own work), 4 minor (2-frame
  guard on the seated export; loop-pair citation; co-author line; trim/pose-provenance).
  All verified factual claims in v1 held.
- v2 by Fable: Route B promoted; lock tool folded into the composite baker's
  verify gate; salsa destination changed from A:\Reallusion content to repo INBOX + LFS;
  seated export spec'd ≥300 frames; kevin-pack Path-1 check added; co-author line added.
- v2 reviewed 2026-07-21 by **GLM-4.6** (direct API call — key from tinqs-docs/.env).
  Accepted → v3: epsilon-tolerance verify gate (strict equality would false-fail on
  resampling); pelvis-Y ground-seat precheck before export; read back salsa clip names
  from the GLB instead of assuming; pingpong-reversal caveat for a 4-segment composite
  + bookend/reorder mitigations; check LoadMotion's returned RStatus. Rejected with
  evidence: "LoadMotion needs LoadFile+ApplyMotion" (contradicts the verified stub
  signature `RFileIO.LoadMotion(strFilePath, kTime, spObject)`, RLPy.py:13700 — still
  probe-first per plan); "no Node toolchain exists" (`tools/bake_run_punch.mjs` is in
  this repo and the gltf-transform route is documented in the animation-creation
  skill); "static 300f take trips the no-motion guard" (cc_retarget.py:104 gates on
  `<5` frames + `*TempMotion` name only); "Route A exports mixamorig bone names"
  (characterized import retargets onto the CC rig before export).