@volter/play 0.5.211 → 0.5.213

package/serving/std-scene-runtime.js

@@ -0,0 +1,240 @@
+/**
+ * THE SCENE VIEW'S RUNTIME, served from the std game's own module graph (`./std-scene.ts`, the id
+ * `\0volter-std-scene-runtime`): its imports resolve as the game's, so the fiber root, react-three-rapier and std's
+ * effects are the game's own instances, the very ones the level's components use. A level's module (`./std-scene.ts`'s
+ * `sceneModule`) names its files and hands them here. It is a browser module, not part of play's page bundle, because
+ * play's page carries none of the game's libraries.
+ */
+import { Component, createElement as h } from 'react';
+import * as THREE from 'three';
+import { advance, createPortal, createRoot, extend, useFrame } from '@react-three/fiber';
+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';
+
+// (a root made by createRoot knows no three.js element until it is told, as <Canvas> tells its own)
+extend(THREE);
+
+/**
+ * THE TREES' LOADS STAY THE GAME'S. The level's components load through fiber's `useLoader`, whose loaders and cache are
+ * fiber's own, shared by every fiber root on the page; nothing here changes them. A file the level's modules import by
+ * URL (`?url`: the glb, the sky, the terrain) carries the game's content version (`./std-scene.ts`), so a new version
+ * is a new URL and a new cache entry. A URL the game's code passes as a plain string, and a glTF's external files, keep
+ * their URL: they show a change on a page reload (`docs/adr/std-scene-view.md`, decision 5).
+ */
+
+/** A frame subscriber of priority 1 takes the render over from fiber, so the stage's own draw is the only one. */
+function StageDraws() {
+  useFrame(() => {}, 1);
+  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 };
+  static getDerivedStateFromError(error) { return { error }; }
+  componentDidCatch(error) { this.props.onError(error); }
+  render() { return this.state.error === null ? this.props.children : null; }
+}
+
+/**
+ * The stage's renderer as fiber holds it. Fiber's unmount releases a renderer it was given (9.8.2's `releaseRenderer`:
+ * for a renderer it did not make, it still calls `forceContextLoss`); the stage's renderer and its context are the
+ * stage's, so fiber holds it through this view, whose `forceContextLoss` and `dispose` leave it to the stage. Every
+ * other member is the renderer's own.
+ */
+function lent(renderer) {
+  return new Proxy(renderer, {
+    get(target, key) {
+      if (key === 'forceContextLoss' || key === 'dispose') return () => {};
+      const value = Reflect.get(target, key, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+    set: (target, key, value) => Reflect.set(target, key, value, target),
+  });
+}
+
+/**
+ * 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;
+ * `<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;
+  const fiber = createRoot(renderer.domElement);
+  const size = renderer.getSize(new THREE.Vector2());
+  const { width, height } = renderer.domElement.style;
+  try {
+    await fiber.configure({ gl: lent(renderer), camera, frameloop: 'never', shadows: canvas.shadows ?? false, flat: true,
+      dpr: renderer.getPixelRatio(), size: { width: size.x, height: size.y, top: 0, left: 0 } });
+  } catch (error) {
+    fiber.unmount();
+    throw error;
+  }
+  // (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),
+      // (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: () => {
+      for (const object of running.made) object.removeFromParent();
+      fiber.unmount();
+    },
+  };
+}
+
+/**
+ * A level's view transform as the stage's display transform: std's `ViewShaperEffect`, then postprocessing's
+ * `LUT3DEffect` on the LUT std baked, read by three's `LUTCubeLoader` as std reads it. Its `dispose` frees the pass, its
+ * effects and the LUT.
+ */
+export async function viewTransform({ lut: url, min, max, exposure }) {
+  const lut = (await new LUTCubeLoader().loadAsync(url)).texture3D;
+  const shaper = new ViewShaperEffect(min, max, exposure);
+  const look = new LUT3DEffect(lut, { tetrahedralInterpolation: true });
+  look.inputColorSpace = THREE.LinearSRGBColorSpace;
+  const pass = new EffectPass(new THREE.PerspectiveCamera(), shaper, look);
+  let initialized = false;
+  return {
+    render(renderer, input, output) {
+      if (!initialized) {
+        pass.initialize(renderer, false, THREE.HalfFloatType);
+        initialized = true;
+      }
+      pass.renderToScreen = output === null;
+      pass.render(renderer, input, output, 0, false);
+    },
+    dispose() {
+      pass.dispose();
+      lut.dispose();
+    },
+  };
+}

package/serving/std-scene.ts

@@ -0,0 +1,240 @@
+/**
+ * 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/
+ * <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 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
+ * level-names.ts `writeGrading`).
+ *
+ * WHAT A VIEW DEPENDS ON is its module's whole import closure among the game's files (Vite's module graph: the level's
+ * components, its prefabs', each URL import, wherever they are), the modules whose import failed to resolve within it,
+ * and the files its source was written from (the grading's LUT among them). A file of those written, made or removed
+ * bumps the game's content version, invalidates the closure and is announced on the session's change channel
+ * (`volter:restart-required`) naming the levels it reached, which their views draw again. Each URL this module writes
+ * (a URL import's, the LUT's) names its file itself (`/@fs/<file>`, which only Vite answers, so the file served is the
+ * file imported) and carries the content version (`?volter-std-scene=`), so a new version is a new URL to the loaders'
+ * cache. A URL the game's code passes as a plain string, and a glTF's external files, keep their URL: they show a
+ * change on a page reload (`docs/adr/std-scene-view.md`, decision 5).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 { BLEND_LEVEL, camel, CODE_LEVEL, levelFiles, pascal } from '../src/std-level-files';
+
+const PREFIX = '/@volter-std-scene/';
+const VIRTUAL = '\0volter-std-scene:';
+/** 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');
+/** The query each URL the Scene module writes carries: the content version it was written at. */
+const MARK = 'volter-std-scene';
+/** 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 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}`;
+
+/** The view transform a level's grading module renders: its LUT file beside it and its shaper's range and exposure. */
+interface ViewGrading {
+  readonly lut: string;
+  readonly min: number;
+  readonly max: number;
+  readonly exposure: number;
+}
+
+/** The module's source for the level whose `.blend` is `blend` (from the game's folder); each file it looks at, present
+ *  or not, goes into `read`. */
+function sceneModule(root: string, blend: string, read: Set<string>, version: number): string {
+  const files = levelFiles(blend);
+  const { base, dir } = files;
+  const level = `${pascal(base)}Level`, environment = `${pascal(base)}Environment`, canvas = `${camel(base)}Canvas`;
+  const exists = (at: string): boolean => {
+    read.add(normalizePath(join(root, at)));
+    return existsSync(join(root, at));
+  };
+  if (!exists(files.component) || !exists(files.canvas)) {
+    throw new Error(`${blend} has no exported level beside it (${files.component} and ${files.canvas}): save it, and std's level export writes them.`);
+  }
+  const hasEnvironment = exists(files.environment);
+  const source = exists(files.grading) ? readFileSync(join(root, files.grading), 'utf8') : null;
+  const shaper = source === null ? null : /<ViewShaper min=\{(-?[\d.]+)\} max=\{(-?[\d.]+)\}(?: exposure=\{(-?[\d.]+)\})? \/>/.exec(source);
+  const lut = source === null ? null : /import viewLut from '\.\/(.+?)\?url';/.exec(source);
+  const grading: ViewGrading | null = shaper !== null && lut !== null
+    ? { lut: join(root, dir, lut[1]!), min: Number(shaper[1]), max: Number(shaper[2]), exposure: Number(shaper[3] ?? 0) } : null;
+  // (the effects the composer holds beyond the shaper and the LUT: a converted level's contrast or saturation)
+  if (grading !== null) read.add(normalizePath(grading.lut));
+  const gradingExtra = source !== null && [...source.matchAll(/^\s+<([A-Z]\w*)\b/gm)]
+    .some((found) => found[1] !== 'EffectComposer' && found[1] !== 'ViewShaper' && found[1] !== 'LUT');
+  return [
+    `import { mountScene as mountLevel, viewTransform as levelTransform } from ${JSON.stringify(RUNTIME)};`,
+    `import { ${level} } from ${JSON.stringify(`/${files.component}`)};`,
+    ...(hasEnvironment ? [`import { ${environment} } from ${JSON.stringify(`/${files.environment}`)};`] : []),
+    `import { ${canvas} } from ${JSON.stringify(`/${files.canvas}`)};`,
+    // (the LUT's address, which its loader fetches as it is: an import of a `.cube` is no asset to Vite, whose import of it
+    // is its text as a module)
+    ...(grading === null ? [] : [`const viewLut = ${JSON.stringify(fileUrl(grading.lut, version))};`]),
+    `export const component = ${JSON.stringify(files.component)};`,
+    `export const canvas = ${canvas};`,
+    `export const gradingExtra = ${String(gradingExtra)};`,
+    `const level = { Level: ${level}, Environment: ${hasEnvironment ? environment : 'null'}, canvas: ${canvas} };`,
+    'export const mountScene = (stage) => mountLevel(level, stage);',
+    grading === null
+      ? 'export const viewTransform = async () => null;'
+      : `export const viewTransform = () => levelTransform({ lut: viewLut, min: ${grading.min}, max: ${grading.max}, exposure: ${grading.exposure} });`,
+    '',
+  ].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;
+  const at = relative(root, file);
+  return !at.startsWith('..') && !at.split(sep).includes('node_modules');
+}
+
+/** The game's modules a module imports, and theirs, all the way down: a level's components, its prefabs', each URL import. */
+function importClosure(graph: EnvironmentModuleGraph, root: string, id: string): Set<EnvironmentModuleNode> {
+  const found = new Set<EnvironmentModuleNode>();
+  const visit = (node: EnvironmentModuleNode): void => {
+    for (const next of node.importedModules) {
+      if (found.has(next) || !gameFile(root, next.file)) continue;
+      found.add(next);
+      visit(next);
+    }
+  };
+  const start = graph.getModuleById(id);
+  if (start) visit(start);
+  return found;
+}
+
+export function stdScenePlugin(services: Pick<ProjectServingServices, 'currentProjectRoot'>): Plugin {
+  const stdGame = (): string | null => {
+    const root = services.currentProjectRoot();
+    return root && existsSync(join(root, 'std.json')) ? root : null;
+  };
+  /** 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 level's document depends on changed. */
+  let version = Date.now();
+  return {
+    name: 'volter-play-std-scene',
+    enforce: 'pre',
+    // (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() {
+      const root = stdGame();
+      if (root === null) return undefined;
+      const include = RUNTIME_PACKAGES.filter((name) => installedFolder(root, name) !== null);
+      return { optimizeDeps: { entries: ['levels/**/*.{ts,tsx}'], include } };
+    },
+    async resolveId(source, importer) {
+      const ours = importer?.startsWith(VIRTUAL) === true || importer === RUNTIME_ID;
+      if (source === RUNTIME && ours) return RUNTIME_ID;
+      const through = THROUGH.get(source);
+      if (through !== undefined && ours) {
+        // (from the owner's installed folder, not the module the owner resolves to: that can be Vite's prebundled copy,
+        // from whose folder the owner's own dependencies don't resolve)
+        const root = stdGame();
+        const owner = root === null ? null : installedFolder(root, through);
+        if (!owner) throw new Error(`${through} is not installed for the game's folder, so its ${source} is not at hand.`);
+        return this.resolve(source, join(owner, 'package.json'), { skipSelf: true });
+      }
+      if (!source.startsWith(PREFIX)) return null;
+      const [path = '', query = ''] = source.slice(PREFIX.length).split('?');
+      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}${level}?${query}`;
+    },
+    load(id) {
+      if (id === RUNTIME_ID) return readFileSync(RUNTIME_FILE, 'utf8');
+      if (id.startsWith(VIRTUAL)) {
+        const root = stdGame();
+        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(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 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)
+    hotUpdate({ file, type, modules, server, timestamp }) {
+      if (this.environment.name !== 'client') return;
+      const root = stdGame();
+      if (!root) return;
+      const graph = this.environment.moduleGraph;
+      const failed = new Set(type === 'create' ? modules : []);
+      const reached = [...scenes].map(([blend, scene]) => ({ blend, scene, closure: importClosure(graph, root, scene.id) }))
+        .filter(({ scene, closure }) => {
+          const start = graph.getModuleById(scene.id);
+          return scene.read.has(file) || (start !== undefined && failed.has(start))
+            || [...closure].some((node) => node.file === file || failed.has(node));
+        });
+      if (reached.length === 0) return;
+      version += 1;
+      const seen = new Set<EnvironmentModuleNode>();
+      for (const { closure } of reached) for (const node of closure) graph.invalidateModule(node, seen, timestamp, true);
+      server.ws.send({
+        type: 'custom',
+        event: 'volter:restart-required',
+        data: { file, path: relative(root, file).replaceAll('\\', '/'), type, affected: reached.map(({ blend }) => blend) },
+      });
+    },
+  };
+}

package/src/editor-blender.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 } from '@volter/editor-blender/api';
+
+let api: BlenderPageApi | null = null;
+
+/** Kept by play's `activate`, and released (`null`) when it deactivates. */
+export function keepEditorBlender(next: BlenderPageApi | null): void {
+  api = next;
+}
+
+/** editor-blender's API. play's modules run once its page half has activated, which is after editor-blender's. */
+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;
+}

package/src/editor-threejs.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 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';
+
+let api: ThreePageApi | null = null;
+
+/** Kept by play's `activate`, and released (`null`) when it deactivates. */
+export function keepEditorThreejs(next: ThreePageApi | null): void {
+  api = next;
+}
+
+/** editor-threejs's API. play's modules run once its page half has activated, which is after editor-threejs's. */
+export function editorThreejs(): ThreePageApi {
+  if (!api) throw new Error("@volter/play is not active, so editor-threejs's API is not at hand.");
+  return api;
+}

package/src/game-controls.ts

@@ -0,0 +1,111 @@
+/**
+ * THE GAME'S CONTROLS, which the Game panel draws (`../contributions/game-panel.tsx`) and its verbs run behind command
+ * ids (`volter.play.<verb>`): Play and Stop, pause, step, speed, Restart and Autoplay, each a call on the run
+ * (`game-run.ts`) or std's own control said to the game's pages (`std-game.ts`, `std-controls.ts`).
+ *
+ * PLAY SAVES THE EDIT FIRST: Play (and Restart) save the `.blend` Blender holds where it changed (a level's or a
+ * prefab's, whichever was edited last), which runs std's level export (`std-level.ts`), and the run's pages load once
+ * that export has run, so the game plays the current edit (`savedEdit`). A save that fails is said in the play log, and
+ * the game plays the level as last exported.
+ *
+ * AUTOPLAY IS THE EDITOR'S SWITCH, and the person always wins: std's own play of one of the game's goals, recorded and
+ * checked, on the player in view while the Game view is on screen and out of view otherwise (`std-game.ts`'s
+ * `setStdAutoplay`); a person's own press in the player's page takes it back, which ends the play. Stopped, it is
+ * armed for the next start.
+ */
+import { armGameAutoplay, gameArm, gamePlaying, restartGame, setGamePlaying, subscribeGameClock } from './game-run';
+import { setStdAutoplay, setStdPaused, setStdSpeed, stdAutoplay, stdRun, stepStd, subscribeStdRun } from './std-game';
+
+/** Autoplay as the panel reads it: on or off, whether it can be switched on and why not, armed
+ *  while stopped, the goals the game's bot offers and the one it plays, and how std's own play of a goal stands
+ *  (`<goal>: playing`, `achieved`, or `failed — why`, `headless ` before it where it plays out of view). */
+export interface GameAutoplay {
+  /** Whether std's play of a goal plays now, wherever it plays (Off ends it). */
+  readonly on: boolean;
+  /** Whether that play drives the player in view, on its page. */
+  readonly driving?: boolean;
+  readonly available: boolean;
+  readonly unavailable?: string | null;
+  readonly armed?: boolean;
+  readonly behaviors?: readonly string[];
+  readonly behavior?: string | null;
+  readonly state?: string | null;
+  /** std's play's report (`build/runs/<run>/report-<n>.json`), once std has written it. */
+  readonly report?: string | null;
+}
+
+/** The save Play runs first (play's page half keeps it, `play.page.tsx`), and the last one Play asked for. */
+let saveEdit: (() => Promise<string | null>) | null = null;
+let saving: Promise<string | null> = Promise.resolve(null);
+
+/** Kept by play's page half while it is active: what saves the edit Blender holds, answering why it failed, if it
+ *  did. */
+export function keepEditSave(save: (() => Promise<string | null>) | null): void {
+  saveEdit = save;
+}
+
+/** The save the run's start waits for, answering why it failed (null: saved, or nothing to save). */
+export const savedEdit = (): Promise<string | null> => saving;
+
+function save(): void {
+  saving = saveEdit?.() ?? Promise.resolve(null);
+}
+
+/** Play (the edit saved first) or Stop. */
+export function playGame(on: boolean): void {
+  if (on && !gamePlaying()) save();
+  setGamePlaying(on);
+}
+
+/** Restart: the edit saved, every player's page loaded afresh; a game not playing simply starts. */
+export function restartPlay(): void {
+  if (!gamePlaying()) { playGame(true); return; }
+  save();
+  restartGame();
+}
+
+export const pauseGame = (paused: boolean): Promise<void> => setStdPaused(paused).then(() => {});
+export const stepGame = (frames = 1): Promise<void> => stepStd(frames).then(() => {});
+export const setGameSpeedOf = (speed: number): Promise<void> => setStdSpeed(speed);
+
+/** Every change of the clock or the run, which Autoplay's state follows. */
+export function subscribeGameControls(listener: () => void): () => void {
+  const stopClock = subscribeGameClock(listener), stopRun = subscribeStdRun(listener);
+  return () => { stopClock(); stopRun(); };
+}
+
+/** The last autoplay state read, and the state it was read over: one snapshot until it changes. */
+let snapshot: { readonly key: string; readonly value: GameAutoplay } | null = null;
+
+export function gameAutoplay(): GameAutoplay {
+  const arm = gameArm();
+  const running = stdRun() !== null;
+  const { on, driving, goal, goals, unavailable, played } = stdAutoplay();
+  const value: GameAutoplay = {
+    on: running && on,
+    driving: running && driving,
+    available: running ? on || unavailable === null : arm === null && goals.length > 0,
+    unavailable: running && !on ? unavailable : null,
+    armed: arm !== null,
+    behaviors: goals,
+    behavior: arm !== null ? arm.goal ?? goal : goal,
+    state: played === null ? null
+      : `${played.device === 'headless' ? 'headless ' : ''}${played.goal}: ${played.state === 'failed' ? `failed — ${played.why ?? 'std did not say why'}` : played.state}`
+        + (played.checks === null ? '' : ` · ${played.checks}`),
+    report: played?.report ?? null,
+  };
+  const key = JSON.stringify(value);
+  if (snapshot?.key !== key) snapshot = { key, value };
+  return snapshot.value;
+}
+
+/** Switch the bot on (the game playing) or off, with `goal` (the game's own when absent). */
+export function setGameAutoplay(on: boolean, by: 'panel' | 'cli', goal?: string): Promise<void> {
+  if (!stdRun()) throw new Error('Nothing is playing; `play` starts it, then `play autoplay on`.');
+  return setStdAutoplay(on, by, goal);
+}
+
+/** Arm (or disarm) Autoplay for the next start, while stopped. */
+export function armAutoplay(armed: boolean, goal?: string): void {
+  armGameAutoplay(armed, goal ?? null);
+}