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:

/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, .gdignored) — 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	⚠ no enum entry	— (no TideDance in the sim DanceType enum as of 2026-07-23 — confirm with Ozan whether the slot is real before filming a 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	1	awaiting take	— (tech-tree "Rain Maker"; RainDance is in the DanceType enum, Age 1 — earlier "not in enum yet" note was wrong, corrected 2026-07-23)

Register

id	status	pack(s)	clip	origin take	notes
nd_01	provisional	nd_01, nd_01_pp	ND01, ND01PP	baraka1 (iClone, 2026-07-21)	1800f@60; _pp loop passes QC (0.00 seam); awaiting ceremony assignment
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_02 (nd_01 = baraka1, issued 2026-07-21).

Boat actions (avatar action clips — direct names, no provisional stage)

Staging prop: exchange/outgoing-props/boat/boat_prop.fbx (built by tools/export_boat_prop.py; see its README for iClone import + filming notes). Cyclic clips (*_loop, *_idle) must pass loop_qc.py before shipping; one-shots (dive/climb/collect) keep their pelvis translation (game moves the avatar).

action code	clip	status	notes
boat_dive	BoatDive	awaiting take	airborne — hand-key/ActorCore or takeoff-only filming
boat_climb	BoatClimb	awaiting take	film over ~0.65 m proxy; Reach-target cleanup
boat_collect	BoatCollect	awaiting take	kneel over gunwale, flotsam grab
boat_row_loop	BoatRowLoop	awaiting take	helm, stern-oar sweep ±18°
boat_fish_loop	BoatFishLoop	awaiting take	Seat_Fisher; coexists with kevin Fishing01_Loop
boat_sail_idle	BoatSailIdle	awaiting take	sway/line-hauling loop
(unregistered)	CanoeDismount, CanoeSitIdle	live in-game since 2026-07-21	shipped as ariki-game/assets/quaternius/dancegen/canoedismount1.glb (content-guessed name, predates this table) — register under a boat_* code at next adoption pass
(unregistered)	run_to_dive	live in-game	Mixamo one-off at ariki-game/assets/quaternius/mixamo/run_to_dive.glb — outside this pipeline, listed for completeness

QC tool split (audit 2026-07-23)

Two QC tools exist and gate different stages — both stay:

• tools/loop_qc.py (this repo) — the pre-commit loop gate: local-rotation pose gap, velocity gap, root drift; exit 0/1. Every _pp (and *_loop/*_idle boat clip) must pass it before adoption — this is the "must pass loop_qc" rule above.
• ariki-game/tools/anim_qc.py — post-ingest QC on the game side: world-space seam position/velocity, mid-clip stutter scan, seam-cross video render for eye review.