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.

docs(dissolve): add the Dissolve guide, source README, docs nav entry, sitemap page and structure row

nirholas64df7ba89e19
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 789257f12..221b9f7fb 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -208,6 +208,7 @@ bottom.
| Animation gallery | [pages/animations.html](pages/animations.html) + [src/animations-gallery.js](src/animations-gallery.js) | Live at `/animations` | 2,100+ clips with poster thumbnails ([scripts/build-animation-thumbnails.mjs](scripts/build-animation-thumbnails.mjs)), derived categories ([src/animation-categories.js](src/animation-categories.js)), shared live-preview engine ([src/animations-live-preview.js](src/animations-live-preview.js)) · see [docs/animations.md](docs/animations.md) |
| Gesture vocabulary | [pages/gestures.html](pages/gestures.html) + [src/gestures-page.js](src/gestures-page.js), slots [src/runtime/animation-slots.js](src/runtime/animation-slots.js) | Live at `/gestures` | The 19 gesture slots an agent plays, each previewed on a live avatar, with the skill hints that trigger it and a builder that saves a per-slot clip override straight onto an agent (`meta.edits.animations`). Hint table is generated from the shipped skill definitions by [scripts/build-agent-hints.mjs](scripts/build-agent-hints.mjs), so attribution cannot go stale · see [docs/animations.md](docs/animations.md) |
| Acoustic gesture control | [pages/sonar.html](pages/sonar.html) + [src/sonar-page.js](src/sonar-page.js), sensor [src/sonar/doppler.js](src/sonar/doppler.js), detectors [src/sonar/gestures.js](src/sonar/gestures.js), shared input chain [src/sonar/controller.js](src/sonar/controller.js), embed surface `<agent-3d sonar>` ([src/element.js](src/element.js) `startSonar()`) | Live at `/sonar` | Hand control for a 3D agent with no camera: the speakers emit an inaudible carrier and the microphone reads the Doppler shift of a hand off it, so a sweep steps through the gesture vocabulary, a push dollies the camera and a held lift turns it. The sensor picks a carrier by measuring every candidate against the machine's own hardware, because the frequency a laptop's speakers can actually project differs per model and an unprojectable one reads exactly like an empty room. Both modules are DOM-free and 3D-free, so any surface can consume them. Ported from [Sonar](https://github.com/nirholas/sonar.cool) (MIT), itself an implementation of SoundWave (CHI 2012) One controller serves both surfaces, so the mode arbitration and reverse handling exist once; the embed loads none of the sensing until a page calls `startSonar()`, and every gesture fires a cancelable `sonar-gesture` event a host page can take over · see [docs/sonar.md](docs/sonar.md), [docs/web-component.md](docs/web-component.md). Tests: [tests/sonar-gestures.test.js](tests/sonar-gestures.test.js), [tests/sonar-controller.test.js](tests/sonar-controller.test.js) |
+| GPU particle morphing | [pages/dissolve.html](pages/dissolve.html) + [src/dissolve/](src/dissolve/README.md) (page.js controller, engine.js GPGPU sim, sample-core.js surface sampling, shape.js GLB to colour cloud, audio.js, recorder.js, shelf.js) | Live at `/dissolve` | Dissolves any GLB into up to 1M GPU particles, morphs A to B over a shared Morton-ordered stage, bends them with black hole, vortex, shockwave and collapse forces, reacts to the mic, records clips and shares pairs by link. See [docs/dissolve.md](docs/dissolve.md). Tests: [tests/dissolve-core.test.js](tests/dissolve-core.test.js), [tests/dissolve-shelf.test.js](tests/dissolve-shelf.test.js) |
| Choreographer | [pages/choreograph.html](pages/choreograph.html) + [src/choreograph-page.js](src/choreograph-page.js), engine [src/runtime/choreography.js](src/runtime/choreography.js) | Live at `/choreograph` | Timeline for composing gesture slots into named, timed routines, previewed on the shared live-preview engine with crossfades and a scrubbable playhead. One dependency-free module defines the routine format, the URL wire format and the timing engine; the studio, `PUT /api/agents/:id/animations` (stored at `meta.choreographies`), the public manifest and `AgentAvatar.playChoreography` all import it, and `<agent-3d>.playRoutine('welcome')` performs one from any embed. Also published as `@three-ws/avatar/runtime/choreography.js` · see [docs/choreography.md](docs/choreography.md) |
| Character Library | [pages/character-library.html](pages/character-library.html) + [src/character-library.js](src/character-library.js) (search/sort/link logic in [src/shared/character-library-view.js](src/shared/character-library-view.js), covered by [tests/character-library-view.test.js](tests/character-library-view.test.js)) → `/character-library`, API [api/avatars/library.js](api/avatars/library.js) | Live at `/character-library` | Professionally rigged Mixamo characters (skinned GLB + thumbnails on R2, `avatars/mixamo/`), each drives the full animation library. The live count comes from the R2 manifest and renders in the hero; no page copy hard-codes it. Pipeline: [scripts/fetch-mixamo-avatars.mjs](scripts/fetch-mixamo-avatars.mjs) → [scripts/convert-mixamo-avatars.mjs](scripts/convert-mixamo-avatars.mjs) → [scripts/fetch-mixamo-avatar-thumbnails.mjs](scripts/fetch-mixamo-avatar-thumbnails.mjs) → [scripts/build-mixamo-avatar-library.mjs](scripts/build-mixamo-avatar-library.mjs) publishes `avatars/library/manifest.json`. Cards deep-link into the 3D viewer (`/app#model=`), Widget Studio (`/studio?model=`), and Animation Studio (`/pose?src=`). Mirrors the animation-library R2-manifest pattern (no DB). See [public/avatars/mixamo/README.md](public/avatars/mixamo/README.md) |
| Object Library | [pages/objects.html](pages/objects.html) + [src/objects-library.js](src/objects-library.js) → `/objects`, API [api/objects/library.js](api/objects/library.js) | Live at `/objects` | Hundreds of CC0 (public-domain) 3D props from Poly Haven (packed to GLB on R2, `objects/polyhaven/`). Pipeline: [scripts/fetch-polyhaven-objects.mjs](scripts/fetch-polyhaven-objects.mjs) (glTF→GLB via @gltf-transform) → [scripts/render-glb-thumbnails.mjs](scripts/render-glb-thumbnails.mjs) → [scripts/build-object-library.mjs](scripts/build-object-library.mjs) publishes `objects/library/manifest.json`. Same R2-manifest pattern as the Character/animation libraries (no DB). Cards preview in the 3D viewer (`/app#model=`), place into AR Studio (`/ar/studio?src=`), and download the GLB directly (CC0). AR Studio's tray also has an Objects tab over the same manifest. The grid renders 48 cards at a time (a Load more button, plus an IntersectionObserver that pulls the next chunk as you approach it) and each card is a still thumbnail until you dwell on it, at which point that one card upgrades to a live auto-rotating `<model-viewer>`; at most six stay mounted. The manifest read falls back to the bucket's public CDN domain when the signed S3 read fails (`getPublicObjectBuffer` in [api/_lib/r2.js](api/_lib/r2.js)), so a bad storage credential can no longer empty a library of public CC0 bytes. |
diff --git a/data/pages.json b/data/pages.json
index fbc13122b..f6dceab1f 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -5582,6 +5582,13 @@
"priority": 0.6,
"changefreq": "monthly"
},
+ {
+ "path": "/docs/dissolve",
+ "title": "Docs · Dissolve",
+ "description": "How Dissolve turns a GLB into a GPU particle storm: surface sampling, Morton-paired morphing, the force tools, share links and the microphone privacy model.",
+ "priority": 0.6,
+ "changefreq": "monthly"
+ },
{
"path": "/docs/architecture",
"title": "Docs · Architecture overview",
diff --git a/docs/dissolve.md b/docs/dissolve.md
new file mode 100644
index 000000000..ce264b785
--- /dev/null
+++ b/docs/dissolve.md
@@ -0,0 +1,34 @@
+# Dissolve
+
+`/dissolve` turns any glTF/GLB model into a storm of GPU particles (65k, 262k or 1M), morphs one shape into another, and lets you bend the storm with forces.
+
+## How it works
+
+1. `shape.js` samples the model surface in world space (skinned meshes included), area-weighted, and reads texture, vertex or material colour per sample.
+2. Both shapes are Morton-sorted over a shared stage box, so particle `i` of A pairs with particle `i` of B and the morph stays spatially coherent.
+3. `engine.js` keeps position and velocity in float textures and runs two ping-pong passes per frame. Points render straight from those textures.
+4. Forces: black hole (with jets past the horizon), vortex, up to four shockwaves, collapse (gravity and a bouncing floor). The microphone adds bass and mid energy.
+
+## Controls
+
+| Key | Action |
+| --- | --- |
+| Space | Morph A to B and back |
+| 1 to 4 | Orbit, black hole, vortex, shockwave |
+| S | Swap A and B |
+| C | Collapse |
+| B | Detonate |
+| M | Microphone |
+| P | PNG snapshot |
+| R | Record a clip |
+| H | Hide or show the dock |
+
+Drop a `.glb` onto the stage to load it into B (hold Shift for A). Quality (Lite, Standard, Ultra) is remembered, and the page offers Lite if frames run slow.
+
+## Share links
+
+`/dissolve?a=agent&b=fox&p=storm&q=standard`. `a` and `b` are shelf ids or https GLB URLs. Files from your device cannot travel in a link.
+
+## Privacy
+
+The microphone is opt-in, analysed in the browser as three band levels, and never recorded or uploaded.
diff --git a/docs/nav.json b/docs/nav.json
index 9ca34f8a8..a420aa78a 100644
--- a/docs/nav.json
+++ b/docs/nav.json
@@ -862,6 +862,10 @@
"label": "Sonar (hand control)",
"path": "sonar"
},
+ {
+ "label": "Dissolve (particle storms)",
+ "path": "dissolve"
+ },
{
"label": "Avatar inspector",
"path": "avatar-inspector"
diff --git a/src/dissolve/README.md b/src/dissolve/README.md
new file mode 100644
index 000000000..11c85a987
--- /dev/null
+++ b/src/dissolve/README.md
@@ -0,0 +1,11 @@
+# src/dissolve
+
+Controller and engine for the `/dissolve` page. See [docs/dissolve.md](../../docs/dissolve.md).
+
+- `page.js`: renderer, bloom, DOM wiring, tools, morph timeline, capture, share links.
+- `engine.js`: GPGPU particle simulation (velocity and position ping-pong passes, point renderer).
+- `sample-core.js`: pure surface sampling, Morton ordering and stage fitting (no three.js).
+- `shape.js`: GLB to coloured point cloud, chunked with progress.
+- `audio.js`: opt-in microphone band levels.
+- `recorder.js`: canvas capture to webm or mp4.
+- `shelf.js`: bundled models, look presets, quality tiers, share-link state.