@volter/play 0.5.210 → 0.5.212

package/src/std-level-files.ts

@@ -0,0 +1,33 @@
+/**
+ * A STD LEVEL'S GENERATED FILES, named from its `.blend` as std's level export names them (std-dev's level-names.ts
+ * `levelNames`, beside `writeGrading`): the files the Scene view's module is written from (`../serving/std-scene.ts`).
+ */
+
+/** std's PascalCase and camelCase of a level's base name (std-dev's level-names.ts `pascal` and `camel`). */
+export const pascal = (name: string): string =>
+  name.replace(/(^|[^A-Za-z0-9]+)([A-Za-z0-9])/g, (_m, _s, c: string) => c.toUpperCase()).replace(/^[0-9]/, (d) => `L${d}`);
+export const camel = (name: string): string => {
+  const p = pascal(name);
+  return p.charAt(0).toLowerCase() + p.slice(1);
+};
+
+/** A level's generated files, from the game's folder, for its `.blend` (`levels/<name>.blend`). */
+export function levelFiles(blend: string): {
+  readonly base: string;
+  readonly dir: string;
+  readonly component: string;
+  readonly environment: string;
+  readonly canvas: string;
+  readonly grading: string;
+} {
+  const dir = blend.slice(0, blend.lastIndexOf('/'));
+  const base = blend.slice(dir.length + 1).replace(/\.blend$/, '');
+  return {
+    base,
+    dir,
+    component: `${dir}/${pascal(base)}Level.tsx`,
+    environment: `${dir}/${pascal(base)}Environment.tsx`,
+    canvas: `${dir}/${base}.canvas.ts`,
+    grading: `${dir}/${base}.grading.tsx`,
+  };
+}

package/src/std-level.ts

@@ -0,0 +1,107 @@
+/**
+ * A STD GAME IN CYCLOTRON'S BLENDER. Where the project is a std game (`std-game.ts`'s `isStdGame`):
+ *
+ * - EACH SAVE OF A LEVEL'S `.blend` (`levels/**\/*.blend`) OR A PREFAB'S (`prefabs/<name>/<name>.blend`, std's) RUNS ITS
+ *   EXPORT, its two halves (std's guide, "Levels": a prefab's export writes its component, `prefabs/<name>/<Name>.tsx`,
+ *   which a level that places it needs first; each save exports, so a prefab saved is exported before the level that
+ *   places it is next saved). The
+ *   Blender half, std-dev's `blend-to-scene.py`, is the save's own script (editor-blender's `modelDocument.setSaveScript`):
+ *   it runs in the save's turn, on the very scene that save wrote, before anything else reaches that Blender, and the
+ *   save's answer carries the files it wrote (`levels/<name>.glb` and what goes beside it). Then, one save after another,
+ *   those files are carried into the project and the Node half, `std level <glb> --description <json>`, runs in the
+ *   game's folder (`../serving/std-dev.ts`, its `/level` route). std's dev server takes the level from there by its own
+ *   hot reload (std-dev's `level-hot.ts`). A save is a person's Save, the workbench's autosave a second after an edit (a
+ *   viewport drag writes Blender once, at its release), an export's flush or the save that retires a document.
+ * - THE GAME'S `prefabs/` IS A BLENDER ASSET LIBRARY WHOSE ASSETS ARE LINKED, not appended ("Prefabs": Blender's
+ *   link-or-append is the library's import method, which std cannot set).
+ *
+ * - PRESSING PLAY SAVES THE LEVEL FIRST (`../contributions/play.page.tsx`), and the game's pages load once that
+ *   save's export has run ({@link stdLevelsSettled}), so the game plays the current edit.
+ *
+ * What each half printed is the console's (`std-level`), and a half that failed is an error there.
+ */
+import type { BlenderPageApi, ModelDocumentSaved } from '@volter/editor-blender/api';
+import { getCurrentProject, onProjectChange } from '@volter/sdk/active-project';
+import { editorHost } from '@volter/sdk/host';
+import { isStdGame, subscribeStdGame } from './std-game';
+
+const ROUTE = '/__editor/play/std/level';
+const SOURCE = 'std-level';
+/** A level's `.blend`, or a prefab's in its own folder: what std's export takes. */
+const EXPORTED = /^(levels\/.+|prefabs\/([^/]+)\/\2)\.blend$/;
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/** One save's carry and Node half after another: each Node half reads and takes away the description its save
+ *  wrote. */
+let tail: Promise<void> = Promise.resolve();
+/** Once every save's export heard so far has run (or failed, which the console says). */
+export const stdLevelsSettled = (): Promise<void> => tail;
+const glbOf = (blend: string): string => blend.replace(/\.blend$/, '.glb');
+
+/** The Blender half's source, as the game has it installed now (read for each save). */
+async function blenderHalf(): Promise<string> {
+  const answer = await fetch(ROUTE);
+  const said = (await answer.json()) as { blenderHalf?: string; error?: string };
+  if (!answer.ok || typeof said.blenderHalf !== 'string') throw new Error(said.error ?? `${ROUTE} answered HTTP ${answer.status}`);
+  return said.blenderHalf;
+}
+
+/** One save's export, after its Blender half ran in the save: its files carried, then the Node half. */
+async function finishExport(saved: ModelDocumentSaved): Promise<void> {
+  const ledger = editorHost().console;
+  const { blend, script } = saved;
+  if (script === null) return;
+  const glb = glbOf(blend);
+  for (const line of script.unstaged) ledger.warn(`std's export of ${blend} ran on Blender's earlier copy of a project file: ${line}`, SOURCE);
+  if (script.output.trim()) ledger.log(script.output.trimEnd(), SOURCE);
+  if (script.error !== null) {
+    ledger.error(`std's export of ${blend} failed in Blender (blend-to-scene.py): ${script.error}`, SOURCE);
+    return;
+  }
+  await saved.carry();
+  const answer = await fetch(ROUTE, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ glb }) });
+  const node = (await answer.json()) as { code?: number | null; output?: string; error?: string };
+  if (!answer.ok) throw new Error(node.error ?? `${ROUTE} answered HTTP ${answer.status}`);
+  if (node.output?.trim()) ledger.log(node.output.trimEnd(), SOURCE);
+  if (node.code !== 0) ledger.error(`std's export of ${blend} failed in Node (std level ${glb}): its exit was ${String(node.code)}`, SOURCE);
+}
+
+/** Start following the project's saves; the answer stops it and withdraws the save script and the prefabs library. */
+export function startStdLevels(blender: BlenderPageApi): () => void {
+  /** The project looked at (null before the first look), and whether it is a std game, as last answered. */
+  let project: string | undefined | null = null;
+  let std = false;
+  let withdraw: (() => void) | null = null;
+  // (each answer of whether the project is a std game is looked at: another project, or this one's manifest changed)
+  const look = (): void => {
+    const root = getCurrentProject()?.rootPath;
+    const answer = isStdGame();
+    if (answer === undefined || (root === project && answer === std)) return;
+    project = root;
+    std = answer;
+    withdraw?.();
+    withdraw = null;
+    if (!std) return;
+    const stopScript = blender.modelDocument.setSaveScript((blend) =>
+      (EXPORTED.test(blend) ? blenderHalf().then((source) => ({ source, args: [glbOf(blend)] })) : null));
+    const stopLibrary = blender.setAssetLibrary({ name: 'Prefabs', directory: 'prefabs', importMethod: 'LINK' });
+    withdraw = () => { stopScript(); stopLibrary(); };
+  };
+  const stopSaves = blender.modelDocument.subscribeSaved((saved) => {
+    if (saved.script === null) return;
+    const done = tail.then(() => finishExport(saved)).catch((error: unknown) =>
+      editorHost().console.error(`std's export of ${saved.blend} did not run: ${message(error)}`, SOURCE));
+    tail = done;
+    return done;
+  });
+  const stopProject = onProjectChange(look);
+  const stopStd = subscribeStdGame(look);
+  look();
+  return () => {
+    stopSaves();
+    stopProject();
+    stopStd();
+    withdraw?.();
+  };
+}

package/src/std-scene-level.ts

@@ -0,0 +1,59 @@
+/**
+ * THE LEVEL A STD GAME'S SCENE VIEW DRAWS (`../contributions/std-scene.document.tsx`): the std level whose Blender
+ * document was active last (`levels/<name>.blend`), or the one `volter.std-scene` named as it opened the view. Another
+ * project forgets it.
+ */
+import type { EditorCommandMessage, EditorCommandResult } from '@volter/sdk/commands';
+import { onProjectChange } from '@volter/sdk/active-project';
+import { editorHost } from '@volter/sdk/host';
+import { isStdGame, subscribeStdGame } from './std-game';
+
+/** The Scene view's document contribution. */
+export const STD_SCENE_DOCUMENT = 'std-scene.document';
+const LEVEL = /^levels\/.+\.blend$/;
+const LEVEL_DOCUMENT = /^document:model:(levels\/.+\.blend)$/;
+
+let level: string | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+const publish = (next: string | null): void => {
+  if (next === level) return;
+  level = next;
+  version += 1;
+  for (const listener of [...listeners]) listener();
+};
+
+export const sceneLevel = (): string | null => level;
+export const sceneLevelVersion = (): number => version;
+export function subscribeSceneLevel(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+/** Follow the active document: a std level's Blender document makes its level the Scene view's. */
+export function followSceneLevel(): () => void {
+  const look = (): void => {
+    const found = LEVEL_DOCUMENT.exec(editorHost().documents.activeId() ?? '')?.[1];
+    if (found !== undefined && isStdGame() === true) publish(found);
+  };
+  const stopDocuments = editorHost().documents.subscribe(look);
+  // (whether the project is a std game is answered later than its first document opens)
+  const stopStd = subscribeStdGame(look);
+  const stopProject = onProjectChange(() => publish(null));
+  look();
+  return () => { stopDocuments(); stopStd(); stopProject(); };
+}
+
+/** `volter.std-scene { level? }`: open the Scene view on `level` (a `levels/<name>.blend`), or on the level it draws. */
+export async function openStdScene(command: EditorCommandMessage): Promise<EditorCommandResult> {
+  if (isStdGame() !== true) return { ok: false, error: 'The open project is not a std game (no std.json), so it has no Scene view.' };
+  const asked = command['level'];
+  if (asked !== undefined && (typeof asked !== 'string' || !LEVEL.test(asked))) {
+    return { ok: false, error: `std-scene opens a level's Blender file, levels/<name>.blend; it was given ${JSON.stringify(asked)}.` };
+  }
+  const at = asked ?? level;
+  if (at === null) return { ok: false, error: "No std level is open: open a level's .blend (levels/<name>.blend), or name one as { level }." };
+  publish(at);
+  if (!(await editorHost().workspace.open({ kind: 'tool', id: STD_SCENE_DOCUMENT }))) return { ok: false, error: `${STD_SCENE_DOCUMENT} is not registered.` };
+  return { ok: true, data: { level: at } };
+}

package/src/std-view-bar.tsx

@@ -0,0 +1,78 @@
+/**
+ * A STD GAME'S VIEW BAR, at the top of the play stage's overlay over the viewport (`std-game.ts`): Edit, each Player N
+ * labelled "you" or "autopilot", Grid, and Players [-][+], each one a client joining or leaving. A press on it gives the
+ * keyboard back to the editor, so the view keys work again while a player's page held it. And the grid's tiles, each
+ * a button that opens its view. Drawn with the play area's own widget (`PlayAreaButton`).
+ */
+import { useSyncExternalStore } from 'react';
+import { editorBlender } from './editor-blender';
+import { addStdPlayer, removeStdPlayer, setStdView, stdRun, stdRunVersion, stdTile, subscribeStdRun, type StdPlayer, type StdRun } from './std-game';
+
+function useRun(): StdRun | null {
+  useSyncExternalStore(subscribeStdRun, stdRunVersion, stdRunVersion);
+  return stdRun();
+}
+
+/** Who drives a player, as its button says it. */
+function driver(run: StdRun, player: StdPlayer, index: number): string {
+  if (player.device === null) return 'joining';
+  if (player.autopilot) return 'autopilot';
+  return run.view === index ? 'you' : 'idle';
+}
+
+export function StdViewBar() {
+  const run = useRun();
+  if (!run) return null;
+  const { PlayAreaButton, timelineGeometry: { TIMELINE_CHROME, TIMELINE_THEME } } = editorBlender();
+  const { players, view } = run;
+  return (
+    <div role="toolbar" aria-label="Views" data-testid="std-view-bar" tabIndex={-1}
+      onPointerDown={(event) => event.currentTarget.focus()}
+      style={{ outline: 'none', margin: '4px auto', width: 'max-content', display: 'flex', alignItems: 'center', gap: TIMELINE_CHROME.headerGap,
+        padding: '2px 6px', pointerEvents: 'auto', background: TIMELINE_THEME.header, color: TIMELINE_CHROME.text,
+        border: `1px solid ${TIMELINE_CHROME.rule}`, borderRadius: TIMELINE_CHROME.widgetRadius, font: '11px Inter, system-ui, sans-serif' }}>
+      <div style={{ display: 'flex' }} role="group" aria-label="View">
+        <PlayAreaButton testId="std-view-edit" label="Edit the level while the game runs (Escape)" pressed={view === 'edit'} wide onClick={() => setStdView('edit')}>
+          Edit
+        </PlayAreaButton>
+        {players.map((player, index) => (
+          <PlayAreaButton key={player.slot} testId={`std-view-player-${player.number}`} wide pressed={view === index}
+            label={`Player ${player.number}, ${driver(run, player, index)}${index < 4 ? ` (${index + 1})` : ''}`} onClick={() => setStdView(index)}>
+            {`Player ${player.number} · ${driver(run, player, index)}`}
+          </PlayAreaButton>
+        ))}
+        <PlayAreaButton testId="std-view-grid" label="Grid: every view tiled (Tab cycles the views)" pressed={view === 'grid'} wide onClick={() => setStdView('grid')}>
+          Grid
+        </PlayAreaButton>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center' }} role="group" aria-label="Players">
+        <span style={{ padding: '0 4px' }}>Players</span>
+        <PlayAreaButton testId="std-players-remove" label="One player fewer: the last one's client leaves" disabled={players.length <= 1} onClick={removeStdPlayer}>
+          −
+        </PlayAreaButton>
+        <span data-testid="std-players-count" style={{ minWidth: 14, textAlign: 'center' }}>{players.length}</span>
+        <PlayAreaButton testId="std-players-add" label="One more player: a client joins" disabled={run.url === null} onClick={addStdPlayer}>
+          +
+        </PlayAreaButton>
+      </div>
+    </div>
+  );
+}
+
+export function StdGridTiles() {
+  const run = useRun();
+  if (!run || run.view !== 'grid') return null;
+  const { timelineGeometry: { TIMELINE_CHROME } } = editorBlender();
+  const count = run.players.length + 1;
+  const tiles = [{ label: 'Edit', open: 'edit' as const }, ...run.players.map((player, index) => ({ label: `Player ${player.number} · ${driver(run, player, index)}`, open: index }))];
+  return tiles.map(({ label, open }, tile) => {
+    const box = stdTile(tile, count);
+    return <button key={label} type="button" data-testid={`std-tile-${tile}`} title={`Open ${label}`} onClick={() => setStdView(open)}
+      style={{ position: 'absolute', left: `${box.left * 100}%`, top: `${box.top * 100}%`, width: `${box.width * 100}%`, height: `${box.height * 100}%`, pointerEvents: 'auto', background: 'transparent', cursor: 'pointer',
+        border: `1px solid ${TIMELINE_CHROME.rule}`, display: 'flex', alignItems: 'flex-end', padding: 6 }}>
+      <span style={{ background: 'rgba(0, 0, 0, 0.6)', color: TIMELINE_CHROME.widgetText, padding: '2px 6px', borderRadius: TIMELINE_CHROME.widgetRadius, font: '11px Inter, system-ui, sans-serif' }}>
+        {label}
+      </span>
+    </button>;
+  });
+}

package/contributions/model-play.command.ts

@@ -1,37 +0,0 @@
-/**
- * THE MODEL PLAY VERB of the session wire (`@volter/sdk/commands`, a
- * `workspace.command` contribution): `model-play-log`, the read behind
- * `cyclotron play-log` and `editor.modelPlayLog()` in `eval`.
- *
- * It answers one model document's play log (`../src/play-log.ts`) — `documentId`'s, or the
- * active Play's when omitted; the current run's, or the last one's after Stop — filtered by
- * `since` (simulation seconds, inclusive) and `kind`. A read
- * only: no play gate, since an empty log is the honest answer when nothing has played.
- */
-import type { CommandContribution } from '@volter/sdk/commands';
-import { readModelPlayLog } from '../src/play-log';
-
-export const point = 'workspace.command';
-
-export const commands: CommandContribution['commands'] = {
-  'model-play-log': {
-    derivedRefresh: 'none',
-    handle: (command) => {
-      const since = command['since'];
-      const kind = command['kind'];
-      const documentId = command['documentId'];
-      if (documentId !== undefined && typeof documentId !== 'string')
-        return { ok: false, error: `model-play-log's documentId is a model document id, a string; it was given ${JSON.stringify(documentId)}.` };
-      if (since !== undefined && (typeof since !== 'number' || !Number.isFinite(since)))
-        return { ok: false, error: `model-play-log's since is simulation seconds, a number; it was given ${JSON.stringify(since)}.` };
-      if (kind !== undefined && typeof kind !== 'string')
-        return { ok: false, error: `model-play-log's kind is an entry kind, a string; it was given ${JSON.stringify(kind)}.` };
-      const reading = readModelPlayLog({
-        ...(documentId === undefined ? {} : { documentId }),
-        ...(since === undefined ? {} : { since }),
-        ...(kind === undefined ? {} : { kind }),
-      });
-      return { ok: true, data: { ...reading } };
-    },
-  },
-};

package/contributions/model-play.service.tsx

@@ -1,152 +0,0 @@
-/** Model script tool, available to every product through project packages. */
-import { useSyncExternalStore } from 'react';
-import { Button, EditorIcon, editorIcons, MenuItem } from '@volter/sdk/widgets';
-import { editorHost } from '@volter/sdk/host';
-import { registerDocumentPlayExtension, type DocumentPlayControlProps } from '@volter/sdk/kit/document-play-extension';
-import {
-  armModelPlayAutoplay,
-  escapeModelPlay,
-  MODEL_PLAY_SPEEDS,
-  modelPlayAutoplay,
-  modelPlayClock,
-  modelPlayGeneration,
-  modelPlaying,
-  restartModelPlay,
-  setModelPlayAutoplay,
-  setModelPlayFailure,
-  setModelPlayPaused,
-  setModelPlaying,
-  setModelPlaySpeed,
-  stepModelPlay,
-  subscribeModelPlay,
-  subscribeModelPlayClock,
-} from '../src/model-play';
-import { playScriptPath, runPlayScript } from '../src/play-script';
-import { beginModelPlayLog, subscribeModelPlayLog, tailModelPlayLog } from '../src/play-log';
-import type * as THREE from 'three';
-import { getCurrentProject, onProjectChange } from '@volter/sdk/kit/active-project';
-
-export const point = 'workspace.service';
-function usePlaying(documentId: string | undefined): boolean {
-  return useSyncExternalStore(subscribeModelPlay, () => documentId ? modelPlaying(documentId) : false, () => false);
-}
-// Kept because `DocumentPlayExtension` requires `Control` and `Menu` for a layout that draws Play in its header; Cyclotron's layout no longer does (its Play is the Game panel's).
-function Control({ documentId, onClose }: DocumentPlayControlProps) {
-  const playing = usePlaying(documentId);
-  return <Button size="compact" data-testid="model-play-button" aria-pressed={playing}
-    disabled={!documentId} title={playing ? 'Stop playing (Escape)' : 'Play this model’s script'}
-    onClick={() => { onClose(); if (documentId) setModelPlaying(documentId, !playing); }}>
-    <EditorIcon icon={playing ? editorIcons.transport.stop : editorIcons.transport.play} />
-    {playing ? 'Stop' : 'Play'}
-  </Button>;
-}
-function Menu({ documentId, onClose }: DocumentPlayControlProps) {
-  const playing = usePlaying(documentId);
-  return <MenuItem data-testid="model-play" disabled={!documentId}
-    onSelect={() => { onClose(); if (documentId) setModelPlaying(documentId, !playing); }}>
-    {playing ? 'Stop' : 'Play'}
-  </MenuItem>;
-}
-
-/**
- * WHETHER A MODEL HAS A PLAY SCRIPT — `src/models/canyon.blend` has one when
- * `src/models/canyon.play.ts` exists (`playScriptPath`), the same file Play imports. Asked once
- * per path through the project's files door and then kept, corrected by that door's change
- * events, so a layout can open a model with a script as a game and one without as a model. A
- * project switch forgets every answer.
- */
-const scripts = new Map<string, boolean>();
-const looking = new Set<string>();
-const scriptListeners = new Set<() => void>();
-function publishScripts(): void {
-  for (const listener of [...scriptListeners]) listener();
-}
-function projectPath(path: string): string {
-  return path.replaceAll('\\', '/').replace(/^\.\//, '');
-}
-function hasScript(sourcePath: string): boolean | null {
-  const path = projectPath(playScriptPath(sourcePath));
-  const known = scripts.get(path);
-  if (known !== undefined) return known;
-  if (!looking.has(path)) {
-    looking.add(path);
-    const project = getCurrentProject()?.rootPath;
-    void editorHost().files.exists(path).then(exists => exists, () => false).then(exists => {
-      looking.delete(path);
-      // An answer about the previous project is no answer about this one.
-      if (getCurrentProject()?.rootPath !== project) return;
-      scripts.set(path, exists);
-      publishScripts();
-    });
-  }
-  return null;
-}
-
-export function start(): () => void {
-  const stopWatching = (() => {
-    try {
-      return editorHost().files.watch((event) => {
-        const path = projectPath(event.path);
-        if (!scripts.has(path) && !path.endsWith('.play.ts')) return;
-        const exists = event.type !== 'remove';
-        if (scripts.get(path) === exists) return;
-        scripts.set(path, exists);
-        publishScripts();
-      });
-    } catch {
-      // A host without a files door still plays; the answer is then read once per path.
-      return () => {};
-    }
-  })();
-  const stopProject = onProjectChange(() => { scripts.clear(); publishScripts(); });
-  const unregister = registerDocumentPlayExtension('model', {
-    Control, Menu, playing: modelPlaying, setPlaying: setModelPlaying, escape: escapeModelPlay,
-    subscribe(listener) {
-      const stopPlay = subscribeModelPlay(listener), stopProject = onProjectChange(listener);
-      scriptListeners.add(listener);
-      return () => { stopPlay(); stopProject(); scriptListeners.delete(listener); };
-    },
-    aspectRatio() {
-      const size = getCurrentProject()?.config.resolution;
-      const ratio = size ? size.width / size.height : null;
-      return ratio !== null && Number.isFinite(ratio) && ratio > 0 ? ratio : null;
-    },
-    run(stage) {
-      // The document kind lends native scene objects; this tool owns their Three types.
-      return runPlayScript({ ...stage, blend: stage.sourcePath, root: stage.root as THREE.Object3D,
-        camera: stage.camera as () => THREE.Camera, editingCamera: stage.editingCamera as () => THREE.Camera,
-        ownMaterial: stage.ownMaterial as ((material: THREE.Material) => THREE.Material | null) | undefined });
-    },
-    // THE RUN'S TRANSPORT (`model-play.ts`): the runner reads all of it each frame.
-    transport: {
-      speeds: MODEL_PLAY_SPEEDS,
-      clock: modelPlayClock,
-      subscribeClock: subscribeModelPlayClock,
-      setPaused: setModelPlayPaused,
-      step: stepModelPlay,
-      setSpeed: setModelPlaySpeed,
-      restart: restartModelPlay,
-      generation: modelPlayGeneration,
-      autoplay: modelPlayAutoplay,
-      setAutoplay: setModelPlayAutoplay,
-      armAutoplay: armModelPlayAutoplay,
-      // NO STAGE, SO NO RUNNER, and until 2026-10-06 the document turned Play off and wrote the
-      // reason to the console: Play flicked on and off with nothing said where anyone looks.
-      // Now the run stands with its failure — the Game panel draws it, the log records it.
-      fail(documentId, sourcePath, failure) {
-        const run = beginModelPlayLog(documentId, playScriptPath(sourcePath));
-        run.append('play', 'script-error', { phase: 'stage', message: failure });
-        run.end({ reason: 'stage-failed' });
-        setModelPlayFailure(documentId, failure);
-      },
-    },
-    log: { tail: tailModelPlayLog, subscribe: subscribeModelPlayLog },
-    scriptPath: playScriptPath,
-    hasScript,
-  });
-  return () => {
-    unregister();
-    stopProject();
-    stopWatching();
-  };
-}

package/src/camera-transition.ts

@@ -1,87 +0,0 @@
-import * as THREE from 'three';
-
-function pose(camera: THREE.Camera) {
-  camera.updateWorldMatrix(true, false);
-  return {
-    position: camera.getWorldPosition(new THREE.Vector3()),
-    quaternion: camera.getWorldQuaternion(new THREE.Quaternion()),
-    projection: camera.projectionMatrix.clone(),
-    fov: (camera as THREE.PerspectiveCamera).fov,
-  };
-}
-type Pose = ReturnType<typeof pose>;
-
-/** The tool blends AFTER the script has stated its complete camera pose.
- * Projection matrices also interpolate, preserving an orthographic editing
- * view exactly at the handoff to a perspective game. Neither editing camera
- * nor its orbit target is ever written.
- *
- * `instant` enters already arrived: a Restart replaces a game that was on screen a frame ago,
- * and flying in again from the editing pose would show the model between two games. The return
- * on Stop still blends. */
-export function cameraTransition(editingCamera: THREE.Camera, options?: { readonly instant?: boolean }) {
-  const editing = pose(editingCamera);
-  let phase: 'entering' | 'playing' | 'leaving' = options?.instant ? 'playing' : 'entering';
-  let elapsed = 0;
-  let last = editing;
-  let leavingFrom = editing;
-  const duration = 0.8;
-  const position = new THREE.Vector3();
-  const quaternion = new THREE.Quaternion();
-  function blend(camera: THREE.Camera, from: Pose, to: Pose, t: number): void {
-    const eased = t * t * (3 - 2 * t);
-    position.lerpVectors(from.position, to.position, eased);
-    quaternion.slerpQuaternions(from.quaternion, to.quaternion, eased);
-    camera.position.copy(position);
-    camera.quaternion.copy(quaternion);
-    if (camera.parent) {
-      camera.parent.worldToLocal(camera.position);
-      const parentRotation = camera.parent.getWorldQuaternion(new THREE.Quaternion());
-      camera.quaternion.premultiply(parentRotation.invert());
-    }
-    if (Number.isFinite(from.fov) && Number.isFinite(to.fov)) {
-      (camera as THREE.PerspectiveCamera).fov = THREE.MathUtils.lerp(from.fov, to.fov, eased);
-    }
-    for (let i = 0; i < 16; i++) {
-      camera.projectionMatrix.elements[i] = THREE.MathUtils.lerp(from.projection.elements[i]!, to.projection.elements[i]!, eased);
-    }
-    camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
-    camera.updateMatrixWorld(true);
-    last = pose(camera);
-  }
-  return {
-    acceptingKeys: () => phase === 'playing',
-    leaving: () => phase === 'leaving',
-    hudOpacity: () => phase === 'playing' ? 1 : phase === 'entering'
-      ? Math.min(1, elapsed / duration)
-      : Math.max(0, 1 - elapsed / (duration - 0.16)),
-    approachingEdit: () => phase === 'leaving' && elapsed >= duration - 0.16,
-    /** A PAUSED frame: put the camera back where the last drawn frame had it. Nothing else
-     *  states the pose while the game's update is held, and the stage's navigation runs before
-     *  this hook each frame; the blend's own clock stands still with the game's. */
-    hold(camera: THREE.Camera): void {
-      blend(camera, last, last, 1);
-    },
-    /** Escape completes an existing blend; otherwise begin the return. */
-    stop(escape: boolean): boolean {
-      if (escape && phase === 'entering') { phase = 'playing'; return false; }
-      if (escape && phase === 'leaving') return true;
-      if (phase !== 'leaving') {
-        leavingFrom = last;
-        elapsed = 0;
-        phase = 'leaving';
-      }
-      return false;
-    },
-    frame(camera: THREE.Camera, dt: number): boolean {
-      if (phase === 'playing') { last = pose(camera); return false; }
-      const t = Math.min(1, elapsed / duration);
-      blend(camera, phase === 'entering' ? editing : leavingFrom, phase === 'entering' ? pose(camera) : editing, t);
-      elapsed += dt;
-      if (t < 1) return false;
-      if (phase === 'leaving') return true;
-      phase = 'playing';
-      return false;
-    },
-  };
-}