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.

9.7 KB
Raw Blame

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. Only https:// and same-origin / URLs are accepted.
  • /scene?handoff=1 pulls a baked GLB (mesh plus embedded animation clip) that the Animation Studio at /pose stashed in IndexedDB via src/shared/scene-handoff.js, adds it to the scene, and attaches a player script that drives an AnimationMixer so 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 with new Function on 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-https link) 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).
  • /forge and /forge-max produce the GLBs that deep-link here; /pose hands 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.