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 (PC-lane overview), and the animation skill (batch workflow details).

Tool mirroring rule (audit 2026-07-23): the retargeters in tools/ (cc_retarget.py, mixamo_retarget.py, kevin_retarget.py, mocap_retarget.py) are mirrors of ariki-game/tools/ — the game copies are authoritative. Never edit them here; re-copy from ariki-game when they change (they silently diverged once already: 2026-07-15 → 2026-07-23, losing --despike/--fingers/--map ual).

---

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 .gdignored), 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