Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

8.1 KB
Raw Blame

animation-sources

Build-time motion source files (FBX and GLB) for the avatar animation pipeline. Everything in this directory except this README is gitignored on purpose: raw sources are multi-megabyte binaries that never ship, while the baked clips in public/animations/clips/ are the committed, deployed artifact. A fresh checkout of this repo therefore contains only this file, and the build handles that gracefully (see "Missing sources are normal" below).

Full pipeline reference: docs/animations.md and docs/3d-asset-pipeline.md. The runtime-facing counterpart of this README is public/animations/README.md.

What lives here

Files What they are How they got here
*.fbx with plain names (Idle.fbx, Capoeira.fbx, wheelbarrow walk.fbx, ...) Humanoid motion clips on the Mixamo skeleton (mixamorig-prefixed bones, centimeter-baked hip translation). The registry and build pipeline identify these as Mixamo clips. Placed by hand; each one is referenced by name from scripts/animations.config.json.
soldier-*.glb, michelle-samba-dance.glb, xbot-*.glb, robot-*.glb Single-animation GLBs split out of the three.js example models (Soldier, Michelle, Xbot, RobotExpressive). scripts/extract-glb-animations.mjs documents them as MIT/CC0-licensed public assets. Generated by npm run extract:animations, which downloads the example GLBs, writes one file per animation track here, and upserts matching config entries. Safe to delete; the script regenerates them.
mx-*.fbx (not always present) Mixamo motion clips downloaded for research/offline retargeting only. scripts/mixamo-all.mjs's upload phase is permanently disabled (see below), so these never publish to the live bulk library. Downloaded by npm run mixamo:download (scripts/mixamo-all.mjs, needs MIXAMO_TOKEN). Explicitly gitignored.
cc0/quaternius/, cc0/mesh2motion/ The bulk motion library's actual source: Quaternius's Universal Animation Library 2 and Mesh2Motion's human animation packs, both CC0 1.0. Downloaded by node scripts/cc0-animation-library.mjs --fetch (scripts/cc0-animation-library.mjs); enumerated into the committed scripts/cc0-library.config.json.
.cc0-library-clips/ Staging output for the baked bulk library, uploaded to R2 by npm run cc0-library:upload and served via GET /api/animations/library. Every entry carries its source pack name and license. Written by npm run cc0-library:build.
.library-thumbs/ Staging area for library poster thumbnails rendered by scripts/build-animation-thumbnails.mjs, uploaded alongside the clips. Written by the thumbnail script.

No license or provenance metadata is stored in this directory itself for the Mixamo/example-model rows; the statements above are limited to what the repo's scripts and registry record. The CC0 rows are the exception: provenance lives right in scripts/cc0-library.config.json (source_name, license, license_url per clip) because that file is committed and is the licensing record for everything the bulk library publishes. See the "Licensing" section of docs/animations.md for the full policy.

How sources become shipped clips

The curated runtime set is built by scripts/build-animations.mjs (npm run build:animations):

  1. It reads scripts/animations.config.json and resolves each entry's source file, looking in animation-sources/ first, then public/animations/ (GLB sources that are also served at runtime live there instead).
  2. Each source clip is retargeted onto the canonical Avaturn reference rig (public/avatars/cz.glb): mixamorig prefixes are stripped, tracks whose bones the reference rig lacks are dropped, and a clip matching fewer than 60% of its tracks is rejected. Hip translation units are detected from the data, not the file extension, so centimeter-baked sources are rescaled to meters and meter-authored round-trips are left alone. Per-entry flags (trim, uprightFix, recenterHips) correct sources with baked transforms; see the config-entry field table in docs/animations.md.
  3. The retargeted clip is serialized as three.js AnimationClip JSON into public/animations/clips/<name>.json (5 to 10 times smaller than a GLB, loaded at runtime with AnimationClip.parse, no loaders or retargeting in the browser), and public/animations/manifest.json is rewritten.
  4. Hand-authored clips with no source file here are merged into the manifest from scripts/animations-extra-clips.json.

The bulk library takes a parallel path through the same build script with staging overrides (--config, --out, --manifest, --url-prefix), baking clips to a staging directory and uploading the result to R2 rather than committing it. scripts/cc0-animation-library.mjs does this from the CC0 sources above and is the only script allowed to publish to the live bulk library. scripts/mixamo-all.mjs still has a --build phase for offline retargeting research against mx-*.fbx, but its upload phase refuses to run (Mixamo's license permits in-project playback, not redistributing raw clip files, which is what publishing to the public endpoint and its mirror script would do).

Missing sources are normal

Because the sources are gitignored, a configured clip whose source file is absent but whose baked JSON already exists in public/animations/clips/ is republished from the baked file and logged as PREBUILT. That is the standard path on a clean checkout, not an error. The build also carries a regression guard: it aborts rather than publish a manifest that would silently drop a clip that is still configured and was in the previous manifest. Retiring a clip is done by removing its config entry, never by deleting its source.

Adding a new motion source

  1. Drop the file here. FBX belongs in this directory (build-time input, never deployed); a GLB that should also be served raw at runtime goes in public/animations/ instead. The build resolves both.

  2. Add an entry to scripts/animations.config.json:

    { "name": "av-my-anim", "source": "My Anim.fbx", "label": "My Anim", "icon": "🎬", "loop": true }
    

    name becomes the clip's runtime id (av-<kebab-case> for new Avaturn-retargeted clips). Add trim, uprightFix, or recenterHips only if the built clip is overlong, on its back, or off its mark.

  3. Run npm run build:animations and check the log line for your clip: a healthy build reports the matched track count and output size; a sub-60% bone match means the source rig is not Mixamo-compatible.

  4. Catalogue the clip in public/animations/registry.json under the clips collection.

  5. Optional: wire an agent slot in src/runtime/animation-slots.js so agents play it automatically, and re-run node scripts/build-animation-thumbnails.mjs so the /animations gallery gets a poster still.

Keep the source file around locally until the baked JSON is committed; after that, the baked clip is self-sufficient.

Related