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.
src/scene-studio
Scene Studio, the full 3D scene editor served at /scene.
Import GLB models, arrange them with transform gizmos, edit materials and lights,
script objects, play the scene, and export the result as GLB, USDZ, or a
publishable app zip.
Why this exists
Building a scene editor from scratch is a solved problem: the three.js project
ships one. Instead of reinventing it, this directory vendors the upstream
editor/ from three.js r184 (MIT, see vendor/LICENSE) and
wraps it with a handful of thin sibling modules that adapt it to three.ws. The wrappers
never modify vendor/**; every local change to upstream files is documented in
vendor/README.md so re-vendoring on a three upgrade stays
mechanical.
The wrappers are what make it a three.ws surface rather than a mirror of the
upstream demo: models forged on /forge or /forge-max deep-link straight into
the scene, animations baked on /pose hand off through IndexedDB, and any
composed scene can be exported with one click or uploaded and embedded on
another site. They also close the gaps the upstream demo never had to care
about: a first-run empty state, accessible names on the icon-only transform and
animation-transport buttons, a sidebar that fits a 320px screen instead of
overflowing it, and failures that surface in the platform's own toast instead of
a native alert().
Layout
src/scene-studio/
├── main.js Boot: mounts the vendored editor into #studio-app, wires
│ autosave, drag-and-drop import, and the deep-link importers
├── loader.js Shared GLB loader: Draco/KTX2/Meshopt-wired GLTFLoader that
│ adds a parsed GLB through the undo-able AddObjectCommand path
├── actions.js Layered action bar: Import from Forge, Export presets, Share
├── agent-tab.js Agent sidebar tab: chat panel that drives the open scene
│ through real editor.execute(Command) tool calls, with a
│ screenshot + undoable version per mutating prompt
├── tsl-editor.js Nodes sidebar tab: dropdown-wired TSL material graph editor
│ for the selected object
├── empty-state.js First-run overlay over the empty grid, retires on first object
├── remote-scene.js Strips scripts and history from a scene opened by #file= link
├── toolbar-a11y.js Accessible names for the icon-only controls: the transform
│ gizmos (plus pressed state) and the animation transport
├── studio.css three.ws chrome overrides (vendor css/main.css is untouched)
└── vendor/ three.js r184 editor source (see vendor/README.md)
Static runtime assets (Draco/Basis decoders, toolbar icons, CodeMirror and the
other classic-script libs, the publish-zip template) live under
public/scene-studio/ and are documented in
vendor/README.md. The classic-script libs load as plain
<script> tags in pages/scene.html, exactly as
upstream's index.html does.
Usage
There is nothing to install. The page is part of the main Vite app:
npm run dev # then open http://localhost:3000/scene
pages/scene.html loads /src/scene-studio/main.js as
a module; main.js mounts the editor into the #studio-app container under the
site nav. The surface is dark-locked: the entry module re-pins
data-theme="dark" because the editor chrome only ships dark.
Scenes autosave to IndexedDB through the vendored editor.storage on every
geometry, material, script, or scene-graph change, so a reload restores the last
state. For debugging, main.js exposes window.editor and window.THREE in
the browser console.
Deep links
/scene?model=<glb_url>&name=<label>adds the GLB at that URL to the scene through the normal undo-able import path, then strips the query from the address bar so a reload does not import a duplicate. This is the "Open in Scene Studio" hand-off used by Forge and Forge Max results. Onlyhttps://and same-origin/URLs are accepted./scene?handoff=1pulls a baked GLB (mesh plus embedded animation clip) that the Animation Studio at/posestashed in IndexedDB via src/shared/scene-handoff.js, adds it to the scene, and attaches a player script that drives anAnimationMixerso the clip plays in the timeline and records through Render, Video./scene#file=<url>(upstream behavior) loads a serialized editor JSON scene after a confirmation prompt. Unlike upstream, the linked scene's object scripts and undo history are dropped (remote-scene.js): scripts are compiled withnew Functionon Play, so keeping them would let any link run code on the three.ws origin as the viewer. A scene you trust keeps its scripts when opened through File, Import.
Action bar
actions.js mounts a toolbar layered over the vendored chrome with three
affordances the stock File and Export menus do not offer on their own:
- Import from Forge: paste a GLB URL from a Forge or Forge Max result into
the platform's own dialog (the shared
<dialog>Modal, with inline validation for a non-httpslink) and drop the model straight into the scene. A fetch that fails is explained in a toast that names the likely cause and points at drag-and-drop as the fallback. - Export presets: one click for a Web GLB (binary, with cloned and optimized animation clips, identical to File, Export, GLB) or an AR bundle (.usdz for iOS Quick Look).
- Share: exports the scene as a GLB, uploads it via api/scene-glb-upload.js (presigned PUT), and opens the platform's "Embed this model" panel from src/forge-embed-panel.js, the same modal Forge results use.
Exports
The wrappers export nine functions; main.js is entry-only and exports nothing.
| Module | Export | What it does |
|---|---|---|
loader.js |
addGltfBufferToScene(editor, contents, label?) |
Parses a GLB ArrayBuffer with the Draco/KTX2/Meshopt-wired loader and adds it via AddObjectCommand (undo-able, autosave-triggering, outliner-visible). Resolves to the added THREE.Object3D. |
actions.js |
mountStudioActions(editor, container) |
Mounts the Import from Forge / Export / Share bar into the studio container. Returns the bar element. |
actions.js |
openImportDialog(editor, triggerEl?) |
Opens the import dialog and, on a confirmed URL, fetches and adds the model. Shared with the empty state so both entry points behave identically. |
actions.js |
sceneTitle(editor) |
The scene's own name, or a stable fallback, for the Share embed panel's label. |
actions.js |
describeImportFailure(error) |
Turns an HTTP 4xx / Failed to fetch into copy that names the likely cause. |
empty-state.js |
mountEmptyState(editor, container) |
Mounts the first-run overlay and keeps it in sync with the scene graph. Returns the overlay element. |
toolbar-a11y.js |
enhanceToolbarA11y(editor, toolbarDom) |
Labels the vendored translate/rotate/scale buttons and mirrors their selected class into aria-pressed. Returns the labelled buttons. |
toolbar-a11y.js |
enhanceAnimationA11y(editor, animationDom) |
Labels the vendored animation timeline's play/pause/stop transport, which ships as three identical unnamed icon buttons. Matches each one on the SVG shape the vendor draws, not on child order, so a control added to that panel can never inherit the wrong label. Returns the labelled buttons. |
agent-tab.js |
createAgentPanel(editor) |
Builds the Agent sidebar tab: a chat panel that posts each turn to api/scene/agent.js, executes the model's tool calls as real editor.execute(Command)s, and pushes a scene+screenshot version per mutating prompt. Returns a UIElement ready for sidebar.addTab('agent', 'Agent', panel). |
tsl-editor.js |
createTslEditorPanel(editor) |
Builds the Nodes sidebar tab: a dropdown-wired TSL material graph editor for the selected object's material. Returns a UIElement ready for sidebar.addTab('nodes', 'Nodes', panel). |
Example
This is how actions.js imports a Forge result into the scene, using the shared
loader (trimmed from openImportDialog in actions.js):
import { addGltfBufferToScene } from './loader.js';
import { describeImportFailure } from './actions.js';
import { toastError } from '../shared/toast.js';
// `editor` is the vendored Editor instance (window.editor on /scene).
// `url` is an https GLB link the user confirmed in the import dialog.
const base = decodeURIComponent(url.split('?')[0].split('/').pop() || '');
const label = (base.replace(/\.(glb|gltf)$/i, '') || 'Forge model').slice(0, 64);
try {
const res = await fetch(url);
if (!res.ok) throw new Error('HTTP ' + res.status);
await addGltfBufferToScene(editor, await res.arrayBuffer(), label);
} catch (error) {
toastError(`Could not import that model: ${describeImportFailure(error)}.`);
}
Both callers of the loader (the ?model= deep link in main.js and the action
bar above) go through this one function, so a GLB added either way decodes and
behaves identically to a manual drag-and-drop import.
Related surfaces
- STRUCTURE.md row: Scene Studio (3D scene editor).
/forgeand/forge-maxproduce the GLBs that deep-link here;/posehands off baked animations; the Share flow reuses the Forge embed panel.- Unit tests for the exported pure logic live in tests/scene-studio-actions.test.js.
- The page entry in data/pages.json (
path: "/scene") feeds the sitemap,llms.txt, and the changelog.