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.