@volter/play 0.5.212 → 0.5.213

package/src/play-log.ts

@@ -1,34 +1,33 @@
 /**
- * THE MODEL PLAY LOG: what a std game's run says happened.
+ * THE PLAY LOG: what the game's run says happened.
  *
  * Each player's page traces its run (std's trace, as the dev server's receiver writes it, `build/runs/<run>/<page>.jsonl`)
  * and the run reads each trace into this log, each entry tagged with its player's slot (`std-game.ts`, `source:
  * 'script'`). Play adds its own lifecycle entries (`source: 'play'`): `play-start`, `running`, `player-joined`,
  * `player-page-loaded`, `player-left`, `view`, `autoplay-on` and `autoplay-off` (each with `by`), `pause`, `resume`,
  * `step` and `speed` (each with the clock std answered), `capture` (its file), `script-error` (with its `phase`) and
- * `play-stop`. An agent reads them back with `cyclotron play-log` or `editor.contributedVerb('model-play-log')` in
+ * `play-stop`. An agent reads them back with `cyclotron play-log` or `editor.contributedVerb('play-log')` in
  * `eval`: the session's console feed keeps warnings and errors only.
  *
  * WHEN EACH HAPPENED: a trace entry carries its page's own time, its trace's step (std's trace format 3: `s`, sixty a
- * second of the page's steady clock) as `tick` and that step in seconds as `simT`; Play's own entries carry the run's
- * elapsed seconds since its `play-start` as `simT`, and the newest trace step heard as `tick`. So `--since` reads the
- * run's seconds, a page's from its own start.
+ * second of the page's game clock, its `performance.now` on a live page) as `tick` and that step in seconds as `simT`;
+ * Play's own entries carry the run's elapsed seconds since its `play-start` as `simT`, and the newest trace step heard
+ * as `tick`. So `--since` reads the run's seconds, a page's from its own start.
  *
- * ONE LOG PER MODEL DOCUMENT, each its document's latest run. A read names its document or takes the active Play's
- * (the latest started that still plays, else the latest started). Each Play replaces its document's log, and the log
- * outlives Stop so a finished run can be read. The run writes through the {@link ModelPlayRun} handle Play started:
- * once that run has ended its handle writes nothing, so a stale timer of an old run cannot reach the next run's log.
+ * ONE LOG, the latest run's. Each Play replaces it, and it outlives Stop so a finished run can be read. The run writes
+ * through the {@link PlayLogRun} handle Play started: once that run has ended its handle writes nothing, so a stale
+ * timer of an old run cannot reach the next run's log.
  *
- * BOUNDED AND PAGE-LIFETIME. The newest {@link MODEL_PLAY_LOG_CAPACITY} entries of a run are kept in a ring (older
- * ones are counted in `dropped`); one entry's facts are kept as JSON of at most {@link MODEL_PLAY_LOG_FACTS_CHARS}
+ * BOUNDED AND PAGE-LIFETIME. The newest {@link PLAY_LOG_CAPACITY} entries of a run are kept in a ring (older
+ * ones are counted in `dropped`); one entry's facts are kept as JSON of at most {@link PLAY_LOG_FACTS_CHARS}
  * characters. It is never stored: a reload of the page forgets it, as it forgets the run.
  *
- * THE GAME PANEL DRAWS IT LIVE: {@link subscribeModelPlayLog} hears every write, and {@link tailModelPlayLog} reads the
- * newest entries of one document without copying the ring.
+ * THE GAME PANEL DRAWS IT LIVE: {@link subscribePlayLog} hears every write, and {@link tailPlayLog} reads the newest
+ * entries without copying the ring.
  */
 
-/** One entry of a document's play log (`model-play-log`): read from a player's page's trace, or written by Play. */
-export interface ModelPlayLogEntry {
+/** One entry of the play log (`play-log`): read from a player's page's trace, or written by Play. */
+export interface PlayLogEntry {
   /** The entry's place in its run, from 0: a gap in `seq` is entries the bounded log dropped. */
   readonly seq: number;
   /** Wall-clock ms. */
@@ -44,19 +43,16 @@ export interface ModelPlayLogEntry {
 }
 
 /** Entries a run's ring keeps; the oldest beyond this are dropped and counted. */
-const MODEL_PLAY_LOG_CAPACITY = 5000;
+const PLAY_LOG_CAPACITY = 5000;
 /** The longest JSON one entry's facts keep; longer facts are kept truncated, as a string. */
-const MODEL_PLAY_LOG_FACTS_CHARS = 2048;
+const PLAY_LOG_FACTS_CHARS = 2048;
 
-export interface ModelPlayLogReading {
+export interface PlayLogReading {
   /** The run is still playing; false after Stop, or when nothing has played. */
   readonly playing: boolean;
-  /** The model document and what its run ran (the game's dev server command); null when nothing has played. */
-  readonly documentId: string | null;
+  /** What the run ran (the game's dev server command); null when nothing has played. */
   readonly script: string | null;
   readonly startedAt: number | null;
-  /** Every model document with a log, so a read can name another. */
-  readonly documents: readonly string[];
   /** The run's clock now. */
   readonly simT: number;
   readonly tick: number;
@@ -65,12 +61,10 @@ export interface ModelPlayLogReading {
   readonly total: number;
   readonly dropped: number;
   /** The kept entries that match the read's filters, oldest first. */
-  readonly entries: readonly ModelPlayLogEntry[];
+  readonly entries: readonly PlayLogEntry[];
 }
 
-export interface ModelPlayLogQuery {
-  /** The model document whose log to read; the active Play's when omitted. */
-  readonly documentId?: string;
+export interface PlayLogQuery {
   /** Only entries at or after this game time (seconds). */
   readonly since?: number;
   /** Only entries of this kind. */
@@ -78,32 +72,31 @@ export interface ModelPlayLogQuery {
 }
 
 interface Run {
-  readonly documentId: string;
   readonly script: string;
   readonly startedAt: number;
   playing: boolean;
   simT: number;
   tick: number;
-  readonly ring: ModelPlayLogEntry[];
+  readonly ring: PlayLogEntry[];
   total: number;
   /** Every kind this run has written, for the panel's filter. */
   readonly kinds: Set<string>;
 }
 
 /** The run's door onto its own log: inert once the run has ended. */
-export interface ModelPlayRun {
+export interface PlayLogRun {
   /** An entry, stamped with `at` (a trace line's page time) or else the run's elapsed seconds. */
-  append(source: ModelPlayLogEntry['source'], kind: string, facts?: unknown, at?: { readonly simT: number; readonly tick: number }): void;
+  append(source: PlayLogEntry['source'], kind: string, facts?: unknown, at?: { readonly simT: number; readonly tick: number }): void;
   /** `play-stop`, then nothing more is written; the entries stay readable. */
   end(facts?: Record<string, unknown>): void;
 }
 
 // One registry per page, whichever copy of this module a contribution loaded it through: the
 // run writes it, the session verb reads it from the command module.
-const key = Symbol.for('volter.model-play-log');
-const page = globalThis as typeof globalThis & { [key]?: Map<string, Run> };
-const runs: Map<string, Run> = page[key] ??= new Map();
-const listenersKey = Symbol.for('volter.model-play-log.listeners');
+const key = Symbol.for('volter.play-log');
+const page = globalThis as typeof globalThis & { [key]?: { run: Run | null } };
+const held: { run: Run | null } = page[key] ??= { run: null };
+const listenersKey = Symbol.for('volter.play-log.listeners');
 const pageListeners = globalThis as typeof globalThis & { [listenersKey]?: Set<() => void> };
 const listeners: Set<() => void> = pageListeners[listenersKey] ??= new Set();
 
@@ -113,8 +106,8 @@ function publish(): void {
   }
 }
 
-/** Hear every write to any document's log (several may land in one frame; coalesce). */
-export function subscribeModelPlayLog(listener: () => void): () => void {
+/** Hear every write to the log (several may land in one frame; coalesce). */
+export function subscribePlayLog(listener: () => void): () => void {
   listeners.add(listener);
   return () => { listeners.delete(listener); };
 }
@@ -153,39 +146,36 @@ function keptFacts(facts: unknown): Record<string, unknown> | undefined {
   try { json = JSON.stringify(ordered); }
   catch (error) { return { unserializable: error instanceof Error ? error.message : String(error) }; }
   if (json === undefined) return undefined;
-  if (json.length > MODEL_PLAY_LOG_FACTS_CHARS && ordered !== facts) json = JSON.stringify(shortened(ordered as Record<string, unknown>));
-  if (json.length > MODEL_PLAY_LOG_FACTS_CHARS) return { truncated: json.slice(0, MODEL_PLAY_LOG_FACTS_CHARS) };
+  if (json.length > PLAY_LOG_FACTS_CHARS && ordered !== facts) json = JSON.stringify(shortened(ordered as Record<string, unknown>));
+  if (json.length > PLAY_LOG_FACTS_CHARS) return { truncated: json.slice(0, PLAY_LOG_FACTS_CHARS) };
   // A snapshot, so a script that goes on mutating what it logged does not rewrite history.
   const value: unknown = JSON.parse(json);
   return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : { value };
 }
 
-function append(run: Run, source: ModelPlayLogEntry['source'], kind: string, facts?: unknown, at?: { readonly simT: number; readonly tick: number }): void {
+function append(run: Run, source: PlayLogEntry['source'], kind: string, facts?: unknown, at?: { readonly simT: number; readonly tick: number }): void {
   try {
     const kept = keptFacts(facts);
     const t = Date.now();
     const simT = at?.simT ?? (t - run.startedAt) / 1000;
     if (at !== undefined) run.tick = Math.max(run.tick, at.tick);
     run.simT = Math.max(run.simT, (t - run.startedAt) / 1000);
-    const entry: ModelPlayLogEntry = {
+    const entry: PlayLogEntry = {
       seq: run.total, t, simT, tick: at?.tick ?? run.tick, kind: String(kind), source,
       ...(kept ? { facts: kept } : {}),
     };
-    run.ring[run.total % MODEL_PLAY_LOG_CAPACITY] = entry;
+    run.ring[run.total % PLAY_LOG_CAPACITY] = entry;
     run.total += 1;
     run.kinds.add(entry.kind);
   } catch { /* A log that cannot be written is not the run's failure. */ }
   publish();
 }
 
-/** Play started from a fresh copy: the document's log replaced by an empty one at zero,
- *  opened by `play-start`. */
-export function beginModelPlayLog(documentId: string, script: string): ModelPlayRun {
-  const run: Run = { documentId, script, startedAt: Date.now(), playing: true, simT: 0, tick: 0, ring: [], total: 0, kinds: new Set() };
-  // Re-inserted, so the map's order is the order Plays started.
-  runs.delete(documentId);
-  runs.set(documentId, run);
-  append(run, 'play', 'play-start', { documentId, script });
+/** A run started: the log replaced by an empty one at zero, opened by `play-start`. */
+export function beginPlayLog(script: string): PlayLogRun {
+  const run: Run = { script, startedAt: Date.now(), playing: true, simT: 0, tick: 0, ring: [], total: 0, kinds: new Set() };
+  held.run = run;
+  append(run, 'play', 'play-start', { script });
   return {
     append(source, kind, facts, at) { if (run.playing) append(run, source, kind, facts, at); },
     end(facts) {
@@ -196,52 +186,46 @@ export function beginModelPlayLog(documentId: string, script: string): ModelPlay
   };
 }
 
-function activeRun(): Run | undefined {
-  const started = [...runs.values()].reverse();
-  return started.find((run) => run.playing) ?? started[0];
-}
-
-export function readModelPlayLog(query: ModelPlayLogQuery = {}): ModelPlayLogReading {
-  const run = query.documentId === undefined ? activeRun() : runs.get(query.documentId);
-  const documents = [...runs.keys()];
+export function readPlayLog(query: PlayLogQuery = {}): PlayLogReading {
+  const { run } = held;
   if (!run) {
     return {
-      playing: false, documentId: query.documentId ?? null, script: null, startedAt: null, documents,
-      simT: 0, tick: 0, capacity: MODEL_PLAY_LOG_CAPACITY, total: 0, dropped: 0, entries: [],
+      playing: false, script: null, startedAt: null,
+      simT: 0, tick: 0, capacity: PLAY_LOG_CAPACITY, total: 0, dropped: 0, entries: [],
     };
   }
-  const dropped = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
-  const entries: ModelPlayLogEntry[] = [];
+  const dropped = Math.max(0, run.total - PLAY_LOG_CAPACITY);
+  const entries: PlayLogEntry[] = [];
   for (let seq = dropped; seq < run.total; seq++) {
-    const entry = run.ring[seq % MODEL_PLAY_LOG_CAPACITY]!;
+    const entry = run.ring[seq % PLAY_LOG_CAPACITY]!;
     if (query.since !== undefined && entry.simT < query.since) continue;
     if (query.kind !== undefined && entry.kind !== query.kind) continue;
     entries.push(entry);
   }
   return {
-    playing: run.playing, documentId: run.documentId, script: run.script, startedAt: run.startedAt, documents,
+    playing: run.playing, script: run.script, startedAt: run.startedAt,
     simT: run.playing ? Math.max(run.simT, (Date.now() - run.startedAt) / 1000) : run.simT, tick: run.tick,
-    capacity: MODEL_PLAY_LOG_CAPACITY, total: run.total, dropped, entries,
+    capacity: PLAY_LOG_CAPACITY, total: run.total, dropped, entries,
   };
 }
 
-export interface ModelPlayLogTail {
-  /** Entries the document's latest run has written; 0 when it has no log. */
+export interface PlayLogTail {
+  /** Entries the latest run has written; 0 when nothing has played. */
   readonly total: number;
   /** Every kind that run has written, in the order first seen. */
   readonly kinds: readonly string[];
   /** The newest kept entries (of the asked kind), at most `last`, oldest first. */
-  readonly entries: readonly ModelPlayLogEntry[];
+  readonly entries: readonly PlayLogEntry[];
 }
 
-/** The newest `last` entries of one document's log, walked from the newest end. */
-export function tailModelPlayLog(documentId: string, last: number, kind?: string): ModelPlayLogTail {
-  const run = runs.get(documentId);
+/** The newest `last` entries of the log, walked from the newest end. */
+export function tailPlayLog(last: number, kind?: string): PlayLogTail {
+  const { run } = held;
   if (!run) return { total: 0, kinds: [], entries: [] };
-  const oldest = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
-  const entries: ModelPlayLogEntry[] = [];
+  const oldest = Math.max(0, run.total - PLAY_LOG_CAPACITY);
+  const entries: PlayLogEntry[] = [];
   for (let seq = run.total - 1; seq >= oldest && entries.length < last; seq--) {
-    const entry = run.ring[seq % MODEL_PLAY_LOG_CAPACITY]!;
+    const entry = run.ring[seq % PLAY_LOG_CAPACITY]!;
     if (kind === undefined || entry.kind === kind) entries.push(entry);
   }
   return { total: run.total, kinds: [...run.kinds], entries: entries.reverse() };

package/src/std-controls.ts

@@ -10,8 +10,8 @@
  *   Colyseus has no pause for a room.
  * - `inspect`: `{ control: 'inspect' }`, answered with the scene the page last drew and its labelled screen nodes,
  *   `{ objects, screen, truncated? }` (at most 2000 objects and 500 nodes, `truncated` saying how many were left out).
- * - `act`: `{ control: 'act', actions, observe? }`, std-driver/2 `Action`s through the page's own input path, answered
- *   with the observation (std-driver/2 `Observation`) where `observe` asks for one, else `{ ok: true }`. A refused
+ * - `act`: `{ control: 'act', actions, observe? }`, std-driver/3 `Action`s through the page's own input path, answered
+ *   with the observation (std-driver/3 `Observation`) where `observe` asks for one, else `{ ok: true }`. A refused
  *   action fails the whole control, the actions before it already taken.
  *
  * `clock`, `inspect` and `act` need a device of exactly one page (a tab or a frame, as each of Play's players is).
@@ -62,7 +62,7 @@ export function stdClock(device: string, asked: StdClockAction): Promise<StdCloc
 }
 
 /** One object of the scene a page last drew, as std's inspect reads it. */
-export interface StdInspectedObject {
+interface StdInspectedObject {
   readonly name: string;
   /** three's own `type`. */
   readonly type: string;
@@ -83,8 +83,8 @@ export interface StdInspection {
   readonly truncated?: { readonly objects: number; readonly screen: number };
 }
 
-/** One labelled node of a page's screen, as std's inspect names it (std-driver/2's `NodeObserved`). */
-export interface StdScreenNode {
+/** One labelled node of a page's screen, as std's inspect names it (std-driver/3's `NodeObserved`). */
+interface StdScreenNode {
   readonly role?: string;
   readonly name?: string;
   readonly [key: string]: unknown;
@@ -94,13 +94,13 @@ export function stdInspect(device: string): Promise<StdInspection> {
   return control<StdInspection>(device, { control: 'inspect' });
 }
 
-/** One std-driver/2 action: a key pressed or let go, or the pointer at a point of the page (0 to 1, x right, y down)
+/** One std-driver/3 action: a key pressed or let go, or the pointer at a point of the page (0 to 1, x right, y down)
  *  with `button` pressed or let go. */
 export type StdAction =
   | { readonly key: { readonly key: string; readonly down: boolean } }
   | { readonly pointer: { readonly x: number; readonly y: number; readonly button?: number; readonly down?: boolean } };
 
-/** Actions taken through the page's own input path, as a player's own; the observation after them (std-driver/2's
+/** Actions taken through the page's own input path, as a player's own; the observation after them (std-driver/3's
  *  `Observation`) where asked, else `{ ok: true }`. */
 export function stdAct(device: string, actions: readonly StdAction[], observe = false): Promise<unknown> {
   return control(device, { control: 'act', actions, ...(observe ? { observe: true } : {}) });

package/src/std-export.ts

@@ -49,14 +49,6 @@ function publish(next: StdExport): void {
   for (const listener of listeners) listener();
 }
 
-/** Whether the Game panel's Export menu is open: its Escape closes it alone, never the game's view as well
- *  (`std-game.ts`'s view keys, which hear a key before the menu does). */
-let menuOpen = false;
-export const exportMenuOpen = (): boolean => menuOpen;
-export function setExportMenuOpen(open: boolean): void {
-  menuOpen = open;
-}
-
 /** The latest export, running or ended; null before any. */
 export const stdExport = (): StdExport | null => current;
 

package/src/std-game-adapter.ts

@@ -3,18 +3,24 @@
  * `std.json`). A std game carries no editor code: std's design has the editor add nothing to the game (design 8), so
  * the adapter a Cyclotron project would keep in `editor/volter.adapter.ts` is Play's. It is the one a models project
  * gets from `cyclotron create`, Blender's layout, keymap and properties inspector, with the game's Blender files as its
- * documents: every `.blend` under `levels/` and every prefab's under `prefabs/` (std's `prefabs/<name>/<name>.blend`).
- * A game with one level opens it.
+ * documents: every `.blend` under `levels/` and every prefab's under `prefabs/` (std's `prefabs/<name>/<name>.blend`),
+ * and each level (`levels/<Name>Level.tsx`) a document of its own (`stdLevelDocuments`), the main level the one the
+ * project opens on.
  */
 import { defineAdapter } from '@volter/project/adapter/adapter-module';
 import { ModelLayout } from '@volter/editor-blender/layouts';
 import { blenderKeymap } from '@volter/editor-blender/looks';
 // (the game's dev server serves this module, so the SDK's change channel it brings is that server's: it joins the
-// editor's page to the server's file events, which a std game's own modules never import, and the Scene view and
+// editor's page to the server's file events, which a std game's own modules never import, and a level's document and
 // Play's remount hear each save's export through it)
 import '@volter/sdk/project-module-changes';
 
 export default defineAdapter({
   editor: { Layout: ModelLayout, keymap: blenderKeymap, inspector: 'properties' },
-  documents: { find: [{ finder: 'modelsFromBlendFiles', include: ['levels/**/*.blend', 'prefabs/**/*.blend'], defaultIn: 'levels/' }] },
+  documents: {
+    find: [
+      { finder: 'modelsFromBlendFiles', include: ['levels/**/*.blend', 'prefabs/**/*.blend'] },
+      { finder: 'stdLevelDocuments', include: ['levels/**/*.tsx', 'levels/**/*.blend'] },
+    ],
+  },
 });