@volter/play 0.5.211 → 0.5.213

package/contributions/std-level.document.tsx

@@ -0,0 +1,477 @@
+/**
+ * A STD GAME'S LEVEL AS ITS DOCUMENT (`docs/adr/std-scene-view.md`): `levels/<Name>Level.tsx`, a document of the
+ * project's table (`levels.finder.ts`) whose source is its code or the `.blend` std's export writes it from, drawn as
+ * the game draws it, by its own component and the game's own React
+ * Three Fiber, react-three-rapier and std, in editor-threejs's viewport (`ThreePageApi`): orbit, pick, frame, the
+ * Hierarchy.
+ * The level's module is `/@volter-std-scene/<level>` (`../serving/std-scene.ts`); its fiber root draws on
+ * the stage's own renderer and camera, the stage drawing the picture, the level's `useFrame`s run on the stage's frame,
+ * and its environment is the document's World (editor-threejs's `documentWorld`). The level follows the stage the
+ * document has now: an attachment the stage makes again (after a lost context) is bound anew.
+ *
+ * - The level's `<Canvas>` settings are the view's presentation: Rendered shading lit by the scene alone, its backdrop
+ *   the scene's own (the level's sky), its tone mapping the canvas's; its shadows are the renderer's.
+ * - Its view transform (std's shaper and baked LUT) is the stage's display transform; a grading with effects beyond it
+ *   is named in the banner, as the view does not draw them.
+ * - The overlays: colliders and sensors as react-three-rapier's debug lines of the paused world, and each std marker (an
+ *   object whose `userData.behaviours` names its behaviours: a spawn point, a seat, a prompt) as a marker and its name,
+ *   on the stage's helper layer (`std-markers`). The toolbar's Overlays shows or hides them.
+ * - The level's source is its record, a Blender level's `.blend` or a level's code: the view edits nothing. A Blender
+ *   level's save exports it again (`../src/std-level.ts`), a code level's file is its own, and the view draws it again
+ *   as anything its module depends on changes (a model a code level places among them), the camera kept.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import * as THREE from 'three';
+import type { DocumentDisplayTransform, ViewportStage } from '@volter/editor-threejs/api';
+import type { ToolContributionProps } from '@volter/sdk/contributions';
+import { projectModuleChangeMatches, subscribeProjectModuleChange } from '@volter/sdk/project-module-changes';
+import { beginLiveModuleRevision } from '@volter/sdk/project-module-url';
+import type { PresentationLayer } from '@volter/sdk/viewport-presentation';
+import { editorThreejs } from '../src/editor-threejs';
+import { askPlay } from '../src/std-controls';
+import { stdRun, stdRunVersion, subscribeStdRun } from '../src/std-game';
+
+export const point = 'workspace.document';
+export const title = 'Level';
+/** The editor of the table's `std-level` documents: a level in code (`levels.finder.ts`). */
+export const documentKind = 'std-level';
+
+/** The level's module, as `../serving/std-scene.ts` writes it. */
+interface StdSceneModule {
+  readonly component: string;
+  readonly canvas: { readonly gl?: { readonly toneMapping?: THREE.ToneMapping; readonly toneMappingExposure?: number } };
+  readonly gradingExtra: boolean;
+  mountScene(args: {
+    readonly renderer: THREE.WebGLRenderer;
+    readonly world: THREE.Scene;
+    readonly camera: THREE.Camera;
+    readonly root: THREE.Group;
+    readonly onError: (error: unknown) => void;
+  }): Promise<MountedScene>;
+  viewTransform(): Promise<(DocumentDisplayTransform & { dispose(): void }) | null>;
+}
+
+interface MountedScene {
+  draw(overlays: boolean): void;
+  advance(seconds: number): void;
+  /** A change of the game's running scene, put on this copy of the level at its next frame ({@link useRunningScene}). */
+  running(read: SceneRead): void;
+  unmount(): void;
+}
+
+/** The viewport's tone mappers, by three's constant: fiber's own default, a canvas stating none, is ACES. */
+const TONE_MAPPERS = new Map<THREE.ToneMapping, 'none' | 'aces' | 'agx'>([
+  [THREE.NoToneMapping, 'none'],
+  [THREE.ACESFilmicToneMapping, 'aces'],
+  [THREE.AgXToneMapping, 'agx'],
+]);
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/** The presentation that draws a level as its canvas does; a string where the canvas asks what the viewport lacks. */
+function canvasPresentation(canvas: StdSceneModule['canvas']): PresentationLayer | string {
+  const toneMapping = canvas.gl?.toneMapping ?? THREE.ACESFilmicToneMapping;
+  const mapper = TONE_MAPPERS.get(toneMapping);
+  if (mapper === undefined) return `The level's canvas tone-maps with three's mapper ${toneMapping}, which the viewport does not draw (it draws none, ACES and AgX).`;
+  return {
+    drawMode: 'rendered',
+    all: {
+      lighting: { source: 'scene', auto: null, tone: { mapper, exposure: canvas.gl?.toneMappingExposure ?? 1 } },
+      backdrop: { source: 'scene' },
+    },
+  };
+}
+
+const MARKER_COLOURS: Readonly<Record<string, number>> = { spawn: 0x4ade80, seat: 0x60a5fa, prompt: 0xfacc15 };
+
+/** A marker's sign on the helper layer: a diamond at the object's origin and its name and behaviours above it. */
+function markerSign(object: THREE.Object3D, behaviours: readonly string[]): THREE.Object3D {
+  const colour = MARKER_COLOURS[behaviours[0] ?? ''] ?? 0xf472b6;
+  const sign = new THREE.Group();
+  const diamond = new THREE.LineSegments(
+    new THREE.EdgesGeometry(new THREE.OctahedronGeometry(0.3)),
+    new THREE.LineBasicMaterial({ color: colour, depthTest: false, transparent: true }),
+  );
+  diamond.renderOrder = 999;
+  const text = `${object.name || '(unnamed)'} · ${behaviours.join(', ')}`;
+  const canvas = document.createElement('canvas');
+  const context = canvas.getContext('2d')!;
+  context.font = '28px Inter, system-ui, sans-serif';
+  canvas.width = Math.ceil(context.measureText(text).width) + 24;
+  canvas.height = 44;
+  context.font = '28px Inter, system-ui, sans-serif';
+  context.fillStyle = 'rgba(0, 0, 0, 0.6)';
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  context.fillStyle = `#${colour.toString(16).padStart(6, '0')}`;
+  context.fillText(text, 12, 31);
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  const label = new THREE.Sprite(new THREE.SpriteMaterial({ map: texture, depthTest: false, transparent: true }));
+  label.scale.set((0.4 * canvas.width) / canvas.height, 0.4, 1);
+  label.position.y = 0.6;
+  label.renderOrder = 999;
+  sign.add(diamond, label);
+  return sign;
+}
+
+function disposeSigns(signs: THREE.Object3D): void {
+  signs.traverse((object) => {
+    if (object instanceof THREE.LineSegments) { object.geometry.dispose(); (object.material as THREE.Material).dispose(); }
+    if (object instanceof THREE.Sprite) { object.material.map?.dispose(); object.material.dispose(); }
+  });
+}
+
+/** The std markers under `root`: each object whose `userData.behaviours` names any. */
+function markersOf(root: THREE.Object3D): { readonly object: THREE.Object3D; readonly behaviours: readonly string[] }[] {
+  const found: { object: THREE.Object3D; behaviours: readonly string[] }[] = [];
+  root.traverse((object) => {
+    const behaviours = (object.userData as { behaviours?: unknown }).behaviours;
+    if (behaviours !== null && typeof behaviours === 'object' && Object.keys(behaviours).length > 0) found.push({ object, behaviours: Object.keys(behaviours) });
+  });
+  return found;
+}
+
+/** The marker signs of `root`, kept on the stage's helper layer at each marker's place, made again as the markers change. */
+function followMarkers(stage: ViewportStage, root: THREE.Object3D, shown: () => boolean): () => void {
+  let signature = '';
+  let signs: THREE.Group | null = null;
+  let objects: THREE.Object3D[] = [];
+  const stop = stage.onFrame(() => {
+    if (!shown()) {
+      if (signs) { stage.setHelper('std-markers', null); disposeSigns(signs); signs = null; signature = ''; }
+      return;
+    }
+    const markers = markersOf(root);
+    const next = markers.map(({ object, behaviours }) => `${object.uuid}:${behaviours.join(',')}`).join('|');
+    if (next !== signature) {
+      signature = next;
+      if (signs) disposeSigns(signs);
+      signs = new THREE.Group();
+      signs.name = 'std markers';
+      for (const { object, behaviours } of markers) signs.add(markerSign(object, behaviours));
+      objects = markers.map(({ object }) => object);
+      stage.setHelper('std-markers', signs);
+    }
+    objects.forEach((object, index) => signs!.children[index]!.position.setFromMatrixPosition(object.matrixWorld));
+  });
+  return () => {
+    stop();
+    stage.setHelper('std-markers', null);
+    if (signs) disposeSigns(signs);
+  };
+}
+
+/** What a binding of the level to one stage reads and reports. */
+interface StageBinding {
+  readonly documentId: string;
+  readonly module: StdSceneModule;
+  readonly transform: DocumentDisplayTransform | null;
+  readonly root: THREE.Group;
+  readonly overlays: () => boolean;
+  readonly mounted: (scene: MountedScene, live: boolean) => void;
+  readonly framed: () => void;
+  readonly fail: (error: unknown) => void;
+}
+
+/**
+ * Each canvas's fiber lifetimes, one after another. Fiber keeps one root per canvas, and a root made on a canvas whose
+ * root is closing takes that root over; so a binding makes its root only once the binding before it on that canvas has
+ * ended its own, and the root a binding made is the one it alone ends.
+ */
+const canvasTurns = new WeakMap<HTMLCanvasElement, Promise<void>>();
+function onCanvas(canvas: HTMLCanvasElement, turn: () => Promise<void>): void {
+  const next = (canvasTurns.get(canvas) ?? Promise.resolve()).then(turn);
+  canvasTurns.set(canvas, next.catch(() => {}));
+}
+
+/**
+ * The level drawn on one stage attachment, as one generation: a fiber root on the attachment's renderer, its frames on
+ * the stage's frame, its markers and its view transform. The answer ends the generation; each of its async steps asks
+ * whether it is still current before it draws or installs anything, and the root it made it ends itself, after its
+ * last step. An attachment the stage makes again (a lost context) has another renderer, and is another generation.
+ */
+function bindStage(stage: ViewportStage, binding: StageBinding): () => void {
+  const { documentId, module, transform, root } = binding;
+  const three = editorThreejs();
+  const world = three.documentWorld(root);
+  if (world === null) {
+    binding.fail(new Error("The level's root stands in no document scene of its stage."));
+    return () => {};
+  }
+  const rig = stage.rig();
+  let current = true;
+  let transformed = false;
+  let ended!: () => void;
+  const end = new Promise<void>((resolve) => { ended = resolve; });
+  const hooks: (() => void)[] = [];
+  onCanvas(rig.renderer.domElement, async () => {
+    if (!current) return;
+    let scene: MountedScene;
+    try {
+      scene = await module.mountScene({ renderer: rig.renderer, world, camera: rig.camera, root, onError: binding.fail });
+    } catch (error) {
+      binding.fail(error);
+      return;
+    }
+    // (from here this generation holds the canvas's root, and ends it below, whatever comes)
+    if (current) {
+      scene.draw(binding.overlays());
+      binding.mounted(scene, true);
+      hooks.push(stage.onFrame(() => {
+        scene.advance(performance.now() / 1000);
+        // (the stage's session stands after its rig: the transform and the framing wait for it)
+        if (transform !== null && !transformed) transformed = three.setDisplayTransform(documentId, transform);
+        binding.framed();
+      }));
+      hooks.push(followMarkers(stage, root, binding.overlays));
+    }
+    await end;
+    binding.mounted(scene, false);
+    scene.unmount();
+  });
+  return () => {
+    current = false;
+    for (const hook of hooks.splice(0).reverse()) hook();
+    if (transformed) three.setDisplayTransform(documentId, null);
+    ended();
+  };
+}
+
+export default function StdLevelDocument({ documentId: given, document, active }: ToolContributionProps) {
+  const level = document?.source?.path ?? null;
+  const documentId = given ?? `level:${level ?? ''}`;
+  // (the level in front last is the current level, which the Game view's Scene shows live)
+  useEffect(() => (active !== false && level !== null ? noteCurrentLevel(level, document?.label ?? level) : undefined), [active, level, document?.label]);
+  return <StdLevelView documentId={documentId} level={level} label={document?.label ?? level} live={false} />;
+}
+
+/** THE CURRENT LEVEL: the level document in front last, which the Game view's Scene draws live; null before any. */
+let currentLevel: { readonly path: string; readonly label: string } | null = null;
+const currentListeners = new Set<() => void>();
+function noteCurrentLevel(path: string, label: string): undefined {
+  if (currentLevel?.path !== path || currentLevel.label !== label) {
+    currentLevel = { path, label };
+    for (const listener of [...currentListeners]) listener();
+  }
+  return undefined;
+}
+export const currentStdLevel = (): { readonly path: string; readonly label: string } | null => currentLevel;
+export function subscribeCurrentStdLevel(listener: () => void): () => void {
+  currentListeners.add(listener);
+  return () => { currentListeners.delete(listener); };
+}
+
+/**
+ * A LEVEL'S VIEW: the level drawn as the game draws it, as authored (its document), or LIVE (the Game view's Scene,
+ * `../src/game-view.tsx`), the game's running scene put on this view's own copy of the level ({@link useRunningScene}).
+ * The same view, code and overlays either way.
+ */
+export function StdLevelView({ documentId, level, label, live }: {
+  readonly documentId: string;
+  readonly level: string | null;
+  readonly label: string | null;
+  /** Live, it reads the running scene while the game runs, drawn or not: its copy of the level is the Hierarchy's. */
+  readonly live: boolean;
+}) {
+  const { Object3DDocumentViewport, frameAll } = editorThreejs();
+  const root = useMemo(() => {
+    const group = new THREE.Group();
+    group.name = 'Level';
+    return group;
+  }, []);
+  const build = useCallback(() => ({ root, dispose() {} }), [root]);
+  const [revision, setRevision] = useState(() => beginLiveModuleRevision());
+  const [overlays, setOverlays] = useState(true);
+  const overlaysRef = useRef(overlays);
+  overlaysRef.current = overlays;
+  const [drawn, setDrawn] = useState<{ readonly presentation: PresentationLayer; readonly component: string } | null>(null);
+  const [notes, setNotes] = useState<{ readonly error: string | null; readonly gradingExtra: boolean }>({ error: null, gradingExtra: false });
+  const mounted = useRef<MountedScene | null>(null);
+  /** The level the camera was framed on, once its content first stood. */
+  const framed = useRef<string | null>(null);
+
+  // (the level drawn again as anything its module depends on is written, made or removed: play's serving half reads
+  // that from the session's module graph and names the levels a change reached, `../serving/std-scene.ts`)
+  useEffect(() => {
+    if (level === null) return;
+    return subscribeProjectModuleChange((_changed, affected) => {
+      if (affected?.some((path) => projectModuleChangeMatches(path, level))) setRevision(beginLiveModuleRevision());
+    });
+  }, [level]);
+
+  useEffect(() => {
+    if (level === null) return;
+    const three = editorThreejs();
+    let disposed = false;
+    let transform: (DocumentDisplayTransform & { dispose(): void }) | null = null;
+    let stopStages: (() => void) | null = null;
+    let bound: THREE.WebGLRenderer | null = null;
+    let unbind: (() => void) | null = null;
+    const fail = (error: unknown): void => { if (!disposed) setNotes((now) => ({ ...now, error: `${level}: ${message(error)}` })); };
+    void (async () => {
+      // (`import` is Vite's mark for a module import: without it a path ending `.blend` is not one Vite transforms, and
+      // the request answers 404)
+      const module = (await import(/* @vite-ignore */ `/@volter-std-scene/${level}?import&v=${revision}`)) as StdSceneModule;
+      if (disposed) return;
+      const look = canvasPresentation(module.canvas);
+      if (typeof look === 'string') { fail(new Error(look)); return; }
+      setDrawn((now) => (now?.component === module.component && JSON.stringify(now.presentation) === JSON.stringify(look) ? now : { presentation: look, component: module.component }));
+      setNotes({ error: null, gradingExtra: module.gradingExtra });
+      const made = await module.viewTransform();
+      if (disposed) { made?.dispose(); return; }
+      transform = made;
+      const binding: StageBinding = {
+        documentId, module, transform: made, root, fail,
+        overlays: () => overlaysRef.current,
+        mounted: (scene, live) => {
+          if (live) mounted.current = scene;
+          else if (mounted.current === scene) mounted.current = null;
+        },
+        // (framed once a level, as its content first stands: a draw again keeps the camera)
+        framed: () => {
+          if (framed.current !== level && !new THREE.Box3().setFromObject(root).isEmpty() && frameAll(documentId)) framed.current = level;
+        },
+      };
+      // (the level follows the stage attachment the document has now, known by its renderer: the stage doors are made
+      // again as any stage binds or goes, its attachment made again after a lost context has another renderer)
+      const follow = (): void => {
+        const stage = three.stage(documentId);
+        const renderer = stage?.rig().renderer ?? null;
+        if (renderer === bound) return;
+        unbind?.();
+        unbind = null;
+        bound = renderer;
+        if (stage) unbind = bindStage(stage, binding);
+      };
+      stopStages = three.onStages(follow);
+      follow();
+    })().catch(fail);
+    return () => {
+      disposed = true;
+      stopStages?.();
+      unbind?.();
+      transform?.dispose();
+    };
+  }, [documentId, frameAll, level, revision, root]);
+
+  useEffect(() => { mounted.current?.draw(overlays); }, [overlays]);
+
+  useRunningScene(live, mounted, useCallback(() => setRevision(beginLiveModuleRevision()), []));
+
+  if (level === null) {
+    return <div data-testid="std-level-empty" style={{ padding: 16, font: '12px Inter, system-ui, sans-serif' }}>
+      This document names no level: a level in code is levels/&lt;Name&gt;Level.tsx.
+    </div>;
+  }
+  const banner = notes.error ?? (notes.gradingExtra ? "The level's grading holds effects beyond its view transform, which this view does not draw: the game shows them." : null);
+  return (
+    // (filled from the host box, as the editor's other documents are: in an editor group's auto-height content box
+    // `height: 100%` resolves to the content's height, which left the stage a strip)
+    <div data-testid="std-level" style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', overflow: 'hidden' }}>
+      <div role="toolbar" aria-label="Level" style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '2px 8px', font: '11px Inter, system-ui, sans-serif' }}>
+        <span data-testid="std-level-path">{level}</span>
+        <label style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+          <input type="checkbox" data-testid="std-level-overlays" checked={overlays} onChange={(event) => setOverlays(event.currentTarget.checked)} />
+          Overlays (colliders, sensors, markers)
+        </label>
+      </div>
+      {banner !== null && <div role={notes.error ? 'alert' : 'status'} data-testid="std-level-banner" style={{ padding: '4px 8px', font: '11px Inter, system-ui, sans-serif', background: notes.error ? 'rgba(220, 38, 38, 0.25)' : 'rgba(250, 204, 21, 0.2)' }}>{banner}</div>}
+      <div style={{ position: 'relative', flex: 1, minHeight: 0 }}>
+        {drawn !== null && (
+          <Object3DDocumentViewport documentId={documentId} sourcePath={drawn.component} displayName={label ?? level} build={build}
+            stageKind={documentKind} presentation={drawn.presentation} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** One object of the game's running scene as std reads it (room/shared's scene-reading.ts). */
+interface SceneObject {
+  readonly path: string;
+  readonly type: string;
+  readonly x: number; readonly y: number; readonly z: number;
+  readonly qx: number; readonly qy: number; readonly qz: number; readonly qw: number;
+  readonly sx: number; readonly sy: number; readonly sz: number;
+  readonly visible: boolean;
+}
+
+/** What changed in the game's running scene since an earlier reading (`GET /__std/scene`), and where it runs: `room:<id>`
+ *  for the world the server runs, else the device whose page renders it. */
+interface SceneRead {
+  readonly of: string;
+  readonly scene: string;
+  readonly at: number;
+  readonly whole: boolean;
+  readonly objects: readonly SceneObject[];
+  readonly gone: readonly string[];
+}
+
+/** A reading of the running scene, or none (`of: null`) where it runs nowhere yet. */
+type RunningScene = SceneRead | { readonly of: null };
+
+/** How often the running scene is read again while the game runs (ms): one reading at a time. */
+const SCENE_ASK_MS = 50;
+
+/**
+ * A LIVE LEVEL VIEW IS THE PLAYING WORLD while the game runs (the Game view's Scene), as an engine's scene view is
+ * during Play: the game's running scene, read where it runs (std-dev's `/__std/scene`, through Play's serving half),
+ * each change put on the view's own copy of the level by the runtime (`../serving/std-scene-runtime.js`'s
+ * `SceneNodes`), so its picking and overlays are the level view's own. The scene read is the world's authority: the one
+ * the game's server runs, where it runs one, else the one the viewed player's page renders (the first player's while the
+ * view is Scene or Grid), a game of one player's among them. Each reading names the one held, so a new scene, or another
+ * place it runs, answers whole, and so does the first reading of each copy of the level (a run's start, an edit's
+ * remount), which holds none. When the game stops, the level is drawn again as authored.
+ */
+function useRunningScene(live: boolean, mounted: { readonly current: MountedScene | null }, again: () => void): void {
+  useSyncExternalStore(subscribeStdRun, stdRunVersion, stdRunVersion);
+  const running = live && (stdRun()?.url ?? null) !== null;
+  const againRef = useRef(again);
+  againRef.current = again;
+  // (the run over, the level drawn again as authored)
+  useEffect(() => {
+    if (!running) return undefined;
+    return () => { againRef.current(); };
+  }, [running]);
+  useEffect(() => {
+    if (!running) return;
+    let ended = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    /** The reading held: the scene read last, and its `at`. */
+    let last: { readonly scene: string; readonly at: number } = { scene: '', at: 0 };
+    let fed: MountedScene | null = null;
+    // (the viewed player's page, or the first player's: where a game the server runs no world for plays)
+    const viewedDevice = (): string | null => {
+      const run = stdRun();
+      const player = run === null ? undefined : typeof run.view === 'number' ? run.players[run.view] : run.players[0];
+      return player?.device ?? null;
+    };
+    // (the reading held, named to whichever place is read: a place that runs another scene answers it whole)
+    const held = (): string => `scene=${encodeURIComponent(last.scene)}&since=${last.at}&`;
+    const readScene = async (): Promise<RunningScene> => {
+      const server = await askPlay<RunningScene>(`/scene?${held()}`);
+      if (server.of !== null) return server;
+      const device = viewedDevice();
+      if (device === null) return server;
+      return askPlay<RunningScene>(`/scene?${held()}of=${encodeURIComponent(device)}`);
+    };
+    void (async () => {
+      while (!ended) {
+        const copy = mounted.current;
+        // (a new copy holds no scene, which std answers whole: what the game removed before it is hidden on it too)
+        if (copy !== fed) { fed = copy; last = { scene: '', at: 0 }; }
+        const read = copy === null ? null : await readScene().catch(() => null);
+        if (ended) return;
+        if (read !== null && read.of !== null && copy !== null && copy === mounted.current) {
+          last = { scene: read.scene, at: read.at };
+          copy.running(read);
+        }
+        await new Promise<void>((done) => { timer = setTimeout(done, SCENE_ASK_MS); });
+      }
+    })();
+    return () => {
+      ended = true;
+      clearTimeout(timer);
+    };
+  }, [mounted, running]);
+}