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(renderer): add the WebGPU renderer guide and update the forge doc
nirholas997d7e4e9b6d
diff --git a/docs/forge.md b/docs/forge.mdindex 9e7a44416..f00fea939 100644--- a/docs/forge.md+++ b/docs/forge.md@@ -649,30 +649,3 @@ dashboard at [/quality-bench](https://three.ws/quality-bench) (internal).- [Diorama](./diorama.md) forges a whole scene of Forge objects into one explorable world.- The 3D generation architecture: [3D pipeline](./3d-pipeline.md), [3D asset pipeline](./3d-asset-pipeline.md), [3D API](./3d-api.md).- Pages: [/create](https://three.ws/create) (the avatar creator), [/scene](https://three.ws/scene) (Scene Studio), [/restyle](https://three.ws/restyle) (re-skin a GLB), [/gallery](https://three.ws/gallery).--### Scene from a photo (SAM 3D Objects)--`/api/forge-scene-objects` rebuilds every object in one photo as a single GLB with-a named node per object (`object_01`, ...), laid out the way the objects sit in-the picture (relative layout, not metric). It runs-[SAM 3D Objects](https://github.com/facebookresearch/sam-3d-objects) on-`workers/model-sam3d-objects` and is also the AR Studio tray tab "From a photo".--```bash-curl -sX POST https://three.ws/api/forge-scene-objects \- -H 'content-type: application/json' \- -d '{"image_url":"https://.../desk.jpg","max_objects":8}'-# → 202 { "job_id": "...", "status": "queued", "eta_seconds": 150,-# "source": "detected", "objects": [{ "label": "mug", "box": [...] }] }--curl -s 'https://three.ws/api/forge-scene-objects?job=<job_id>'-# → { "status": "done", "result_url": "https://.../scene.glb", "object_count": 3, "skipped": [] }-```--Choose the objects with `boxes` (`[x0,y0,x1,y1]` fractions, top-left origin),-`mask_urls` (one https PNG per object), or neither and the vision chain finds-them. Requests from comprehensively sanctioned territories (the SAM License's-Trade Controls clause) get `451` before any work is queued. Returns `503-backend_unconfigured` until `MODEL_SAM3D_URL` and `GCP_RECONSTRUCTION_KEY` point-at the deployed worker; staging the gated weights is `npm run stage:sam3d-objects`-(see the worker README).diff --git a/docs/webgpu-renderer.md b/docs/webgpu-renderer.mdnew file mode 100644index 000000000..0233f3232--- /dev/null+++ b/docs/webgpu-renderer.md@@ -0,0 +1,48 @@+# WebGPU renderer (opt-in)++three.ws ships on three r186. The classic WebGL2 renderer is still the default everywhere. WebGPU is strictly opt-in and always degrades to the same WebGL2 picture.++## Opting in++- Query string: `/restyle?renderer=webgpu`+- Element attribute (read by `pagePreference(el)`): `renderer="webgpu"`. The attribute wins over the query string, so an embedder can pin `renderer="webgl"`.++Only the exact value `webgpu` opts in. The factory is [src/renderer-factory.js](../src/renderer-factory.js): `createAutoRenderer(options, { prefer, fallback })` returns `{ renderer, backend, reason }` and stamps `data-renderer` on the canvas. It falls back to the guarded WebGL2 path when `navigator.gpu` is missing, `requestAdapter()` resolves null or throws, `WebGPURenderer.init()` fails, or the node renderer lands on its own GL backend. Callers branch on `backend`, never on what was requested.++## Where it is wired++[Restyle Studio](restyle.md) (`/restyle`) uses the factory. Its view-only Fresnel rim light lives in [src/restyle-effects.js](../src/restyle-effects.js):++- WebGL2: an `onBeforeCompile` GLSL patch on the glTF PBR materials.+- WebGPU: `MeshStandard/PhysicalNodeMaterial` with a TSL `emissiveNode` (`three/tsl`).++Node materials are not glTF-exportable, so on WebGPU every export goes through `withClassicMaterials`, which swaps the original classic materials back (carrying live edits) for the duration of the export. The exported GLB is identical on both paths and never contains the rim.++A renderer badge in the Restyle toolbar shows the backend in use. The Rim slider and color are in the same toolbar.++## Not ported, and why++- The main viewer and `<agent-3d>` still use `CinematicPipeline` (EffectComposer), which is WebGL-only. The factory and the `renderer` attribute parser are ready, but the viewer is not switched until its post-processing moves to TSL.+- `three/examples` `GaussianSplat` is WebGPU-only. The viewer splat stage keeps Spark, which also runs on WebGL2.+- `three-mesh-bvh/webgpu` (pinned 0.9.16) accelerates GPU-side queries. The viewer's picking is CPU raycasting, so it does not apply.++## Measuring++```+npm run dev # or any server on another port+node scripts/renderer-bench.mjs --base http://localhost:3000 --frames 200+```++The harness loads `/restyle?bench` three ways (default, `?renderer=webgpu`, `?renderer=webgpu` with `navigator.gpu` removed) and reports backend, console errors, offscreen render time per frame, pixel difference and silhouette overlap against the default, and the rim effect. It exits non-zero on any console error or wrong fallback. Parity and timing use an offscreen render target with readback because headless software WebGPU cannot present to a canvas.++### Results (2026-10-24, software adapter)++Headless Chromium with SwiftShader, 384x512 target, 200 frames, same model. This is a software rasterizer, so it compares the two code paths and is not GPU hardware data. Run the command above on a machine with a GPU for hardware numbers.++| Case | Backend | Render ms/frame (2 runs) | Mean diff vs default | Silhouette overlap | Console errors |+| --- | --- | --- | --- | --- | --- |+| default | WebGL2 | 9.2, 10.9 | n/a | n/a | 0 |+| `?renderer=webgpu` | WebGPU | 12.8, 17.0 | 0.01 / 255 | 1.0 | 0 |+| `?renderer=webgpu`, GPU denied | WebGL2 (fallback) | 9.4, 10.1 | 0 / 255 | 1.0 | 0 |++The rim effect shifts the frame by 1.18 / 255 on both paths and the two paths agree on it to 0.02 / 255.