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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(animations): document the dedicated bow motion across guides
nirholase3dd0e7043da
diff --git a/docs/animations.md b/docs/animations.mdindex 9d52824f4..6007fa2e0 100644--- a/docs/animations.md+++ b/docs/animations.md@@ -67,7 +67,7 @@ Every slot below is previewable on a live avatar at [three.ws/gestures](https://| `think` | `think` | || `celebrate` | `celebrate` | || `concern` | `defeated` | |-| `bow` | `sitclap` | **Approximation.** No bow clip is baked; `sitclap` reads as gratitude. The one slot whose clip does not mean what the slot means |+| `bow` | `bow` | Dedicated project-authored, anchored 1.8-second bow generated by `scripts/build-original-animations.mjs` || `point` | `point` | || `shrug` | `shrug` | || `fidget` | `av-listening-music` | Clean anchored restless loop. Was the never-baked `Fidget` (fixed 2026-07-08), then `av-waiting`, whose loop seam measures open in `signatures.json` and snapped every cycle |@@ -135,11 +135,25 @@ Its measured companion is `public/animations/signatures.json`: a motion-signatur- **Deep links**: `?clip=<id>` opens a clip's detail modal directly; `q`, `cat`, `filter`, and `sort` round-trip through the URL so filtered views are shareable. Every one of them is validated against the values the controls can represent, so a hand-edited `?sort=bogus` falls back to `featured` rather than blanking the sort menu, and an arriving `?filter=once` presses the matching segmented button instead of filtering invisibly.- **Detail modal**: a real dialog. Focus moves into it on open, Tab wraps inside it, Escape closes it and returns focus to the card that opened it. Arrow keys step through the filtered list (except while a slider is focused, which owns its own arrows), and Space toggles playback. The transport row only appears once a clip is actually on the stage, so a preview that fails to load shows the error and its Studio link rather than controls that do nothing.-## Known issues--- **`bow` is an approximation.** No bow clip is baked, so the slot resolves to `sitclap`, which reads as gratitude/applause rather than a bow. Tracked in `public/animations/registry.json` under `known_issues` (`bow-slot-approximation`), with the Mixamo source to add.--Resolved (see `public/animations/registry.json` under `resolved_issues`): the `wave`, `nod`, `point`, `think`, and `shrug` slots each play their own dedicated clip instead of a borrowed `reaction`/`pray`/`defeated` stand-in (2026-07-30); the skill hints `gesture`, `inspect`, `present`, `sign`, `curiosity`, and `patience` all resolve to real slots via `resolveHint()` instead of silently no-oping (2026-07-30); the `fidget` slot no longer points at the never-baked `Fidget` clip (2026-07-08, later moved to `av-listening-music` when `signatures.json` measured `av-waiting`'s loop seam open); and the 6 formerly-orphaned source FBX (`Cover To Stand`, `Goalkeeper Scoop`, `Jumping Down` ×3, `Removing Driver`) are entries in `scripts/animations.config.json` and built into the manifest.+## Resolved issues++See `public/animations/registry.json` under `resolved_issues` for the durable+history. The `bow` slot now plays its own project-authored clip instead of the+semantically incorrect `sitclap` approximation ([#113](https://github.com/nirholas/three.ws/issues/113),+2026-09-15). The reproducible generator is+`scripts/build-original-animations.mjs`; visual QA confirmed a grounded bow and+100% canonical-track coverage on the reference avatar.++Earlier fixes: the `wave`, `nod`, `point`, `think`, and `shrug` slots each play+their own dedicated clip instead of a borrowed `reaction`/`pray`/`defeated`+stand-in (2026-07-30); the skill hints `gesture`, `inspect`, `present`, `sign`,+`curiosity`, and `patience` all resolve to real slots via `resolveHint()` instead+of silently no-oping (2026-07-30); the `fidget` slot no longer points at the+never-baked `Fidget` clip (2026-07-08, later moved to `av-listening-music` when+`signatures.json` measured `av-waiting`'s loop seam open); and the 6+formerly-orphaned source FBX (`Cover To Stand`, `Goalkeeper Scoop`, `Jumping+Down` ×3, `Removing Driver`) are entries in `scripts/animations.config.json`+and built into the manifest.## Relateddiff --git a/docs/tutorials/animate-your-agent.md b/docs/tutorials/animate-your-agent.mdindex 4c4b99597..fcf1260bd 100644--- a/docs/tutorials/animate-your-agent.md+++ b/docs/tutorials/animate-your-agent.md@@ -44,7 +44,7 @@ Open **[three.ws/gestures](https://three.ws/gestures)**.Every slot an agent can play is on that page, on a card with the clip it resolves to. Click one and it plays on a live avatar. Three things are worth noticing before you build anything:- **`inspect` plays `lookdown`.** Nineteen skills declare that hint, every read-only lookup in the catalog. It is the gesture your agent will spend the most time in.-- **`bow` plays `sitclap`.** The one approximation in the vocabulary, marked `approx` on its card: no bow clip is baked yet, so it borrows a seated clap. Everything else plays a clip that means what the slot means.+- **`bow` plays `bow`.** It is a dedicated, grounded one-shot generated from project-authored keyframes, so the gesture no longer borrows a seated clap.- **The hint table underneath is generated from the shipped skills**, so the skill names next to each hint are the real ones, not an illustration.Deep-link any slot to show someone: [three.ws/gestures?slot=celebrate](https://three.ws/gestures?slot=celebrate).@@ -168,6 +168,6 @@ The difference that matters is the layer. `wave`, `point`, `nod` and `shrug` are## Where to go next- **[three.ws/gestures](https://three.ws/gestures)** is the reference you will come back to: every slot, its clip, and the skills that fire it.-- **[Animation Studio](/pose)** if none of the 112 clips is the motion you want. Pose an avatar with FK/IK, keyframe a timeline, export the clip, and point a slot at it.+- **[Animation Studio](/pose)** if none of the 113 clips is the motion you want. Pose an avatar with FK/IK, keyframe a timeline, export the clip, and point a slot at it.- **[docs/animations](/docs/animations)** for the developer reference: the clip pipeline, how to bake a new clip from an FBX, and how the slot and hint tables are held to the manifest by tests.- **[The club stage](/club)** for what happens when a dance becomes a product: agents pay $0.001 USDC per performance, and the style they book is one of the same clips.diff --git a/docs/tutorials/animate-your-avatar.md b/docs/tutorials/animate-your-avatar.mdindex 059373d69..5b227fe71 100644--- a/docs/tutorials/animate-your-avatar.md+++ b/docs/tutorials/animate-your-avatar.md@@ -173,7 +173,7 @@ This is the remix loop: find a motion someone else published, open it in the StuApplying clips in the Studio is the **authoring** side. On a *running* agent, the same library drives emotion and gesture automatically through two channels that share one emotional state, the avatar's **Empathy Layer** ([src/agent-avatar.js](../../src/agent-avatar.js)):-**Gesture slots** ([src/runtime/animation-slots.js](../../src/runtime/animation-slots.js)), a fixed vocabulary the agent plays in conversation. The conversational slots are `idle`, `wave`, `nod`, `shake`, `think`, `celebrate`, `concern`, `bow`, `point`, `shrug`, `fidget`, `dance`; a second group exists because skills emit the matching hint: `inspect`, `present`, `sign`, `curiosity`, `patience`, `manipulate`, `conjure`. Each slot resolves to a concrete library clip at runtime through `DEFAULT_ANIMATION_MAP`, most map to the clip of the same name (`celebrate` → `celebrate`, `think` → `think`), and a few borrow the closest baked motion where no dedicated clip exists yet (`concern` → `defeated`, `bow` → `sitclap`, `dance` → `rumba`). An agent picks a slot when the moment calls for it; the clip retargets onto that agent's avatar exactly as in the Studio. You can override any slot per agent via `meta.edits.animations`, point `wave` at a different clip, or map a slot to a motion you authored yourself.+**Gesture slots** ([src/runtime/animation-slots.js](../../src/runtime/animation-slots.js)), a fixed vocabulary the agent plays in conversation. The conversational slots are `idle`, `wave`, `nod`, `shake`, `think`, `celebrate`, `concern`, `bow`, `point`, `shrug`, `fidget`, `dance`; a second group exists because skills emit the matching hint: `inspect`, `present`, `sign`, `curiosity`, `patience`, `manipulate`, `conjure`. Each slot resolves to a concrete library clip at runtime through `DEFAULT_ANIMATION_MAP`; most map to the clip of the same name (`celebrate` → `celebrate`, `think` → `think`, `bow` → `bow`), while a few deliberately use the closest established motion (`concern` → `defeated`, `dance` → `rumba`). An agent picks a slot when the moment calls for it; the clip retargets onto that agent's avatar exactly as in the Studio. You can override any slot per agent via `meta.edits.animations`, point `wave` at a different clip, or map a slot to a motion you authored yourself.**Facial expression** ([src/runtime/arkit52.js](../../src/runtime/arkit52.js)), driven from the same blend of morph targets as the gesture layer, not a separate track. If your avatar carries ARKit-52 blendshapes (most modern avatar-platform exports do, as do VRoid models), the runtime resolves those morph targets and drives expression and lip-sync directly on the face. A skeletal clip plays the body; the blendshape layer plays the eyes, brows, and mouth on top.diff --git a/docs/tutorials/character-library-to-embed.md b/docs/tutorials/character-library-to-embed.mdindex 02d5049fa..80c4b6c9f 100644--- a/docs/tutorials/character-library-to-embed.md+++ b/docs/tutorials/character-library-to-embed.md@@ -156,7 +156,7 @@ Open that. Orbit around it. Check the silhouette at the size your page will actuThis is the step people skip, and it is the one that makes the whole thing work.-The manifest said `"animations": 1`. That number counts clips baked into the GLB file, and it is nearly always 1 for every character in the library. It says nothing about what the character can play, because **the animations do not come from the file.** three.ws holds a canonical clip library (112 clips: idle, walk, run, wave, dance, cheer, and the rest) and retargets them onto any humanoid skeleton at runtime. There is no per-character allowlist. Any character in the library plays any clip.+The manifest said `"animations": 1`. That number counts clips baked into the GLB file, and it is nearly always 1 for every character in the library. It says nothing about what the character can play, because **the animations do not come from the file.** three.ws holds a canonical clip library (113 clips: idle, walk, run, wave, bow, dance, cheer, and the rest) and retargets them onto any humanoid skeleton at runtime. There is no per-character allowlist. Any character in the library plays any clip.You can prove that in one request, without a browser, by asking the server to pose the character:@@ -394,7 +394,7 @@ The methods worth knowing for a decorative embed:| `el.pause()` / `el.resume()` | Stop and restart the render loop. Useful when your own code knows the element is hidden. || `el.lookAt('user')` | Point the head at the camera. |-`playClip` is the one to reach for. The reason it exists is that `loop` is a property of the clip, not of your intent, and a host page should not have to keep a table of which of the 112 clips loop.+`playClip` is the one to reach for. The reason it exists is that `loop` is a property of the clip, not of your intent, and a host page should not have to keep a table of which of the 113 clips loop.Because events are dispatched with `composed: true`, they cross the shadow DOM boundary and bubble, so you can also listen on a container instead of the element:diff --git a/public/animations/manifest.json b/public/animations/manifest.jsonindex c1c668113..86560f0cd 100644--- a/public/animations/manifest.json+++ b/public/animations/manifest.json@@ -893,5 +893,14 @@"icon": "🪑","loop": true,"duration": 1+ },+ {+ "name": "bow",+ "url": "/animations/clips/bow.json",+ "label": "Bow",+ "icon": "🙇",+ "loop": false,+ "category": "gesture",+ "duration": 1.8}]diff --git a/public/animations/registry.json b/public/animations/registry.jsonindex b310313e9..a1dc29856 100644--- a/public/animations/registry.json+++ b/public/animations/registry.json@@ -283,15 +283,15 @@}},- "known_issues": [+ "known_issues": [],++ "resolved_issues": [{"id": "bow-slot-approximation",- "description": "The 'bow' slot has no dedicated clip: it resolves to 'sitclap' (Sitting Clap), which reads as gratitude/applause rather than a bow. Every other slot now plays a clip that means what the slot means. Fix: add Mixamo 'Bowing' (In Place, Without Skin) to animation-sources/, register it in scripts/animations.config.json as 'bow', run npm run build:animations, then point DEFAULT_ANIMATION_MAP.bow at it. tests/animation-slots.test.js already asserts the target exists, so the swap is a one-line change once the clip is baked.",+ "resolved": "2026-09-15",+ "description": "GitHub issue #113 is resolved: the 'bow' slot now plays a dedicated 1.8-second, project-authored bow instead of Sitting Clap. scripts/build-original-animations.mjs deterministically generates the clip from the cleared canonical idle pose; the committed motion is torso-led, anchored, non-looping, and visually verified on the CZ avatar at 100% canonical-track coverage.","affected_file": "src/runtime/animation-slots.js"- }- ],-- "resolved_issues": [+ },{"id": "unused-agent-hint-targets","resolved": "2026-07-30",diff --git a/tests/animation-registry.test.js b/tests/animation-registry.test.jsindex a86ef2c9f..1990f66c5 100644--- a/tests/animation-registry.test.js+++ b/tests/animation-registry.test.js@@ -1,7 +1,7 @@/*** public/animations/registry.json is the developer-facing catalogue of every* animation asset, and its own header tells the reader to consult it first.- * A registry that has drifted is worse than none: it drifted to 37 of 112 built+ * A registry that has drifted is worse than none: it once drifted to 37 built* clips, with `source_fbx` paths pointing into a directory that has held no FBX* since the sources moved to animation-sources/, and `agent_slots` recording* slot assignments that had moved to other clips.