# Architecture — animation pipeline

Entry point to architecture law for this repo. Per-system detail lives in
`.agents/wiki/architecture/`.

## The one-sentence shape

PC-side motion capture (iClone 8 + Video Mocap) → this repo (Mac↔PC bridge,
Blender-headless retargeting, loop QC) → `ariki-game` (Quaternius-rig GLB
consumption via ClipCatalog).

## Machines and where things live

| Machine | Owns |
|---|---|
| PC (Windows) | iClone 8 + Video Mocap plugin — authors motion, exports FBX |
| Mac (and PC) | Blender 5.1.2, this repo's retarget tools, `ariki-game` checkout |

Files move machine-to-machine only through `exchange/` in this repo, synced
with `tinqs push`/`tinqs pull` (Git LFS for `.fbx/.glb/.mp4/.task` — see
`.gitattributes`). Raw `git pull` hangs on LFS in tinqs.com repos.

## Pipeline stages

1. **Capture (PC)** — iClone export, Blender preset, Range=All, Preserve Bone
   Names ON → `exchange/incoming-fbx/`.
2. **Retarget (either machine)** — Blender-headless, source-specific retargeter
   in `tools/`, all bake onto the shared Quaternius rig and export a
   mesh-stripped GLB with one NLA track per clip:
   - `cc_retarget.py` — Reallusion CC/iClone `CC_Base_*` FBX (60fps; rejects
     2-frame `_TempMotion` exports as a guard against motion-less takes)
   - `mixamo_retarget.py` — Mixamo FBX (prefix auto-detect)
   - `kevin_retarget.py` — Kevin Iglesias Unity FBX (`B-*` rig; hardcoded
     target path, non-portable)
   - `mocap_retarget.py` — MediaPipe pose JSON → GLB (rotation solving, no
     source armature)
   → `exchange/converted-glb/`.
3. **Loop QC** — `tools/loop_qc.py` (pre-commit gate: pose/velocity/root-drift
   continuity across the seam, exit 0 = smooth). Fixers when it fails:
   `tools/loop_fix.py` (de-drift/trim/seam-blend → `exchange/looped-glb/`) and
   `tools/pingpong_bake.py` (palindrome bake, seam-perfect but motion reverses
   at the turn → `exchange/pingpong-glb/`, clip suffix `PP`). Every adopted
   dance ships as a base clip + `_pp` pair.
4. **Ship** — commit + `tinqs push` the GLBs in this repo, then copy into
   `ariki-game/assets/quaternius/dancegen/` (auto-discovered by ClipCatalog as
   `<pack>/<ClipName>` — also watches `kevin/`, `mixamo/`), write one dance JSON
   per clip in `ariki-game/assets/dances/`, `game.sh import`, verify clip names
   match GLB `animations[].name` exactly, commit in ariki-game (push only when
   Jeremy asks).
5. **Post-ingest QC (game side, out of this repo)** — `ariki-game/tools/anim_qc.py`
   re-checks world-space seam continuity + renders a seam-cross video for eye
   review. Two QC tools by design: this repo's gate is pre-commit/local-space,
   the game's is post-ingest/world-space.

## Naming law

Full detail: `.agents/wiki/dances/REGISTRY.md` (source of truth — do not
duplicate its content elsewhere). Summary: new takes get a provisional `nd_##`
id (never a content-derived name); a take is renamed to its ceremony code
(snake_case of the sim's `DanceType` enum + index) only once Jeremy assigns it
to a specific ceremony, via `tools/rename_clip.py`. Rejected/superseded takes
are archived (`archive/`), never deleted; numbers are never reused.

## Canonical target rig

All retargeters bake onto ariki-game's
`assets/quaternius/base-characters/.../Godot - UE/Superhero_Male_FullBody.gltf`.
Run from this repo, `--target` must be passed explicitly (the tool's default
path is ariki-relative and won't resolve here). The rig/pack standard itself
(65-bone Quaternius UE-named skeleton, hero body `Ariki_Female_QuatSkin.glb`) is
governed by `ariki-game/.humans/animation-bone-sources.html` and
`ariki-game/.agents/wiki/quaternius-ual-packs.md` — this repo's iClone/mocap
lane is explicitly a separate clip source (not UAL1/UAL2/Kevin/Mixamo), landing
in `dancegen/` only.

## Tool provenance / mirroring

`tools/cc_retarget.py`, `mixamo_retarget.py`, `kevin_retarget.py`,
`mocap_retarget.py` are **mirrors of `ariki-game/tools/`** — the game copies are
authoritative; re-copy from ariki-game when they change (they have silently
diverged before). `.claude/skills/` here mirror a subset of `ariki-game/.claude/skills/`
plus `~/.claude/skills/pose-estimation` — see `README.md` Provenance section.

## See also

- `.agents/wiki/architecture/` — per-system detail (currently: this file covers
  the whole pipeline; split out if a subsystem grows its own doc).
- `.agents/wiki/dances/REGISTRY.md` — naming/registry source of truth.
- `.agents/wiki/iclone-bridge.md` — PC-lane routing stub.
- `.agents/wiki/devops-reports/` — point-in-time audits and convergence reports.