animation/docs/dances/REGISTRY.md

# Dance registry — single source of truth for names

Every dance clip in the pipeline is tracked here. **Numbers are never reused.**

## Naming system

Names follow the **game's item-id convention: lowercase snake_case** (like
`ceremonial_garb`, `dance_platform`, `war_challenge`).

**Stage 1 — provisional (new dances).** Every new take gets the next free `nd_##`
number at conversion time, regardless of what the PC-side export was called:
pack/file `nd_08`, clip `ND08`, dance JSON `nd_08.json`. Variants keep the base id +
suffix: `nd_08_pp` / `ND08PP`. The `nd` prefix means "not yet adopted — subject to
rename or archive". Never name a new dance after its content (a take called
"firedance1" turned out to be dance1's choreography — content-guessed names lie).

**Stage 2 — adopted (chosen for a specific dance ceremony).** Dance codes are the
**game ceremony** the dance belongs to — snake_case of the sim's `DanceType` enum
(`sim/arena/src/GameSystems.cs`) + a two-digit index for multiple takes per ceremony:
pack `war_dance_01`, clip `WarDance01` (PascalCase, matching the enum), dance JSON
`war_dance_01.json`, variants `war_dance_01_pp` / `WarDance01PP`. A take is only
renamed once Jeremy says which ceremony it corresponds to. Rename with:

```bash
/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/rename_clip.py -- \
  --src exchange/<dir>/nd08.glb --out exchange/<dir>/haka01.glb --name Haka01
```
…then rename the dance JSON (+ its `name` and `clip` fields) in ariki-game, re-run
`game.sh import`, and `git mv` the old files out. Update the row below.

**Loop rule.** Every adopted dance ships as a PAIR: the base clip (`war_dance_01`) plus its ping-pong loop variant (`war_dance_01_pp` / `WarDance01PP`, baked with `tools/pingpong_bake.py`, must pass `loop_qc.py`). No adoption is complete without the loop.

**Archive.** Rejected/superseded takes move to `archive/` (this repo) and
`archive/dances/` (ariki-game, `.gdignore`d) — never deleted, never renamed.

## Ceremony slots (from the sim's `DanceType` enum + tech tree)

| ceremony code | Age | status | take |
|---|---|---|---|
| `water_dance_01` | 1 | awaiting take | — |
| `fire_dance_01` | 1 | awaiting take | — (the old "firedance1" was mislabeled dance1 choreography) |
| `tide_dance_01` | 1 | awaiting take | — |
| `fertility_dance_01` | 1 | **adopted** 2026-07-16 | aloha1 (hula) — shipped with `_pp` loop |
| `food_dance_01` | 1 | awaiting take | — |
| `taming_dance_01` | 1 | **adopted** 2026-07-16 | dance1 — shipped with `_pp` loop |
| `sailing_dance_01` | 2 | awaiting take | — |
| `war_dance_01` | 2 | **adopted** 2026-07-16 | hakadance1 (haka) — shipped with `_pp` loop |
| `building_dance_01` | 2 | awaiting take | — |
| `colony_shield_dance_01` | 2 | awaiting take | — |
| `age_progression_dance_01` | 3 | awaiting take | — (gates Age advancement) |
| `star_watching_dance_01` | 3 | awaiting take | — |
| `rain_dance_01` | tech | awaiting take | — (tech-tree "Rain Maker"; not in DanceType enum yet) |

## Register

| id | status | pack(s) | clip | origin take | notes |
|---|---|---|---|---|---|
| fertility_dance_01 | **adopted** | `fertility_dance_01`, `fertility_dance_01_pp` | `FertilityDance01`, `FertilityDance01PP` | aloha1 (iClone, 2026-07-15) | hula |
| taming_dance_01 | **adopted** | `taming_dance_01`, `taming_dance_01_pp` | `TamingDance01`, `TamingDance01PP` | dance1 (iClone, 2026-07-15) | |
| war_dance_01 | **adopted** | `war_dance_01`, `war_dance_01_pp` | `WarDance01`, `WarDance01PP` | hakadance1 (iClone, 2026-07-15) | haka |
| — | archived | `hakadance2` | `HakaDance2` | hakadance2 | near-duplicate of hakadance1 take family |
| — | archived | `alohaOG` | `AlohaOG` | alohaOG | superseded by aloha1 |
| — | archived | `firedance1` | `FireDance1` | firedance1 | **same choreography as dance1** — mislabeled export |
| — | archived | `hakaOG` | `HakaOG` | hakaOG | near-identical to hakadance1 |
| — | archived | `haka_mocap` | `HakaFull` | MediaPipe video mocap (2026-07-13) | pre-iClone experiment |

Next free provisional number: **nd_01** (none issued yet — the five keepers predate
the system and keep legacy names until adopted).