animation/exchange/GUIDE.md

# exchange/ — Folder guide for agents

This folder is the Mac↔PC bridge for the animation pipeline (iClone on the PC ↔
ariki-game on the Mac). Every file in here is **in transit** on one of the tracks
below. If you are an agent dropping files into this repo, or processing a batch,
this file tells you which folder to use, when a file moves to the next stage, and
when the previous version gets archived.

Related docs: `docs/dances/REGISTRY.md` (naming — the source of truth),
`docs/iclone-bridge.md`, and the `animation` skill (batch workflow details).

---

## Folder map — EDIT PATHS HERE ONLY

Folder locations may change. Every rule in this guide refers to folders by the
**KEY** below, never by a hardcoded path. If a folder moves, update this table
(and nothing else in this file).

| KEY | Current path | One-liner |
|---|---|---|
| `INBOX` | `exchange/INBOX/` | Untriaged drop zone for anything sent to Jeremy |
| `INCOMING_FBX` | `exchange/incoming-fbx/` | Accepted FBX takes queued for retargeting |
| `CONVERTED_GLB` | `exchange/converted-glb/` | Retargeted game-ready GLBs (base clips) |
| `LOOPED_GLB` | `exchange/looped-glb/` | Seam-fixed loop variants from `tools/loop_fix.py` (created on demand) |
| `PINGPONG_GLB` | `exchange/pingpong-glb/` | Palindrome `_pp` loop variants from `tools/pingpong_bake.py` |
| `OUTGOING_PROPS` | `exchange/outgoing-props/` | Game → iClone direction: staging props + source motions for iClone editing |
| `REFERENCE_VIDEO` | `exchange/reference-video/` | Choreography/mocap reference footage |
| `ICLONE_PROJECTS` | `exchange/workingfiles-iclone/` | iClone `.iProject` working-file backups |
| `ARCHIVE` | `archive/` (repo root) | Rejected/superseded files — mirrors the exchange subfolder names |
| `GAME_DANCEGEN` | `<ariki-game>/assets/quaternius/dancegen/` | Final GLB destination in the game repo |
| `GAME_DANCES` | `<ariki-game>/assets/dances/` | Dance JSON destination in the game repo |

Notes that apply everywhere:
- Binary formats (`.fbx`, `.glb`, `.mp4`, `.task`) go through **Git LFS**; push with `tinqs push`.
- **Move, never delete.** Anything obsolete goes to `ARCHIVE` (see archiving rules at the bottom).
- Stage files **by explicit path** — never `git add -A` (this repo often has unrelated in-flight work).

---

## Track 1 — INBOX triage (anyone → Jeremy)

**Folder:** `INBOX`

The only folder outside agents should ever write to. Drop whatever you're sending
(FBX, textures, JSON, video, etc.), commit, push. Do **not** place files directly
into the pipeline folders and do not reorganize the rest of `exchange/`.

| Event | Action |
|---|---|
| File arrives | Sits in `INBOX` untouched until Jeremy (or a session he directs) triages it |
| Triaged as an animation take | Move to `INCOMING_FBX` → enters Track 2 |
| Triaged as reference footage | Move to `REFERENCE_VIDEO` → Track 4 |
| Triaged as anything else | Jeremy decides; ask, don't guess |
| Junk / duplicate | Move to the matching `ARCHIVE` subfolder |

`INBOX` should trend toward **empty** — a file living there long-term means triage
was missed.

## Track 2 — Animation intake (iClone/PC → game) — the main track

**Stages:** `INBOX` → `INCOMING_FBX` → `CONVERTED_GLB` (+ loop variant in
`PINGPONG_GLB` or `LOOPED_GLB`) → copied to `GAME_DANCEGEN` + JSON in `GAME_DANCES`.

A "take" is a **file set that always travels together**: `<take>.fbx` +
`<take>.json` + `<take>.fbm/` texture folder (when present). Move all three,
always.

| Stage | What lives here | Moves forward when |
|---|---|---|
| `INCOMING_FBX` | Raw iClone FBX exports (1800f @ 60fps typical) awaiting retarget | Retargeted via `tools/cc_retarget.py` → GLB written to `CONVERTED_GLB` |
| `CONVERTED_GLB` | Game-ready GLB, named per the registry (`nd_##` provisional, ceremony code once adopted) | Copied (not moved) into `GAME_DANCEGEN` with a dance JSON |
| `PINGPONG_GLB` / `LOOPED_GLB` | The loop variant (`<pack>_pp` / seam-fixed). **Every shipped dance is a pair: base + loop.** Must pass `tools/loop_qc.py` (exit 0) | Copied into `GAME_DANCEGEN` alongside the base clip |

Rules on this track:
- **Naming:** new takes get the next free `nd_##` from `docs/dances/REGISTRY.md`
  at conversion — never a content name. Update the registry row at every
  conversion/adoption/archive.
- **FBX stays in `INCOMING_FBX` after conversion** (it's the re-export source)
  until its take is adopted or rejected.
- The GLB is **copied** to the game repo, not moved — `CONVERTED_GLB` keeps the
  canonical copy.

**Archive triggers (move old version → matching `ARCHIVE` subfolder):**

| Trigger | What to archive |
|---|---|
| A **re-export of the same take** arrives (same choreography, new FBX) | The old FBX set from `INCOMING_FBX` and its old GLBs from `CONVERTED_GLB`/`PINGPONG_GLB`/`LOOPED_GLB` |
| Take is **rejected** | Its entire file set across all stage folders (and `archive/dances/` on the game side) |
| Take is **adopted** (renamed `nd_##` → ceremony code via `tools/rename_clip.py`) | The old `nd_##`-named files, once the renamed set is verified in-game |

Never archive mid-batch — wait until Jeremy confirms the batch looks right in-game.

## Track 3 — Outgoing to iClone (game/Mac → PC)

**Folder:** `OUTGOING_PROPS`

The reverse direction: anything exported from the game side for use inside
iClone. Two kinds live here today:
- **Staging props** (e.g. `boat/` — built by `tools/export_boat_prop.py`, with
  renders for eyeball QA). Each prop gets its own subfolder with a README.
- **Source motion FBX** (Mixamo/Kevin-Iglesias clips like `Swimming.fbx`) sent
  over as raw material for iClone editing. Note: some earlier source-motion drops
  (the `HumanM@Mining*` set) landed in `INCOMING_FBX`; going forward,
  game→PC source motions belong here.

| Event | Action |
|---|---|
| New version of a prop | Overwrite in place (git history is the archive for props) — but **render and eyeball before shipping**; a green verify gate has passed a visually-wrong prop before |
| PC has consumed the files and the resulting take shipped | Leave in place until Jeremy says to clean up |

## Track 4 — Reference footage

**Folder:** `REFERENCE_VIDEO`

Choreography/mocap reference videos (inputs for iClone Video Mocap and for
`pose-estimation` scoring). These are **inputs, not pipeline items** — they don't
advance through stages.

| Event | Action |
|---|---|
| New reference arrives (usually via `INBOX`) | Move here |
| The dance it references is adopted and shipped | Video becomes archivable — ask Jeremy before moving (these are large LFS objects; he may want them kept for re-scoring) |

## Track 5 — iClone working files

**Folder:** `ICLONE_PROJECTS`

`.iProject` backups from the PC so iClone sessions can be resumed/recovered.
These are big (100 MB+) LFS blobs.

| Event | Action |
|---|---|
| Newer save of the same project | Overwrite in place — git history keeps priors |
| Project's takes all adopted or rejected | Archivable on Jeremy's call only |

---

## Archiving rules (all tracks)

1. `ARCHIVE` **mirrors the exchange subfolder names** — a file from
   `INCOMING_FBX` goes to `ARCHIVE/incoming-fbx/`, a GLB from `CONVERTED_GLB` to
   `ARCHIVE/converted-glb/`, etc. If a mirror subfolder doesn't exist yet, create it.
2. **`git mv`, never delete.** Archived files keep their names; nothing in
   `ARCHIVE` is ever renamed or reused.
3. **Registry numbers are never reused.** An archived `nd_03` retires the number
   forever.
4. Every archive action gets a **registry update** (`docs/dances/REGISTRY.md`)
   when it involves a tracked dance.
5. Game-side counterparts (GLBs/JSON already copied into ariki-game) archive to
   `<ariki-game>/archive/dances/` (which is `.gdignore`d), in the same commit
   cycle.

## Quick decision table

| You are… | You should… |
|---|---|
| An outside agent sending files | Drop in `INBOX`, commit, push. Touch nothing else. |
| Processing a new batch | Follow Track 2 top to bottom; read the `animation` skill first |
| Delivering game assets to the PC/iClone | Put them in `OUTGOING_PROPS` (subfolder per prop) |
| Holding a newer version of something already here | Same-name working files: overwrite. Pipeline takes: move the old set to `ARCHIVE` first (Track 2 triggers) |
| Unsure which track applies | Leave it in `INBOX` and say so — wrong-folder moves are worse than no move |