tinqs/animation
5
0
Fork 0
Code Pull Requests Actions Packages Projects Releases Wiki Activity Issues
Files
main
animation/.agents/wiki/ARCHITECTURE.md
T
jeremy 854dbb5ce4 chore(agents): migrate to agents.md protocol — .agents/ wiki/plans/rules/skills 
Root AGENTS.md is now a thin entry point + knowledge map; the batch-workflow
detail it duplicated already lived in .claude/skills/animation/SKILL.md.
Folded docs/ (dances registry + iclone-bridge stub), root plans/, and
devops-reports/ into .agents/wiki/ and .agents/plans/ per the per-repo .agents/
convention. Added .agents/SOUL.md, .agents/AGENTS.md, wiki/ARCHITECTURE.md,
wiki/architecture/, and wiki/master-plan.md (derived from the closed plans +
the dance registry's live ceremony-slot table). Fixed doc-path references in
exchange/GUIDE.md, the animation skill, and the iclone-bridge stub. All moves
via mv (git detected as renames) — no content deleted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-24 15:02:47 -07:00

4.5 KiB
Raw Permalink Blame History

Architecture — animation pipeline

Entry point to architecture law for this repo. Per-system detail lives in .agents/wiki/architecture/.

The one-sentence shape

PC-side motion capture (iClone 8 + Video Mocap) → this repo (Mac↔PC bridge, Blender-headless retargeting, loop QC) → ariki-game (Quaternius-rig GLB consumption via ClipCatalog).

Machines and where things live

Machine Owns
PC (Windows) iClone 8 + Video Mocap plugin — authors motion, exports FBX
Mac (and PC) Blender 5.1.2, this repo's retarget tools, ariki-game checkout

Files move machine-to-machine only through exchange/ in this repo, synced with tinqs push/tinqs pull (Git LFS for .fbx/.glb/.mp4/.task — see .gitattributes). Raw git pull hangs on LFS in tinqs.com repos.

Pipeline stages

  1. Capture (PC) — iClone export, Blender preset, Range=All, Preserve Bone Names ON → exchange/incoming-fbx/.
  2. Retarget (either machine) — Blender-headless, source-specific retargeter in tools/, all bake onto the shared Quaternius rig and export a mesh-stripped GLB with one NLA track per clip:
    • cc_retarget.py — Reallusion CC/iClone CC_Base_* FBX (60fps; rejects 2-frame _TempMotion exports as a guard against motion-less takes)
    • mixamo_retarget.py — Mixamo FBX (prefix auto-detect)
    • kevin_retarget.py — Kevin Iglesias Unity FBX (B-* rig; hardcoded target path, non-portable)
    • mocap_retarget.py — MediaPipe pose JSON → GLB (rotation solving, no source armature) → exchange/converted-glb/.
  3. Loop QC — tools/loop_qc.py (pre-commit gate: pose/velocity/root-drift continuity across the seam, exit 0 = smooth). Fixers when it fails: 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 → exchange/pingpong-glb/, clip suffix PP). Every adopted dance ships as a base clip + _pp pair.
  4. Ship — commit + tinqs push the GLBs in this repo, then copy into ariki-game/assets/quaternius/dancegen/ (auto-discovered by ClipCatalog as <pack>/<ClipName> — also watches kevin/, mixamo/), write one dance JSON per clip in ariki-game/assets/dances/, game.sh import, verify clip names match GLB animations[].name exactly, commit in ariki-game (push only when Jeremy asks).
  5. Post-ingest QC (game side, out of this repo) — ariki-game/tools/anim_qc.py re-checks world-space seam continuity + renders a seam-cross video for eye review. Two QC tools by design: this repo's gate is pre-commit/local-space, the game's is post-ingest/world-space.

Naming law

Full detail: .agents/wiki/dances/REGISTRY.md (source of truth — do not duplicate its content elsewhere). Summary: new takes get a provisional nd_## id (never a content-derived name); a take is renamed to its ceremony code (snake_case of the sim's DanceType enum + index) only once Jeremy assigns it to a specific ceremony, via tools/rename_clip.py. Rejected/superseded takes are archived (archive/), never deleted; numbers are never reused.

Canonical target rig

All retargeters bake onto ariki-game's assets/quaternius/base-characters/.../Godot - UE/Superhero_Male_FullBody.gltf. Run from this repo, --target must be passed explicitly (the tool's default path is ariki-relative and won't resolve here). The rig/pack standard itself (65-bone Quaternius UE-named skeleton, hero body Ariki_Female_QuatSkin.glb) is governed by ariki-game/.humans/animation-bone-sources.html and ariki-game/.agents/wiki/quaternius-ual-packs.md — this repo's iClone/mocap lane is explicitly a separate clip source (not UAL1/UAL2/Kevin/Mixamo), landing in dancegen/ only.

Tool provenance / mirroring

tools/cc_retarget.py, mixamo_retarget.py, kevin_retarget.py, mocap_retarget.py are mirrors of ariki-game/tools/ — the game copies are authoritative; re-copy from ariki-game when they change (they have silently diverged before). .claude/skills/ here mirror a subset of ariki-game/.claude/skills/ plus ~/.claude/skills/pose-estimation — see README.md Provenance section.

See also

  • .agents/wiki/architecture/ — per-system detail (currently: this file covers the whole pipeline; split out if a subsystem grows its own doc).
  • .agents/wiki/dances/REGISTRY.md — naming/registry source of truth.
  • .agents/wiki/iclone-bridge.md — PC-lane routing stub.
  • .agents/wiki/devops-reports/ — point-in-time audits and convergence reports.
Reference in New Issue View Git Blame Copy Permalink