@volter/editor-model-play 0.5.192 → 0.5.194

package/package.json

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

package/src/model-play.ts

@@ -55,29 +55,82 @@ const generations = new Map<string, number>();
 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';
+ *  in the game, the running script no longer offering a bot (replaced, failed, or its bot
+ *  threw), or the run's time limit. */
+export type ModelPlayAutoplayBy = 'panel' | 'cli' | 'takeover' | 'script' | 'limit';
+/**
+ * EVERY AUTOPLAY RUN HAS A LIMIT, in simulation seconds: a bot whose game never ends would
+ * otherwise drive forever, and an agent waiting on it would wait forever. Reaching it turns
+ * autoplay off, pauses the game and logs `autoplay-limit` (`play-script.ts`).
+ */
+export const MODEL_PLAY_AUTOPLAY_LIMIT_SECONDS = 300;
 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;
+  /** The behaviours the running script's bot offers (`play.autoplay({ win, lose })`), in its
+   *  order; a bare function is the one behaviour `play`. */
+  readonly behaviors: readonly string[];
+  /** The behaviour driving now, or armed for the next start. */
+  readonly behavior: string | null;
+  /** This run's limit and the simulation time it began at; null while autoplay is off. */
+  readonly limit: number | null;
+  readonly since: number | null;
   readonly by: ModelPlayAutoplayBy | null;
   /** Pressed while stopped: the next start turns autoplay on once its script offers a bot. */
   readonly armed: boolean;
+  /** A person's key or pointer reached the game in this run. Until one does, nobody drives
+   *  while autoplay is off — the game runs on no input. */
+  readonly person: boolean;
+  /** What the bot last said it is doing (`{ keys, state }` from its controller); kept after
+   *  autoplay goes off, so a limit or takeover still shows where the bot was. */
+  readonly state: string | null;
+  /** Why the last arm was not taken at start (the bot offers no bot, or not the behaviour it asked
+   *  for, or several with none named); null otherwise. Said in the panel and the play log. */
+  readonly refused: string | null;
 }
-const NO_BOT: ModelPlayAutoplay = { on: false, available: false, by: null, armed: false };
+/** What a switch-on asks for: the behaviour (required when the bot offers several) and the limit. */
+export interface ModelPlayAutoplayRequest {
+  readonly behavior?: string | null;
+  readonly limit?: number | null;
+}
+const NO_BOT: ModelPlayAutoplay = { on: false, available: false, behaviors: [], behavior: null, limit: null, since: null, by: null, armed: false, person: false, state: null, refused: null };
 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. */
+/** A new run's autoplay: off, no bot yet, nobody driving. Play keeps an arm made while stopped
+ *  (with the behaviour and limit it asked for); Stop drops it. The behaviours the last run's bot
+ *  offered are kept, not available: while stopped they are what the panel's picker offers for an
+ *  arm, which is checked against the bot the next start offers. */
 function resetAutoplay(documentId: string, keepArm: boolean): void {
-  if (keepArm && modelPlayAutoplay(documentId).armed) autoplays.set(documentId, ARMED);
+  const now = modelPlayAutoplay(documentId);
+  if (keepArm && now.armed) autoplays.set(documentId, { ...ARMED, behaviors: now.behaviors, behavior: now.behavior, limit: now.limit });
+  else if (now.behaviors.length) autoplays.set(documentId, { ...NO_BOT, behaviors: now.behaviors });
   else autoplays.delete(documentId);
 }
 
+/** A limit as given: a positive number of simulation seconds, or the default. */
+function autoplayLimit(limit: number | null | undefined): number {
+  if (limit === undefined || limit === null) return MODEL_PLAY_AUTOPLAY_LIMIT_SECONDS;
+  if (!Number.isFinite(limit) || limit <= 0) throw new Error(`An autoplay limit is a positive number of simulation seconds; got ${String(limit)}.`);
+  return limit;
+}
+
+/** The behaviour a switch-on drives: the one named, which the bot must offer; with none named,
+ *  the bot's only behaviour. A bot with several needs one named, so a run always says what its
+ *  bot was trying to do. */
+function chosenBehavior(behaviors: readonly string[], named: string | null | undefined): string {
+  if (named) {
+    if (!behaviors.includes(named))
+      throw new Error(`This game's bot has no behaviour "${named}"; it offers ${behaviors.map(b => `"${b}"`).join(', ')}.`);
+    return named;
+  }
+  if (behaviors.length === 1) return behaviors[0]!;
+  throw new Error(`This game's bot offers several behaviours (${behaviors.join(', ')}); name the one to run: \`play autoplay on <behaviour>\`.`);
+}
+
 function publish(): void {
   for (const listener of [...listeners]) listener();
 }
@@ -250,9 +303,10 @@ function setAutoplay(documentId: string, next: Partial<ModelPlayAutoplay>): void
 }
 
 /** 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 {
+ *  registered a bot, names the behaviour to drive (required when the bot offers several) and
+ *  starts the run's limit; 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, request: ModelPlayAutoplayRequest = {}): 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\`.`);
@@ -261,29 +315,62 @@ export function setModelPlayAutoplay(documentId: string, on: boolean, by: ModelP
     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 });
+  if (on) {
+    const behavior = chosenBehavior(now.behaviors, request.behavior);
+    const limit = autoplayLimit(request.limit);
+    // Switching on again (another behaviour, a new limit) is a new run of the bot.
+    setAutoplay(documentId, { on, by, behavior, limit, since: clock.time, armed: false, state: null, refused: null });
+  } else if (now.on || now.armed) setAutoplay(documentId, { on, by, armed: false, since: null });
 }
 
 /** 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 {
+ *  before Play. The behaviour and limit are checked when the start takes the arm, since the bot
+ *  is offered only then. Disarming always succeeds. */
+export function armModelPlayAutoplay(documentId: string, armed: boolean, request: ModelPlayAutoplayRequest = {}): 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 });
+  if (armed) setAutoplay(documentId, { armed, refused: null, behavior: request.behavior ?? null, limit: request.limit === undefined || request.limit === null ? null : autoplayLimit(request.limit) });
+  else if (modelPlayAutoplay(documentId).armed) setAutoplay(documentId, { armed, behavior: null, limit: null });
 }
 
-/** 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 {
+/** The runner's report that a script has run its first update, offering a bot's behaviours or
+ *  none. An arm is taken here: on with a bot that has the behaviour it asked for (or only one),
+ *  dropped otherwise. */
+export function settleModelPlayAutoplay(documentId: string, behaviors: readonly string[]): 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' });
+  if (!now.armed) { setModelPlayAutoplayAvailable(documentId, behaviors); return; }
+  let behavior: string | null = null;
+  let refused: string | null = null;
+  if (!behaviors.length) refused = 'the play script registers no bot with play.autoplay';
+  else {
+    try { behavior = chosenBehavior(behaviors, now.behavior); }
+    catch (error) { refused = error instanceof Error ? error.message : String(error); }
+  }
+  setAutoplay(documentId, behavior !== null
+    ? { available: true, behaviors, armed: false, on: true, by: 'panel', behavior, limit: now.limit ?? MODEL_PLAY_AUTOPLAY_LIMIT_SECONDS, since: modelPlayClock(documentId).time, state: null, refused: null }
+    : { available: behaviors.length > 0, behaviors, armed: false, behavior: null, limit: null, by: 'script', refused });
 }
 
-/** 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 {
+/** The runner's report of the behaviours the running script's bot offers (none: no bot). Losing
+ *  the bot, or the behaviour driving, turns autoplay off. */
+export function setModelPlayAutoplayAvailable(documentId: string, behaviors: readonly string[]): void {
   const now = modelPlayAutoplay(documentId);
-  if (now.available === available || !playing.has(documentId)) return;
-  setAutoplay(documentId, available || !now.on ? { available } : { available, on: false, by: 'script' });
+  if (!playing.has(documentId)) return;
+  const available = behaviors.length > 0;
+  const same = now.available === available && now.behaviors.length === behaviors.length && now.behaviors.every((b, i) => b === behaviors[i]);
+  if (same) return;
+  const lost = now.on && (now.behavior === null || !behaviors.includes(now.behavior));
+  setAutoplay(documentId, lost ? { available, behaviors, on: false, by: 'script', since: null } : { available, behaviors });
+}
+
+/** The runner's report of what the driving bot says it is doing; announced only when it changes. */
+export function setModelPlayBotState(documentId: string, state: string | null): void {
+  if (playing.has(documentId) && modelPlayAutoplay(documentId).state !== state) setAutoplay(documentId, { state });
+}
+
+/** The runner's report that a person's key or pointer reached the game: from now on in this run,
+ *  autoplay off means the person drives. */
+export function noteModelPlayPerson(documentId: string): void {
+  if (playing.has(documentId) && !modelPlayAutoplay(documentId).person) setAutoplay(documentId, { person: true });
 }

package/src/play-script.ts

@@ -74,10 +74,13 @@ import {
   modelPlayAutoplay,
   modelPlayClock,
   modelPlayGeneration,
+  noteModelPlayPerson,
   registerModelPlayStop,
   setModelPlayAutoplay,
+  setModelPlayBotState,
   setModelPlayFailure,
   setModelPlayAutoplayAvailable,
+  setModelPlayPaused,
   settleModelPlayAutoplay,
   subscribeModelPlayClock,
   takeModelPlayStep,
@@ -136,20 +139,30 @@ export interface ModelPlayContext {
    *  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.
+   * Offer this game's bot, as named BEHAVIOURS: what the bot sets out to do, each its own
+   * controller. While the person (or an agent, `play autoplay on <behaviour>`) has autoplay on in
+   * the Game panel, the chosen behaviour's controller is called before each `update` and the keys
+   * it answers are held for that update, merged into `keys`. Offer the outcomes worth checking —
+   * one that plays to win and one that loses on purpose — so a run tests an ending by saying so,
+   * not by leaving the game alone. A bare function is the one behaviour `play`. Every run has a
+   * limit in simulation seconds (`play autoplay on <behaviour> --for <seconds>`, 300 unless
+   * given): reaching it turns autoplay off and pauses the game. 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'] : []));
+   *     play.autoplay({
+   *       win: ({ dt }) => (car.speed < 20 ? ['ArrowUp'] : []),
+   *       lose: () => ['ArrowLeft'],   // drives off the track
+   *     });
    */
-  autoplay(controller: ModelPlayAutoplayController | null): void;
+  autoplay(bot: ModelPlayAutoplayController | Readonly<Record<string, ModelPlayAutoplayController>> | null): void;
 }
 
 /** What the bot is handed before each `update` it drives. */
 export interface ModelPlayAutoplayInput {
+  /** The behaviour driving (`play autoplay on <behaviour>`), for a controller shared by several. */
+  readonly behavior: string;
   /** 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. */
@@ -158,8 +171,27 @@ export interface ModelPlayAutoplayInput {
   /** 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;
+/**
+ * A game's bot: the keys (`KeyboardEvent.code`) it holds for the coming update — or those keys
+ * with what it is doing now, `{ keys, state: 'heading to nest 2' }`. The state is the bot
+ * explaining itself: the Game panel shows it beside the driver, `play state` reports it, and
+ * each change is a `bot-state` entry in the play log. Say intentions and their reasons (a goal,
+ * a target, why it is waiting), not per-frame numbers.
+ */
+export type ModelPlayAutoplayController = (input: ModelPlayAutoplayInput) =>
+  Iterable<string> | { readonly keys?: Iterable<string> | null; readonly state?: string | null } | null | undefined;
+
+/** The longest bot state kept: a line for the panel, not a report. */
+const BOT_STATE_CHARACTERS = 160;
+
+/** A controller's answer as its keys and its state (undefined: it said nothing about its state). */
+function botAnswer(answer: ReturnType<ModelPlayAutoplayController>): { keys: Iterable<string>; state: string | null | undefined } {
+  if (answer === null || answer === undefined) return { keys: [], state: undefined };
+  if (typeof (answer as Iterable<string>)[Symbol.iterator] === 'function') return { keys: answer as Iterable<string>, state: undefined };
+  const { keys, state } = answer as { keys?: Iterable<string> | null; state?: string | null };
+  const said = state === undefined ? undefined : state === null ? null : String(state).replace(/\s+/g, ' ').trim().slice(0, BOT_STATE_CHARACTERS) || null;
+  return { keys: keys ?? [], state: said };
+}
 
 export interface ModelPlayGame {
   /** Once per drawn frame, with the simulation seconds since the last call (at most a tenth).
@@ -174,10 +206,32 @@ export interface ModelPlayGame {
  *  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;
+  /** The bot's behaviours by name, in the order offered; null without a bot. */
+  bot: Readonly<Record<string, ModelPlayAutoplayController>> | null;
   readonly unknown: Set<string>;
 }
 
+/** The behaviour names a script's bot offers, in its order. */
+function behaviorsOf(script: Script | undefined): string[] {
+  return script?.bot ? Object.keys(script.bot) : [];
+}
+
+/** `play.autoplay`'s argument as behaviours by name: a bare function is the one behaviour `play`. */
+function botBehaviors(bot: unknown): Readonly<Record<string, ModelPlayAutoplayController>> | null {
+  if (bot === null) return null;
+  if (typeof bot === 'function') return { play: bot as ModelPlayAutoplayController };
+  if (typeof bot === 'object' && !Array.isArray(bot)) {
+    const entries = Object.entries(bot as Record<string, unknown>);
+    if (entries.length === 0) throw new Error('play.autoplay was given no behaviours: offer at least one, `{ win: (input) => keys }`.');
+    for (const [name, controller] of entries) {
+      if (!/^[A-Za-z][\w-]{0,39}$/.test(name)) throw new Error(`play.autoplay behaviour "${name}" is not a name: letters, digits, - and _, starting with a letter.`);
+      if (typeof controller !== 'function') throw new Error(`play.autoplay behaviour "${name}" is not a function (the controller).`);
+    }
+    return Object.freeze({ ...(bot as Record<string, ModelPlayAutoplayController>) });
+  }
+  throw new Error('play.autoplay takes a function (the bot), its behaviours by name (`{ win, lose }`), or null.');
+}
+
 /** The longest `dt` one update is handed; longer scaled frames are split (`frameUpdates`). */
 const MAX_UPDATE_SECONDS = 0.1;
 
@@ -296,10 +350,11 @@ export function runPlayScript(options: {
     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 });
+    if (bot.on !== seenBot.on || (bot.on && (bot.behavior !== seenBot.behavior || bot.since !== seenBot.since)))
+      run.append('play', bot.on ? 'autoplay-on' : 'autoplay-off', bot.on ? { by: bot.by, behavior: bot.behavior, limit: bot.limit } : { by: bot.by, behavior: seenBot.behavior });
     // 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 });
+    else if (seenBot.armed && !bot.armed && bot.by !== null) run.append('play', 'autoplay-off', { by: bot.by, armed: true, ...(bot.refused ? { why: bot.refused } : {}) });
     seenBot = bot;
   });
   options.container.style.opacity = '0';
@@ -326,10 +381,9 @@ export function runPlayScript(options: {
       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;
+    autoplay(bot) {
+      const behaviors = botBehaviors(bot);
+      if (alive.value) alive.bot = behaviors;
     },
   });
   const scripts = new WeakMap<ModelPlayGame, Script>();
@@ -450,7 +504,7 @@ export function runPlayScript(options: {
     else if (!transition.acceptingKeys()) keys.clear();
     else for (const key of heldKeys) keys.add(key);
     // 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);
+    if (current()) setModelPlayAutoplayAvailable(options.documentId, game !== null ? behaviorsOf(scripts.get(game)) : []);
     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.
@@ -478,13 +532,20 @@ export function runPlayScript(options: {
     /** 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;
+      // Asked again per update: the bot's own failure, a takeover, its limit, or
+      // `play.autoplay(null)` ends it mid-frame.
+      const now = modelPlayAutoplay(options.documentId);
+      const behavior = driving && now.on ? now.behavior : null;
+      const bot = behavior !== null ? scripts.get(script)?.bot?.[behavior] : undefined;
+      if (!bot || behavior === null) return false;
       restorePerson();
       try {
-        for (const key of bot({ dt, simT: clock.time + simulated, tick: clock.tick + ran, keys: person }) ?? []) keys.add(String(key));
+        const answer = botAnswer(bot({ behavior, dt, simT: clock.time + simulated, tick: clock.tick + ran, keys: person }));
+        for (const key of answer.keys) keys.add(String(key));
+        if (answer.state !== undefined && answer.state !== now.state) {
+          setModelPlayBotState(options.documentId, answer.state);
+          run.append('play', 'bot-state', { behavior, state: answer.state });
+        }
         return true;
       } catch (error) {
         restorePerson();
@@ -524,7 +585,8 @@ export function runPlayScript(options: {
         // 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;
+        const behaviors = behaviorsOf(scripts.get(next.game));
+        const offered = behaviors.length > 0;
         if (!offered && offeredBot !== false)
           run.append('play', 'autoplay-unavailable', { why: 'the play script registers no bot with play.autoplay(controller)' });
         offeredBot = offered;
@@ -532,7 +594,7 @@ export function runPlayScript(options: {
         // 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);
+        settleModelPlayAutoplay(options.documentId, behaviors);
         setModelPlayFailure(options.documentId, null);
         startedAt = Date.now();
         endedAt = null;
@@ -551,6 +613,17 @@ export function runPlayScript(options: {
       }
       advanceModelPlayClock(options.documentId, simulated, ran);
       ran = 0;
+      // THE RUN'S LIMIT: a bot still driving when its simulation seconds are spent is stopped and
+      // the game held, so a game that never ends cannot keep a bot (and whoever waits on it) going.
+      const bot = modelPlayAutoplay(options.documentId);
+      if (current() && bot.on && bot.limit !== null && bot.since !== null) {
+        const now = modelPlayClock(options.documentId).time;
+        if (now - bot.since >= bot.limit) {
+          run.append('play', 'autoplay-limit', { behavior: bot.behavior, limit: bot.limit, ran: now - bot.since, state: bot.state });
+          setModelPlayAutoplay(options.documentId, false, 'limit');
+          setModelPlayPaused(options.documentId, true);
+        }
+      }
       transition.frame(camera(), deltaSeconds);
       options.container.style.opacity = String(transition.hudOpacity());
       if (firstFrame) { firstFrame = false; options.ready(); }
@@ -571,9 +644,12 @@ export function runPlayScript(options: {
   // by hand.
   const surface = options.container.parentElement ?? options.container;
   const takeover = (): void => {
+    if (!current()) return;
+    // Whether or not a bot was driving, the person is driving from here on in this run.
+    noteModelPlayPerson(options.documentId);
     // 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');
+    if (now.on || now.armed) setModelPlayAutoplay(options.documentId, false, 'takeover');
   };
   const onKeyDown = (event: KeyboardEvent): void => {
     if (!surfaceAcceptsKey(event)) return;