@volter/editor-model-play 0.5.190 → 0.5.191

package/README.md

@@ -1,6 +1,6 @@
 # Volter Model Play
 
-Play scripts on detached model documents. The header's Play runs
+Play scripts on detached model documents. Play (the Game panel's, in Cyclotron) 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
@@ -29,26 +29,35 @@ export default (play: ModelPlayContext): ModelPlayGame => {
 
 `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
+`tick` (the update in progress). Facts are snapshotted as JSON when logged. `simT` and `tick` are the Game panel's
+clock: they stand still while paused and run at the speed (see Time below). The
+runner adds `play-start`, `play-restart` (`{ speed }`, right after a Restart's
+`play-start`), `script-reload` (`{ reason: 'saved' | 'dependency-deleted', path }`),
+`script-error` (`{ phase, message }`), `tint-unsupported` (`{ object, material, why }`),
+`tint-unknown-object` (`{ object, call }`, once per name: `tint` or `setOpacity` was given a
+name the model has none of, and did nothing), `autoplay-on` / `autoplay-off`
+(`{ by: 'panel' | 'cli' | 'takeover' | 'script' }`, see Autoplay below),
+`autoplay-unavailable` (`{ why }`, when a script's first update has run and it registered no
+bot; once per run, and again only if a bot came and went),
+`pause`, `resume`, `step` (`{ dt }`, one per stepped update), `speed`
+(`{ speed, from }` on a change; `{ speed }` at a start that is not 1×) 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
+copy, and Restart, empty 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"
+cyclotron play-log                     # every kept entry, one per line
+cyclotron play-log --kind death        # one kind
+cyclotron play-log --since 12.5 --json # entries at or after simT 12.5, as JSON
+cyclotron play-log --document <id>     # another model document's log
+cyclotron eval "(await editor.modelPlayLog({ kind: 'death' })).entries"
 ```
 
 ## Recolouring the copy
@@ -69,3 +78,108 @@ object wears copies of its own slots that draw the material's constant inputs
 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`.
+
+## Autoplay
+
+A game offers its bot; the editor decides whether it drives.
+
+```ts
+play.autoplay(({ dt, simT, tick, keys }) => {
+  // the game's own decision, from its own state
+  return car.speed < 20 ? ['ArrowUp'] : [];
+});
+```
+
+The controller is a plain function. While autoplay is on it is called before each `update`
+with that update's `dt`, `simT` and `tick` (the stamps that update's log entries carry) and
+`keys`, the keys the person holds; it returns the `KeyboardEvent.code` keys the bot holds for
+that update (any iterable, or nothing). The runner merges them into `play.keys`, so the bot
+drives through the script's own input code exactly as a person does. One bot per script:
+registering again replaces it, `play.autoplay(null)` withdraws it, and it goes with the script
+on a reload or Stop. The bot is called only inside the editor's Play runner; a game run
+anywhere else never drives itself.
+
+Whether it drives is the editor's:
+
+- Autoplay is **off** whenever Play starts or restarts.
+- Only the Game panel's **Autoplay** toggle, `cyclotron play autoplay on|off` or
+  `await editor.command('volter.model-play.autoplay', { on: true })` turn it on (or off).
+- **A bot exists only while the game runs**: `play.autoplay` is called by the play script, so
+  a stopped game (or one still starting) has none, and neither has a running script that never
+  registers one. The panel says which, in words beside the toggle — "Available once the game is
+  running" or "No autoplay — this game doesn't provide a bot" — and `on` is refused with the
+  same reason, which `play state` also gives as `autoplay.why`.
+- **Arming.** Pressed while stopped, the panel's Autoplay arms the next start: autoplay turns
+  on (`by: 'panel'`) as soon as that run's script has run its first update with a bot, and the
+  arm is dropped if it offers none. A person's key or click in the game before then drops it
+  too (`autoplay-off` with `{ by: 'takeover', armed: true }`): the person always wins. Only an
+  explicit arm carries over; Stop, and closing the model, drop it.
+- **The person always wins.** A new key press the game would hear, or a pointer pressed in the
+  game's area (the HUD included), turns autoplay off before that key reaches `play.keys`, and
+  the panel reads "You're driving" until someone switches the bot on again. Synthetic keys and
+  clicks (`editor.document.key`, `click`) count as a person's: they are how an agent plays by
+  hand. A key repeat is not a new press; keys typed in a text field, or while the game's surface
+  does not hold the keyboard, are not the game's and do not take over.
+- A bot that throws turns autoplay off (`by: 'script'`, with a `script-error` of phase
+  `autoplay`), as does a reload whose script offers no bot.
+
+Each change is a play-log entry, `autoplay-on` or `autoplay-off`, with `by`.
+
+## Time
+
+`update(dt)` is the only clock a play script is given, and the editor decides it:
+
+| Control | What the script sees |
+| --- | --- |
+| Playing at 1× | One `update` per drawn frame, `dt` = the frame's seconds (at most 0.1). |
+| Speed 0.25× – 4× | `dt` scaled by the speed. A scaled frame longer than 0.1 s is split into equal updates, so no single `dt` exceeds 0.1. |
+| Pause | No `update` at all. The copy, the camera and the HUD hold the last frame. |
+| Step (while paused) | One `update` with `dt` = 1/60. |
+| Restart | The run begins again on a fresh detached copy, the clock at zero, without the camera's fly-in. |
+
+A script that reads the page's own clock (`performance.now()`, `Date.now()`) instead of
+summing `dt` is outside the reach of pause and speed.
+
+The run's clock — simulation time (the sum of the `dt`s handed to the script) and tick (the
+number of updates) — is kept per document beside whether it plays (`src/model-play.ts`).
+Speed is kept for the page's life; pause and the clock reset on every Play.
+When the run plays but no game runs — the script failed to start, or threw — the clock's
+`failure` says why (the Game panel shows it in place of "Playing"); a save of the script
+retries, and the next running game clears it.
+
+## Controls
+
+The tool registers the `model` document Play extension
+(`@volter/editor-sdk/kit/document-play-extension`). Beside Play and Stop it offers:
+
+- `transport` — `setPaused`, `step`, `setSpeed`, `restart`, the `clock` and its own
+  subscription, the offered `speeds`, and the restart `generation` the document keys its
+  detached copy on.
+- `transport.autoplay(documentId)` and `transport.setAutoplay(documentId, on, by)` — the bot's
+  switch: `{ on, available, by, armed }`, announced through `subscribeClock`;
+  `transport.armAutoplay(documentId, armed)` arms it, while stopped, for the next start.
+- `log` — `tail(documentId, last, kind?)` (the newest entries and every kind the run wrote) and
+  `subscribe`, which the Game panel draws live.
+- `scriptPath(sourcePath)` and `hasScript(sourcePath)` — where a model's play script goes and
+  whether it exists, so a layout can open a model with a script as a game.
+
+In Cyclotron these are drawn by the Game panel (`@volter/editor-blender`): the Game /
+Movie switch at the left of the bottom area's header puts it there in place of the Timeline. The panel's controls
+are also commands, `volter.model-play.<verb>`, so an agent drives the same run the person
+sees:
+
+| Command | Arguments |
+| --- | --- |
+| `volter.model-play.state` | — |
+| `volter.model-play.play` / `stop` | — (`play` also switches the document to Game mode) |
+| `volter.model-play.pause` / `resume` | — |
+| `volter.model-play.step` | `{ count?: 1–600 }`, while paused |
+| `volter.model-play.speed` | `{ speed: 0.25 \| 0.5 \| 1 \| 2 \| 4 }` |
+| `volter.model-play.restart` | — |
+| `volter.model-play.mode` | `{ mode?: 'game' \| 'movie' }` |
+| `volter.model-play.autoplay` | `{ on: boolean }` — the game's bot drives, or the person does |
+
+Each takes an optional `document` (the model document's id) and otherwise acts on the model
+document on screen; each answers with the panel's state. From the shell:
+`cyclotron play pause`; under `eval`:
+`await editor.command('volter.model-play.speed', { speed: 0.5 })`.

package/contributions/model-play.command.ts

@@ -1,7 +1,7 @@
 /**
  * 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`.
+ * `cyclotron 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

package/contributions/model-play.service.tsx

@@ -1,9 +1,28 @@
 /** Model script tool, available to every product through project packages. */
 import { useSyncExternalStore } from 'react';
 import { Button, EditorIcon, editorIcons, MenuItem } from '@volter/editor-sdk/widgets';
+import { editorHost } from '@volter/editor-sdk/host';
 import { registerDocumentPlayExtension, type DocumentPlayControlProps } from '@volter/editor-sdk/kit/document-play-extension';
-import { escapeModelPlay, modelPlaying, setModelPlaying, subscribeModelPlay } from '../src/model-play';
-import { runPlayScript } from '../src/play-script';
+import {
+  armModelPlayAutoplay,
+  escapeModelPlay,
+  MODEL_PLAY_SPEEDS,
+  modelPlayAutoplay,
+  modelPlayClock,
+  modelPlayGeneration,
+  modelPlaying,
+  restartModelPlay,
+  setModelPlayAutoplay,
+  setModelPlayFailure,
+  setModelPlayPaused,
+  setModelPlaying,
+  setModelPlaySpeed,
+  stepModelPlay,
+  subscribeModelPlay,
+  subscribeModelPlayClock,
+} from '../src/model-play';
+import { playScriptPath, runPlayScript } from '../src/play-script';
+import { beginModelPlayLog, subscribeModelPlayLog, tailModelPlayLog } from '../src/play-log';
 import type * as THREE from 'three';
 import { getCurrentProject, onProjectChange } from '@volter/editor-sdk/kit/active-project';
 
@@ -11,6 +30,7 @@ export const point = 'workspace.service';
 function usePlaying(documentId: string | undefined): boolean {
   return useSyncExternalStore(subscribeModelPlay, () => documentId ? modelPlaying(documentId) : false, () => false);
 }
+// Kept because `DocumentPlayExtension` requires `Control` and `Menu` for a layout that draws Play in its header; Cyclotron's layout no longer does (its Play is the Game panel's).
 function Control({ documentId, onClose }: DocumentPlayControlProps) {
   const playing = usePlaying(documentId);
   return <Button size="compact" data-testid="model-play-button" aria-pressed={playing}
@@ -27,12 +47,64 @@ function Menu({ documentId, onClose }: DocumentPlayControlProps) {
     {playing ? 'Stop' : 'Play'}
   </MenuItem>;
 }
+
+/**
+ * WHETHER A MODEL HAS A PLAY SCRIPT — `src/models/track.blend` has one when
+ * `src/models/track.play.ts` exists (`playScriptPath`), the same file Play imports. Asked once
+ * per path through the project's files door and then kept, corrected by that door's change
+ * events, so a layout can open a model with a script as a game and one without as a model. A
+ * project switch forgets every answer.
+ */
+const scripts = new Map<string, boolean>();
+const looking = new Set<string>();
+const scriptListeners = new Set<() => void>();
+function publishScripts(): void {
+  for (const listener of [...scriptListeners]) listener();
+}
+function projectPath(path: string): string {
+  return path.replaceAll('\\', '/').replace(/^\.\//, '');
+}
+function hasScript(sourcePath: string): boolean | null {
+  const path = projectPath(playScriptPath(sourcePath));
+  const known = scripts.get(path);
+  if (known !== undefined) return known;
+  if (!looking.has(path)) {
+    looking.add(path);
+    const project = getCurrentProject()?.rootPath;
+    void editorHost().files.exists(path).then(exists => exists, () => false).then(exists => {
+      looking.delete(path);
+      // An answer about the previous project is no answer about this one.
+      if (getCurrentProject()?.rootPath !== project) return;
+      scripts.set(path, exists);
+      publishScripts();
+    });
+  }
+  return null;
+}
+
 export function start(): () => void {
+  const stopWatching = (() => {
+    try {
+      return editorHost().files.watch((event) => {
+        const path = projectPath(event.path);
+        if (!scripts.has(path) && !path.endsWith('.play.ts')) return;
+        const exists = event.type !== 'remove';
+        if (scripts.get(path) === exists) return;
+        scripts.set(path, exists);
+        publishScripts();
+      });
+    } catch {
+      // A host without a files door still plays; the answer is then read once per path.
+      return () => {};
+    }
+  })();
+  const stopProject = onProjectChange(() => { scripts.clear(); publishScripts(); });
   const unregister = registerDocumentPlayExtension('model', {
     Control, Menu, playing: modelPlaying, setPlaying: setModelPlaying, escape: escapeModelPlay,
     subscribe(listener) {
       const stopPlay = subscribeModelPlay(listener), stopProject = onProjectChange(listener);
-      return () => { stopPlay(); stopProject(); };
+      scriptListeners.add(listener);
+      return () => { stopPlay(); stopProject(); scriptListeners.delete(listener); };
     },
     aspectRatio() {
       const size = getCurrentProject()?.config.resolution;
@@ -45,6 +117,36 @@ export function start(): () => void {
         camera: stage.camera as () => THREE.Camera, editingCamera: stage.editingCamera as () => THREE.Camera,
         ownMaterial: stage.ownMaterial as ((material: THREE.Material) => THREE.Material | null) | undefined });
     },
+    // THE RUN'S TRANSPORT (`model-play.ts`): the runner reads all of it each frame.
+    transport: {
+      speeds: MODEL_PLAY_SPEEDS,
+      clock: modelPlayClock,
+      subscribeClock: subscribeModelPlayClock,
+      setPaused: setModelPlayPaused,
+      step: stepModelPlay,
+      setSpeed: setModelPlaySpeed,
+      restart: restartModelPlay,
+      generation: modelPlayGeneration,
+      autoplay: modelPlayAutoplay,
+      setAutoplay: setModelPlayAutoplay,
+      armAutoplay: armModelPlayAutoplay,
+      // NO STAGE, SO NO RUNNER, and until 2026-10-06 the document turned Play off and wrote the
+      // reason to the console: Play flicked on and off with nothing said where anyone looks.
+      // Now the run stands with its failure — the Game panel draws it, the log records it.
+      fail(documentId, sourcePath, failure) {
+        const run = beginModelPlayLog(documentId, playScriptPath(sourcePath));
+        run.append('play', 'script-error', { phase: 'stage', message: failure });
+        run.end({ reason: 'stage-failed' });
+        setModelPlayFailure(documentId, failure);
+      },
+    },
+    log: { tail: tailModelPlayLog, subscribe: subscribeModelPlayLog },
+    scriptPath: playScriptPath,
+    hasScript,
   });
-  return unregister;
+  return () => {
+    unregister();
+    stopProject();
+    stopWatching();
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/editor-model-play",
-  "version": "0.5.190",
+  "version": "0.5.191",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -28,7 +28,7 @@
     ]
   },
   "dependencies": {
-    "@volter/editor-sdk": "0.5.190"
+    "@volter/editor-sdk": "0.5.191"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/camera-transition.ts

@@ -14,10 +14,14 @@ type Pose = ReturnType<typeof pose>;
 /** The tool blends AFTER the script has stated its complete camera pose.
  * Projection matrices also interpolate, preserving an orthographic editing
  * view exactly at the handoff to a perspective game. Neither editing camera
- * nor its orbit target is ever written. */
-export function cameraTransition(editingCamera: THREE.Camera) {
+ * nor its orbit target is ever written.
+ *
+ * `instant` enters already arrived: a Restart replaces a game that was on screen a frame ago,
+ * and flying in again from the editing pose would show the model between two games. The return
+ * on Stop still blends. */
+export function cameraTransition(editingCamera: THREE.Camera, options?: { readonly instant?: boolean }) {
   const editing = pose(editingCamera);
-  let phase: 'entering' | 'playing' | 'leaving' = 'entering';
+  let phase: 'entering' | 'playing' | 'leaving' = options?.instant ? 'playing' : 'entering';
   let elapsed = 0;
   let last = editing;
   let leavingFrom = editing;
@@ -52,6 +56,12 @@ export function cameraTransition(editingCamera: THREE.Camera) {
       ? Math.min(1, elapsed / duration)
       : Math.max(0, 1 - elapsed / (duration - 0.16)),
     approachingEdit: () => phase === 'leaving' && elapsed >= duration - 0.16,
+    /** A PAUSED frame: put the camera back where the last drawn frame had it. Nothing else
+     *  states the pose while the game's update is held, and the stage's navigation runs before
+     *  this hook each frame; the blend's own clock stands still with the game's. */
+    hold(camera: THREE.Camera): void {
+      blend(camera, last, last, 1);
+    },
     /** Escape completes an existing blend; otherwise begin the return. */
     stop(escape: boolean): boolean {
       if (escape && phase === 'entering') { phase = 'playing'; return false; }

package/src/model-play.ts

@@ -1,25 +1,125 @@
 /**
- * WHETHER A MODEL DOCUMENT IS PLAYING (the header's Play, `blender-header-menus.tsx`; drawn by
+ * WHETHER A MODEL DOCUMENT IS PLAYING (Play in the Game panel, `blender-game-panel.tsx`; drawn by
  * `blender-runtime.document.tsx`). Playing, the document's area shows a detached copy of the
  * model (`BlenderRuntimeView.detach`) that the project's play script moves
  * (`play-script.ts`); the model, its selection and its history stand as they were, and Stop
  * returns to them. Kept for the page's life and never stored: a reload opens the model, not a
  * game.
+ *
+ * AND HOW ITS CLOCK RUNS. Pause, step, speed and restart are state of the RUN, so they are kept
+ * here beside "is it playing", and the runner (`play-script.ts`) reads them on every frame: the
+ * `dt` a script's `update` receives is the only time a play script is given, so holding it is
+ * what freezes the game and scaling it is what speeds the game up. A script that reads the
+ * page's own clock (`performance.now()`, `Date.now()`) instead is outside that reach.
+ *
+ * AND WHO DRIVES. Autoplay is the editor's switch, not the game's: a script only offers a bot
+ * (`play.autoplay(controller)`, `play-script.ts`), and whether that bot drives is kept here. It
+ * is off whenever a run begins — Play, Restart, Stop — and only the Game panel's toggle or its
+ * verb (`volter.model-play.autoplay`) turns it on. The one carry-over is an ARM: a person may
+ * press Autoplay while stopped (there is no bot yet — a script offers it only once it runs), and
+ * the next start turns autoplay on the moment its script has run its first update with a bot, or
+ * drops the arm if it offers none. The runner turns it off the moment a person
+ * presses a key or touches the game (`takeover`), or when the running script stops offering a
+ * bot (`script`). Its changes are announced through the clock's subscription, which the panel
+ * and the runner already hold.
  */
 const listeners = new Set<() => void>();
+const clockListeners = new Set<() => void>();
 const playing = new Set<string>();
-const stops = new Map<string, (escape: boolean) => void>();
+const stops = new Map<string, { readonly stop: (escape: boolean) => void; readonly generation: number }>();
+
+/** The speeds the transport offers, slowest first (simulation seconds per real second). */
+export const MODEL_PLAY_SPEEDS: readonly number[] = [0.25, 0.5, 1, 2, 4];
+/** The `dt` one Step hands the game: one nominal 60 Hz frame, whatever the speed. */
+export const MODEL_PLAY_STEP_SECONDS = 1 / 60;
+
+export interface ModelPlayClock {
+  readonly time: number;
+  readonly tick: number;
+  readonly paused: boolean;
+  readonly speed: number;
+  /** The run is playing but no game runs: the script failed to start, or threw (`play-script.ts`). */
+  readonly failure: string | null;
+  /** A game has started in this run and runs (`DocumentPlayClock.running`). */
+  readonly running: boolean;
+}
+const STILL: ModelPlayClock = { time: 0, tick: 0, paused: false, speed: 1, failure: null, running: false };
+/** Replaced, never mutated, so a snapshot read by `useSyncExternalStore` changes identity
+ *  exactly when it changes value. */
+const clocks = new Map<string, ModelPlayClock>();
+/** Steps asked for while paused and not yet run; the runner takes one per drawn frame. */
+const steps = new Map<string, number>();
+/** Bumped by Restart; the document keys its detached copy on it (`DocumentPlayTransport`). */
+const generations = new Map<string, number>();
+/** Documents whose next run was begun by Restart, and so enters without the camera's blend. */
+const restarted = new Set<string>();
+
+/** Who last switched autoplay: the panel's toggle, a verb (CLI or `eval`), a person's input
+ *  in the game, or the running script no longer offering a bot (replaced, failed, or its bot
+ *  threw). */
+export type ModelPlayAutoplayBy = 'panel' | 'cli' | 'takeover' | 'script';
+export interface ModelPlayAutoplay {
+  /** The bot drives: its keys are merged into the keys the script reads. */
+  readonly on: boolean;
+  /** The running script registered a bot with `play.autoplay`. */
+  readonly available: boolean;
+  readonly by: ModelPlayAutoplayBy | null;
+  /** Pressed while stopped: the next start turns autoplay on once its script offers a bot. */
+  readonly armed: boolean;
+}
+const NO_BOT: ModelPlayAutoplay = { on: false, available: false, by: null, armed: false };
+const ARMED: ModelPlayAutoplay = { ...NO_BOT, armed: true };
+/** Replaced, never mutated, as the clocks are. Absent is {@link NO_BOT}: a new run's state. */
+const autoplays = new Map<string, ModelPlayAutoplay>();
+
+/** A new run's autoplay: off, no bot yet. Play keeps an arm made while stopped; Stop drops it. */
+function resetAutoplay(documentId: string, keepArm: boolean): void {
+  if (keepArm && modelPlayAutoplay(documentId).armed) autoplays.set(documentId, ARMED);
+  else autoplays.delete(documentId);
+}
+
+function publish(): void {
+  for (const listener of [...listeners]) listener();
+}
+function publishClock(): void {
+  for (const listener of [...clockListeners]) listener();
+}
+function setClock(documentId: string, next: Partial<ModelPlayClock>): void {
+  clocks.set(documentId, { ...modelPlayClock(documentId), ...next });
+  publishClock();
+}
 
 export function modelPlaying(documentId: string): boolean {
   return playing.has(documentId);
 }
 
 export function setModelPlaying(documentId: string, value: boolean): void {
-  if (playing.has(documentId) === value) return;
-  if (!value && stops.has(documentId)) { stops.get(documentId)!(false); return; }
-  if (value) playing.add(documentId);
-  else playing.delete(documentId);
-  for (const listener of [...listeners]) listener();
+  if (playing.has(documentId) === value) {
+    // Stop with nothing playing is how a closing document lets go of its play: an arm made while
+    // stopped goes with it, or reopening the model and pressing Play would still take it.
+    if (!value && modelPlayAutoplay(documentId).armed) { resetAutoplay(documentId, false); publishClock(); }
+    return;
+  }
+  const stop = value ? null : currentStop(documentId);
+  if (stop) { stop(false); return; }
+  if (value) {
+    playing.add(documentId);
+    // A new run starts its clock at zero and running; the speed is the person's and stays.
+    steps.delete(documentId);
+    resetAutoplay(documentId, true);
+    setClock(documentId, { time: 0, tick: 0, paused: false, failure: null, running: false });
+  } else {
+    playing.delete(documentId);
+    restarted.delete(documentId);
+    steps.delete(documentId);
+    resetAutoplay(documentId, false);
+    // The clock keeps the stopped run's time and tick, so the panel still says how far it got.
+    // Re-issued even unchanged, after `playing` has changed: every way a game stops (Stop,
+    // Escape, a deleted script, a mode switch, an agent's `stop`) ends here, and a reader of
+    // the clock alone must see the run end too.
+    setClock(documentId, { paused: false, failure: null, running: false });
+  }
+  publish();
 }
 
 export function finishModelPlay(documentId: string): void {
@@ -28,14 +128,36 @@ export function finishModelPlay(documentId: string): void {
 }
 
 export function escapeModelPlay(documentId: string): void {
-  const stop = stops.get(documentId);
+  const stop = currentStop(documentId);
   if (stop) stop(true);
   else finishModelPlay(documentId);
 }
 
+/**
+ * A RUNNER'S STOP, BOUND TO ITS GENERATION. Stop and Escape go to the runner of the CURRENT
+ * generation, which blends the camera back first; a stop a Restart has superseded is never
+ * asked, because that runner stands still from the moment its generation passes
+ * (`play-script.ts`) and would never finish the blend — the stop would be lost. With no current
+ * runner (a restarted game still preparing) the play simply ends.
+ */
 export function registerModelPlayStop(documentId: string, stop: (escape: boolean) => void): () => void {
-  stops.set(documentId, stop);
-  return () => { if (stops.get(documentId) === stop) stops.delete(documentId); };
+  const entry = { stop, generation: modelPlayGeneration(documentId) };
+  stops.set(documentId, entry);
+  return () => { if (stops.get(documentId) === entry) stops.delete(documentId); };
+}
+
+function currentStop(documentId: string): ((escape: boolean) => void) | null {
+  const entry = stops.get(documentId);
+  return entry !== undefined && entry.generation === modelPlayGeneration(documentId) ? entry.stop : null;
+}
+
+/** The runner's report that no game runs although the run plays (`null` once one does, which
+ *  is also the moment the run is `running`). */
+export function setModelPlayFailure(documentId: string, failure: string | null): void {
+  const clock = modelPlayClock(documentId);
+  const running = failure === null;
+  if (!playing.has(documentId) || (clock.failure === failure && clock.running === running)) return;
+  setClock(documentId, { failure, running });
 }
 
 export function subscribeModelPlay(listener: () => void): () => void {
@@ -44,3 +166,124 @@ export function subscribeModelPlay(listener: () => void): () => void {
     listeners.delete(listener);
   };
 }
+
+export function modelPlayClock(documentId: string): ModelPlayClock {
+  return clocks.get(documentId) ?? STILL;
+}
+
+export function subscribeModelPlayClock(listener: () => void): () => void {
+  clockListeners.add(listener);
+  return () => {
+    clockListeners.delete(listener);
+  };
+}
+
+/** Hold or release the game's updates. Only a playing document has updates to hold. */
+export function setModelPlayPaused(documentId: string, paused: boolean): void {
+  if (!playing.has(documentId) || modelPlayClock(documentId).paused === paused) return;
+  if (!paused) steps.delete(documentId);
+  setClock(documentId, { paused });
+}
+
+/** One update while paused. Steps asked for faster than frames are drawn queue, one per frame,
+ *  so each one is seen. */
+export function stepModelPlay(documentId: string): void {
+  if (!playing.has(documentId) || !modelPlayClock(documentId).paused) return;
+  steps.set(documentId, (steps.get(documentId) ?? 0) + 1);
+}
+
+/** The runner's half of {@link stepModelPlay}: whether this frame runs a step. */
+export function takeModelPlayStep(documentId: string): boolean {
+  const pending = steps.get(documentId) ?? 0;
+  if (pending === 0) return false;
+  if (pending === 1) steps.delete(documentId);
+  else steps.set(documentId, pending - 1);
+  return true;
+}
+
+export function setModelPlaySpeed(documentId: string, speed: number): void {
+  if (!MODEL_PLAY_SPEEDS.includes(speed))
+    throw new Error(`Play speed ${speed} is not one the transport offers: ${MODEL_PLAY_SPEEDS.join(', ')}.`);
+  if (modelPlayClock(documentId).speed !== speed) setClock(documentId, { speed });
+}
+
+/** The runner's report of the updates it ran this frame. */
+export function advanceModelPlayClock(documentId: string, seconds: number, ticks: number): void {
+  if (ticks === 0) return;
+  const clock = modelPlayClock(documentId);
+  setClock(documentId, { time: clock.time + seconds, tick: clock.tick + ticks });
+}
+
+export function modelPlayGeneration(documentId: string): number {
+  return generations.get(documentId) ?? 0;
+}
+
+/**
+ * BEGIN THE RUN AGAIN ON A FRESH COPY. Playing stays true throughout — nothing returns to the
+ * model — and the generation moves, which is what makes the document detach a new copy and mount
+ * a new runner over it; the old runner sees it is no longer the current generation and stands
+ * down without ending the play. A document that is not playing simply starts.
+ */
+export function restartModelPlay(documentId: string): void {
+  if (!playing.has(documentId)) { setModelPlaying(documentId, true); return; }
+  generations.set(documentId, modelPlayGeneration(documentId) + 1);
+  restarted.add(documentId);
+  steps.delete(documentId);
+  // An arm not yet taken (the game was still starting) carries to the fresh run.
+  resetAutoplay(documentId, true);
+  setClock(documentId, { time: 0, tick: 0, paused: false, failure: null, running: false });
+  publish();
+}
+
+/** Whether the run starting now was begun by Restart (asked once, by that run's runner). */
+export function consumeModelPlayRestart(documentId: string): boolean {
+  return restarted.delete(documentId);
+}
+
+export function modelPlayAutoplay(documentId: string): ModelPlayAutoplay {
+  return autoplays.get(documentId) ?? NO_BOT;
+}
+
+function setAutoplay(documentId: string, next: Partial<ModelPlayAutoplay>): void {
+  autoplays.set(documentId, { ...modelPlayAutoplay(documentId), ...next });
+  publishClock();
+}
+
+/** Switch the running script's bot on or off. On asks for a playing document whose script
+ *  registered a bot; off always succeeds, and also drops an arm not yet taken — a person who
+ *  takes over while the game is still starting is driving, and the arm must not override them. */
+export function setModelPlayAutoplay(documentId: string, on: boolean, by: ModelPlayAutoplayBy): void {
+  const now = modelPlayAutoplay(documentId);
+  if (on && !playing.has(documentId))
+    throw new Error(`Autoplay is available once the game is running, and nothing is playing in ${documentId}; \`play\` starts it, then \`play autoplay on\`.`);
+  const clock = modelPlayClock(documentId);
+  if (on && !now.available)
+    throw new Error(clock.running
+      ? 'No autoplay: this game doesn’t provide a bot — its play script registers none with `play.autoplay(controller)`.'
+      : `Autoplay is available once the game is running, and it is not running yet${clock.failure ? ` (${clock.failure})` : ''}.`);
+  if (on ? !now.on : now.on || now.armed) setAutoplay(documentId, on ? { on, by } : { on, by, armed: false });
+}
+
+/** Arm (or disarm) autoplay for the next start, while stopped: the Game panel's Autoplay button
+ *  before Play. Disarming always succeeds. */
+export function armModelPlayAutoplay(documentId: string, armed: boolean): void {
+  if (armed && playing.has(documentId))
+    throw new Error(`${documentId} is already playing; switch autoplay on instead of arming it.`);
+  if (modelPlayAutoplay(documentId).armed !== armed) setAutoplay(documentId, { armed });
+}
+
+/** The runner's report that a script has run its first update, offering a bot or not. An arm is
+ *  taken here: on with a bot, dropped without one. */
+export function settleModelPlayAutoplay(documentId: string, offered: boolean): void {
+  const now = modelPlayAutoplay(documentId);
+  if (!playing.has(documentId)) return;
+  if (!now.armed) { setModelPlayAutoplayAvailable(documentId, offered); return; }
+  setAutoplay(documentId, offered ? { available: true, armed: false, on: true, by: 'panel' } : { available: false, armed: false, by: 'script' });
+}
+
+/** The runner's report of whether the running script offers a bot. Losing it turns autoplay off. */
+export function setModelPlayAutoplayAvailable(documentId: string, available: boolean): void {
+  const now = modelPlayAutoplay(documentId);
+  if (now.available === available || !playing.has(documentId)) return;
+  setAutoplay(documentId, available || !now.on ? { available } : { available, on: false, by: 'script' });
+}

package/src/play-log.ts

@@ -4,15 +4,21 @@
  * 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
+ * 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. The runner adds its own lifecycle entries (`source: 'play'`):
- * `play-start`, `script-reload` with its reason, `script-error`, `tint-unsupported`,
+ * 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
@@ -28,6 +34,9 @@
  * 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.
  */
@@ -90,6 +99,8 @@ interface Run {
   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. */
@@ -106,6 +117,21 @@ export interface ModelPlayRun {
 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;
@@ -128,13 +154,15 @@ function append(run: Run, source: ModelPlayLogEntry['source'], kind: string, fac
     };
     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 };
+  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);
@@ -181,3 +209,25 @@ export function readModelPlayLog(query: ModelPlayLogQuery = {}): ModelPlayLogRea
     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

@@ -25,7 +25,10 @@
  * 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.
+ * 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';
 
@@ -39,6 +42,11 @@ interface Override {
   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];
@@ -71,6 +79,20 @@ export function materialOverrides(options: {
     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);
@@ -116,6 +138,7 @@ export function materialOverrides(options: {
   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
@@ -126,6 +149,7 @@ export function materialOverrides(options: {
     override.shown = override.mesh.material;
     if (dress(override)) return true;
     release(override);
+    unwatch(override);
     overrides.delete(override.mesh);
     return false;
   };
@@ -137,21 +161,19 @@ export function materialOverrides(options: {
       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 };
+        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);
     });
   };
-  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) {
@@ -161,7 +183,11 @@ export function materialOverrides(options: {
     },
     frame() {
       for (const override of [...overrides.values()]) {
-        if (!inCopy(override.mesh)) { forget(override); continue; }
+        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);
       }
     },

package/src/play-script.ts

@@ -22,6 +22,34 @@
  * The tool blends the camera from the editing pose for 0.8 seconds after
  * update, holding keys empty until arrival. Stop freezes the copy and blends
  * back before disposing it; Escape during either blend completes that blend.
+ *
+ * THE GAME'S TIME IS THE `dt` IT IS HANDED, and the runner decides it (`model-play.ts` keeps
+ * the run's clock): paused, `update` is not called at all and the camera holds the last drawn
+ * pose; a Step is one `update` of one nominal frame; a speed scales the frame's seconds, and a
+ * scaled frame longer than a tenth of a second is run as several updates so the promise below —
+ * at most a tenth per call — holds at 4× too. The camera's own blends run on the page's time,
+ * because they are the editor's motion and not the game's. Restart is the document detaching a
+ * fresh copy for a new runner (`restartModelPlay`); this runner, no longer the current
+ * generation, stands down without ending the play.
+ *
+ * THE PLAY LOG KEEPS THE SAME CLOCK (`play-log.ts`): the run's log is advanced by exactly the
+ * `dt` of each `update` the panel's clock counts, at the same call, so an entry's `simT` and
+ * `tick` are the numbers the Game panel shows. A Restart is a fresh copy and so a fresh log,
+ * opened by `play-start` and then `play-restart`; pause, resume, each step and a speed change
+ * are lifecycle entries of their own.
+ *
+ * AUTOPLAY IS THE GAME'S BOT AND THE EDITOR'S SWITCH. A script offers one bot,
+ * `play.autoplay(controller)`: a plain function the runner calls before each `update` while
+ * autoplay is on, handed that update's `dt`, `simT`, `tick` and the keys the person holds, and
+ * answering the keys the bot holds. The runner merges those into `keys` for that update, so the
+ * bot drives through the script's own input code, exactly as a person's keys do. Whether it
+ * drives is not the script's to say (`model-play.ts`): off at every Play and Restart, on only
+ * from the Game panel or its verb, and off again the moment a person presses a key the game
+ * would hear or presses a pointer in the game — before that key reaches `keys`. A synthetic key
+ * (`editor.document.key`) is dispatched as a DOM event like a person's and is handled as one;
+ * the bot's own keys never pass through the DOM, so they cannot take over from themselves. The
+ * controller is called only here, inside the editor's runner: a game run anywhere else never
+ * drives itself.
  */
 import { editorHost } from '@volter/editor-sdk/host';
 import { getCurrentProject } from '@volter/editor-sdk/kit/active-project';
@@ -38,7 +66,22 @@ import type * as THREE from 'three';
 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 {
+  advanceModelPlayClock,
+  consumeModelPlayRestart,
+  finishModelPlay,
+  MODEL_PLAY_STEP_SECONDS,
+  modelPlayAutoplay,
+  modelPlayClock,
+  modelPlayGeneration,
+  registerModelPlayStop,
+  setModelPlayAutoplay,
+  setModelPlayFailure,
+  setModelPlayAutoplayAvailable,
+  settleModelPlayAutoplay,
+  subscribeModelPlayClock,
+  takeModelPlayStep,
+} from './model-play';
 import { beginModelPlayLog } from './play-log';
 import { materialOverrides } from './play-materials';
 interface PlayComposition {
@@ -64,7 +107,7 @@ export interface ModelPlayContext {
    * 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]`
+   * frame. Read back with `cyclotron 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.
    *
@@ -92,14 +135,65 @@ export interface ModelPlayContext {
   /** 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;
+  /**
+   * Offer this game's bot. While the person (or an agent, `play autoplay on`) has autoplay on in
+   * the Game panel, `controller` is called before each `update` and the keys it answers are held
+   * for that update, merged into `keys`. Autoplay is off at every Play and Restart, and a
+   * person's key or pointer in the game turns it off. One bot per script: registering again
+   * replaces it, `null` withdraws it, and it goes with the script. Never bind autoplay to a game
+   * key, and never start it from the script.
+   *
+   *     play.autoplay(({ dt }) => (car.speed < 20 ? ['ArrowUp'] : []));
+   */
+  autoplay(controller: ModelPlayAutoplayController | null): void;
+}
+
+/** What the bot is handed before each `update` it drives. */
+export interface ModelPlayAutoplayInput {
+  /** The `dt` the coming `update` is handed. */
+  readonly dt: number;
+  /** Simulation seconds and the update's number, as that update's log entries carry them. */
+  readonly simT: number;
+  readonly tick: number;
+  /** The keys the person holds, by `KeyboardEvent.code`; the bot's are merged with them. */
+  readonly keys: ReadonlySet<string>;
 }
+/** A game's bot: the keys (`KeyboardEvent.code`) it holds for the coming update. */
+export type ModelPlayAutoplayController = (input: ModelPlayAutoplayInput) => Iterable<string> | null | undefined;
 
 export interface ModelPlayGame {
-  /** Once per drawn frame, with the seconds since the last one (at most a tenth). */
+  /** Once per drawn frame, with the simulation seconds since the last call (at most a tenth).
+   *  Not called while the game is paused; called once per Step; at a speed other than 1× the
+   *  seconds are scaled, and a fast frame may call it more than once. */
   update(deltaSeconds: number): void;
   dispose?(): void;
 }
 
+/** One script's lifetime: `value` until it is replaced, fails or the run stops; `bot` is what it
+ *  offered `play.autoplay`; `unknown` the object names it asked for that the model lacks, each
+ *  logged once — per script, so a typo that survives a reload is said again for the new one. */
+interface Script {
+  value: boolean;
+  bot: ModelPlayAutoplayController | null;
+  readonly unknown: Set<string>;
+}
+
+/** The longest `dt` one update is handed; longer scaled frames are split (`frameUpdates`). */
+const MAX_UPDATE_SECONDS = 0.1;
+
+/**
+ * THE UPDATES THIS DRAWN FRAME RUNS, as the `dt` each is handed: none while paused, one nominal
+ * frame for a Step, and otherwise the frame's seconds times the speed, split into equal parts of
+ * at most {@link MAX_UPDATE_SECONDS}.
+ */
+function frameUpdates(documentId: string, frameSeconds: number): number[] {
+  const clock = modelPlayClock(documentId);
+  if (clock.paused) return takeModelPlayStep(documentId) ? [MODEL_PLAY_STEP_SECONDS] : [];
+  const scaled = frameSeconds * clock.speed;
+  const parts = Math.max(1, Math.ceil(scaled / MAX_UPDATE_SECONDS - 1e-9));
+  return Array.from({ length: parts }, () => scaled / parts);
+}
+
 /** The play script's project path for a model's `.blend`. */
 export function playScriptPath(blend: string): string {
   return blend.replace(/\.blend$/i, '') + '.play.ts';
@@ -148,9 +242,14 @@ export function runPlayScript(options: {
   // 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 report = (phase: 'start' | 'update' | 'stop' | 'autoplay', title: string, error: unknown): void => {
     const detail = error instanceof Error ? error.message : String(error);
     run.append('play', 'script-error', { phase, message: detail });
+    // NO GAME RUNS NOW (a first start that failed, or the running game threw): the run still
+    // plays, and a save retries it, but what is on screen is not a game. Said on the clock, so
+    // the Game panel can say so and the document drops a Restart's cover (`failure`).
+    if ((phase === 'start' || phase === 'update') && game === null && current())
+      setModelPlayFailure(options.documentId, `${title}: ${detail}`);
     options.report(title, detail);
   };
   // Said once per object: a script that tints every frame would otherwise fill the log.
@@ -165,19 +264,48 @@ export function runPlayScript(options: {
         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 => {
+  // An unknown name is the script's typo, not a reason to stop its game: said once per name, per script.
+  const objectOf = (script: Script, target: THREE.Object3D | string, call: 'tint' | 'setOpacity'): THREE.Object3D | null => {
     if (typeof target !== 'string') return target;
-    const object = root.getObjectByName(target);
-    if (!object) throw new Error(`The model has no object named ${target}.`);
+    const object = root.getObjectByName(target) ?? null;
+    if (!object && !script.unknown.has(target)) {
+      script.unknown.add(target);
+      run.append('play', 'tint-unknown-object', { object: target, call });
+    }
     return object;
   };
   const keys = new Set<string>();
   const heldKeys = new Set<string>();
-  const transition = cameraTransition(options.editingCamera());
+  // The run this runner belongs to. A Restart moves the document to the next generation, whose
+  // own runner takes over; this one must then stand down without ending the play.
+  const generation = modelPlayGeneration(options.documentId);
+  const current = (): boolean => modelPlayGeneration(options.documentId) === generation;
+  const restarted = consumeModelPlayRestart(options.documentId);
+  const transition = cameraTransition(options.editingCamera(), { instant: restarted });
+  // THE TRANSPORT'S CHANGES, IN THE LOG. Pause, resume and speed are the person's (or an
+  // agent's) calls on `model-play.ts`, between frames; this run notes each as it lands. A run
+  // that Restart has replaced notes nothing more — its successor's log has the restart.
+  let seen = modelPlayClock(options.documentId);
+  let seenBot = modelPlayAutoplay(options.documentId);
+  if (restarted) run.append('play', 'play-restart', { speed: seen.speed });
+  else if (seen.speed !== 1) run.append('play', 'speed', { speed: seen.speed });
+  const stopClock = subscribeModelPlayClock(() => {
+    const now = modelPlayClock(options.documentId);
+    if (!current()) return;
+    if (now.paused !== seen.paused) run.append('play', now.paused ? 'pause' : 'resume');
+    if (now.speed !== seen.speed) run.append('play', 'speed', { speed: now.speed, from: seen.speed });
+    seen = now;
+    const bot = modelPlayAutoplay(options.documentId);
+    if (bot.on !== seenBot.on) run.append('play', bot.on ? 'autoplay-on' : 'autoplay-off', { by: bot.by });
+    // An arm dropped before it was taken: a takeover, or a script that offers no bot. (Stop's
+    // reset has no `by`, and its `play-stop` says enough.)
+    else if (seenBot.armed && !bot.armed && bot.by !== null) run.append('play', 'autoplay-off', { by: bot.by, armed: true });
+    seenBot = bot;
+  });
   options.container.style.opacity = '0';
-  /** One script's context: its log, tint and opacity do nothing once that script is gone
+  /** One script's context: its log, tint, opacity and bot 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 => ({
+  const contextFor = (alive: Script): ModelPlayContext => ({
     root,
     find(name) {
       const object = root.getObjectByName(name) ?? null;
@@ -190,10 +318,21 @@ export function runPlayScript(options: {
     },
     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); },
+    tint(object, color) {
+      const target = alive.value ? objectOf(alive, object, 'tint') : null;
+      if (target) materials.tint(target, color);
+    },
+    setOpacity(object, opacity) {
+      const target = alive.value ? objectOf(alive, object, 'setOpacity') : null;
+      if (target) materials.setOpacity(target, opacity);
+    },
+    autoplay(controller) {
+      if (controller !== null && typeof controller !== 'function')
+        throw new Error('play.autoplay takes a function (the bot) or null.');
+      if (alive.value) alive.bot = controller;
+    },
   });
-  const scripts = new WeakMap<ModelPlayGame, { value: boolean }>();
+  const scripts = new WeakMap<ModelPlayGame, Script>();
   let stopped = false;
   let attempt = 0;
   let game: ModelPlayGame | null = null;
@@ -224,7 +363,7 @@ export function runPlayScript(options: {
     } finally {
       // After its own dispose, which may still log; nothing it scheduled may.
       const alive = ending && scripts.get(ending);
-      if (alive) alive.value = false;
+      if (alive) { alive.value = false; alive.bot = null; }
       layers?.dispose();
     }
   };
@@ -240,7 +379,7 @@ export function runPlayScript(options: {
     const mine = ++attempt;
     if (pending) { dispose(pending.game, pending.composition); pending = null; }
     let nextComposition: PlayComposition | undefined;
-    const alive = { value: true };
+    const alive: Script = { value: true, bot: null, unknown: new Set() };
     try {
       if (mountLayers) {
         const project = getCurrentProject();
@@ -282,6 +421,9 @@ export function runPlayScript(options: {
     }
   };
   let firstFrame = true;
+  /** Whether the last script to run its first update offered a bot (null before any did), so
+   *  `autoplay-unavailable` is said once per run, and again only after a bot came and went. */
+  let offeredBot: boolean | null = null;
   let returning = false;
   let stopReason = 'stop';
   const stopRequest = registerModelPlayStop(options.documentId, (escape) => {
@@ -291,6 +433,13 @@ export function runPlayScript(options: {
     if (firstFrame || transition.stop(escape)) finishModelPlay(options.documentId);
   });
   const stopFrames = onFrame((deltaSeconds) => {
+    // REPLACED BY A RESTART, and not yet unmounted: the document keeps this copy on screen until
+    // the new one has drawn, so it stands as it is — no update, no clock, the camera held.
+    if (!current()) {
+      if (game !== null) transition.hold(camera());
+      keys.clear();
+      return;
+    }
     if (transition.leaving()) {
       options.container.style.opacity = String(transition.hudOpacity());
       if (!returning && transition.approachingEdit()) { returning = true; options.returning(); }
@@ -300,33 +449,114 @@ export function runPlayScript(options: {
     if (!surfaceHoldsKeyboard()) { keys.clear(); heldKeys.clear(); }
     else if (!transition.acceptingKeys()) keys.clear();
     else for (const key of heldKeys) keys.add(key);
-    let replacementUpdated = false;
-    if (pending || game) run.advance(deltaSeconds);
+    // The panel's toggle is enabled by the bot the running script offers, as of the last frame.
+    if (current()) setModelPlayAutoplayAvailable(options.documentId, game !== null && scripts.get(game)?.bot != null);
+    const updates = frameUpdates(options.documentId, deltaSeconds);
+    if (updates.length === 0) {
+      // PAUSED: no update, so nothing states the camera; hold the pose the last frame drew.
+      // A pending replacement waits too — its first update is a tick of the game's time.
+      // A tap made while paused is dropped; a key still held is seen by the next step.
+      if (game !== null) transition.hold(camera());
+      keys.clear();
+      return;
+    }
+    // Each update is counted — by the panel's clock and the log alike — as it is CALLED, so an
+    // update that throws still took its tick, in both.
+    let ran = 0;
+    let simulated = 0;
+    // THE BOT'S KEYS, per update: the person's keys of this frame and what the bot holds now. It
+    // drives only once the camera has arrived, as a person's keys reach the game only then.
+    const clock = modelPlayClock(options.documentId);
+    const driving = current() && modelPlayAutoplay(options.documentId).on && transition.acceptingKeys();
+    const person: ReadonlySet<string> = driving ? new Set(keys) : keys;
+    /** `keys` back to the person's alone. Only ever after `drive` has added the bot's, when
+     *  `person` is a copy — never `keys` itself. */
+    const restorePerson = (): void => {
+      keys.clear();
+      for (const key of person) keys.add(key);
+    };
+    /** Merge the bot's keys into `keys` for one update; true when it did, and the caller then
+     *  restores the person's keys after that update, however it ends. */
+    const drive = (script: ModelPlayGame, dt: number): boolean => {
+      const bot = driving ? scripts.get(script)?.bot : null;
+      // Asked again per update: the bot's own failure, a takeover, or `play.autoplay(null)`
+      // ends it mid-frame.
+      if (!bot || !modelPlayAutoplay(options.documentId).on) return false;
+      restorePerson();
+      try {
+        for (const key of bot({ dt, simT: clock.time + simulated, tick: clock.tick + ran, keys: person }) ?? []) keys.add(String(key));
+        return true;
+      } catch (error) {
+        restorePerson();
+        setModelPlayAutoplay(options.documentId, false, 'script');
+        report('autoplay', `${modulePath}'s autoplay failed`, error);
+        return false;
+      }
+    };
+    /** One update, bot-driven or not. The bot's keys hold for this update only: restored in a
+     *  `finally`, so neither a bot withdrawn mid-frame, nor an update that throws, nor a reloaded
+     *  script leaves them reading as held. */
+    const update = (script: ModelPlayGame, dt: number): void => {
+      tick(dt);
+      const driven = drive(script, dt);
+      try { script.update(dt); }
+      finally { if (driven) restorePerson(); }
+    };
+    // A paused frame that runs an update is a Step; its entry carries the step's own tick.
+    const stepping = modelPlayClock(options.documentId).paused;
+    const tick = (dt: number): void => {
+      run.advance(dt);
+      ran += 1;
+      simulated += dt;
+      if (stepping) run.append('play', 'step', { dt });
+    };
+    // A replacement's first update takes the frame's first slot whether it starts or throws; a
+    // running game that a failed replacement leaves in place runs the rest of the frame.
+    let firstSlot = 0;
     if (pending) {
+      firstSlot = 1;
       const next = pending;
       pending = null;
       try {
-        next.game.update(deltaSeconds);
+        update(next.game, updates[0]!);
         end();
         game = next.game;
+        // NOW THE SCRIPT HAS SAID WHETHER IT OFFERS A BOT (its default export and first update
+        // are where `play.autoplay` is called): said before `running`, so no reader sees a running
+        // game with its bot not yet counted, and an arm made while stopped is taken or dropped.
+        const offered = scripts.get(next.game)?.bot != null;
+        if (!offered && offeredBot !== false)
+          run.append('play', 'autoplay-unavailable', { why: 'the play script registers no bot with play.autoplay(controller)' });
+        offeredBot = offered;
+        // A KEY THE PERSON ALREADY HOLDS is a takeover the runner did not hear: it was pressed while
+        // the stage was still preparing, before these listeners existed, and has only repeated
+        // since. The person is driving, so an arm waiting for this update is dropped.
+        if (heldKeys.size > 0 && modelPlayAutoplay(options.documentId).armed) takeover();
+        settleModelPlayAutoplay(options.documentId, offered);
+        setModelPlayFailure(options.documentId, null);
         startedAt = Date.now();
         endedAt = null;
         composition = next.composition;
         live.notifyChanged();
         composition?.reveal();
-        replacementUpdated = true;
       } catch (error) {
         dispose(next.game, next.composition);
         report('start', `${modulePath} did not start`, error);
       }
     }
-    if (game === null) return;
+    if (game === null) { advanceModelPlayClock(options.documentId, simulated, ran); keys.clear(); return; }
     try {
-      if (!replacementUpdated) game.update(deltaSeconds);
+      for (let index = firstSlot; index < updates.length; index++) {
+        update(game, updates[index]!);
+      }
+      advanceModelPlayClock(options.documentId, simulated, ran);
+      ran = 0;
       transition.frame(camera(), deltaSeconds);
       options.container.style.opacity = String(transition.hudOpacity());
       if (firstFrame) { firstFrame = false; options.ready(); }
     } catch (error) {
+      advanceModelPlayClock(options.documentId, simulated, ran);
+      keys.clear();
       end();
       report('update', `${modulePath} failed`, error);
       return;
@@ -335,8 +565,21 @@ export function runPlayScript(options: {
     keys.clear();
     root.updateMatrixWorld(true);
   });
+  // THE PERSON ALWAYS WINS: a new key press the game would hear, or a pointer pressed anywhere
+  // in the game's area (its HUD included), hands control back before the input is the game's.
+  // Untrusted events count: `editor.document.key` and the probe's clicks are how an agent plays
+  // by hand.
+  const surface = options.container.parentElement ?? options.container;
+  const takeover = (): void => {
+    // An arm still waiting for the bot counts too: the person is driving before it could start.
+    const now = modelPlayAutoplay(options.documentId);
+    if (current() && (now.on || now.armed)) setModelPlayAutoplay(options.documentId, false, 'takeover');
+  };
   const onKeyDown = (event: KeyboardEvent): void => {
     if (!surfaceAcceptsKey(event)) return;
+    // A repeat is a key already held, not a new press — unless this runner never saw it go down:
+    // then it was pressed before the runner was listening, and that press was a takeover.
+    if (!event.repeat || !heldKeys.has(event.code)) takeover();
     heldKeys.add(event.code);
     if (transition.acceptingKeys()) keys.add(event.code);
   };
@@ -344,7 +587,11 @@ export function runPlayScript(options: {
     // Preserve a between-frame tap until one game update has observed it.
     heldKeys.delete(event.code);
   };
+  const onPointerDown = (event: PointerEvent): void => {
+    if (event.target instanceof Node && surface.contains(event.target)) takeover();
+  };
   const onBlur = (): void => { keys.clear(); heldKeys.clear(); };
+  window.addEventListener('pointerdown', onPointerDown, true);
   window.addEventListener('keydown', onKeyDown, true);
   window.addEventListener('keyup', onKeyUp, true);
   window.addEventListener('blur', onBlur);
@@ -369,9 +616,12 @@ export function runPlayScript(options: {
     stopped = true;
     unregisterLive();
     stopRequest();
-    finishModelPlay(options.documentId);
+    // A runner replaced by Restart leaves the play running for its successor.
+    if (current()) finishModelPlay(options.documentId);
     stopFrames();
+    stopClock();
     stopChanges();
+    window.removeEventListener('pointerdown', onPointerDown, true);
     window.removeEventListener('keydown', onKeyDown, true);
     window.removeEventListener('keyup', onKeyUp, true);
     window.removeEventListener('blur', onBlur);