@volter/play 0.5.211 → 0.5.213

package/src/game-run.ts

@@ -0,0 +1,165 @@
+/**
+ * THE GAME'S RUN, the project's one (Play in the Game panel, `contributions/game-panel.tsx`; drawn in the Game view,
+ * `game-view.tsx`): whether it plays, its clock as std last answered it, its generation and autoplay armed for its next
+ * start. Kept for the page's life and never stored: a reload opens the editor, not a game.
+ *
+ * THE CLOCK. 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 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. Its time comes from one of two readings, and `from` says which:
+ * - held (paused or stepped): std's answer to the control, exact, as the play log's `pause` and `step` entries record it;
+ * - running: the newest step the viewed player's page traced (std's trace format 3, `s`, sixty a game second from the
+ *   trace's start, since std's live clock is the page's `performance.now`, `adoptLiveClock`). A client page writes a
+ *   trace line only as something happens (an input, a word said, its bot's intent), so this holds while the page is
+ *   idle: it is when the page last traced, not the clock now.
+ *
+ * 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>();
+
+/** The speeds the panel offers, slowest first: std's clock takes 0.25 to 4. */
+export const GAME_SPEEDS: readonly number[] = [0.25, 0.5, 1, 2, 4];
+
+export interface GameClock {
+  /** The viewed player's page's game seconds and `tick`, read as `from` says. */
+  readonly time: number;
+  readonly tick: number;
+  /** Where `time` and `tick` were read. `std-answer`: std's answer to the pause or step that held the game (`tick` its
+   *  frame). `newest-traced-step`: the newest step the viewed page traced while the game ran, `time` that step in
+   *  seconds (0 until its trace says a line past its start); it holds while that page traces nothing. After Stop the
+   *  clock keeps the run's last reading and where it was read, with `running` and `paused` false: a reading still in
+   *  flight when its run ended is not written (`std-game.ts`). */
+  readonly from: 'std-answer' | 'newest-traced-step';
+  readonly paused: boolean;
+  /** Simulation seconds per real second; one of `GAME_SPEEDS`. */
+  readonly speed: number;
+  /** The run plays 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. A reader that must know whether Play WORKED (the CLI's `play`) waits for
+   *  this or for `failure`, never for "playing" alone. */
+  readonly running: boolean;
+}
+
+let playing = false;
+/** Replaced, never mutated, so a snapshot read by `useSyncExternalStore` changes identity exactly when it changes
+ *  value. */
+let clock: GameClock = { time: 0, tick: 0, from: 'newest-traced-step', paused: false, speed: 1, failure: null, running: false };
+/** The newest step the viewed page traced, and its seconds: the running clock's reading, kept while the game is held. */
+let traced = { tick: 0, time: 0 };
+/** Bumped by Restart: the Game view runs the game again on it. */
+let generation = 0;
+/** Autoplay armed while stopped, with the goal it drives (null: the game's own). */
+let arm: { readonly goal: string | null } | null = null;
+
+function publish(): void {
+  for (const listener of [...listeners]) listener();
+}
+function publishGameClock(): void {
+  for (const listener of [...clockListeners]) listener();
+}
+function setClock(next: Partial<GameClock>): void {
+  clock = { ...clock, ...next };
+  publishGameClock();
+}
+
+export const gamePlaying = (): boolean => playing;
+
+export function setGamePlaying(value: boolean): void {
+  if (playing === value) {
+    // Stop with nothing playing lets go of an arm made while stopped.
+    if (!value && arm !== null) { arm = null; publishGameClock(); }
+    return;
+  }
+  playing = value;
+  if (value) {
+    // A new run's clock starts at zero and running; the speed is the person's and stays.
+    traced = { tick: 0, time: 0 };
+    setClock({ time: 0, tick: 0, from: 'newest-traced-step', paused: false, failure: null, running: false });
+  } else {
+    arm = null;
+    // The clock keeps the stopped run's time and frames, so `play state` still says how far it got.
+    setClock({ 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 setGameFailure(failure: string | null): void {
+  const running = failure === null;
+  if (!playing || (clock.failure === failure && clock.running === running)) return;
+  setClock({ failure, running });
+}
+
+/** A page's clock as std answered it (`std-controls.ts`'s `StdClock`), kept as the run's: held, its time and frame
+ *  exactly as answered; running, its speed, the time going back to the newest traced step. */
+export function setGameClock(said: { readonly paused: boolean; readonly speed: number; readonly time: number; readonly frame: number }): void {
+  const next: Pick<GameClock, 'paused' | 'speed' | 'time' | 'tick' | 'from'> = said.paused
+    ? { paused: true, speed: said.speed, time: said.time, tick: said.frame, from: 'std-answer' }
+    : { paused: false, speed: said.speed, ...traced, from: 'newest-traced-step' };
+  if (clock.paused === next.paused && clock.speed === next.speed && clock.time === next.time && clock.tick === next.tick
+    && clock.from === next.from) return;
+  setClock(next);
+}
+
+/** The newest step the viewed player's page traced (std's trace format 3, `s`): the run's clock while it runs. */
+export function setGameTraceStep(step: number, stepsPerSecond: number): void {
+  traced = { tick: step, time: step / stepsPerSecond };
+  if (clock.paused || (clock.tick === step && clock.from === 'newest-traced-step')) return;
+  setClock({ ...traced, from: 'newest-traced-step' });
+}
+
+/** The person's speed, kept for the page's life and said to each player's page as it joins. */
+export function setGameSpeed(speed: number): void {
+  if (!GAME_SPEEDS.includes(speed))
+    throw new Error(`Play speed ${speed} is not one the panel offers: ${GAME_SPEEDS.join(', ')}.`);
+  if (clock.speed !== speed) setClock({ speed });
+}
+
+export function subscribeGame(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+export const gameClock = (): GameClock => clock;
+
+export function subscribeGameClock(listener: () => void): () => void {
+  clockListeners.add(listener);
+  return () => { clockListeners.delete(listener); };
+}
+
+export const gameGeneration = (): number => generation;
+
+/**
+ * BEGIN THE RUN AGAIN. Playing stays true throughout and the generation moves, which is what makes the Game view run
+ * the game again: every player's page loaded afresh. A game that is not playing simply starts.
+ */
+export function restartGame(): void {
+  if (!playing) { setGamePlaying(true); return; }
+  generation += 1;
+  traced = { tick: 0, time: 0 };
+  setClock({ time: 0, tick: 0, from: 'newest-traced-step', 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 const gameArm = (): { readonly goal: string | null } | null => arm;
+
+/** Arm (or disarm) autoplay for the next start, while stopped: the Game panel's Autoplay button before Play. Disarming
+ *  always succeeds. */
+export function armGameAutoplay(armed: boolean, goal: string | null = null): void {
+  if (armed && playing) throw new Error('The game is already playing; switch autoplay on instead of arming it.');
+  if (armed) arm = { goal };
+  else if (arm === null) return;
+  else arm = null;
+  publishGameClock();
+}
+
+/** The arm taken by the start it was made for. */
+export function takeGameArm(): { readonly goal: string | null } | null {
+  const taken = arm;
+  if (taken !== null) { arm = null; publishGameClock(); }
+  return taken;
+}

package/src/game-view.tsx

@@ -0,0 +1,219 @@
+/**
+ * THE GAME, PLAYED AS THE PROJECT'S (`docs/adr/std-scene-view.md`, decision 8): Play is the project's (`game-run.ts`),
+ * as an engine's Play button is, whatever document is in front, and the game shows in a GAME VIEW of its own, as
+ * Unity's Game view and Godot's Game workspace do. Play opens the Game view as a tab of the editor (`GAME_DOCUMENT`) and
+ * brings it to the front; Stop closes it and brings back the tab that was in front. Another tab in front never stops
+ * the game, and closing the Game view does.
+ *
+ * THE PLAYERS' PAGES OUTLIVE THE TAB'S BOX. The host parks a document's box out of the page while its tab is behind
+ * another, and a frame taken out of the page loads again, so the run draws in the Game view's retained layer
+ * (`@volter/sdk/document-layer`), mounted in the workbench's container, which the Game view's box claims while it is
+ * shown (laid over it, hidden once no view claims it), as Code-OSS keeps a webview that retains its context; the
+ * editor's doors that read the document in front (`editor.document.key`, `query`, `inspect`, `capture`) read the layer as
+ * its content. A hidden layer's pages are throttled, as a hidden retained webview is, and kept.
+ */
+import { type CSSProperties, useLayoutEffect, useRef, useSyncExternalStore } from 'react';
+import { editorHost } from '@volter/sdk/host';
+import { useProgress } from '@volter/sdk/progress';
+import { StateSurface, themeVars } from '@volter/sdk/widgets';
+import { claimDocumentLayer, claimedBox, documentLayer, documentLayerOf, releaseDocumentLayer } from '@volter/sdk/document-layer';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  openWorkspaceDocuments,
+  workspaceDocumentSelection,
+} from '@volter/sdk/workspace-document-registry';
+import { setDocumentPlaySignal } from '@volter/sdk/document-play-extension';
+import { currentStdLevel, StdLevelView, subscribeCurrentStdLevel } from '../contributions/std-level.document';
+import { gameClock, gameGeneration, gamePlaying, setGamePlaying, subscribeGame, subscribeGameClock } from './game-run';
+import { stdRun, stdRunVersion, subscribeStdRun, type GameStage, type StdTileBox } from './std-game';
+
+/** The Game view's id, and the run's: the project's one game. */
+const GAME_DOCUMENT = 'play:game';
+/** The Game view's Scene: the current level's view, live, a view of the Game view's document. */
+const SCENE_VIEW = `${GAME_DOCUMENT}#scene`;
+
+/** The run's stage, made as Play starts and kept across its restarts, in the Game view's retained layer: the players'
+ *  frames, and over them the view bar and the grid's tiles. It takes no press itself: each player's frame and the view
+ *  bar take their own, so the live Scene beneath it is the editor's to orbit and pick. */
+interface StageLayer {
+  readonly host: HTMLDivElement;
+  readonly players: HTMLDivElement;
+  readonly overlay: HTMLDivElement;
+}
+
+let stage: StageLayer | null = null;
+const stageListeners = new Set<() => void>();
+function setStage(next: StageLayer | null): void {
+  stage = next;
+  if (next === null) releaseDocumentLayer(GAME_DOCUMENT);
+  for (const listener of [...stageListeners]) listener();
+}
+function subscribeStage(listener: () => void): () => void {
+  stageListeners.add(listener);
+  return () => { stageListeners.delete(listener); };
+}
+
+function makeStage(): StageLayer {
+  const host = documentLayer(GAME_DOCUMENT);
+  host.dataset['testid'] = 'game-stage';
+  const players = document.createElement('div');
+  Object.assign(players.style, { position: 'absolute', inset: '0', pointerEvents: 'none' });
+  const overlay = document.createElement('div');
+  Object.assign(overlay.style, { position: 'absolute', inset: '0', pointerEvents: 'none' });
+  host.replaceChildren(players, overlay);
+  return { host, players, overlay };
+}
+
+/** Where the live Scene stands in the Game view, as the run places it (`GameStage.scene`). */
+let sceneArea: StdTileBox | 'whole' | null = null;
+const sceneListeners = new Set<() => void>();
+function placeScene(area: StdTileBox | 'whole' | null): void {
+  if (JSON.stringify(area) === JSON.stringify(sceneArea)) return;
+  sceneArea = area;
+  for (const listener of [...sceneListeners]) listener();
+}
+function subscribeSceneArea(listener: () => void): () => void {
+  sceneListeners.add(listener);
+  return () => { sceneListeners.delete(listener); };
+}
+
+/** The Game view: the run's stage over its box, the live Scene where the run places it (the current level's view,
+ *  live, `std-level.document.tsx`, mounted for the run's whole life so its camera stays), and what the run says. */
+function GameView({ active }: { readonly active: boolean }) {
+  const box = useRef<HTMLDivElement | null>(null);
+  const held = useSyncExternalStore(subscribeStage, () => stage, () => null);
+  const area = useSyncExternalStore(subscribeSceneArea, () => sceneArea, () => null);
+  const level = useSyncExternalStore(subscribeCurrentStdLevel, currentStdLevel, () => null);
+  const playing = useSyncExternalStore(subscribeGame, gamePlaying, () => false);
+  const failure = useSyncExternalStore(subscribeGameClock, () => gameClock().failure, () => null);
+  const running = useSyncExternalStore(subscribeGameClock, () => gameClock().running, () => false);
+  useSyncExternalStore(subscribeStdRun, stdRunVersion, stdRunVersion);
+  useLayoutEffect(() => {
+    if (!active || held === null || box.current === null) return undefined;
+    return claimDocumentLayer(GAME_DOCUMENT, box.current);
+  }, [active, held]);
+  // (the play frame `capture --region play` takes, `editor-chrome-capture.ts`: the viewed player's page in the stage, or
+  // the Scene; Grid shows several, and names none)
+  const view = stdRun()?.view;
+  useLayoutEffect(() => {
+    if (held === null) return;
+    if (typeof view === 'number') held.host.dataset['volterPlayFrame'] = '';
+    else delete held.host.dataset['volterPlayFrame'];
+  }, [held, view]);
+  const said = !playing ? 'Stopped: press Play in the Game panel.' : failure;
+  useProgress(playing && !failure && !running ? { documentId: GAME_DOCUMENT, title: 'Starting the game' } : null);
+  const sceneBox: CSSProperties = area === null ? { inset: 0, visibility: 'hidden' } : area === 'whole' ? { inset: 0 } : {
+    left: `${area.left * 100}%`, top: `${area.top * 100}%`, width: `${area.width * 100}%`, height: `${area.height * 100}%`,
+  };
+  return (
+    <div ref={box} data-testid="game-view" style={{ position: 'absolute', inset: 0, background: themeVars.surface.inset }}>
+      {playing && (
+        <div data-testid="game-view-scene" {...(view === 'scene' ? { 'data-volter-play-frame': '' } : {})}
+          style={{ position: 'absolute', ...sceneBox, display: 'flex', flexDirection: 'column' }}>
+          {level === null
+            ? <StateSurface fill title="Open a level to see it here, live." />
+            : <StdLevelView documentId={SCENE_VIEW} level={level.path} label={level.label} live />}
+        </div>
+      )}
+      {said !== null && <StateSurface fill tone={playing ? 'error' : 'neutral'} title={said} style={{ pointerEvents: 'none' }} />}
+    </div>
+  );
+}
+
+/** What runs the game in a stage, as play's page half runs it (`play.page.tsx`): the answer stops it. */
+export type GameRunner = (stage: GameStage) => () => void;
+
+/** Whether the Game view holds the keyboard: it is the document in front, and the focus is the page's own, in the
+ *  Game view (its box or its layer), or the pane that holds the Game view alone, never another part of the workbench. */
+function gameViewHasKeys(): boolean {
+  const shown = claimedBox(GAME_DOCUMENT);
+  if (activeWorkspaceDocumentId() !== GAME_DOCUMENT || shown === null) return false;
+  const focused = document.activeElement;
+  if (focused === null || focused === document.body) return true;
+  if (shown.contains(focused) || (documentLayerOf(GAME_DOCUMENT)?.contains(focused) ?? false)) return true;
+  // (a pane parks the documents behind its tab, unseen: the one it shows is the Game view)
+  const seen = [...focused.querySelectorAll<HTMLElement>('[data-volter-document]')].filter((one) => one.checkVisibility());
+  return focused.contains(shown) && seen.length === 1;
+}
+
+/** The Game view brought to the front while the game runs (`play` asked of a game already playing), as Play brings it
+ *  there as the run starts; nothing while the game has no Game view. */
+export function showGameView(): void {
+  if (openWorkspaceDocuments().some((open) => open.descriptor.id === GAME_DOCUMENT)) activateWorkspaceDocument(GAME_DOCUMENT);
+}
+
+/**
+ * THE PROJECT'S RUN, kept while play is active: Play opens the Game view and runs the game in its stage, a Restart runs
+ * it again, and Stop (or the Game view closed) ends it and brings back the tab that was in front.
+ */
+export function keepGameRuns(run: GameRunner): () => void {
+  let stop: (() => void) | null = null;
+  let generation = -1;
+  let before: string | null = null;
+  const view = (): boolean => openWorkspaceDocuments().some((open) => open.descriptor.id === GAME_DOCUMENT);
+  const sync = (): void => {
+    const playing = gamePlaying();
+    const now = gameGeneration();
+    if (playing && (stop === null || generation !== now)) {
+      stop?.();
+      stop = null;
+      generation = now;
+      if (!view()) {
+        const front = activeWorkspaceDocumentId();
+        before = front === GAME_DOCUMENT ? before : front;
+        openWorkspaceDocument({
+          id: GAME_DOCUMENT,
+          title: 'Game',
+          kind: 'tool-contribution',
+          Content: GameView,
+          // (the Game view closed is the game stopped)
+          onDispose: () => { if (gamePlaying()) setGamePlaying(false); },
+          // (the Hierarchy and the Inspector in every view are the running level's, its Scene's copy, as Unity's
+          // Hierarchy shows the running scene whichever view is focused: `docs/adr/std-scene-view.md`, decision 8)
+          selection: () => workspaceDocumentSelection(SCENE_VIEW),
+        });
+      } else activateWorkspaceDocument(GAME_DOCUMENT);
+      if (stage === null) setStage(makeStage());
+      const { players, overlay } = stage!;
+      stop = run({
+        container: players,
+        overlay,
+        report: (title, detail) => editorHost().console.error(`${title}: ${detail}`, 'play'),
+        keys: gameViewHasKeys,
+        scene: placeScene,
+        // (the stage's layer laid over the Game view's box, in a page that is seen: its players' pages draw)
+        shown: () => document.visibilityState !== 'hidden' && claimedBox(GAME_DOCUMENT) !== null,
+      });
+    } else if (!playing && stop !== null) {
+      stop();
+      stop = null;
+      placeScene(null);
+      setStage(null);
+      const back = before;
+      before = null;
+      if (view()) closeWorkspaceDocument(GAME_DOCUMENT);
+      if (back !== null) activateWorkspaceDocument(back);
+    }
+  };
+  const unsubscribe = subscribeGame(sync);
+  // (the host hears that the Game view is the document that plays, and whether it is paused: its status line says so)
+  setDocumentPlaySignal('play', {
+    state: (documentId) => (documentId !== GAME_DOCUMENT || !gamePlaying() ? 'stopped' : gameClock().paused ? 'paused' : 'playing'),
+    subscribe: (listener) => {
+      const stopRun = subscribeGame(listener), stopClock = subscribeGameClock(listener);
+      return () => { stopRun(); stopClock(); };
+    },
+  });
+  sync();
+  return () => {
+    unsubscribe();
+    setDocumentPlaySignal('play', null);
+    stop?.();
+    stop = null;
+    if (view()) closeWorkspaceDocument(GAME_DOCUMENT);
+    setStage(null);
+  };
+}

package/src/play-clock.ts

@@ -0,0 +1,62 @@
+/**
+ * THE GAME PANEL'S CLOCK, READ AT TWO RATES (`../contributions/game-panel.tsx`).
+ *
+ * The run announces its clock every frame, and one changed text node in the workbench's
+ * document repaints and re-layerizes the page around it (about 4 ms a frame measured), so the
+ * panel does not re-render on every announcement.
+ *
+ * So the panel reads the clock's STATE (paused, speed, failure, running), which changes when a
+ * person or the game changes it and re-renders at once, and its TEXT (time and tick) at most
+ * {@link CLOCK_TEXT_INTERVAL_MS} apart. The text's last change always lands (a trailing update),
+ * so a paused game's step or a stop reads exactly.
+ */
+import type { GameClock } from './game-run';
+
+/** The clock text's update period: ten times a second, faster than its hundredths can be read. */
+export const CLOCK_TEXT_INTERVAL_MS = 100;
+
+/** `subscribe`, with the listener called at most once per `interval` ms, always after the last
+ *  announcement (trailing). For `useSyncExternalStore`. */
+export function throttledSubscription(
+  subscribe: (listener: () => void) => () => void,
+  interval: number,
+  timers: { set: (run: () => void, ms: number) => unknown; clear: (handle: unknown) => void; now: () => number } = {
+    set: (run, ms) => setTimeout(run, ms),
+    clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+    now: () => performance.now(),
+  },
+): (listener: () => void) => () => void {
+  return (listener) => {
+    let pending: unknown = null;
+    let last = -Infinity;
+    const unsubscribe = subscribe(() => {
+      if (pending !== null) return;
+      pending = timers.set(() => {
+        pending = null;
+        last = timers.now();
+        listener();
+      }, Math.max(0, last + interval - timers.now()));
+    });
+    return () => {
+      if (pending !== null) timers.clear(pending);
+      pending = null;
+      unsubscribe();
+    };
+  };
+}
+
+/** The clock's state without its time: what the panel's controls and status line read. */
+export type ClockState = Pick<GameClock, 'paused' | 'speed' | 'failure' | 'running'>;
+
+/** A snapshot reader for {@link ClockState} that answers the SAME object until a field changes, so
+ *  `useSyncExternalStore` re-renders only on a change of state, not on every tick. */
+export function clockStateReader(read: () => GameClock): () => ClockState {
+  let held: ClockState | null = null;
+  return () => {
+    const clock = read();
+    if (held === null || held.paused !== clock.paused || held.speed !== clock.speed ||
+      (held.failure ?? null) !== (clock.failure ?? null) || held.running !== clock.running)
+      held = { paused: clock.paused, speed: clock.speed, failure: clock.failure ?? null, running: clock.running };
+    return held;
+  };
+}