@volter/play 0.5.212 → 0.5.213

package/serving/std-dev.ts

@@ -15,8 +15,9 @@
  * - `POST /__editor/play/std/start` — `{ url }`: the game's dev server, started where none runs (`npm run dev --
  *   --no-open`, in the project's folder, owned by this session and ended with it), found by the record std's dev server
  *   writes in Vite's cacheDir (`node_modules/.vite/std-dev.json`: its address, its process and its endpoints' token).
- * - `GET  /__editor/play/std/devices` and `POST /__editor/play/std/devices/<id>/control` — std's own endpoints
- *   (`/__std/devices`, `/__std/devices/<id>/control`), asked with the record's token, which stays in this process.
+ * - `GET  /__editor/play/std/devices`, `POST /__editor/play/std/devices/<id>/control` and `GET
+ *   /__editor/play/std/scene` — std's own endpoints (`/__std/devices`, `/__std/devices/<id>/control`, and the game's
+ *   running scene, `/__std/scene`), asked with the record's token, which stays in this process.
  * - `GET  /__editor/play/std/goals` — `{ goals }`: the goals of the game's bot, its `autopilot/index.ts` program's
  *   (`autopilot({ goals })`, std-driver's `program`), read by Node in the game's folder as std reads the game's
  *   `autopilot/checks.ts` (std-dev's play-checks.ts: Node's own type stripping), each read a process of its own so an
@@ -24,9 +25,10 @@
  *
  * - `GET  /__editor/play/std/level` — `{ blenderHalf }`: the level export's Blender half as the game installed it
  *   (std-dev's `blender/blend-to-scene.py`), which the page runs in the document's Blender (`../src/std-level.ts`).
- * - `POST /__editor/play/std/level` `{ glb }` — `{ code, output }`: its Node half, `std level <glb> --description <its
- *   .level.json>` in the game's folder, by the game's own std (std-dev's `bin/std.js`, under the session's Node), for a
- *   level's glb or a prefab's (`prefabs/<name>/<name>.glb`, whose component std writes as `<Name>.tsx`).
+ * - `POST /__editor/play/std/level` `{ glb }` — `{ code, output }`: its Node half, `std level-scene <glb>` in the
+ *   game's folder (from the glb and the `.level.json` the Blender half wrote beside it), by the game's own std
+ *   (std-dev's `bin/std.js`, under the session's Node), for a level's glb or a prefab's (`prefabs/<name>/<name>.glb`,
+ *   whose component std writes as `<Name>.tsx`).
  *
  * Every route is the machine owner's alone (`requireLocalOwner`), and a mutating one takes the editor's own origin
  * (the router's check on `/__editor`); a body is the JSON the router has parsed.
@@ -34,16 +36,17 @@
  *   id, with the slot its address named (its trace's first line): how Play tells its own players' pages apart.
  * - `GET  /__editor/play/std/trace?page=<page id>&from=<byte>` — `{ lines, next }`: the page's trace (`<page>.jsonl`
  *   in that folder) from a byte on, whole lines only.
- * - `POST /__editor/play/std/play` `{ goal, bots? }` — std's own play of the game's bots to the goal's end
- *   (`/__std/play`, std-dev's std-endpoints.ts) on the headless device, one bot unless asked, recorded in the run's
- *   folder and checked by the goal's checks (`autopilot/checks.ts`): answered as it goes, one JSON object a line
- *   (`application/x-ndjson`), each `{ line }` std says, then `{ end: { ok } }`. Its pages are std's, headless, so it
- *   plays whether or not the editor is seen.
+ * - `POST /__editor/play/std/play` `{ goal, bots?, device? }` — std's own play of the game's bots to the goal's end
+ *   (`/__std/play`, std-dev's std-endpoints.ts) on `device` (one of std's devices by its id: a player's page in the
+ *   Game view, which std drives as it is) or, where none is named, std's headless device, one bot unless asked,
+ *   recorded in the run's folder and checked by the goal's checks (`autopilot/checks.ts`): answered as it goes, one JSON
+ *   object a line (`application/x-ndjson`), each `{ line }` std says, then `{ end: { ok } }`.
  * - `GET  /__editor/play/std/capture?file=<page id>-capture-<n>.png` — a page's captured frame, the PNG std's receiver
  *   wrote in that folder for a `capture` control.
- * - `GET  /__editor/play/std/errors?server=<pid>&from=<line>` — `{ lines, next, server }`: the error output (stderr) of
- *   the dev server this session started, from a line on (every line, where `server` names another), or with no `from`
- *   none and where it ends: the room's own exceptions are Colyseus's to log there, never a page's trace.
+ * - `GET  /__editor/play/std/output?server=<pid>&stdout=<line>&stderr=<line>` — `{ server, stdout, stderr }`, each
+ *   stream's `{ lines, next }`: what the dev server this session started wrote on each, whole lines, from a line on
+ *   (every line, where `server` names another), or with no lines asked none and where each ends: the room runs in that
+ *   process, so its `console.log` is on stdout and the exceptions Colyseus logs on stderr, never in a page's trace.
  */
 import { spawn, type ChildProcess } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
@@ -85,7 +88,7 @@ const isLevelGlb = (path: string): boolean =>
 /** The level export's Node half: its exit code and everything it printed, in order. */
 function runStdLevel(root: string, glb: string): Promise<{ readonly code: number | null; readonly output: string }> {
   return new Promise((resolve) => {
-    const run = spawn(process.execPath, [join(stdDev(root), 'bin', 'std.js'), 'level', glb, '--description', glb.replace(/\.glb$/, '.level.json')], { cwd: root, windowsHide: true });
+    const run = spawn(process.execPath, [join(stdDev(root), 'bin', 'std.js'), 'level-scene', glb], { cwd: root, windowsHide: true });
     let output = '';
     run.stdout.on('data', (chunk: Buffer) => { output += chunk.toString(); });
     run.stderr.on('data', (chunk: Buffer) => { output += chunk.toString(); });
@@ -259,53 +262,75 @@ async function runningServer(root: string): Promise<RunningServer | null> {
   return alive(record.pid) ? record : null;
 }
 
-/** The most of a dev server's error output kept, in lines. */
-const ERRORS_KEPT = 500;
+/** The most of each of a dev server's streams kept, in lines. */
+const OUTPUT_KEPT = 500;
+
+/** One of a dev server's output streams as lines (the first kept one being line `dropped`), the line not yet ended,
+ *  and its decoder. Each stream is kept apart, so a room logging at every tick never pushes out an exception. */
+interface OutputStream {
+  readonly lines: string[];
+  dropped: number;
+  partial: string;
+  readonly decoder: StringDecoder;
+}
 
 /** The dev servers this session started, by project, with the last of what each said, why its launch failed, and its
- *  error output (stderr, where Colyseus logs a room's exceptions and Vite its errors and warnings) as lines, the first
- *  kept one being line `dropped`. */
+ *  two streams: stdout, where a room's `console.log` and Vite's notices go, and stderr, where Colyseus logs a room's
+ *  exceptions and Vite its errors and warnings. */
 interface OwnedServer {
   readonly child: ChildProcess;
   said: string;
   failed: string | null;
-  readonly errors: string[];
-  dropped: number;
-  partial: string;
-  readonly decoder: StringDecoder;
+  readonly streams: { readonly stdout: OutputStream; readonly stderr: OutputStream };
 }
 
 /** The most of a line kept before it ends (a progress line redrawn with `\r` never does). */
 const LINE_MOST = 4000;
 const owned = new Map<string, OwnedServer>();
 
-/** A chunk of a dev server's stderr taken into its lines, whole lines only (`null`, its output's end: the last one
- *  too), terminal escapes left out. */
-function heardError(server: OwnedServer, chunk: Buffer | null): void {
-  const text = chunk === null ? server.decoder.end() : server.decoder.write(chunk);
-  const lines = stripVTControlCharacters(server.partial + text).split(/\r?\n/);
-  server.partial = chunk === null ? '' : (lines.pop() ?? '').slice(-LINE_MOST);
-  server.errors.push(...lines.filter((line, at) => chunk !== null || at < lines.length - 1 || line !== ''));
-  const over = server.errors.length - ERRORS_KEPT;
+/** A chunk of one of a dev server's streams taken into its lines, whole lines only (`null`, the stream's end: the last
+ *  one too), terminal escapes left out. */
+function heardOutput(stream: OutputStream, chunk: Buffer | null): void {
+  const text = chunk === null ? stream.decoder.end() : stream.decoder.write(chunk);
+  const lines = stripVTControlCharacters(stream.partial + text).split(/\r?\n/);
+  stream.partial = chunk === null ? '' : (lines.pop() ?? '').slice(-LINE_MOST);
+  stream.lines.push(...lines.filter((line, at) => chunk !== null || at < lines.length - 1 || line !== ''));
+  const over = stream.lines.length - OUTPUT_KEPT;
   if (over > 0) {
-    server.errors.splice(0, over);
-    server.dropped += over;
+    stream.lines.splice(0, over);
+    stream.dropped += over;
   }
 }
 
-/** The session's dev server's error output from line `from` of the server `server` (its process) on, every line of
- *  another server's, or none and where it ends (`from` null: a run's mark); and the server and the line after them.
- *  None where this session didn't start the game's dev server (one already running is its own terminal's). */
-function errorsFrom(root: string, server: number | null, from: number | null): {
-  readonly lines: readonly string[]; readonly next: number; readonly server: number | null;
+/** Where each of a dev server's streams has been read to; null, none asked of it (its end, a run's mark). */
+interface StreamsFrom { readonly stdout: number | null; readonly stderr: number | null }
+
+/** A stream's line as a query names it, or null where it names none. */
+const lineOf = (asked: string | null): number | null => (asked === null ? null : Number(asked) || 0);
+
+/** One stream's lines from line `from` on (none where `from` is null), and the line after them. */
+function streamFrom(stream: OutputStream, from: number | null): { readonly lines: readonly string[]; readonly next: number } {
+  const next = stream.dropped + stream.lines.length;
+  return { lines: from === null ? [] : stream.lines.slice(Math.max(0, from - stream.dropped)), next };
+}
+
+/** The session's dev server's two streams, each from its line in `from` on where `server` is its process, every line
+ *  of another server's, or none and where it ends (its line null: a run's mark); and the server. None where this
+ *  session didn't start the game's dev server (one already running is its own terminal's). */
+function outputFrom(root: string, server: number | null, from: StreamsFrom): {
+  readonly server: number | null;
+  readonly stdout: ReturnType<typeof streamFrom>;
+  readonly stderr: ReturnType<typeof streamFrom>;
 } {
   const mine = owned.get(root);
   const pid = mine?.child.pid ?? null;
-  if (!mine || pid === null) return { lines: [], next: 0, server: null };
-  const next = mine.dropped + mine.errors.length;
-  if (from === null) return { lines: [], next, server: pid };
-  const start = server === pid ? from : 0;
-  return { lines: mine.errors.slice(Math.max(0, start - mine.dropped)), next, server: pid };
+  if (!mine || pid === null) return { server: null, stdout: { lines: [], next: 0 }, stderr: { lines: [], next: 0 } };
+  const start = (line: number | null): number | null => (line === null ? null : server === pid ? line : 0);
+  return {
+    server: pid,
+    stdout: streamFrom(mine.streams.stdout, start(from.stdout)),
+    stderr: streamFrom(mine.streams.stderr, start(from.stderr)),
+  };
 }
 
 /** Ends the dev servers this session started, each `npm run dev` with everything it started. */
@@ -323,13 +348,16 @@ async function startedServer(root: string): Promise<RunningServer> {
     const npm = npmProcess(['run', 'dev', '--', '--no-open'], root);
     // (a group of its own on POSIX, so its whole tree ends with it: `signalProcessTree`)
     const child = spawn(npm.program, npm.args, { cwd: root, detached: process.platform !== 'win32', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
-    mine = { child, said: '', failed: null, errors: [], dropped: 0, partial: '', decoder: new StringDecoder('utf8') };
+    const stream = (): OutputStream => ({ lines: [], dropped: 0, partial: '', decoder: new StringDecoder('utf8') });
+    mine = { child, said: '', failed: null, streams: { stdout: stream(), stderr: stream() } };
     const kept = mine;
     const hear = (chunk: Buffer): void => { kept.said = (kept.said + chunk.toString('utf8')).slice(-4000); };
     child.stdout?.on('data', hear);
     child.stderr?.on('data', hear);
-    child.stderr?.on('data', (chunk: Buffer) => heardError(kept, chunk));
-    child.stderr?.on('end', () => heardError(kept, null));
+    for (const name of ['stdout', 'stderr'] as const) {
+      child[name]?.on('data', (chunk: Buffer) => heardOutput(kept.streams[name], chunk));
+      child[name]?.on('end', () => heardOutput(kept.streams[name], null));
+    }
     child.on('error', (error) => { kept.failed = error.message; });
     owned.set(root, mine);
   }
@@ -399,9 +427,10 @@ const PLAY_MS = 15 * 60_000;
  * messages, then `{ end: { ok } }`), its messages passed on as they come, one JSON line each.
  */
 async function playGoal(root: string, body: unknown, response: ServerResponse): Promise<void> {
-  const asked = body as { goal?: unknown; bots?: unknown } | undefined;
-  if (typeof asked?.goal !== 'string' || asked.goal === '' || (asked.bots !== undefined && !(Number.isInteger(asked.bots) && Number(asked.bots) >= 1)))
-    return answer(response, 400, { error: `A play is { goal, bots? }: a goal of the game's bot, and a whole number of bots; it was given ${JSON.stringify(body)}.` });
+  const asked = body as { goal?: unknown; bots?: unknown; device?: unknown } | undefined;
+  if (typeof asked?.goal !== 'string' || asked.goal === '' || (asked.bots !== undefined && !(Number.isInteger(asked.bots) && Number(asked.bots) >= 1))
+    || (asked.device !== undefined && (typeof asked.device !== 'string' || asked.device === '')))
+    return answer(response, 400, { error: `A play is { goal, bots?, device? }: a goal of the game's bot, a whole number of bots, and one of std's devices by its id; it was given ${JSON.stringify(body)}.` });
   const running = await runningServer(root);
   if (!running) return answer(response, 409, { error: "The game's dev server is not running: press Play." });
   response.statusCode = 200;
@@ -419,7 +448,7 @@ async function playGoal(root: string, body: unknown, response: ServerResponse):
     if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) socket.close();
   };
   const limit = setTimeout(() => end(false, `Play ended std's play of ${asked.goal}: it ran ${PLAY_MS / 60_000} minutes.`), PLAY_MS);
-  socket.addEventListener('open', () => socket.send(JSON.stringify({ goal: asked.goal, bots: asked.bots ?? 1, device: 'headless' })));
+  socket.addEventListener('open', () => socket.send(JSON.stringify({ goal: asked.goal, bots: asked.bots ?? 1, device: asked.device ?? 'headless' })));
   socket.addEventListener('message', (event) => {
     const message = JSON.parse(String(event.data)) as { line?: unknown; end?: { ok?: unknown } };
     if (message.end !== undefined) end(message.end.ok === true);
@@ -443,7 +472,9 @@ function answer(response: ServerResponse, status: number, value: unknown): void
 async function askStd(root: string, path: string, init?: RequestInit): Promise<{ readonly status: number; readonly body: unknown }> {
   const running = await runningServer(root);
   if (!running) return { status: 409, body: { error: "The game's dev server is not running: press Play." } };
-  const response = await fetch(`${running.url}${path}?token=${running.token}`, init);
+  const at = new URL(path, running.url);
+  at.searchParams.set('token', running.token);
+  const response = await fetch(at, init);
   return { status: response.status, body: await response.json() };
 }
 
@@ -492,6 +523,8 @@ export function stdDevPlugin(services: Pick<ProjectServingServices, 'currentProj
           url.pathname === '/' && request.method === 'GET' ? Promise.resolve({ status: 200, body: stdGame(root) })
           : url.pathname === '/start' && request.method === 'POST' ? startedServer(root).then(({ url: at }) => ({ status: 200, body: { url: at } }))
           : url.pathname === '/devices' && request.method === 'GET' ? askStd(root, '/__std/devices')
+          // (the game's running scene, read where it runs: the level document draws the playing world from it)
+          : url.pathname === '/scene' && request.method === 'GET' ? askStd(root, `/__std/scene${url.search}`)
           : control !== undefined && request.method === 'POST'
             ? askStd(root, `/__std/devices/${encodeURIComponent(decodeURIComponent(control))}/control`,
               { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(bodyOf(request)) })
@@ -501,10 +534,10 @@ export function stdDevPlugin(services: Pick<ProjectServingServices, 'currentProj
           : url.pathname === '/pages' && request.method === 'GET' ? pageSlots(root).then((body) => ({ status: 200, body }))
           : url.pathname === '/trace' && request.method === 'GET' && PAGE_ID.test(url.searchParams.get('page') ?? '')
             ? traceFrom(root, url.searchParams.get('page')!, Number(url.searchParams.get('from') ?? 0)).then((body) => ({ status: 200, body }))
-          : url.pathname === '/errors' && request.method === 'GET'
-            ? Promise.resolve({ status: 200, body: errorsFrom(root,
+          : url.pathname === '/output' && request.method === 'GET'
+            ? Promise.resolve({ status: 200, body: outputFrom(root,
               url.searchParams.has('server') ? Number(url.searchParams.get('server')) : null,
-              url.searchParams.has('from') ? Number(url.searchParams.get('from')) || 0 : null) })
+              { stdout: lineOf(url.searchParams.get('stdout')), stderr: lineOf(url.searchParams.get('stderr')) }) })
           : Promise.resolve({ status: 404, body: { error: `${STD_ROUTE}${url.pathname} is not a route of Play's` } });
         asked.then(({ status, body }) => answer(response, status, body),
           (error: unknown) => answer(response, 500, { error: error instanceof Error ? error.message : String(error) }));

package/serving/std-scene-runtime.js

@@ -8,7 +8,7 @@
 import { Component, createElement as h } from 'react';
 import * as THREE from 'three';
 import { advance, createPortal, createRoot, extend, useFrame } from '@react-three/fiber';
-import { Physics } from '@react-three/rapier';
+import { Physics, useRapier } from '@react-three/rapier';
 import { EffectPass, LUT3DEffect } from 'postprocessing';
 import { LUTCubeLoader } from 'three/addons/loaders/LUTCubeLoader.js';
 import { ViewShaperEffect } from '@volter-ai/std/level/client';
@@ -30,6 +30,119 @@ function StageDraws() {
   return null;
 }
 
+/** An object's children, each with its name in a running scene's path (std's "The running scene": its name, else its
+ *  three type, siblings of one name numbered `~2`, `~3` in their parent's order). */
+function namedChildren(object) {
+  const seen = new Map();
+  return object.children.map((child) => {
+    const own = child.name === '' ? child.type : child.name;
+    const n = (seen.get(own) ?? 0) + 1;
+    seen.set(own, n);
+    return [child, n === 1 ? own : `${own}~${n}`];
+  });
+}
+
+/** The object at a running scene's path below `root`, where there is one. */
+function objectBelow(root, path) {
+  let at = root;
+  for (const name of path.split('/')) {
+    at = namedChildren(at).find(([, own]) => own === name)?.[0];
+    if (at === undefined) return undefined;
+  }
+  return at;
+}
+
+const place = new THREE.Vector3();
+const turn = new THREE.Quaternion();
+const size = new THREE.Vector3();
+
+/** A running scene's object put on this copy's: its local transform and visibility, and the body it carries where it
+ *  has one, where the object now stands in the world (the copy's physics is paused, so its collider lines follow the
+ *  object only so), without waking it. */
+function putNode(object, node, body) {
+  object.position.set(node.x, node.y, node.z);
+  object.quaternion.set(node.qx, node.qy, node.qz, node.qw);
+  object.scale.set(node.sx, node.sy, node.sz);
+  object.visible = node.visible;
+  if (body === undefined) return;
+  object.updateWorldMatrix(true, false);
+  object.matrixWorld.decompose(place, turn, size);
+  body.setTranslation(place, false);
+  body.setRotation(turn, false);
+}
+
+/** Each object below `root` with its path, into `into`. */
+function pathsBelow(root, above, into) {
+  for (const [child, name] of namedChildren(root)) {
+    const path = above === '' ? name : `${above}/${name}`;
+    into.set(path, child);
+    pathsBelow(child, path, into);
+  }
+}
+
+/** Whether an object stands as a node has it. */
+const standsAt = (object, node) =>
+  object.visible === node.visible &&
+  object.position.x === node.x && object.position.y === node.y && object.position.z === node.z &&
+  object.quaternion.x === node.qx && object.quaternion.y === node.qy && object.quaternion.z === node.qz && object.quaternion.w === node.qw &&
+  object.scale.x === node.sx && object.scale.y === node.sy && object.scale.z === node.sz;
+
+/**
+ * THE RUNNING SCENE ON THE LEVEL, while the game plays: each change std reads of the game's running scene (std-dev's
+ * `/__std/scene`: the world its server runs, or the scene a player's page renders), every object by its path below that
+ * scene, put on this root's own copy of the level as a page puts the room's nodes on its own (`putNode`, the object's
+ * body too), so the scene view is the playing world, as an engine's scene view is during Play. As std's own
+ * page does with the room's moved objects (`useRoomScene`), the nodes the running scene changed are put again every
+ * frame, after the level's own frame callbacks (a priority after theirs), each found by its path: what the running
+ * scene moved stands where it has it; an object it holds as the copy draws it is left to the level. An object of the
+ * running scene's this copy has none of (a character, an object the game adds) stands as an empty of its name and type
+ * at its place; an object gone from it is hidden here, or let go where it was the running scene's alone. A whole answer
+ * names every object there is: any other is gone.
+ */
+function SceneNodes({ running }) {
+  const { rigidBodyStates } = useRapier();
+  useFrame(() => {
+    const leave = (path, object) => {
+      running.moved.delete(path);
+      if (running.made.has(object)) { object.removeFromParent(); running.made.delete(object); }
+      else object.visible = false;
+    };
+    for (const { whole, objects, gone } of running.pending.splice(0)) {
+      if (whole) {
+        const named = new Set(objects.map((node) => node.path));
+        const here = new Map();
+        pathsBelow(running.root, '', here);
+        for (const [path, object] of here) if (!named.has(path) && object.parent !== null) leave(path, object);
+      }
+      for (const node of objects) {
+        const object = objectBelow(running.root, node.path);
+        if (object === undefined) {
+          const at = node.path.lastIndexOf('/');
+          const parent = at < 0 ? running.root : objectBelow(running.root, node.path.slice(0, at));
+          if (parent === undefined) continue;
+          const made = node.type === 'Group' ? new THREE.Group() : new THREE.Object3D();
+          made.name = node.path.slice(at + 1).replace(/~\d+$/, '');
+          parent.add(made);
+          running.made.add(made);
+          running.moved.set(node.path, node);
+        } else if (running.moved.has(node.path) || !standsAt(object, node)) running.moved.set(node.path, node);
+      }
+      for (const path of gone) {
+        const object = objectBelow(running.root, path);
+        if (object !== undefined) leave(path, object);
+      }
+    }
+    if (running.moved.size === 0) return;
+    const bodies = new Map();
+    rigidBodyStates.forEach((state) => { bodies.set(state.object, state.rigidBody); });
+    for (const [path, node] of running.moved) {
+      const object = objectBelow(running.root, path);
+      if (object !== undefined) putNode(object, node, bodies.get(object));
+    }
+  }, 1);
+  return null;
+}
+
 /** What the level throws as it renders or loads, the view's to show. */
 class Failed extends Component {
   state = { error: null };
@@ -57,10 +170,11 @@ function lent(renderer) {
 
 /**
  * A fiber root for `level` on the stage's renderer and camera, its children portalled into the document: the level's
- * environment into `world`, the document's own scene, whose sky, environment light and fog the stage draws by, and
- * `<Physics paused debug={overlays}><Level /></Physics>` into `root`. Fiber keeps a scene of its own, as its unmount
- * disposes what that scene holds. It draws nothing until `draw` is asked; `advance` runs a frame of the level's own
- * `useFrame`s (the stage draws the picture); `unmount` ends it.
+ * environment into `world`, the document's own scene, whose sky, environment light and fog the stage draws by;
+ * `<Physics paused debug={overlays}>` there too, its collider lines beside the level; and in it `<Level />` into
+ * `root`, which holds the level alone. Fiber keeps a scene of its own, as its unmount disposes what that scene holds. It draws nothing until `draw` is asked; `advance` runs a frame of the level's own
+ * `useFrame`s (the stage draws the picture); `running` takes a change of the game's running scene ({@link SceneNodes}),
+ * put on the next frame; `unmount` ends it.
  */
 export async function mountScene(level, { renderer, world, camera, root, onError }) {
   const { Level, Environment, canvas } = level;
@@ -77,16 +191,23 @@ export async function mountScene(level, { renderer, world, camera, root, onError
   // (fiber sizes the canvas's style in pixels; the stage sizes it by its box)
   Object.assign(renderer.domElement.style, { width, height });
   let store = null;
+  const running = { root, pending: [], made: new Set(), moved: new Map() };
   const draw = (shown) => {
     store = fiber.render(h(Failed, { onError }, h(StageDraws),
       Environment === null ? null : createPortal(h(Environment), world),
-      createPortal(h(Physics, { paused: true, debug: shown }, h(Level)), root)));
+      // (the physics world in the document's World, its collider lines there, and the level alone in the root: the
+      // root's objects are the level's, by the same paths as the game's scene)
+      createPortal(h(Physics, { paused: true, debug: shown }, createPortal(h(Level), root), h(SceneNodes, { running })), world)));
   };
   return {
     draw,
+    running: (changes) => { running.pending.push(changes); },
     // (this root's frame alone: another view's level is its own root)
     advance: (seconds) => { if (store !== null) advance(seconds, true, store.getState()); },
-    unmount: () => { fiber.unmount(); },
+    unmount: () => {
+      for (const object of running.made) object.removeFromParent();
+      fiber.unmount();
+    },
   };
 }
 

package/serving/std-scene.ts

@@ -1,10 +1,12 @@
 /**
  * A STD LEVEL'S SCENE AS A MODULE OF THE GAME'S OWN GRAPH (`docs/adr/std-scene-view.md`, decision 2). `/@volter-std-scene/
- * <levels/name.blend>` is a module the session's Vite serves from the game's folder, so its imports resolve as the game's
- * own. It names the level's generated files (std's level export writes them beside the `.blend`, named by std's rule:
- * `../src/std-level-files.ts`) and hands them to the Scene view's runtime (`./std-scene-runtime.js`), served from the
+ * <level>` is a module the session's Vite serves from the game's folder, so its imports resolve as the game's own. A
+ * level is a Blender file's (`levels/<name>.blend`), whose module names the level's generated files (std's level export
+ * writes them beside the `.blend`, named by std's rule: `../src/std-level-files.ts`), or a level in code
+ * (`levels/<Name>Level.tsx`), whose module names that file's component alone, the level lighting itself. Either hands
+ * them to the level document's runtime (`./std-scene-runtime.js`), served from the
  * same graph so that the game's own React Three Fiber, react-three-rapier, postprocessing and std draw it. It exports
- * what the Scene view (`../contributions/std-scene.document.tsx`) reads: `component` (the level's component's file),
+ * what the level's document (`../contributions/std-level.document.tsx`) reads: `component` (the level's component's file),
  * `canvas` (its `<Canvas>` settings), `gradingExtra` (whether its grading holds effects beyond its view transform, which
  * the view does not draw), `mountScene` and `viewTransform` (the runtime's, for this level). Only the level's names are
  * written here; the grading's shaper and LUT are read from the grading module std's writer makes (std-dev's
@@ -27,30 +29,34 @@ import { installedPackageDir } from '@volter/live/installed-package';
 import { fsFileUrl } from '@volter/sdk/project-module-url';
 import type { ProjectServingServices } from '@volter/sdk/session/project-serving';
 import { normalizePath, type EnvironmentModuleGraph, type EnvironmentModuleNode, type Plugin } from 'vite';
-import { camel, levelFiles, pascal } from '../src/std-level-files';
+import { BLEND_LEVEL, camel, CODE_LEVEL, levelFiles, pascal } from '../src/std-level-files';
 
 const PREFIX = '/@volter-std-scene/';
 const VIRTUAL = '\0volter-std-scene:';
-/** The Scene view's runtime (`./std-scene-runtime.js`), which a level's module imports by this name. */
+/** The level document's runtime (`./std-scene-runtime.js`), which a level's module imports by this name. */
 const RUNTIME = 'volter-std-scene-runtime';
 const RUNTIME_ID = '\0volter-std-scene-runtime';
 /** The runtime's file, beside this module in play's `serving/` (this module runs from there or from `dist-node/`). */
 const RUNTIME_FILE = join(dirname(fileURLToPath(import.meta.url)), '..', 'serving', 'std-scene-runtime.js');
-const LEVEL = /^levels\/.+\.blend$/;
 /** The query each URL the Scene module writes carries: the content version it was written at. */
 const MARK = 'volter-std-scene';
-/** The packages the Scene view's runtime imports by name that the game installs itself (`std-scene-runtime.js`'s
+/** The packages the level document's runtime imports by name that the game installs itself (`std-scene-runtime.js`'s
  *  imports, beside react, three and THROUGH's). */
 const RUNTIME_PACKAGES: readonly string[] = ['@react-three/fiber', '@react-three/rapier'];
 
-/** The runtime's imports the game has only through one of its dependencies, each resolved from that dependency, so it
- *  is the very instance the dependency uses: std's postprocessing (whose `Effect` std's `ViewShaperEffect` extends). */
+/** The runtime's imports that must be the very instance one of the game's dependencies uses, each resolved from that
+ *  dependency whatever the game also declares: std's postprocessing (whose `Effect` std's `ViewShaperEffect` extends). */
 const THROUGH: ReadonlyMap<string, string> = new Map([['postprocessing', '@volter-ai/std/level/client']]);
 
 /** The folder the package `name` names (a package, or a subpath of one) is installed in, as Node finds it from `root`. */
 const installedFolder = (root: string, name: string): string | null =>
   installedPackageDir(root, name.split('/').slice(0, name.startsWith('@') ? 2 : 1).join('/'));
 
+/** A level's module that refuses: it throws `why` as it runs, so the document's import of it fails with that message,
+ *  which the level's view shows (a load that throws reaches the page as a failed fetch, its reason in the server's log
+ *  alone). */
+const refused = (why: string): string => `throw new Error(${JSON.stringify(why)});`;
+
 /** The URL that serves `file` itself (`/@fs/`, which Vite alone answers), at the content version `version`. */
 const fileUrl = (file: string, version: number): string => `${fsFileUrl(file)}?${MARK}=${version}`;
 
@@ -105,6 +111,26 @@ function sceneModule(root: string, blend: string, read: Set<string>, version: nu
   ].join('\n');
 }
 
+/** The module's source for a level in code (`levels/<Name>Level.tsx`, from the game's folder): its own component, with
+ *  no environment, canvas settings or grading of std's export, as the level lights itself, its lights' shadows drawn
+ *  as std's starter's `<Canvas shadows="percentage">` draws them; the file goes into `read`. */
+function codeSceneModule(root: string, file: string, read: Set<string>): string {
+  const component = CODE_LEVEL.exec(file)![1]!;
+  read.add(normalizePath(join(root, file)));
+  if (!existsSync(join(root, file))) throw new Error(`${file} is not in the game: a level in code is levels/<Name>Level.tsx.`);
+  return [
+    `import { mountScene as mountLevel } from ${JSON.stringify(RUNTIME)};`,
+    `import { ${component} } from ${JSON.stringify(`/${file}`)};`,
+    `export const component = ${JSON.stringify(file)};`,
+    "export const canvas = { shadows: 'percentage' };",
+    'export const gradingExtra = false;',
+    `const level = { Level: ${component}, Environment: null, canvas: { shadows: 'percentage' } };`,
+    'export const mountScene = (stage) => mountLevel(level, stage);',
+    'export const viewTransform = async () => null;',
+    '',
+  ].join('\n');
+}
+
 /** Whether a module's file is the game's own (in its folder, not a dependency's). */
 function gameFile(root: string, file: string | null): file is string {
   if (file === null) return false;
@@ -132,15 +158,15 @@ export function stdScenePlugin(services: Pick<ProjectServingServices, 'currentPr
     const root = services.currentProjectRoot();
     return root && existsSync(join(root, 'std.json')) ? root : null;
   };
-  /** Each level's latest Scene module, by its `.blend`: its id and the files its source was written from. */
+  /** Each level's latest Scene module, by its level: its id and the files its source was written from. */
   const scenes = new Map<string, { readonly id: string; readonly read: ReadonlySet<string> }>();
   /** The game's content version, which every URL a game's module imports carries: a loader's cache keyed by the URL
-   *  loads anew whatever a Scene view depends on changed. */
+   *  loads anew whatever a level's document depends on changed. */
   let version = Date.now();
   return {
     name: 'volter-play-std-scene',
     enforce: 'pre',
-    // (a std game's Scene view and its levels' modules prebundled as the session starts: found on the view's first open,
+    // (a std game's level documents and its levels' modules prebundled as the session starts: found on the view's first open,
     // Vite would optimize them again then, and the editor's page, which does not reload for it, would hold two copies of
     // React. The levels' files are crawled, and the runtime's own packages are included where the game has them)
     config() {
@@ -163,27 +189,28 @@ export function stdScenePlugin(services: Pick<ProjectServingServices, 'currentPr
       }
       if (!source.startsWith(PREFIX)) return null;
       const [path = '', query = ''] = source.slice(PREFIX.length).split('?');
-      const blend = decodeURIComponent(path);
-      if (!LEVEL.test(blend)) throw new Error(`${blend} is not a std level's Blender file (levels/<name>.blend).`);
+      const level = decodeURIComponent(path);
+      if (!BLEND_LEVEL.test(level) && !CODE_LEVEL.test(level))
+        throw new Error(`${level} is not a std level: a level's Blender file (levels/<name>.blend) or a level in code (levels/<Name>Level.tsx).`);
       // (each of the view's imports is a module of its own, written from the level's files as they are then)
-      return `${VIRTUAL}${blend}?${query}`;
+      return `${VIRTUAL}${level}?${query}`;
     },
     load(id) {
       if (id === RUNTIME_ID) return readFileSync(RUNTIME_FILE, 'utf8');
       if (id.startsWith(VIRTUAL)) {
         const root = stdGame();
-        if (!root) throw new Error('The open project is not a std game (no std.json), so it has no level to draw.');
-        const blend = id.slice(VIRTUAL.length).replace(/\?.*$/, '');
+        if (!root) return refused('The open project is not a std game (no std.json), so it has no level to draw.');
+        const level = id.slice(VIRTUAL.length).replace(/\?.*$/, '');
         const read = new Set<string>();
-        scenes.set(blend, { id, read });
-        return sceneModule(root, blend, read, version);
+        scenes.set(level, { id, read });
+        return CODE_LEVEL.test(level) ? codeSceneModule(root, level, read) : sceneModule(root, level, read, version);
       }
       const [file = id, query] = id.split('?');
       const root = query === 'url' ? stdGame() : null;
       if (!root || !gameFile(root, file)) return null;
       return `export default ${JSON.stringify(fileUrl(file, version))};`;
     },
-    // (a Scene view depends on its module's whole import closure among the game's files, the modules whose import failed
+    // (a level's document depends on its module's whole import closure among the game's files, the modules whose import failed
     // to resolve within it and the files its source was written from. Any file of those written, made or removed bumps
     // the content version, invalidates the closure, so each of its modules and URLs is served anew, and is announced on
     // the session's change channel naming the levels it reached)

package/src/editor-blender.ts

@@ -1,19 +1,14 @@
 /**
- * EDITOR-BLENDER'S API, AS PLAY'S PAGE HALF KEPT IT (`../contributions/play.page.tsx`), and the model
- * Play that page half registered through it. play's modules read them here rather than importing
- * editor-blender's modules: its API is the one instance editor-blender's own `activate` returned.
+ * EDITOR-BLENDER'S API, AS PLAY'S PAGE HALF KEPT IT (`../contributions/play.page.tsx`). play's modules read it here
+ * rather than importing editor-blender's modules: its API is the one instance editor-blender's own `activate` returned.
  */
-import type { BlenderPageApi, DocumentPlayExtension } from '@volter/editor-blender/api';
+import type { BlenderPageApi } from '@volter/editor-blender/api';
 
 let api: BlenderPageApi | null = null;
-let modelPlay: DocumentPlayExtension | null = null;
-const listeners = new Set<() => void>();
 
 /** Kept by play's `activate`, and released (`null`) when it deactivates. */
-export function keepEditorBlender(next: BlenderPageApi | null, registered: DocumentPlayExtension | null): void {
+export function keepEditorBlender(next: BlenderPageApi | null): void {
   api = next;
-  modelPlay = registered;
-  for (const listener of listeners) listener();
 }
 
 /** editor-blender's API. play's modules run once its page half has activated, which is after editor-blender's. */
@@ -21,13 +16,3 @@ export function editorBlender(): BlenderPageApi {
   if (!api) throw new Error("@volter/play is not active, so editor-blender's API is not at hand.");
   return api;
 }
-
-/** The model Play play registered, or `null` while it is not. */
-export function registeredModelPlay(): DocumentPlayExtension | null {
-  return modelPlay;
-}
-
-export function subscribeRegisteredModelPlay(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => { listeners.delete(listener); };
-}

package/src/editor-threejs.ts

@@ -1,6 +1,6 @@
 /**
  * EDITOR-THREEJS'S API, AS PLAY'S PAGE HALF KEPT IT (`../contributions/play.page.tsx`): the shared viewport and its
- * stages, which a std level's Scene view draws in (`../contributions/std-scene.document.tsx`). play reads it here rather than importing
+ * stages, which a std level in code is drawn in (`../contributions/std-level.document.tsx`). play reads it here rather than importing
  * editor-threejs's modules: its API is the one instance editor-threejs's own `activate` returned.
  */
 import type { ThreePageApi } from '@volter/editor-threejs/api';