@volter/play 0.0.0-stage → 0.5.204

package/src/play-log.ts

@@ -0,0 +1,233 @@
+/**
+ * THE MODEL PLAY LOG — what a play script says happened, stamped with the run's own clock.
+ *
+ * The game editor's play log is the receipt of a run (`play-*.jsonl`, `log-format.ts`); this
+ * is Model Play's. A script calls `play.log(kind, facts)` (`play-script.ts`) on the
+ * transitions that explain a run — a jump, a landing, a death and its cause, autoplay's
+ * choice — and an agent reads them back with `cyclotron play-log` or
+ * `editor.modelPlayLog()` in `eval`. `console.log` cannot do this job: the session's
+ * console feed keeps warnings and errors only.
+ *
+ * Every entry carries `simT` (the seconds of simulation since Play started: the sum of the
+ * `dt`s the runner has handed to `update`) and `tick` (the number of the update in
+ * progress; 0 while the script's default export runs), the same two stamps the game
+ * editor's entries carry. They are the Game panel's clock too: the runner advances both at
+ * the same call (`play-script.ts`), so they stand still while paused and run at the speed. The
+ * runner adds its own lifecycle entries (`source: 'play'`): `play-start`, `play-restart` (a
+ * Restart's fresh run, right after its `play-start`), `script-reload` with its reason,
+ * `script-error`, `tint-unsupported`, `tint-unknown-object`, `pause`, `resume`, `step` (one per
+ * stepped update, with its `dt`), `speed` (on a change, and at a start that is not 1×),
+ * `autoplay-on` and `autoplay-off` (each with `by`: `panel`, `cli`, `takeover`, `script`),
+ * `autoplay-unavailable` (a script ran its first update without offering a bot),
+ * `play-stop`.
+ *
+ * ONE LOG PER MODEL DOCUMENT, each its document's latest run. Two documents playing at once
+ * keep separate logs; a read names its document or takes the active Play's (the latest
+ * started that still plays, else the latest started). Play starting from a fresh copy
+ * replaces its document's log; a script reload does not, and the log outlives Stop so a
+ * finished run can be read. The runner writes through the {@link ModelPlayRun} handle Play
+ * started: once that run has ended its handle writes nothing, so a stale timer of an old
+ * script 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} characters. It is never stored: a reload of the
+ * page forgets it, as it forgets the game.
+ *
+ * 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.
+ *
+ * Logging is a read of the script's own values: it never throws into the script and touches
+ * neither the clock nor the copy.
+ */
+
+/** Entries a run's ring keeps; the oldest beyond this are dropped and counted. */
+export const MODEL_PLAY_LOG_CAPACITY = 5000;
+/** The longest JSON one entry's facts keep; longer facts are kept truncated, as a string. */
+export const MODEL_PLAY_LOG_FACTS_CHARS = 2048;
+
+export interface ModelPlayLogEntry {
+  /** The entry's place in this run, from 0: a gap in `seq` is entries the ring dropped. */
+  readonly seq: number;
+  /** Wall-clock ms. */
+  readonly t: number;
+  /** Seconds of simulation since Play started, across script reloads. */
+  readonly simT: number;
+  /** The update in progress (the first is 1); 0 before the first. */
+  readonly tick: number;
+  readonly kind: string;
+  /** `script` for the play script's own entries; `play` for the runner's lifecycle ones. */
+  readonly source: 'script' | 'play';
+  readonly facts?: Record<string, unknown>;
+}
+
+export interface ModelPlayLogReading {
+  /** The run is still playing; false after Stop, or when nothing has played. */
+  readonly playing: boolean;
+  /** The model document and play script of the run read; null when nothing has played. */
+  readonly documentId: string | null;
+  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;
+  readonly capacity: number;
+  /** Entries this run has written, and how many of those the ring has dropped. */
+  readonly total: number;
+  readonly dropped: number;
+  /** The kept entries that match the read's filters, oldest first. */
+  readonly entries: readonly ModelPlayLogEntry[];
+}
+
+export interface ModelPlayLogQuery {
+  /** The model document whose log to read; the active Play's when omitted. */
+  readonly documentId?: string;
+  /** Only entries at or after this simulation time (seconds). */
+  readonly since?: number;
+  /** Only entries of this kind. */
+  readonly kind?: string;
+}
+
+interface Run {
+  readonly documentId: string;
+  readonly script: string;
+  readonly startedAt: number;
+  playing: boolean;
+  simT: number;
+  tick: number;
+  readonly ring: ModelPlayLogEntry[];
+  total: number;
+  /** Every kind this run has written, for the panel's filter. */
+  readonly kinds: Set<string>;
+}
+
+/** The runner's door onto its own run's log: inert once the run has ended. */
+export interface ModelPlayRun {
+  /** The runner is about to call `update(deltaSeconds)`. */
+  advance(deltaSeconds: number): void;
+  append(source: ModelPlayLogEntry['source'], kind: string, facts?: unknown): 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
+// runner writes it from the service, 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 pageListeners = globalThis as typeof globalThis & { [listenersKey]?: Set<() => void> };
+const listeners: Set<() => void> = pageListeners[listenersKey] ??= new Set();
+
+function publish(): void {
+  for (const listener of [...listeners]) {
+    try { listener(); } catch { /* A reader's failure is not the writer's. */ }
+  }
+}
+
+/** Hear every write to any document's log (several may land in one frame; coalesce). */
+export function subscribeModelPlayLog(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+function keptFacts(facts: unknown): Record<string, unknown> | undefined {
+  if (facts === undefined || facts === null) return undefined;
+  let json: string | undefined;
+  try { json = JSON.stringify(facts); }
+  catch (error) { return { unserializable: error instanceof Error ? error.message : String(error) }; }
+  if (json === undefined) return undefined;
+  if (json.length > MODEL_PLAY_LOG_FACTS_CHARS) return { truncated: json.slice(0, MODEL_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): void {
+  try {
+    const kept = keptFacts(facts);
+    const entry: ModelPlayLogEntry = {
+      seq: run.total, t: Date.now(), simT: run.simT, tick: run.tick, kind: String(kind), source,
+      ...(kept ? { facts: kept } : {}),
+    };
+    run.ring[run.total % MODEL_PLAY_LOG_CAPACITY] = entry;
+    run.total += 1;
+    run.kinds.add(entry.kind);
+  } catch { /* A log that cannot be written is not the script'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 });
+  return {
+    advance(deltaSeconds) {
+      if (!run.playing) return;
+      run.tick += 1;
+      run.simT += deltaSeconds;
+    },
+    append(source, kind, facts) { if (run.playing) append(run, source, kind, facts); },
+    end(facts) {
+      if (!run.playing) return;
+      append(run, 'play', 'play-stop', facts);
+      run.playing = false;
+    },
+  };
+}
+
+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()];
+  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: [],
+    };
+  }
+  const dropped = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
+  const entries: ModelPlayLogEntry[] = [];
+  for (let seq = dropped; seq < run.total; seq++) {
+    const entry = run.ring[seq % MODEL_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,
+    simT: run.simT, tick: run.tick, capacity: MODEL_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. */
+  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[];
+}
+
+/** 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);
+  if (!run) return { total: 0, kinds: [], entries: [] };
+  const oldest = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
+  const entries: ModelPlayLogEntry[] = [];
+  for (let seq = run.total - 1; seq >= oldest && entries.length < last; seq--) {
+    const entry = run.ring[seq % MODEL_PLAY_LOG_CAPACITY]!;
+    if (kind === undefined || entry.kind === kind) entries.push(entry);
+  }
+  return { total: run.total, kinds: [...run.kinds], entries: entries.reverse() };
+}

package/src/play-materials.ts

@@ -0,0 +1,199 @@
+/**
+ * RECOLOURING THE DETACHED COPY — `play.tint` and `play.setOpacity` (`play-script.ts`).
+ *
+ * Changing a presented mesh's colour the three.js way does not work on the copy, for reasons
+ * the presenter has and a script cannot see:
+ *
+ * - A Blender mesh's `material` is an ARRAY, one entry per material slot (a lone material only
+ *   for an object with no slots, which wears the presenter's grey fallback), so
+ *   `mesh.material.color` is `undefined`.
+ * - The entries are SHARED: one material per Blender material, worn by every object with it
+ *   in a slot. Recolouring one in place recolours them all.
+ * - The presenter OWNS `mesh.material`: whenever it re-applies shading it assigns every mesh's
+ *   slots again from its own table, so materials a script assigned are put back.
+ * - `clone()` drops the presenter's draw hooks (its shader, private uniforms and node graph).
+ * - A material whose Base Color or Alpha a node graph drives never reads `color` or `opacity`:
+ *   the graph's output replaces them in the shader.
+ *
+ * So an override is per OBJECT: the object's slots are swapped for copies of their own (the
+ * document's `ownMaterial`, which keeps its hooks and draws the material's constants, its
+ * image texture included), the copies carry the tint and opacity, and the slots the presenter
+ * gave are remembered. A slot the document cannot copy (no `ownMaterial`, or a material that
+ * is not the document's) leaves the object as it is and says so through `unsupported`; a
+ * `clone()` would draw without the presenter's hooks.
+ *
+ * The presenter's slots are re-read whenever they may have moved: an object whose slots the
+ * presenter has put back is given copies of the slots it now has, both each frame and before
+ * any change, so clearing returns the presenter's current slots, never a stale set. An object
+ * the script removed from the copy is let go on the next frame. That is heard, not searched
+ * for: each overridden mesh and its parents up to the copy's root report their own removal
+ * (three's `removed` event, which `remove`, `add` elsewhere and `attach` all dispatch), and only
+ * a mesh one of them reported is walked up to see whether it is still in the copy.
+ */
+import type * as THREE from 'three';
+
+type Slots = THREE.Material | THREE.Material[];
+type Colored = THREE.Material & { color?: THREE.Color; emissive?: THREE.Color };
+
+interface Override {
+  readonly mesh: THREE.Mesh;
+  authored: Slots;
+  shown: Slots;
+  copies: Colored[];
+  color: THREE.ColorRepresentation | null;
+  opacity: number | null;
+  /** The mesh and its parents below the copy's root, each told to report its removal. */
+  watched: THREE.Object3D[];
+  /** One of them was removed from its parent since the last frame. */
+  moved: boolean;
+  readonly onRemoved: () => void;
+}
+
+const slotsOf = (slots: Slots): THREE.Material[] => Array.isArray(slots) ? slots : [slots];
+const isColor = (value: unknown): value is THREE.Color =>
+  typeof value === 'object' && value !== null && (value as THREE.Color).isColor === true;
+
+export interface MaterialOverrides {
+  tint(target: THREE.Object3D, color: THREE.ColorRepresentation | null): void;
+  setOpacity(target: THREE.Object3D, opacity: number | null): void;
+  /** After the script's update: let go of removed objects, and re-wear the copies on any
+   *  object the presenter re-dressed. */
+  frame(): void;
+  /** Return every object the presenter's slots and release the copies; later calls do nothing. */
+  dispose(): void;
+}
+
+/**
+ * `ownMaterial` answers the document's copy of one of its materials, or null for one that is
+ * not the document's. `unsupported` hears of an object that could not be overridden.
+ */
+export function materialOverrides(options: {
+  readonly root: THREE.Object3D;
+  readonly ownMaterial: ((material: THREE.Material) => THREE.Material | null) | undefined;
+  readonly unsupported: (mesh: THREE.Mesh, material: THREE.Material) => void;
+}): MaterialOverrides {
+  const { root, ownMaterial } = options;
+  const overrides = new Map<THREE.Mesh, Override>();
+  let disposed = false;
+  const release = (override: Override): void => {
+    for (const copy of override.copies) copy.dispose();
+    override.copies = [];
+  };
+  const unwatch = (override: Override): void => {
+    for (const object of override.watched) object.removeEventListener('removed', override.onRemoved);
+    override.watched = [];
+  };
+  /** Hear the mesh or a parent leave; a mesh not under the copy's root is let go next frame. */
+  const watch = (override: Override): void => {
+    unwatch(override);
+    let at: THREE.Object3D | null = override.mesh;
+    for (; at && at !== root; at = at.parent) {
+      at.addEventListener('removed', override.onRemoved);
+      override.watched.push(at);
+    }
+    override.moved = at !== root;
+  };
+  /** Wear copies of the object's slots; false (and nothing worn) when one cannot be copied. */
+  const dress = (override: Override): boolean => {
+    release(override);
+    const copies: Colored[] = [];
+    for (const material of slotsOf(override.authored)) {
+      const copy = ownMaterial?.(material) ?? null;
+      if (!copy) {
+        for (const made of copies) made.dispose();
+        override.mesh.material = override.authored;
+        options.unsupported(override.mesh, material);
+        return false;
+      }
+      copies.push(copy as Colored);
+    }
+    override.copies = copies;
+    override.shown = Array.isArray(override.authored) ? copies : copies[0]!;
+    override.mesh.material = override.shown;
+    return true;
+  };
+  // Values only: the copies were made from the authored slots, so each starts from its own.
+  const paint = (override: Override): void => {
+    const authored = slotsOf(override.authored) as Colored[];
+    override.copies.forEach((copy, index) => {
+      const source = authored[index]!;
+      if (isColor(copy.color) && isColor(source.color)) {
+        if (override.color === null) copy.color.copy(source.color);
+        else copy.color.set(override.color);
+      }
+      // An emitting surface glows in its tint; one that does not stays unlit by it.
+      if (isColor(copy.emissive) && isColor(source.emissive)) {
+        const emits = source.emissive.r + source.emissive.g + source.emissive.b > 0;
+        if (override.color === null || !emits) copy.emissive.copy(source.emissive);
+        else copy.emissive.set(override.color);
+      }
+      copy.opacity = override.opacity ?? source.opacity;
+      const transparent = source.transparent || copy.opacity < 1;
+      if (copy.transparent !== transparent) {
+        copy.transparent = transparent;
+        copy.needsUpdate = true;
+      }
+    });
+  };
+  const forget = (override: Override): void => {
+    if (override.mesh.material === override.shown) override.mesh.material = override.authored;
+    release(override);
+    unwatch(override);
+    overrides.delete(override.mesh);
+  };
+  /** The presenter re-assigned the object's slots since it last wore copies: adopt its slots
+   *  as the authored ones and dress again. False when they cannot be copied. */
+  const resync = (override: Override): boolean => {
+    if (override.mesh.material === override.shown) return true;
+    override.authored = override.mesh.material;
+    override.shown = override.mesh.material;
+    if (dress(override)) return true;
+    release(override);
+    unwatch(override);
+    overrides.delete(override.mesh);
+    return false;
+  };
+  const change = (target: THREE.Object3D, edit: (override: Override) => void): void => {
+    if (disposed) return;
+    target.traverse((object) => {
+      const mesh = object as THREE.Mesh;
+      if (mesh.isMesh !== true || !mesh.material) return;
+      let override = overrides.get(mesh);
+      if (override && !resync(override)) override = undefined;
+      if (!override) {
+        const fresh: Override = { mesh, authored: mesh.material, shown: mesh.material, copies: [], color: null, opacity: null,
+          watched: [], moved: false, onRemoved: () => { fresh.moved = true; } };
+        edit(fresh);
+        if (fresh.color === null && fresh.opacity === null) return;
+        if (!dress(fresh)) return;
+        overrides.set(mesh, fresh);
+        watch(fresh);
+        override = fresh;
+      } else edit(override);
+      if (override.color === null && override.opacity === null) forget(override);
+      else paint(override);
+    });
+  };
+  return {
+    tint(target, color) { change(target, (override) => { override.color = color; }); },
+    setOpacity(target, opacity) {
+      if (opacity !== null && !Number.isFinite(opacity)) throw new Error(`setOpacity takes a number from 0 to 1, or null; it was given ${String(opacity)}.`);
+      const value = opacity === null ? null : Math.min(1, Math.max(0, opacity));
+      change(target, (override) => { override.opacity = value; });
+    },
+    frame() {
+      for (const override of [...overrides.values()]) {
+        if (override.moved) {
+          // Re-walked only after a reported removal; one put back under the copy is watched anew.
+          watch(override);
+          if (override.moved) { forget(override); continue; }
+        }
+        if (override.mesh.material !== override.shown && resync(override)) paint(override);
+      }
+    },
+    dispose() {
+      disposed = true;
+      for (const override of [...overrides.values()]) forget(override);
+    },
+  };
+}