animation/docs/animations/AUDIT.md

# Animation Audit — 2026-07-24

Working audit for the animation naming-system project. Captures the current-state
inventory, what the game actually implements, what Ozan removed during his recent
animation work, and the open scope decisions. This is the evidence base for the
plan at `~/.claude/plans/i-want-to-audit-enchanted-squid.md`.

**Status:** audit findings recorded. **Decision (Ozan, 2026-07-24): do NOT implement a
mass-renaming system.** Pivot to *document the existing conventions + catalogue provenance/
status*; keep vendor names, name new files to conform. See `docs/animations/NAMING.md` for
the conventions. Nothing renamed. The rename-scope questions in §6 are now moot (resolved:
no rename); the registry catalogue in §6 still proceeds.

---

## 1. Goal

Audit and revise the animation naming system across the two repos. Five deliverables:

1. Create a naming system for **all** animations.
2. Figure out which animations Ozan removed ("Kevin" clips) during his last animation
   work, and document the full list of animations the game needs.
3. Rename current animations per the new naming system.
4. Document the system.
5. The animation list must store, per clip: where it came from, when it was created,
   how it was created, and whether it is **approved / work-in-progress / not-started**.

### Decisions locked (Jeremy, 2026-07-24)

- **Rename every animation in the game** per the new system; the registry stores each
  clip's **old/original name**. *(Scope of "in the game" narrowed by the §3 finding —
  see the open question in §6.)*
- Registry is **machine-readable YAML + a generated Markdown** view.
- Coverage = **all avatar skeletal clips** (locomotion, tools/work, combat, swim, dance,
  boat, emotes/social). Animals out of scope.
- Naming docs + registry live in the **animation repo** under `docs/animations/`, with
  pointers from ariki-game docs.

### Registry fields required

`canonical name` · `old name(s)` · `category` · `source/origin` · `creation date` ·
`creation method` · `status (approved | wip | not_started)` · `notes`.

---

## 2. Where the packs live

All game-loaded animation packs are under `assets/quaternius/` in **ariki-game**
(`/Users/jeremykashkett/Tinqs/local.repo/ariki-game`).

| Group | Path | Files | Clips | What it is |
|---|---|---|---|---|
| **UAL vendor** | `assets/quaternius/anim/` | UAL1.glb, UAL2.glb (+ `_RM` twins, Mannequin_F) | 254 unique (508 w/ RM) | Purchased Quaternius packs — the game's loco + work source of truth |
| **Kevin** | `assets/quaternius/kevin/` | 12 GLBs (`kevin_{male,female}_{combat,idles,misc,movement,social,work}.glb`) | 1,307 (male/female mirror → ~650 unique) | Kevin Iglesias retargets; game uses "gap-only" |
| **msrig** (stale) | `assets/quaternius/msrig/` | 18 GLBs (Kevin packs + UAL_Standard + a few Mixamo) | 1,399 | Superseded MixamoSkin retargets — flagged stale in the 2026-07-23 audit |
| **Mixamo** | `assets/quaternius/mixamo/` | 4 GLBs (run_to_dive, walking, northern_soul, ual_loco) | 11 | One-off Mixamo clips |
| **dancegen** | `assets/quaternius/dancegen/` | 10 GLBs (war/fertility/taming + `_pp`, nd_01, canoedismount1, hakadance1_static) | 11 | Our authored iClone-mocap dances + boat one-off |
| **anim-combined** | `assets/quaternius/anim-combined/` | Run_Punch.glb | 1 | Baked composite (run legs + punch upper body) |

**Animation-repo side** (`/Users/jeremykashkett/Tinqs/local.repo/animation`) holds the
pipeline staging/source, not what the game loads:
- `exchange/` — incoming FBX, converted GLB, pingpong loops, outgoing props
- `archive/` — retired takes (never deleted, per policy)
- `.agents/wiki/dances/REGISTRY.md` — existing partial naming system (dances + boat actions)
- `tools/` — all Blender-based (`cc_retarget.py`, `rename_clip.py`, `loop_qc.py`, `pingpong_bake.py`, …)

Dance JSONs that tell the game which clip to play: `ariki-game/assets/dances/*.json`.

---

## 3. Full clip census (2026-07-24)

Read directly from each GLB's glTF JSON chunk (pure-stdlib parser, no Blender).

| Pack | Files | Clips |
|---|---|---|
| `anim/` (UAL1 120, UAL1_RM 120, UAL2 134, UAL2_RM 134, Mannequin_F 0) | 5 | 508 |
| `kevin/` | 12 | 1,307 |
| `msrig/` | 18 | 1,399 |
| `mixamo/` (ual_loco 8, + 3 one-offs) | 4 | 11 |
| `dancegen/` | 10 | 11 |
| `anim-combined/` | 1 | 1 |
| **GRAND TOTAL** | 50 | **3,237** |

Per-file Kevin breakdown (male mirrors female): `combat` 286, `movement` 157, `work` 72,
`social` 68, `misc` 55, `idles` 15–16. Most Kevin clips are irrelevant to this game —
`Rifle_Aim*`, `ThrowGrenade*`, `ThrowBoomerang*`, `Bow*`, `Casting*`/magic.

---

## 4. What the game actually implements (~90–100 clips)

Traced through `PlayerController.SetupAnimations()`
(`ariki-game/src/Viewer/PlayerController.cs:779`) — the authoritative clip→game-key
mapping — plus the dance system's `ClipCatalog` auto-discovery of `dancegen/`.

**Only 9 pack files are loaded at all. Of ~3,237 clips on disk, ~90–100 are wired.**

| Pack (loaded) | Clips wired | On disk | What's used |
|---|---|---|---|
| `anim/UAL1.glb` | ~41 | 120 | idle/walk/jog/sprint 8-dir, crouch 8-dir, jumps, turns, drink/sit, sword, interact |
| `anim/UAL2.glb` | ~30 | 134 | chop/mine/fish/farm/carry/eat/sleep, 8-dir walk, shield set, running jump, 180 turns |
| `kevin_*_movement.glb` | 10 | 157 | full directional swim set (loaded after UAL to override stock swim) |
| `kevin_*_combat.glb` | 3 | 286 | ThrowWeapon01_R, ThrowSpear02_R, ThrowBall01_R |
| `kevin_*_work.glb` | 1 | 72 | skin (SkinningGround01_R_Loop) |
| `kevin_*_social.glb` | 1 | 68 | pray (Reverence01_Loop) |
| `anim-combined/Run_Punch.glb` | 1 | 1 | run_punch composite |
| `mixamo/` (3 files) | 3 | 11 | walking, run_to_dive, northern_soul (→ dance_soul) |
| `dancegen/` | ~10 | 11 | war/fertility/taming dances + `_pp` loops, nd_01 + `_pp`, canoe clips |

**Packs with ZERO clips implemented:** all of `msrig/` (1,399, superseded), `kevin_*_idles`
and `kevin_*_misc` (0 wired), the `_RM` root-motion UAL twins (never loaded — game loads
non-RM only), `mixamo/ual_loco.glb`.

**Takeaway:** ~97% of on-disk clips are unused vendor-library bulk buried inside purchased
multi-clip GLBs. The implemented ~90 are what map cleanly to a naming system and are worth
physically renaming; the rest are candidates you *could* pull from later.

### Sample of implemented clip → game-key mapping (UAL, from SetupAnimations)

UAL1 clip → key: `Idle_Loop→idle`, `Walk_Loop→walk`, `Jog_Fwd_Loop→run`,
`Sprint_Loop→sprint`, `Dance_Loop→dance/dance2/dance3` (one source, 3 keys),
`Sword_Attack→weapon_attack`, `Fixing_Kneeling→hammer`, `Spell_Simple_Shoot→throw`,
`GroundSit_Idle_Loop→sit`, 8-dir jog/crouch, `Turn90_L/R`.
UAL2 clip → key: `TreeChopping_Loop→chop`, `Mining_Loop→mine`, `Fish_Cast_Idle_Loop→fish`,
`Farm_Harvest→gathering`, `Farm_PlantSeed→farm`, `Consume→eat`, `IdleToLay→sleep`,
`Walk_*_Loop→walk_*` (8-dir), shield set, `NinjaJump_*→running_jump_*`.

Kevin gap clips (game-key = same or mapped): swim set `Swim01_*→swim*` / `SwimIdle01→swim_idle`,
`SkinningGround01_R_Loop→skin`, `Reverence01_Loop→pray`, three throw clips kept as-is.

---

## 5. Kevin-removal forensics (what Ozan removed)

During Ozan's recent animation work (2026-07-22/23), two relevant removals in **ariki-game**:

### 5a. Loose Kevin + Synty FBXs deleted — commit `f5ee3a7d0` (2026-07-22)
> `chore(anims): drop unused Unity/Synty FBXs and dead import-time retarget`

Deleted animation FBXs (each with its `.import` sidecar):
- **Kevin** (`assets/animations/kevin/`): `Archer@CombatIdle01/02`, `Archer@Death01/02`,
  `Archer@Idle01/02`, `Archer@Run01`, `Archer@TakeDamage01`, `Throwing@BigAxe`,
  `Villager@Gathering01/02/03`, `Villager@Skinning01` — **13 clips**
- **Synty BasicMotions** (`assets/animations/basic-motions/`): `@Idle01`, `@Run01`,
  `@Sprint01`, `@Walk01` — 4 clips
- Also dropped: Unity-format UAL/mannequin/base-character FBX exports (the Godot pipeline
  uses the Godot/GLB exports, so these were redundant format duplicates).

**Important nuance:** these were the *loose per-clip FBX* form of Kevin content. The Kevin
**category GLB packs** (`assets/quaternius/kevin/kevin_*_*.glb`, 1,307 clips) survive and
still contain equivalent content — e.g. the deleted `Villager@Skinning01` corresponds to
`SkinningGround01_R_Loop` still present in `kevin_*_work.glb` (and still wired as `skin`).
So most of these are **superseded**, not truly lost. Each needs a clip-level cross-check in
Phase 1 to classify **truly gone** vs **still available in a pack / covered by a UAL clip**
(e.g. `Villager@Gathering` ↔ UAL2 `Farm_Harvest`; Archer combat ↔ `kevin_*_combat.glb`).

### 5b. UAL Standard packs removed — commit `2292174dc` (2026-07-23)
> `feat(anims+character): canonicalize UAL packs under anim/, land QuatSkin body work + tool kit`

Removed the older UAL **Standard** clip GLBs (`UAL1_Standard.glb`, `UAL2_Standard.glb`, etc.)
in favor of **UAL1 Pro (120 clips)** + **UAL2 Source (134 clips)** under `anim/`. This is a
supersession/upgrade, not a loss — the Pro/Source packs are complete supersets. (Stale
`UAL*_Standard.glb` copies still linger inside `msrig/`.)

### 5c. Animation-repo archive
Retired dance takes are already tracked in `.agents/wiki/dances/REGISTRY.md` and physically in
`animation/archive/` (`alohaOG`, `firedance1`, `hakaOG`, `hakadance2`, `haka_mocap`) —
never deleted.

**Git authors for context:** Ozan Bozkurt is by far the dominant author of animation commits;
"Kevin" refers to the Kevin Iglesias vendor animation packs, not a team member.

---

## 6. Open scope decisions (BLOCKING — need Jeremy)

The §3/§4 findings changed the picture after the "rename everything" decision was made,
so these need an explicit call before any renaming:

1. **Rename scope.** Given ~90 clips are implemented and ~3,000+ are unused vendor bulk:
   - **(A, recommended)** Physically rename only the ~90 implemented clips + all our
     authored content; catalogue everything else in the registry with a canonical ID +
     old-name mapping but leave vendor names in the GLBs. Keeps the vendor re-download/upgrade
     path clean.
   - **(B)** Rename the whole functional set the game might ever wire (few hundred), leaving
     only clearly-irrelevant vendor clips (rifles, magic) untouched.
   - **(C)** Literally rename all 3,237 — max consistency, breaks vendor upgrade path, huge
     effort for near-zero value on unused clips.

2. **msrig/ (1,399 stale clips).** Recommended: archive it (never delete), mark superseded in
   the registry, don't rename — but confirm with Ozan first since code still has `msrig`
   fallback paths (`PlayerController.cs`, test beds). Alternatives: catalogue-in-place, or
   rename-too.

---

## 7. Key technical constraints (for the rename phase)

- **One skeleton:** Quaternius 65-bone UE-named rig. Renaming a clip name inside a GLB is
  **metadata-only** and safe for the rig. The risk is entirely in *references*.
- **Reference sites to migrate** (ariki-game): `PlayerController.SetupAnimations()` (the
  clip→game-key arrays — #1 silent-failure spot), `PlayerAnimGraphBuilder.cs`,
  `CharacterAnimDriver.Resolve()` (already has alias fallback — useful during migration),
  `ToolActionResolver.cs`, `ThrowActionCatalog.cs`, `AnimationClipProfile.cs` +
  `data/animation-clip-profile.json`, `ClipCatalog.cs` (dance bed, discovers packs by
  basename), `assets/dances/*.json`, docs.
- **Multi-clip GLBs:** `rename_clip.py` assumes one action per armature; UAL/Kevin packs have
  many. The batch rename tool must handle multi-action GLBs.
- **Godot sidecars:** after any asset rename, regenerate `.import` via `bash tools/game.sh import`.
- **Vendor originals** are archived unmodified in `tinqs/ariki-assets`; renames must be applied
  by a **re-runnable rename-map script** so a future pack update re-canonicalizes in one pass.
- **Existing gates to reuse:** `tools/rig_pose_gate.py` (rest-pose delta vs UAL1 ref),
  `ariki-game/tools/anim_qc.py` (post-ingest seam/stutter), animation-repo `tools/loop_qc.py`
  (pre-commit loop gate), locomotion + dance test beds (launch only after asking Jeremy).
- **Repo etiquette:** `tinqs push` / `tinqs pull` (raw git pull hangs on LFS), explicit-path
  staging, report commit hashes, archive-never-delete, clip numbers never reused.

---

## 8. Existing naming precedent (to generalize)

From `animation/.agents/wiki/dances/REGISTRY.md` (currently dances + boat only):
- **snake_case** matching the game's item-id convention (e.g. `war_dance_01`); clip name baked
  in GLB is **PascalCase** (`WarDance01`).
- **Provisional stage:** new takes get `nd_##` (never a content name), renamed to a dance code
  only when Jeremy adopts them for a ceremony.
- **Loop-pair rule:** every adopted dance ships base + ping-pong `_pp` variant, must pass
  `loop_qc.py`.
- **Suffixes seen in use:** `_loop`, `_idle`, `_pp`, directional (`_fwd/_bwd/_l/_r`), `_rm`.
- **Archive, never delete; numbers never reused.**

Game-side keys already in use (lowercase snake_case): `idle`, `walk`, `run`, `sprint`, `swim`,
`swim_idle`, `chop`, `mine`, `fish`, `gathering`, `farm`, `skin`, `pray`, `crouch_*`, `turn90_l`,
etc. The new naming system should reconcile the canonical clip IDs with these existing game keys.

---

## 9. Next steps

1. **Resolve §6 scope decisions** (blocking).
2. Phase 0 — draft `docs/animations/NAMING.md` (naming spec) + Jeremy approval gate.
3. Phase 1 — full clip inventory JSON + `docs/animations/REMOVALS.md` (clip-level removal
   cross-check).
4. Phase 2 — `docs/animations/registry.yaml` + render/check tools.
5. Phase 3 — staged, gated rename execution.
6. Phase 4 — documentation + maintenance protocol.

Full plan: `~/.claude/plans/i-want-to-audit-enchanted-squid.md`.