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(renderer): add the WebGPU renderer guide and update the forge doc

nirholas997d7e4e9b6d
diff --git a/docs/forge.md b/docs/forge.md
index 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.md
new file mode 100644
index 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.