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.
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):
- It reads
scripts/animations.config.jsonand resolves each entry'ssourcefile, looking inanimation-sources/first, thenpublic/animations/(GLB sources that are also served at runtime live there instead). - Each source clip is retargeted onto the canonical Avaturn reference rig
(
public/avatars/cz.glb):mixamorigprefixes 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. - The retargeted clip is serialized as three.js
AnimationClipJSON intopublic/animations/clips/<name>.json(5 to 10 times smaller than a GLB, loaded at runtime withAnimationClip.parse, no loaders or retargeting in the browser), andpublic/animations/manifest.jsonis rewritten. - 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
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.Add an entry to
scripts/animations.config.json:{ "name": "av-my-anim", "source": "My Anim.fbx", "label": "My Anim", "icon": "🎬", "loop": true }namebecomes the clip's runtime id (av-<kebab-case>for new Avaturn-retargeted clips). Addtrim,uprightFix, orrecenterHipsonly if the built clip is overlong, on its back, or off its mark.Run
npm run build:animationsand 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.Catalogue the clip in
public/animations/registry.jsonunder theclipscollection.Optional: wire an agent slot in
src/runtime/animation-slots.jsso agents play it automatically, and re-runnode scripts/build-animation-thumbnails.mjsso the/animationsgallery 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
- docs/animations.md: collections, agent slots, config fields, known issues.
- docs/3d-asset-pipeline.md: how FBX, GLB, and clip JSON relate across the whole generate, rig, animate, export chain.
- docs/procedural-animation.md: the runtime layers (look-at, foot planting) that adjust these pre-baked clips each frame after the mixer runs.
- public/animations/README.md: the served side of this pipeline (built clips, manifest, registry).