@volter/play 0.5.212 → 0.5.214

package/src/std-level-files.ts

@@ -1,6 +1,6 @@
 /**
  * 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`).
+ * `levelNames`, beside `writeGrading`): the files a level'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`). */
@@ -31,3 +31,20 @@ export function levelFiles(blend: string): {
     grading: `${dir}/${base}.grading.tsx`,
   };
 }
+
+/** A level's Blender file (`levels/<name>.blend`), whose export writes its component. */
+export const BLEND_LEVEL = /^levels\/.+\.blend$/;
+
+/** A level in code: `levels/<Name>Level.tsx`, its component the file's export of that name (std's starter's own level),
+ *  where no level's Blender file in that folder writes it. */
+export const CODE_LEVEL = /^levels\/(?:[^/]+\/)*([A-Z][A-Za-z0-9]*Level)\.tsx$/;
+
+/** The level a level's document draws for a file of the game's (from its folder, among `files`, the game's file list): a
+ *  level's Blender file as itself; a level's component as the Blender file that writes it where one does, else as a
+ *  level in code; anything else none. */
+export function sceneLevelOf(file: string, files: readonly string[]): string | null {
+  if (BLEND_LEVEL.test(file)) return file;
+  if (!CODE_LEVEL.test(file)) return null;
+  const writer = files.find((other) => BLEND_LEVEL.test(other) && levelFiles(other).component === file);
+  return writer ?? file;
+}

package/src/std-level.ts

@@ -8,9 +8,9 @@
  *   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
+ *   those files are carried into the project and the Node half, `std level-scene <glb>`, runs in the game's folder
+ *   (`../serving/std-dev.ts`, its `/level` route). std's dev server takes the level from there, its rooms reloaded by
+ *   Colyseus's own dev mode. 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).
@@ -64,7 +64,7 @@ async function finishExport(saved: ModelDocumentSaved): Promise<void> {
   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);
+  if (node.code !== 0) ledger.error(`std's export of ${blend} failed in Node (std level-scene ${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. */

package/src/std-view-bar.tsx

@@ -1,12 +1,12 @@
 /**
- * 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 STD GAME'S VIEW BAR, at the top of the Game view (`game-view.tsx`, `std-game.ts`): Scene (the current level,
+ * live), each Player N labelled "you" or "autopilot", and Grid (how many play is the Game panel's Players, beside Play). 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';
+import { setStdView, stdRun, stdRunVersion, stdTile, subscribeStdRun, type StdPlayer, type StdRun } from './std-game';
 
 function useRun(): StdRun | null {
   useSyncExternalStore(subscribeStdRun, stdRunVersion, stdRunVersion);
@@ -32,8 +32,8 @@ export function StdViewBar() {
         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 testId="std-view-scene" label="Scene: the current level, live" pressed={view === 'scene'} wide onClick={() => setStdView('scene')}>
+          Scene
         </PlayAreaButton>
         {players.map((player, index) => (
           <PlayAreaButton key={player.slot} testId={`std-view-player-${player.number}`} wide pressed={view === index}
@@ -45,16 +45,6 @@ export function StdViewBar() {
           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>
   );
 }
@@ -64,7 +54,7 @@ export function StdGridTiles() {
   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 }))];
+  const tiles = [{ label: 'Scene', open: 'scene' 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)}

package/contributions/model-play.verbs.ts

@@ -1,44 +0,0 @@
-/**
- * THE MODEL PLAY VERBS of the session wire (`@volter/sdk/commands`): each the Code-OSS command `volter.<verb>`, registered
- * by play's page half (`play.page.tsx`), with its budget on its `contributes.commands` entry.
- *
- * `model-play-log`, the read behind `cyclotron play-log` and `editor.contributedVerb('model-play-log')` in `eval`, 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` (game seconds, inclusive) and `kind`. A read only: no play gate,
- * since an empty log is the honest answer when nothing has played.
- *
- * `model-play`, the agent's tool for Play (declared in this package's `contributes.languageModelTools`), runs the Game
- * panel's own view verbs, the ones `volter.model-play.<action>` runs (`game-panel.tsx`), so an agent drives the run the
- * person sees and answers with the game's state.
- */
-import type { VerbHandler } from '@volter/sdk/commands';
-import { executeCommand } from '@volter/sdk/editor-commands';
-import { readModelPlayLog } from '../src/play-log';
-
-const ACTIONS = ['state', 'play', 'stop', 'pause', 'resume', 'restart'] as const;
-
-export const modelPlayVerbs: Readonly<Record<string, VerbHandler>> = {
-  'model-play': async (command) => {
-    const action = command['action'];
-    if (typeof action !== 'string' || !(ACTIONS as readonly string[]).includes(action))
-      return { ok: false, error: `model-play's action is one of ${ACTIONS.join(', ')}; it was given ${JSON.stringify(action)}.` };
-    return { ok: true, data: { result: (await executeCommand(`volter.model-play.${action}`, {})) ?? null } };
-  },
-  'model-play-log': (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 game 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/src/model-play.ts

@@ -1,149 +0,0 @@
-/**
- * WHETHER A MODEL DOCUMENT IS PLAYING (Play in the Game panel, `contributions/game-panel.tsx`; drawn by
- * `blender-runtime.document.tsx`). Playing, the document's stage shows the std game's players' pages (`std-game.ts`);
- * the model, its selection and its history stand as they were, and Stop returns to them. Kept for the page's life and
- * never stored: a reload opens the model, not a game.
- *
- * AND ITS CLOCK, AS STD LAST ANSWERED IT. Pause, step and speed are std's `clock` control on each player's page
- * (`std-controls.ts`); each answer is the page's clock (`{ paused, speed, time, frame }`), kept here per document
- * beside whether a game runs and why not, and announced through the clock's own subscription. The speed is the
- * person's: kept across Plays, and said to each player's page as it joins.
- *
- * AND AUTOPLAY ARMED WHILE STOPPED: the next start drives the viewed player's bot as its page joins, with the goal it
- * was armed with (`std-game.ts`). Stop drops the arm.
- */
-const listeners = new Set<() => void>();
-const clockListeners = new Set<() => void>();
-const playing = new Set<string>();
-
-/** The speeds the transport offers, slowest first: std's clock takes 0.25 to 4. */
-export const MODEL_PLAY_SPEEDS: readonly number[] = [0.25, 0.5, 1, 2, 4];
-
-export interface ModelPlayClock {
-  /** The viewed player's page's game seconds and frames, as std last answered them. */
-  readonly time: number;
-  readonly tick: number;
-  readonly paused: boolean;
-  readonly speed: number;
-  /** The run is playing but no game runs: its dev server could not start, or no player's page joined. */
-  readonly failure: string | null;
-  /** A player's page has joined this run (`DocumentPlayClock.running`). */
-  readonly running: boolean;
-}
-const STILL: ModelPlayClock = { time: 0, tick: 0, paused: false, speed: 1, failure: null, running: false };
-/** Replaced, never mutated, so a snapshot read by `useSyncExternalStore` changes identity exactly when it changes
- *  value. */
-const clocks = new Map<string, ModelPlayClock>();
-/** Bumped by Restart; the document keys its detached copy on it (`DocumentPlayTransport`). */
-const generations = new Map<string, number>();
-/** Autoplay armed while stopped, with the goal it drives (null: the game's own). */
-const arms = new Map<string, { readonly goal: string | null }>();
-
-function publish(): void {
-  for (const listener of [...listeners]) listener();
-}
-export function publishModelPlayClock(): void {
-  for (const listener of [...clockListeners]) listener();
-}
-function setClock(documentId: string, next: Partial<ModelPlayClock>): void {
-  clocks.set(documentId, { ...modelPlayClock(documentId), ...next });
-  publishModelPlayClock();
-}
-
-export function modelPlaying(documentId: string): boolean {
-  return playing.has(documentId);
-}
-
-export function setModelPlaying(documentId: string, value: boolean): void {
-  if (playing.has(documentId) === value) {
-    // Stop with nothing playing is how a closing document lets go of its play: an arm made while stopped goes with it.
-    if (!value && arms.delete(documentId)) publishModelPlayClock();
-    return;
-  }
-  if (value) {
-    playing.add(documentId);
-    // A new run's clock starts at zero and running; the speed is the person's and stays.
-    setClock(documentId, { time: 0, tick: 0, paused: false, failure: null, running: false });
-  } else {
-    playing.delete(documentId);
-    arms.delete(documentId);
-    // The clock keeps the stopped run's time and frames, so the panel still says how far it got.
-    setClock(documentId, { paused: false, failure: null, running: false });
-  }
-  publish();
-}
-
-/** The run's report that no game runs although the run plays (`null` once a player's page joins, which is also the
- *  moment the run is `running`). */
-export function setModelPlayFailure(documentId: string, failure: string | null): void {
-  const clock = modelPlayClock(documentId);
-  const running = failure === null;
-  if (!playing.has(documentId) || (clock.failure === failure && clock.running === running)) return;
-  setClock(documentId, { failure, running });
-}
-
-/** A page's clock as std answered it (`std-controls.ts`'s `StdClock`), kept as the run's. */
-export function setModelPlayClock(documentId: string, clock: { readonly paused: boolean; readonly speed: number; readonly time: number; readonly frame: number }): void {
-  const now = modelPlayClock(documentId);
-  if (now.paused === clock.paused && now.speed === clock.speed && now.time === clock.time && now.tick === clock.frame) return;
-  setClock(documentId, { paused: clock.paused, speed: clock.speed, time: clock.time, tick: clock.frame });
-}
-
-/** The person's speed, kept for the page's life and said to each player's page as it joins. */
-export function setModelPlaySpeed(documentId: string, speed: number): void {
-  if (!MODEL_PLAY_SPEEDS.includes(speed))
-    throw new Error(`Play speed ${speed} is not one the transport offers: ${MODEL_PLAY_SPEEDS.join(', ')}.`);
-  if (modelPlayClock(documentId).speed !== speed) setClock(documentId, { speed });
-}
-
-export function subscribeModelPlay(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => { listeners.delete(listener); };
-}
-
-export function modelPlayClock(documentId: string): ModelPlayClock {
-  return clocks.get(documentId) ?? STILL;
-}
-
-export function subscribeModelPlayClock(listener: () => void): () => void {
-  clockListeners.add(listener);
-  return () => { clockListeners.delete(listener); };
-}
-
-export function modelPlayGeneration(documentId: string): number {
-  return generations.get(documentId) ?? 0;
-}
-
-/**
- * BEGIN THE RUN AGAIN. Playing stays true throughout (nothing returns to the model) and the generation moves, which is
- * what makes the document detach a new copy and run Play's runner again: every player's page loaded afresh. A document
- * that is not playing simply starts.
- */
-export function restartModelPlay(documentId: string): void {
-  if (!playing.has(documentId)) { setModelPlaying(documentId, true); return; }
-  generations.set(documentId, modelPlayGeneration(documentId) + 1);
-  setClock(documentId, { time: 0, tick: 0, paused: false, failure: null, running: false });
-  publish();
-}
-
-/** Autoplay armed for the next start, and the goal it drives; null when it is not armed. */
-export function modelPlayArm(documentId: string): { readonly goal: string | null } | null {
-  return arms.get(documentId) ?? null;
-}
-
-/** Arm (or disarm) autoplay for the next start, while stopped: the Game panel's Autoplay button before Play. Disarming
- *  always succeeds. */
-export function armModelPlayAutoplay(documentId: string, armed: boolean, goal: string | null = null): void {
-  if (armed && playing.has(documentId))
-    throw new Error(`${documentId} is already playing; switch autoplay on instead of arming it.`);
-  if (armed) arms.set(documentId, { goal });
-  else if (!arms.delete(documentId)) return;
-  publishModelPlayClock();
-}
-
-/** The arm taken by the start it was made for. */
-export function takeModelPlayArm(documentId: string): { readonly goal: string | null } | null {
-  const arm = arms.get(documentId) ?? null;
-  if (arm !== null) { arms.delete(documentId); publishModelPlayClock(); }
-  return arm;
-}

package/src/std-scene-level.ts

@@ -1,59 +0,0 @@
-/**
- * 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 } };
-}