animation/.agents/wiki/ARCHITECTURE.md

# Architecture — animation pipeline

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

This file covers the **animation lane** (motion → clips). The repo also runs a
**clothing lane** (garments → worn outfits) that targets the same skeleton —
see `.agents/wiki/architecture/clothing-lane.md`.

## 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; verified identical 2026-08-06). `.claude/skills/` here mirror a
subset of `ariki-game/.claude/skills/` plus `~/.claude/skills/pose-estimation` —
see `README.md` Provenance section.

The **character/body lane is authoritative HERE and is not mirrored** (moved out
of ariki-game 2026-08-06): `tools/rigbait_decimate.py`,
`make_lena_nude_body.py`, `_bake_nude_body_texture.py`,
`_render_body_closeup.py`, `verify_body_variant.py`. Anything that authors a
character mesh, rig, or body texture is born here from now on, governed by
`characters/REGISTRY.md`. The game repo keeps only the historical committed
generators (`make_lena_body.py`, `make_male_ib_quatskin_accurig.py`,
`male_mesh_decimate.py`, the `_convert_lena_quat_v*` series): they are cited by
game-side plans and some carry game-side tests.

### Which repo does a non-gameplay tool belong to

Decided by **subject, not by "is it gameplay"** — nothing in `ariki-game/tools/`
is gameplay (no `.gd` runtime script references it at all), so that test would
empty the folder into this one. Three questions, in order:

1. Does the engine, CI, or the game's own test suite run it? → **stays in
   ariki-game.** `asset_pipeline.py`, `game.sh`, `session.py`,
   `e2e_interaction.py`, `anim_qc.py`, `rig_pose_gate.py`,
   `targeted_reimport.sh`, `clothing_motion_qa.sh`, and every module a
   `tools/test_*.py` imports.
2. Does it author characters or motion? → **here.**
3. Neither? → it is **game-asset authoring** (trees, terrain, water, props,
   items, animals, VFX). Not gameplay, but not animation either — leave it there
   rather than making this repo a dumping ground.

Two things that keep tripping this up: some character tools have game-side tests
(`brow_cover_math.py`, `generate_lena_brow_surface.py`, `test_mako_rig_math.py`),
so they move with their tests or not at all — and **this repo has no test
harness**, so receiving them means standing one up. And `anim_qc.py` staying is a
deliberate split, not drift (see the two-QC-tools note above).

**Cross-repo paths in tools that moved here:** resolve the game checkout from
`$ARIKI_GAME`, else guess the sibling directory and *verify it*, aborting with the
path tried. Never let an ariki-relative default resolve silently wrong — same rule
as `--target` above.

## See also

- `.agents/wiki/architecture/clothing-lane.md` — the clothing lane (reference
  image → Marvelous Designer → `clothing/` → worn outfit in-game).
- `.agents/wiki/architecture/` — per-system detail (split a subsystem out when
  it 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.