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(dissolve): add the Dissolve guide, source README, docs nav entry, sitemap page and structure row
nirholas64df7ba89e19
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 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.jsonindex 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.mdnew file mode 100644index 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.jsonindex 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.mdnew file mode 100644index 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.