animation/AGENTS.md

AGENTS.md — animation repo

Guidance for AI agents working in local.repo/animation. This repo is Jeremy's animation-pipeline hub and the Mac↔PC bridge that carries iClone exports into ariki-game. iClone 8 + Video Mocap live on the PC; Blender 5, the retarget tools, and the game repo live on both machines.

Deeper knowledge lives in the repo skills (.claude/skills/): use animation for the operator's playbook and hard-won lessons, animation-creation for authoring new clips, iclone-video-mocap for iClone-side "how do I X", and pose-estimation for video→pose extraction. docs/dances/REGISTRY.md is the source of truth for clip names. This file is the fast orientation; the skills and registry are authoritative.

The batch workflow ("process the incoming animations")

1. Pull first — tinqs pull (raw git pull hangs on LFS in tinqs.com repos). Incoming FBX + textures + JSON land in exchange/incoming-fbx/.
2. Retarget each FBX → GLB in exchange/converted-glb/ (command below). Every dance ships as a pair: also bake its loop variant with tools/pingpong_bake.py → exchange/pingpong-glb/<id>_pp.glb (clip <Clip>PP).
3. Commit + push the GLBs in this repo with tinqs push (self-heals auth, uploads LFS direct-to-S3). Report the commit hash.
4. Copy GLBs into ariki-game assets/quaternius/dancegen/, write one dance JSON per clip in ariki-game/assets/dances/.
5. Loop QC gate — run loop_qc.py on each GLB; flag anything not smooth before it ships.
6. Import so Godot generates sidecars: bash tools/game.sh import (ariki root).
7. Verify clip names, then commit in ariki-game.
8. Launch the test bed only after asking Jeremy.
9. Leave exchange/ cleanup until Jeremy confirms the batch looks right in-game.

Canonical retarget command

/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/cc_retarget.py -- \
  --src exchange/incoming-fbx/<take>.fbx \
  --out exchange/converted-glb/<pack>.glb --name <ClipName> \
  --target "/Users/jeremykashkett/Tinqs/local.repo/ariki-game/assets/quaternius/base-characters/Universal Base Characters[Standard]/Base Characters/Godot - UE/Superhero_Male_FullBody.gltf"

Blender is 5.1.2. --target is required when running from this repo (the tool's default target path is ariki-relative and won't resolve here). Other retargeters: mixamo_retarget.py (Mixamo), kevin_retarget.py (Kevin Iglesias B-* rig, hardcoded target), mocap_retarget.py (MediaPipe pose JSON).

Naming (see docs/dances/REGISTRY.md)

Lowercase snake_case, matching the game's item-id convention. New takes get a provisional nd_## id, never a content name — pack nd_08, clip ND08, JSON nd_08.json, variants nd_08_pp / ND08PP. Only when Jeremy adopts a take for a ceremony is it renamed to its dance code (snake_case of the sim's DanceType enum + index, e.g. war_dance_01 / WarDance01). Never guess the ceremony — Jeremy assigns it. Rename via tools/rename_clip.py + JSON + registry update. Rejected takes are archived, never deleted; numbers are never reused. Update the registry row on every convert/adopt/archive.

• Pack name = GLB basename (lowercase); clip name = --name baked into the GLB.
• Clip ref in JSON = <pack>/<ClipName> (e.g. nd08/ND08).
• ClipCatalog auto-discovers anything in dancegen/ (also kevin/, mixamo/) — no code change needed.

Loop QC

The game loops with Godot LoopMode.Linear (last keyframe → frame 0). A clip only looks right if pose, motion velocity, and root position are continuous across the seam — raw takes rarely are. QC every clip:

/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/loop_qc.py -- \
  --src exchange/converted-glb/<pack>.glb   # exit 0 = SMOOTH, 1 = NOT SMOOTH, 2 = error

Fixers (no iClone round-trip): tools/loop_fix.py (de-drift + trim + seam blend → exchange/looped-glb/) and tools/pingpong_bake.py (palindrome bake, seam-perfect but motion reverses at the turn — prefer for sway-heavy dances). Re-run loop_qc.py to confirm exit 0. Or use the loop-qc agent.

Gotchas that have actually bitten

• 2-frame _TempMotion FBX = no motion. The tool rejects by frame count, not name; that's the guard working. Re-export from iClone with Include/Export Motion.
• A-pose arms. CC/iClone bind in A-pose. Eyeball arm orientation in the test bed on the first clip of any new source; re-export with Use T-Pose As Bind Pose if wrong.
• Verify GLB animations[].name == JSON clip ref before shipping — a mismatch is a silent no-play.
• Commit the .glb.import sidecar with the GLB (Godot embeds uid:// there; no separate .uid). GLB + .import + JSON go together.
• game.sh import warnings are pre-existing noise — only errors matter.
• Green verify ≠ correct. An agent-authored gate once passed an upside-down boat export. Always render and eyeball a new visual asset before shipping.

Repo etiquette

• Don't touch unrelated uncommitted work. ariki-game often has in-flight files; stage only this batch's files by explicit path, never git add -A.
• Use tinqs push / tinqs pull, not raw git — this repo uses Git LFS for .fbx/.glb/.mp4/.task. Report the commit hash after pushing.
• Commit co-author line: Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>.
• ariki-game commits stay local until Jeremy asks to push — pushing the game repo is not part of the bridge steps.
• Ask before launching the game. SCENE=dance_test_bed bash tools/game.sh spawn (from ariki root); animation_showcase pages every clip. Never use *RM / *RootMotion variants — everything is in-place. If you pipe spawn through tail, the log stays 0 bytes until exit — confirm via the lease file + pgrep, don't assume it failed.

Layout

• .claude/skills/ — repo skills (see intro); .claude/agents/loop-qc.md.
• tools/ — Blender-headless retargeters, loop tools, prop export, rename_clip.py.
• exchange/ — files in flight: incoming-fbx/, converted-glb/, looped-glb/, pingpong-glb/, outgoing-props/, reference-video/, INBOX/.
• docs/ — dances/REGISTRY.md, iclone-bridge.md.
• plans/ — pipeline design docs. archive/ — retired takes. devops-reports/.