animation/docs/animations/NAMING.md

# Animation Naming Conventions

**Decision (Ozan, 2026-07-24): do NOT mass-rename existing animations.** Renaming clip
strings inside purchased vendor packs (Quaternius UAL, Kevin Iglesias) breaks the
vendor re-download/upgrade path, forces a risky full-pack re-export through Blender, and
buys only cosmetic consistency. Instead: **document the conventions that already exist,
keep each source's native names, and name new files to conform going forward.** Provenance
and status are tracked in the registry catalogue, not by renaming.

This file is the source of truth for *how animations are named*. `.agents/wiki/dances/REGISTRY.md`
remains the source of truth for the dance/boat clip roster.

---

## 1. The three name-spaces

Animation naming spans three independent layers. They are joined by explicit mappings, not
by making the strings equal. **You almost never need them to match.**

| Layer | What it is | Case style | Example | Who reads it |
|---|---|---|---|---|
| **Pack file** | the `.glb` basename on disk | lowercase snake_case | `kevin_male_movement.glb`, `UAL1.glb`, `war_dance_01.glb` | filesystem, `ClipCatalog` (discovers by basename) |
| **Clip name** | the animation string baked inside the GLB | *source-dependent* (see §3) | `Swim01_Forward`, `TreeChopping_Loop`, `WarDance01` | GLB metadata, dance JSON `clip` field, `SetupAnimations()` mapping |
| **Game key** | the logical id the game code plays | lowercase snake_case | `swim`, `chop`, `war_dance_01` | `PlayerAnimController`, `PlayerAnimationLogic`, `AnimationTree`, AI, dance JSON `name` |

**Key fact:** the game controller speaks *only game keys* — it never references a raw clip
name. The single place the clip-name layer meets the game-key layer is the mapping arrays in
`ariki-game/src/Viewer/PlayerController.cs → SetupAnimations()` (`clip name → game key`).
That indirection is why we can keep vendor clip names untouched: the game key is our stable
API, the vendor clip name is just what that key happens to bind to.

---

## 2. Game keys — the one namespace we fully own

Game keys are the cleanest, most important naming layer, because they are the game's actual
vocabulary and we control them 100%. **Rules:**

- **lowercase snake_case**, matching the game's item-id convention (`ceremonial_garb`, `dance_platform`).
- **Semantic, not source-derived.** Name the *action*, never the vendor clip it currently
  points at: `chop`, not `treechopping`. If we later swap the underlying clip, the key is stable.
- **Directional suffixes** use short forms: `_fwd`, `_bwd`, `_l`, `_r`, and diagonals
  `_fwd_l`, `_fwd_r`, `_bwd_l`, `_bwd_r`.
- **State suffixes:** `_idle`, `_enter`, `_exit`, `_start`, `_land`.
- Examples in use: `idle`, `walk`, `run`, `sprint`, `crouch_idle`, `crouch_walk`, `swim`,
  `swim_idle`, `swim_up`, `swim_down`, `swim_strafe_left`, `chop`, `mine`, `fish`, `gathering`,
  `farm`, `carry`, `eat`, `sleep`, `skin`, `pray`, `weapon_attack`, `shield_block`, `turn90_l`.

When you wire a new animation, **the game key is what you invent** — pick a semantic
snake_case key and add the `clip → key` row in `SetupAnimations()`. The clip name stays
whatever the source produced.

---

## 3. Current clip-name conventions, by source

We keep each source's native convention. Recognise them; don't fight them.

### 3a. Quaternius UAL (`anim/UAL1.glb`, `anim/UAL2.glb`) — VENDOR, keep as-is
- **PascalCase, `_`-separated.** `Climb_Idle_Loop`, `Jog_Fwd_Loop`, `TreeChopping_Loop`.
- Looping clips end **`_Loop`** (or `_Idle_Loop`).
- Directions: **`_Fwd` / `_Bwd` / `_Left` / `_Right`**; diagonals **`_Fwd_L` / `_Fwd_R` / `_Bwd_L` / `_Bwd_R`**.
- Transitions: **`_Enter` / `_Exit`**; jumps **`_Start` / `_Land`**; variants numbered **`01`, `02`**.
- Root-motion twins carry **`_RM`** (in the `*_RM.glb` packs; game loads non-RM only).

### 3b. Kevin Iglesias (`kevin/kevin_{male,female}_*.glb`) — VENDOR, keep as-is
- **PascalCase, action + zero-padded number, then full-word direction.**
  `Walk01_ForwardLeft`, `Swim01_Forward`, `Crouch01_Walk_BackwardRight`.
- Looping clips end **`_Loop`**; handedness uses **`_L` / `_R`** (`SkinningGround01_R_Loop`,
  `ThrowSpear02_R`); root-motion uses a trailing **`RM`** (`Walk01_ForwardRM`).
- Packs are split by theme: `combat`, `movement`, `work`, `social`, `idles`, `misc`.

### 3c. Our authored clips — the convention WE apply to new content
This is the part you actively control. Two sub-cases:

**Dances & boat actions** — follow `.agents/wiki/dances/REGISTRY.md` exactly:
- New dance take → **provisional** id `nd_##` (never a content-guessed name): pack/file
  `nd_08`, clip `ND08`, dance JSON `nd_08.json`. Variants keep the base id + suffix:
  `nd_08_pp` / `ND08PP`.
- On **adoption** to a ceremony → dance code = snake_case of the sim `DanceType` enum + index:
  pack `war_dance_01`, clip **`WarDance01`** (PascalCase, matches the enum), JSON `war_dance_01.json`.
- **Loop-pair rule:** every adopted dance ships base + ping-pong `_pp` variant
  (`war_dance_01_pp` / `WarDance01PP`), baked with `tools/pingpong_bake.py`, must pass `loop_qc.py`.
- Boat actions get direct `boat_*` codes (no provisional stage): `boat_dive`, `boat_row_loop`,
  clip `BoatDive` / `BoatRowLoop`.

**Other authored one-offs (Mixamo, iClone mocap, composites):**
- Pack file = **lowercase snake_case**: `run_to_dive.glb`, `northern_soul.glb`, `Run_Punch.glb`.
- Clip name = **PascalCase of the file**: `RunToDive`, `NorthernSoulFloorCombo`, `Run_Punch`.
- Game key = **semantic snake_case**: `run_to_dive`, `dance_soul`, `run_punch`.

### The general rule for a NEW authored clip
```
pack file:  <category>_<descriptor>_<##>.glb     (lowercase snake_case)   e.g. work_haul_01.glb
clip name:  PascalCase of the file                                         e.g. WorkHaul01
game key:   <semantic snake_case>                                          e.g. haul
```
Categories (closed set): `loco`, `swim`, `work`, `combat`, `dance`, `boat`, `emote`, `misc`.
Variants numbered, **never reused**. Looping authored clips ship a `_pp` (or `_loop`) variant
that passes `loop_qc.py`.

---

## 4. Suffix & direction quick-reference

| Meaning | Game key (ours) | UAL (vendor) | Kevin (vendor) |
|---|---|---|---|
| looping | `_idle` / (implicit) | `_Loop` | `_Loop` |
| forward / back | `_fwd` / `_bwd` | `_Fwd` / `_Bwd` | `_Forward` / `_Backward` |
| left / right | `_l` / `_r` | `_Left` / `_Right` | `_Left` / `_Right` |
| diagonal | `_fwd_l` … | `_Fwd_L` … | `_ForwardLeft` … |
| transition | `_enter` / `_exit` | `_Enter` / `_Exit` | — |
| ping-pong loop | `_pp` | — | — |
| root motion | (not loaded) | `_RM` | `RM` |
| variant index | `_01` | `01` | `01` |

---

## 5. Decision tree — naming a future file

1. **Is it a vendor clip (UAL/Kevin/other purchased pack)?**
   → Keep the vendor's clip name and pack layout untouched. To use it, add a `clip → game key`
   row in `SetupAnimations()` and a catalogue entry in the registry. Do **not** re-export or rename.
2. **Is it a dance or boat action?** → Follow `.agents/wiki/dances/REGISTRY.md` (`nd_##` → ceremony
   code; boat `boat_*`; loop-pair rule).
3. **Is it another clip we author (Mixamo/iClone/composite)?** → Apply the §3c general rule:
   snake_case file, PascalCase clip, semantic snake_case game key, closed-set category, `_pp` loop.
4. **In all cases:** add/update the registry row (§6) in the same commit, and — if the game plays
   it — the `SetupAnimations()` mapping.

---

## 6. The registry catalogue (provenance & status — no renaming)

The catalogue records, per clip we care about, the fields Jeremy asked for — **without
changing any names**:

`canonical_id` (our snake_case handle) · `clip` (actual name in GLB, vendor or ours) ·
`pack` · `category` · `game_keys` · `source` · `created` · `method` · `status`
(`approved` / `wip` / `not_started`) · `notes`.

- For vendor clips, `canonical_id` is just our stable handle for the catalogue; `clip` stays
  the vendor string. Nothing on disk changes.
- `not_started` rows capture animations the game *needs but doesn't have yet* (the 13 dance
  ceremony slots, the 6 boat actions awaiting takes, any gap from the removals audit).
- Kept machine-readable (YAML/JSON) with a generated Markdown view; see the audit doc for the
  build plan. This is the deliverable that survives Ozan's no-rename decision.

---

## 7. Maintenance

- Every convert / adopt / archive **updates the registry row in the same commit** — the rule
  already in `.agents/wiki/dances/REGISTRY.md`, generalized to all categories.
- **Archive, never delete; numbers never reused.** Rejected/superseded takes move to
  `archive/` (this repo) and `archive/dances/` (ariki-game), keeping their names.
- Sync via `tinqs push` / `tinqs pull` (raw git pull hangs on LFS). Report commit hashes.

---

## 8. Why this shape (rationale, for future readers)

The game controller is decoupled from asset names by the game-key layer, so the *valuable*
outcomes — provenance, status, a "what do we still need" list, and a stable controller
vocabulary — come from the **registry + game-key discipline**, not from mutating vendor clip
strings. Renaming purchased packs would cost a full-pack Blender re-export (risking rig-pose
drift, caught only by `rig_pose_gate.py`), permanent vendor-upgrade friction, and LFS bloat,
for cosmetic gain. Hence: document the conventions, name new files to fit, catalogue
everything, rename nothing that already ships.