@volter/play 0.5.210 → 0.5.212

package/serving/std-scene.ts

@@ -0,0 +1,213 @@
+/**
+ * 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
+ * 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),
+ * `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 { camel, 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. */
+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
+ *  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). */
+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('/'));
+
+/** 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');
+}
+
+/** 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 `.blend`: 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. */
+  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,
+    // 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 blend = decodeURIComponent(path);
+      if (!LEVEL.test(blend)) throw new Error(`${blend} is not a std level's Blender file (levels/<name>.blend).`);
+      // (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}`;
+    },
+    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(/\?.*$/, '');
+        const read = new Set<string>();
+        scenes.set(blend, { id, read });
+        return sceneModule(root, blend, 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
+    // 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,33 @@
+/**
+ * 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.
+ */
+import type { BlenderPageApi, DocumentPlayExtension } 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 {
+  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. */
+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

@@ -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's Scene view draws in (`../contributions/std-scene.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;
+}