@volter/editor-model-play 0.5.188 → 0.5.190

package/README.md

@@ -0,0 +1,71 @@
+# Volter Model Play
+
+Play scripts on detached model documents. The header's Play runs
+`src/models/<name>.play.ts` beside `src/models/<name>.blend` on a detached copy
+of the model; the model, its selection and its history stand as they were, and
+Stop returns to them. The script's default export is called once with the play
+context (`ModelPlayContext`, `src/play-script.ts`) and answers the game:
+
+```ts
+import type { ModelPlayContext, ModelPlayGame } from '@volter/editor-model-play/play-script';
+
+export default (play: ModelPlayContext): ModelPlayGame => {
+  const player = play.find('Player')!;
+  let checkpoint = false;
+  return {
+    update(dt) {
+      player.position.y += dt;
+      if (!checkpoint && player.position.y > 10) {
+        checkpoint = true;
+        play.tint('Checkpoint.Pad', '#2bff6b');
+        play.log('checkpoint', { stage: 2, at: player.position });
+      }
+    },
+  };
+};
+```
+
+## The play log
+
+`play.log(kind, facts?)` writes one entry, stamped with `simT` (seconds of
+simulation since Play started, the sum of the `dt`s given to `update`) and
+`tick` (the update in progress). Facts are snapshotted as JSON when logged. The
+runner adds `play-start`, `script-reload` (`{ reason: 'saved' | 'dependency-deleted', path }`),
+`script-error` (`{ phase, message }`), `tint-unsupported` (`{ object, material, why }`)
+and `play-stop` (`{ reason }`). Log transitions rather than every frame. Logging
+never throws and never changes timing or state; a script's `log`, `tint` and
+`setOpacity` do nothing once it has been replaced or Play has stopped.
+
+Each model document keeps its own log; a read takes the active Play's unless it
+names a document. The newest 5000 entries are kept (older ones are counted as
+`dropped`), each entry's facts up to 2048 characters of JSON. Play from a fresh
+copy empties the document's log; a script reload does not, and the log stays readable after Stop until the
+next Play. `console.log` does not reach the session's console feed (only
+warnings and errors do); the play log does.
+
+```sh
+volter-model-editor play-log                     # every kept entry, one per line
+volter-model-editor play-log --kind death        # one kind
+volter-model-editor play-log --since 12.5 --json # entries at or after simT 12.5, as JSON
+volter-model-editor play-log --document <id>     # another model document's log
+volter-model-editor eval "(await editor.modelPlayLog({ kind: 'death' })).entries"
+```
+
+## Recolouring the copy
+
+`play.tint(object, color)` draws an object (a name, or what `find` answered)
+and every mesh under it in `color`; an emitting surface glows in it, and an
+image texture is multiplied by it. `play.setOpacity(object, opacity)` fades it.
+`null` returns the authored look. Other objects wearing the same Blender
+material are not affected.
+
+Use these instead of editing materials directly: a presented mesh's `material`
+is an array with one `MeshPhysicalMaterial` per Blender material slot, shared by
+every object with that material; the presenter re-assigns those slots whenever
+it re-applies shading; `clone()` drops its shader hooks; and a node graph that
+drives Base Color or Alpha ignores `color` and `opacity`. A tinted or faded
+object wears copies of its own slots that draw the material's constant inputs
+(so a node graph's other inputs are not drawn while it does), and keeps them
+across a script reload. An object with a material the document cannot copy
+(one the script made itself) is left as it is, and the log says so once with
+`tint-unsupported`.

package/contributions/model-play.command.ts

@@ -0,0 +1,37 @@
+/**
+ * THE MODEL PLAY VERB of the session wire (`@volter/editor-sdk/commands`, a
+ * `workspace.command` contribution): `model-play-log`, the read behind
+ * `volter-model-editor 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/editor-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

@@ -5,6 +5,7 @@ import { registerDocumentPlayExtension, type DocumentPlayControlProps } from '@v
 import { escapeModelPlay, modelPlaying, setModelPlaying, subscribeModelPlay } from '../src/model-play';
 import { runPlayScript } from '../src/play-script';
 import type * as THREE from 'three';
+import { getCurrentProject, onProjectChange } from '@volter/editor-sdk/kit/active-project';
 
 export const point = 'workspace.service';
 function usePlaying(documentId: string | undefined): boolean {
@@ -28,11 +29,21 @@ function Menu({ documentId, onClose }: DocumentPlayControlProps) {
 }
 export function start(): () => void {
   const unregister = registerDocumentPlayExtension('model', {
-    Control, Menu, playing: modelPlaying, setPlaying: setModelPlaying, escape: escapeModelPlay, subscribe: subscribeModelPlay,
+    Control, Menu, playing: modelPlaying, setPlaying: setModelPlaying, escape: escapeModelPlay,
+    subscribe(listener) {
+      const stopPlay = subscribeModelPlay(listener), stopProject = onProjectChange(listener);
+      return () => { stopPlay(); stopProject(); };
+    },
+    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 });
+        camera: stage.camera as () => THREE.Camera, editingCamera: stage.editingCamera as () => THREE.Camera,
+        ownMaterial: stage.ownMaterial as ((material: THREE.Material) => THREE.Material | null) | undefined });
     },
   });
   return unregister;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/editor-model-play",
-  "version": "0.5.188",
+  "version": "0.5.190",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -23,11 +23,12 @@
   },
   "volter": {
     "contributions": [
+      "./contributions/model-play.command.ts",
       "./contributions/model-play.service.tsx"
     ]
   },
   "dependencies": {
-    "@volter/editor-sdk": "0.5.188"
+    "@volter/editor-sdk": "0.5.190"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/play-log.ts

@@ -0,0 +1,183 @@
+/**
+ * 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 `volter-model-editor 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. The runner adds its own lifecycle entries (`source: 'play'`):
+ * `play-start`, `script-reload` with its reason, `script-error`, `tint-unsupported`,
+ * `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.
+ *
+ * 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;
+}
+
+/** 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();
+
+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;
+  } catch { /* A log that cannot be written is not the script's failure. */ }
+}
+
+/** 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 };
+  // 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,
+  };
+}

package/src/play-materials.ts

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ */
+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;
+}
+
+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 = [];
+  };
+  /** 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);
+    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);
+    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 };
+        edit(fresh);
+        if (fresh.color === null && fresh.opacity === null) return;
+        if (!dress(fresh)) return;
+        overrides.set(mesh, fresh);
+        override = fresh;
+      } else edit(override);
+      if (override.color === null && override.opacity === null) forget(override);
+      else paint(override);
+    });
+  };
+  const inCopy = (object: THREE.Object3D): boolean => {
+    for (let at: THREE.Object3D | null = object; at; at = at.parent) if (at === root) return true;
+    return false;
+  };
+  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 (!inCopy(override.mesh)) { forget(override); continue; }
+        if (override.mesh.material !== override.shown && resync(override)) paint(override);
+      }
+    },
+    dispose() {
+      disposed = true;
+      for (const override of [...overrides.values()]) forget(override);
+    },
+  };
+}

package/src/play-script.ts

@@ -23,6 +23,7 @@
  * update, holding keys empty until arrival. Stop freezes the copy and blends
  * back before disposing it; Escape during either blend completes that blend.
  */
+import { editorHost } from '@volter/editor-sdk/host';
 import { getCurrentProject } from '@volter/editor-sdk/kit/active-project';
 import { surfaceAcceptsKey, surfaceHoldsKeyboard } from '@volter/editor-sdk/kit/surface-keyboard';
 import {
@@ -38,6 +39,8 @@ import { projectPlayLayers } from '@volter/editor-sdk/kit/project-play-layers';
 import { beginProjectMountEpoch, projectEntryImportUrl } from '@volter/editor-sdk/session/project-module-url';
 import { cameraTransition } from './camera-transition';
 import { finishModelPlay, registerModelPlayStop } from './model-play';
+import { beginModelPlayLog } from './play-log';
+import { materialOverrides } from './play-materials';
 interface PlayComposition {
   readonly entries: readonly string[];
   loadScript(): Promise<{ default?: unknown }>;
@@ -57,6 +60,38 @@ export interface ModelPlayContext {
   readonly camera: THREE.Camera;
   /** The keys held now, by `KeyboardEvent.code` (`ArrowUp`, `KeyW`, `Space`). */
   readonly keys: ReadonlySet<string>;
+  /**
+   * Write one entry to the play log, stamped with the run's simulation time and frame
+   * (`play-log.ts`): a kind and the facts that explain it, JSON-serialisable and snapshotted
+   * now. Log transitions (a landing, a death and its cause, autoplay's choice), not every
+   * frame. Read back with `volter-model-editor play-log [--since <simT>] [--kind <k>] [--json]`
+   * or `editor.modelPlayLog({ since, kind })` in `eval`. Never throws, never changes the game,
+   * and does nothing once this script has been replaced or Play has stopped.
+   *
+   *     play.log('death', { cause: 'lava', at: player.position, stage });
+   */
+  log(kind: string, facts?: Record<string, unknown>): void;
+  /**
+   * Draw an object and the meshes under it in `color` (a `THREE.Color`, `'#2bff6b'`,
+   * `0x2bff6b`); an emitting surface glows in it too, an image texture is multiplied by it.
+   * `null` returns the authored colours. Other objects wearing the same Blender material keep
+   * theirs. An object is a name or one `find` answered.
+   *
+   * THE PRESENTED MATERIALS, which is why this exists: a mesh's `material` is an array with
+   * one shared `MeshPhysicalMaterial` per Blender material slot (a lone material only for an
+   * object without slots), so `material.color` is undefined, and editing an entry recolours
+   * every object wearing that Blender material. The presenter re-assigns those slots
+   * whenever it re-applies shading, `clone()` drops its shader hooks, and a node graph
+   * driving Base Color or Alpha ignores `color` and `opacity`. A tinted or faded object
+   * wears copies of its own slots, drawn from their constant inputs (a node graph's
+   * other inputs are not drawn while it does), and keeps them through a script reload. An
+   * object with a material the document cannot copy (one the script made) is left as it is,
+   * and the log says so once with a `tint-unsupported` entry.
+   */
+  tint(object: THREE.Object3D | string, color: THREE.ColorRepresentation | null): void;
+  /** Fade an object and the meshes under it to `opacity` (0 to 1); `null` returns the
+   *  authored opacity. Its colour is untouched, and the copies are `tint`'s. */
+  setOpacity(object: THREE.Object3D | string, opacity: number | null): void;
 }
 
 export interface ModelPlayGame {
@@ -106,14 +141,43 @@ export function runPlayScript(options: {
   readonly container: HTMLElement;
   readonly ready: () => void;
   readonly returning: () => void;
+  readonly ownMaterial?: ((material: THREE.Material) => THREE.Material | null) | undefined;
 }): () => void {
-  const { blend, root, camera, onFrame, report } = options;
+  const { blend, root, camera, onFrame } = options;
   const modulePath = playScriptPath(blend);
+  // A fresh copy is a fresh run: its log starts empty, its clock at zero. Writes go through
+  // this run's handle, which is inert once the run has ended.
+  const run = beginModelPlayLog(options.documentId, modulePath);
+  const report = (phase: 'start' | 'update' | 'stop', title: string, error: unknown): void => {
+    const detail = error instanceof Error ? error.message : String(error);
+    run.append('play', 'script-error', { phase, message: detail });
+    options.report(title, detail);
+  };
+  // Said once per object: a script that tints every frame would otherwise fill the log.
+  const unsupported = new WeakSet<THREE.Mesh>();
+  const materials = materialOverrides({
+    root,
+    ownMaterial: options.ownMaterial,
+    unsupported: (mesh, material) => {
+      if (unsupported.has(mesh)) return;
+      unsupported.add(mesh);
+      run.append('play', 'tint-unsupported', { object: mesh.name, material: material.name,
+        why: options.ownMaterial ? 'the material is not one the document presents' : 'this document lends no material copies' });
+    },
+  });
+  const objectOf = (target: THREE.Object3D | string): THREE.Object3D => {
+    if (typeof target !== 'string') return target;
+    const object = root.getObjectByName(target);
+    if (!object) throw new Error(`The model has no object named ${target}.`);
+    return object;
+  };
   const keys = new Set<string>();
   const heldKeys = new Set<string>();
   const transition = cameraTransition(options.editingCamera());
   options.container.style.opacity = '0';
-  const context: ModelPlayContext = {
+  /** One script's context: its log, tint and opacity do nothing once that script is gone
+   *  (replaced, failed, or the run stopped), so a stale timer cannot reach a later one. */
+  const contextFor = (alive: { value: boolean }): ModelPlayContext => ({
     root,
     find(name) {
       const object = root.getObjectByName(name) ?? null;
@@ -125,11 +189,30 @@ export function runPlayScript(options: {
       return camera();
     },
     keys,
-  };
+    log(kind, facts) { if (alive.value) run.append('script', kind, facts); },
+    tint(object, color) { if (alive.value) materials.tint(objectOf(object), color); },
+    setOpacity(object, opacity) { if (alive.value) materials.setOpacity(objectOf(object), opacity); },
+  });
+  const scripts = new WeakMap<ModelPlayGame, { value: boolean }>();
   let stopped = false;
   let attempt = 0;
   let game: ModelPlayGame | null = null;
   let composition: PlayComposition | null = null;
+  let startedAt: number | null = null;
+  let endedAt: number | null = null;
+  const live = editorHost().live;
+  const unregisterLive = live.register({
+    id: `model-script:${options.documentId}`,
+    mounted: () => !stopped && game !== null,
+    // The live game owns the viewport through the camera return. Its update
+    // loop is held during that transition; Edit begins when disposal completes.
+    playing: () => !stopped && game !== null,
+    stop: () => { if (!stopped) finishModelPlay(options.documentId); },
+    instanceContainer: (id) => !id && !stopped && game !== null ? options.container : null,
+    startedAt: () => startedAt,
+    endedAt: () => endedAt,
+    surface: () => 'three',
+  });
   let pending: { game: ModelPlayGame; composition: PlayComposition | null } | null = null;
   // A failed mount/update still owns a dependency graph whose next save retries it.
   let retryEntries: readonly string[] = [];
@@ -137,25 +220,34 @@ export function runPlayScript(options: {
   const dispose = (ending: ModelPlayGame | null, layers: PlayComposition | null): void => {
     try { ending?.dispose?.(); }
     catch (error) {
-      report(`${modulePath} failed while stopping`, error instanceof Error ? error.message : String(error));
-    } finally { layers?.dispose(); }
+      report('stop', `${modulePath} failed while stopping`, error);
+    } finally {
+      // After its own dispose, which may still log; nothing it scheduled may.
+      const alive = ending && scripts.get(ending);
+      if (alive) alive.value = false;
+      layers?.dispose();
+    }
   };
   const end = (): void => {
     dispose(game, composition);
     game = null;
     composition = null;
+    if (startedAt !== null) endedAt = Date.now();
+    live.notifyChanged();
   };
-  const start = async (): Promise<void> => {
+  /** `reload` says why a replacement mounts, for the log's `script-reload`; null for Play's first start. */
+  const start = async (reload: { readonly reason: string; readonly path: string } | null): Promise<void> => {
     const mine = ++attempt;
     if (pending) { dispose(pending.game, pending.composition); pending = null; }
     let nextComposition: PlayComposition | undefined;
+    const alive = { value: true };
     try {
       if (mountLayers) {
         const project = getCurrentProject();
         if (!project) throw new Error('No project is open.');
         const epoch = beginProjectMountEpoch();
         const container = document.createElement('div');
-        container.dataset.mountEpoch = String(epoch);
+        container.dataset['mountEpoch'] = String(epoch);
         Object.assign(container.style, { position: 'absolute', inset: '0', visibility: 'hidden', pointerEvents: 'none' });
         options.container.appendChild(container);
         let layers;
@@ -173,21 +265,27 @@ export function runPlayScript(options: {
         };
       }
       if (stopped || mine !== attempt) { nextComposition?.dispose(); return; }
-      const next = await startGame(modulePath, context, nextComposition);
+      // Before the replacement's default export runs, so what it logs follows this.
+      if (reload) run.append('play', 'script-reload', reload);
+      const next = await startGame(modulePath, contextFor(alive), nextComposition);
+      scripts.set(next, alive);
       if (stopped || mine !== attempt) {
         dispose(next, nextComposition ?? null);
         return;
       }
       pending = { game: next, composition: nextComposition ?? null };
     } catch (error) {
+      alive.value = false;
       nextComposition?.dispose();
       if (stopped || mine !== attempt) return;
-      report(`${modulePath} did not start`, error instanceof Error ? error.message : String(error));
+      report('start', `${modulePath} did not start`, error);
     }
   };
   let firstFrame = true;
   let returning = false;
+  let stopReason = 'stop';
   const stopRequest = registerModelPlayStop(options.documentId, (escape) => {
+    if (escape) stopReason = 'escape';
     keys.clear();
     heldKeys.clear();
     if (firstFrame || transition.stop(escape)) finishModelPlay(options.documentId);
@@ -203,6 +301,7 @@ export function runPlayScript(options: {
     else if (!transition.acceptingKeys()) keys.clear();
     else for (const key of heldKeys) keys.add(key);
     let replacementUpdated = false;
+    if (pending || game) run.advance(deltaSeconds);
     if (pending) {
       const next = pending;
       pending = null;
@@ -210,12 +309,15 @@ export function runPlayScript(options: {
         next.game.update(deltaSeconds);
         end();
         game = next.game;
+        startedAt = Date.now();
+        endedAt = null;
         composition = next.composition;
+        live.notifyChanged();
         composition?.reveal();
         replacementUpdated = true;
       } catch (error) {
         dispose(next.game, next.composition);
-        report(`${modulePath} did not start`, error instanceof Error ? error.message : String(error));
+        report('start', `${modulePath} did not start`, error);
       }
     }
     if (game === null) return;
@@ -226,9 +328,11 @@ export function runPlayScript(options: {
       if (firstFrame) { firstFrame = false; options.ready(); }
     } catch (error) {
       end();
-      report(`${modulePath} failed`, error instanceof Error ? error.message : String(error));
+      report('update', `${modulePath} failed`, error);
       return;
     }
+    materials.frame();
+    keys.clear();
     root.updateMatrixWorld(true);
   });
   const onKeyDown = (event: KeyboardEvent): void => {
@@ -237,22 +341,33 @@ export function runPlayScript(options: {
     if (transition.acceptingKeys()) keys.add(event.code);
   };
   const onKeyUp = (event: KeyboardEvent): void => {
-    keys.delete(event.code);
+    // Preserve a between-frame tap until one game update has observed it.
     heldKeys.delete(event.code);
   };
   const onBlur = (): void => { keys.clear(); heldKeys.clear(); };
   window.addEventListener('keydown', onKeyDown, true);
   window.addEventListener('keyup', onKeyUp, true);
   window.addEventListener('blur', onBlur);
-  const stopChanges = subscribeProjectModuleChange((changed, affected) => {
+  const stopChanges = subscribeProjectModuleChange((changed, affected, type) => {
+    // Removing this run's entry ends its lifetime. A rename can remove it
+    // before the model document switches; importing that vanished entry
+    // would manufacture a mount failure while the old game is still alive.
+    // A missing dependency continues through the ordinary error-reporting path.
+    if (type === 'delete' && projectModuleChangeMatches(changed, modulePath)) {
+      stopReason = 'script-deleted';
+      finishModelPlay(options.documentId);
+      return;
+    }
     // A composed HUD and script must remount together, including shared-store
     // edits. A fresh epoch is threaded to both through the UI tool door.
     const entries = [modulePath, ...retryEntries, ...(composition?.entries ?? []), ...(pending?.composition?.entries ?? [])];
-    if ([changed, ...(affected ?? [])].some(path => entries.some(entry => projectModuleChangeMatches(path, entry)))) void start();
+    if ([changed, ...(affected ?? [])].some(path => entries.some(entry => projectModuleChangeMatches(path, entry))))
+      void start({ reason: type === 'delete' ? 'dependency-deleted' : 'saved', path: changed });
   });
-  void start();
+  void start(null);
   return () => {
     stopped = true;
+    unregisterLive();
     stopRequest();
     finishModelPlay(options.documentId);
     stopFrames();
@@ -262,5 +377,7 @@ export function runPlayScript(options: {
     window.removeEventListener('blur', onBlur);
     if (pending) { dispose(pending.game, pending.composition); pending = null; }
     end();
+    materials.dispose();
+    run.end({ reason: stopReason });
   };
 }