Merge branch 'main' of https://tinqs.com/tinqs/animation

exchange/GUIDE.md

@@ -0,0 +1,162 @@
+# 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 |

exchange/INBOX/README.md

@@ -0,0 +1,13 @@
+# INBOX
+
+Drop zone for anyone sending files to Jeremy through this repo.
+
+Put whatever you're sending in here (FBX takes, textures, reference video, JSON, etc.),
+commit, and push. Jeremy will pull, triage, and move things into the proper pipeline
+folders (`incoming-fbx/`, etc.) from there.
+
+Notes:
+- Binary formats (`.fbx`, `.glb`, `.mp4`, `.task`) go through Git LFS automatically.
+- Don't reorganize other folders in `exchange/` — just drop your files here.
+- Full folder guide (what each `exchange/` folder is for, and how files move
+  between them): see [`../GUIDE.md`](../GUIDE.md).