| `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 |
