@volter/editor-blender 0.1.132 → 0.1.133

package/contributions/blender-game-panel.tsx

@@ -163,15 +163,24 @@ function gameState(documentId: string): unknown {
   };
 }
 
-/** The bot's switch and who drives: `bot` while autoplay is on, `person` otherwise, null when
- *  nothing plays. `by` is who made the last change (`takeover`: a person's key or pointer);
- *  `why` says why there is no bot to switch, null when there is one. */
+/** Who drives a playing game: the bot while autoplay is on; the person once their key or pointer
+ *  has reached the game this run; otherwise nobody — the game runs on no input. A tool that
+ *  predates `person` cannot say, and counts autoplay off as the person driving, as it always did. */
+function driverOf(playing: boolean, autoplay: DocumentPlayAutoplay): 'bot' | 'person' | 'none' | null {
+  if (!playing) return null;
+  if (autoplay.on) return 'bot';
+  return autoplay.person === false ? 'none' : 'person';
+}
+
+/** The bot's switch and who drives (`driverOf`), null when nothing plays. `by` is who made the
+ *  last change (`takeover`: a person's key or pointer; `limit`: the run's seconds spent); `state`
+ *  what the bot says it is doing; `why` says why there is no bot to switch, null when there is one. */
 function autoplayState(documentId: string): unknown {
   const found = extension();
   const autoplay = found?.transport?.autoplay?.(documentId) ?? NO_BOT;
   const playing = found?.playing(documentId) ?? false;
   const why = autoplayWhy(playing, found?.transport?.clock(documentId) ?? STILL, autoplay);
-  return { ...autoplay, driver: playing ? (autoplay.on ? 'bot' : 'person') : null, why };
+  return { ...autoplay, driver: driverOf(playing, autoplay), why };
 }
 
 /**
@@ -299,8 +308,9 @@ registerViewVerbs({
       },
     },
     {
-      // THE EDITOR'S AUTOPLAY SWITCH: on drives the game's own bot (`play.autoplay`), off hands
-      // the game back to the person. Off at every Play and Restart.
+      // THE EDITOR'S AUTOPLAY SWITCH: on drives one of the game's bot behaviours (`play.autoplay`)
+      // for at most `for` simulation seconds, off hands the game back to the person. Off at every
+      // Play and Restart. `behavior` is required when the bot offers several.
       id: 'autoplay',
       run: (args) => {
         const documentId = verbDocument(args);
@@ -308,6 +318,11 @@ registerViewVerbs({
         const on = raw === true || raw === 'on' || raw === 'true' ? true
           : raw === false || raw === 'off' || raw === 'false' ? false : undefined;
         if (on === undefined) throw new Error(`autoplay's \`on\` is true or false (\`play autoplay on|off\`); got ${String(raw)}.`);
+        const behavior = typeof args?.['behavior'] === 'string' && args['behavior'] !== '' ? args['behavior'] : null;
+        const rawLimit = args?.['for'] ?? args?.['limit'];
+        const limit = rawLimit === undefined || rawLimit === null ? null : Number(rawLimit);
+        if (limit !== null && !(Number.isFinite(limit) && limit > 0))
+          throw new Error(`autoplay's \`for\` is a positive number of simulation seconds; got ${JSON.stringify(rawLimit)}.`);
         const found = verbExtension();
         const { transport } = found;
         if (transport.setAutoplay === undefined)
@@ -315,7 +330,7 @@ registerViewVerbs({
         // Refused with the reason, stopped or no bot, as `play state`'s `autoplay.why` gives it.
         const why = on ? autoplayWhy(found.playing(documentId), transport.clock(documentId), transport.autoplay?.(documentId) ?? NO_BOT) : null;
         if (why !== null) throw new Error(why);
-        transport.setAutoplay(documentId, on, 'cli');
+        transport.setAutoplay(documentId, on, 'cli', on ? { behavior, limit } : undefined);
         return gameState(documentId);
       },
     },
@@ -635,8 +650,32 @@ function AutoplayControl({ documentId, playing, clock, autoplay, transport }: {
     : unavailable === 'not-running'
       ? armed ? 'Armed — turns on once the game is running' : 'Available once the game is running'
       : null;
+  // THE BEHAVIOUR TO RUN, when the bot offers several: chosen here, as `play autoplay on <behaviour>`
+  // names it. Shown with the one driving (or armed) selected, else the bot's first.
+  const behaviors = autoplay.behaviors ?? [];
+  const [picked, setPicked] = useState<string | null>(null);
+  const behavior = autoplay.on || armed ? autoplay.behavior ?? null : picked !== null && behaviors.includes(picked) ? picked : behaviors[0] ?? null;
+  const driver = driverOf(playing, autoplay);
+  // Said while nobody drives; once the person's input reaches the game, the driver line says they are.
+  const limitNote = driver !== 'none' ? null
+    : autoplay.by === 'limit' && autoplay.limit ? `Autoplay stopped at its ${Math.round(autoplay.limit)} s limit`
+    // An arm the start could not take says why, rather than leaving the person to wonder.
+    : autoplay.refused ? `Autoplay didn’t start: ${autoplay.refused}` : null;
+  const botLine = [autoplay.behavior, autoplay.state].filter(Boolean).join(' — ');
   return (
     <div style={{ display: 'flex', alignItems: 'center', gap: TIMELINE_CHROME.headerGap, minWidth: 0 }}>
+      {behaviors.length > 1 && (
+        <select
+          data-testid="model-play-autoplay-behavior"
+          title="The bot behaviour Autoplay runs"
+          value={behavior ?? ''}
+          disabled={autoplay.on}
+          onChange={(event) => setPicked(event.target.value)}
+          style={{ background: TIMELINE_CHROME.widget, color: TIMELINE_CHROME.widgetText, border: 'none', borderRadius: TIMELINE_CHROME.widgetRadius, font: 'inherit', minWidth: 0 }}
+        >
+          {behaviors.map((name) => <option key={name} value={name}>{name}</option>)}
+        </select>
+      )}
       {/* The tooltip lives on a wrapper too: a disabled button is the one that most needs it. */}
       <span title={label} style={{ display: 'inline-flex' }}>
       {/* KEEP THE KEYBOARD OFF THIS BUTTON (`GameButton`'s `keepFocus`). Left focused, a person
@@ -652,8 +691,8 @@ function AutoplayControl({ documentId, playing, clock, autoplay, transport }: {
         // between the render and the click.
         onClick={() => {
           const now = transport.autoplay?.(documentId) ?? NO_BOT;
-          if (!(extension()?.playing(documentId) ?? false)) transport.armAutoplay?.(documentId, !now.armed);
-          else transport.setAutoplay?.(documentId, !now.on, 'panel');
+          if (!(extension()?.playing(documentId) ?? false)) transport.armAutoplay?.(documentId, !now.armed, { behavior });
+          else transport.setAutoplay?.(documentId, !now.on, 'panel', now.on ? undefined : { behavior });
         }}
       >
         Autoplay
@@ -664,12 +703,17 @@ function AutoplayControl({ documentId, playing, clock, autoplay, transport }: {
           {note}
         </span>
       ) : playing && (
+        // WHO DRIVES, AND WHAT THE BOT SAYS IT IS DOING: "Bot driving · win — heading to nest 2".
+        // Nobody drives a game that runs on no input; the person only once their input reached it.
         <span
           data-testid="model-play-driver"
-          data-driver={autoplay.on ? 'bot' : 'person'}
-          style={{ color: autoplay.on ? TIMELINE_THEME.playhead : TIMELINE_CHROME.widgetText, whiteSpace: 'nowrap' }}
+          data-driver={driver ?? undefined}
+          title={autoplay.state ? `The bot: ${autoplay.state}` : undefined}
+          style={{ color: autoplay.on ? TIMELINE_THEME.playhead : TIMELINE_CHROME.widgetText, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', minWidth: 0 }}
         >
-          {autoplay.on ? 'Bot driving' : 'You’re driving'}
+          {driver === 'bot' ? `Bot driving${botLine ? ` · ${botLine}` : ''}`
+            : limitNote ? `${limitNote}${autoplay.state ? ` — ${autoplay.state}` : ''}`
+            : driver === 'person' ? 'You’re driving' : 'Nobody’s driving'}
         </span>
       )}
     </div>

package/host/blender-runtime-host.ts

@@ -158,6 +158,7 @@ export async function photographSnapshot(
   await snapshot.prepare(renderCamera);
   assertCurrent();
   const captureOptions = {
+    prepareDraw:snapshot.prepareDraw,
     effect: snapshot.effect,
     width: render.width,
     height: render.height,
@@ -218,16 +219,29 @@ export function bindModelDocument(bound: ModelDocumentBinding | null): () => voi
   };
 }
 
-function modelDocumentConflict(): string | null {
-  const held = runtime?.document;
-  // The finder owns model:<path>, wrapped by the host as document:<entry>.
-  // Read the active address too: activation precedes the contributed pane's
-  // effect, so an immediate command must not slip through that binding gap.
+/** The `.blend` the editor is showing as the Model: the active tab's own file, or the bound one.
+ * The finder owns model:<path>, wrapped by the host as document:<entry>. Read the active address
+ * too: activation precedes the contributed pane's effect, so an immediate command must not slip
+ * through that binding gap. */
+function shownModelBlend(): string | undefined {
   const activeId = editorHost().documents.activeId();
-  const requested = activeId?.startsWith('document:model:')
+  return activeId?.startsWith('document:model:')
     ? activeId.slice('document:model:'.length)
     : boundModel?.blend;
+}
+
+/**
+ * A script's Save As into a project `.blend` that no Model document lists (`followMovedDocument`): Blender edits
+ * that file and saves there, and the tab it left (`from`) keeps showing Blender, since there is no tab to move to.
+ * Without this, every later call was refused as a conflict naming a file no tab can show.
+ */
+let unlistedFollow: { readonly owner: BlenderRuntime; readonly from: string; readonly document: string } | null = null;
+
+function modelDocumentConflict(): string | null {
+  const held = runtime?.document;
+  const requested = shownModelBlend();
   if (!requested || !held || requested === held) return null;
+  if (unlistedFollow !== null && unlistedFollow.owner === runtime && unlistedFollow.document === held && unlistedFollow.from === requested) return null;
   // Say how to get Blender onto the document the editor shows, not only how to go back: an agent told
   // just "return to <held>" took it as the Blender door being unusable and built its level by
   // another route (2026-10-06, the WSL obby run).
@@ -513,7 +527,10 @@ export async function blenderViewShading(shading: 'WIREFRAME' | 'SOLID' | 'MATER
  * reads rather than this execute path, which always presents a mutation.
  */
 export async function blenderExecute(code: string, history = true, label = 'Blender Python'): Promise<BlenderExecuteAnswer> {
-  const text = await blenderRuntime().execute(code, history, label);
+  const session = blenderRuntime();
+  const text = await session.execute(code, history, label);
+  // Before the caller hears back: its next call must find the tab on the file Blender now holds.
+  await followMovedDocument(session);
   noteBlenderRnaChanged();
   const failed = /^Error executing code:/.exec(text);
   return {
@@ -524,6 +541,71 @@ export async function blenderExecute(code: string, history = true, label = 'Blen
   };
 }
 
+/**
+ * A Save As the worker reported (`BlenderRuntimeOptions.documentMoved`) that the open Model tab
+ * has not followed yet. Taken by the {@link blenderExecute} whose script moved it, once that
+ * call's own save has landed the new file in the project.
+ */
+let unfollowedMove: { readonly owner: BlenderRuntime; readonly from: string; readonly document: string } | null = null;
+
+/**
+ * THE MODEL TAB FOLLOWS BLENDER'S SAVE AS. The runtime already holds the new file and its saves
+ * go there (`session.py::follow_open_file`); what is left is the tab. Until it moves, the editor
+ * is showing the old file while Blender edits the new one, which `modelDocumentConflict` refuses
+ * on every later call. So the new file's own Model document is opened: it binds to the session
+ * that already holds that file (no stop, no reload), and the old tab, no longer active, releases
+ * its binding. Re-activating the old tab later opens the old file the ordinary way.
+ *
+ * Only a tab that was showing the old file (or the standing Model of a project that had no
+ * `.blend`) is moved; a person who has since switched elsewhere is not pulled back. A new file
+ * no Model document lists (outside the project's model finder) is said, not guessed at.
+ */
+async function followMovedDocument(owner: BlenderRuntime): Promise<void> {
+  const move = unfollowedMove;
+  if (!move || move.owner !== owner) return;
+  unfollowedMove = null;
+  const host = editorHost();
+  // The tab showing Blender: the file Blender left, or, after an earlier Save As to an unlisted file, the tab
+  // that one left.
+  const shownFrom = unlistedFollow !== null && unlistedFollow.owner === owner && unlistedFollow.document === move.from ? unlistedFollow.from : move.from;
+  unlistedFollow = null;
+  const stillShowingOld = () => {
+    if (runtime !== owner || owner.document !== move.document) return false;
+    const shown = shownModelBlend();
+    return shown === shownFrom || (shown === undefined && host.documents.activeId() === BLENDER_RUNTIME_DOCUMENT_ID);
+  };
+  if (!stillShowingOld()) return;
+  try {
+    // The table re-reads the project's files, which now include the file this call saved.
+    const table = await host.project.documentTable();
+    const entry = table.entries.find(candidate => candidate.kind === 'model' && candidate.source?.path === move.document);
+    if (!entry) {
+      if (!stillShowingOld()) return;
+      unlistedFollow = { owner, from: shownFrom, document: move.document };
+      host.console.warn(
+        `Blender now has ${move.document} open and the model saves there. No Model document lists that file ` +
+          `(the project's model finder does not include its folder), so the ${shownFrom} tab keeps showing ` +
+          `Blender, which now edits ${move.document}; ${shownFrom} keeps what it last saved. Save the model ` +
+          `under src/models/ to give it a Model tab of its own.`,
+        'blender-document',
+      );
+      return;
+    }
+    if (!stillShowingOld()) return;
+    if (!await host.workspace.open({ kind: 'document', id: entry.id })) {
+      keepShowing();
+      host.console.warn(`Blender now has ${move.document} open, but its Model document ${entry.id} did not open; the ${shownFrom} tab keeps showing Blender, which edits ${move.document}.`, 'blender-document');
+    }
+  } catch (error) {
+    keepShowing();
+    host.console.error(`The Model tab could not follow Blender to ${move.document}: ${error instanceof Error ? error.message : String(error)}`, 'blender-document');
+  }
+  /** A tab that could not move keeps working on the file Blender holds, as for an unlisted file. */
+  function keepShowing(): void {
+    if (stillShowingOld()) unlistedFollow = { owner, from: shownFrom, document: move!.document };
+  }
+}
+
 /** Coalesce a human gesture; Blender retains the states, Code-OSS the ordering. */
 export function beginBlenderGesture(): void {
   void blenderRuntime().historyGesture('history-begin').catch(error =>
@@ -1077,6 +1159,19 @@ export function blenderRuntime(): BlenderRuntime {
     // traceback out of it.
     // biome-ignore lint/suspicious/noConsole: the Blender worker's log is page output by design.
     log: (level, text) => console[level](`[blender] ${text}`),
+    // A SCRIPT'S SAVE AS MOVED THE DOCUMENT. Said in the editor's console, where the change of
+    // file is a fact a person needs; the tab follows once the script's call answers
+    // (`followMovedDocument`), when the new file is in the project to open.
+    documentMoved: (moved) => {
+      const owner = runtime;
+      if (!owner) return;
+      unfollowedMove = { owner, from: moved.from, document: moved.document };
+      editorHost().console.log(
+        `Blender now has ${moved.document} open (a script saved or opened it there), so the model saves to ` +
+          `${moved.document} from now on; ${moved.from} keeps what it last saved.`,
+        'blender-document',
+      );
+    },
   });
   const session = runtime;
   // MEASUREMENT, PUBLISHED THE MOMENT THE SESSION EXISTS. The worker cannot say
@@ -1122,7 +1217,8 @@ const string = (cmd: Record<string, unknown>, key: string): string => {
 /**
  * The project-relative path of the `.blend` the SESSION'S PYTHON currently
  * holds — `bpy.data.filepath`, which a bake script's own `open_mainfile`
- * retargets and the session's bound document does not. Answers `{}` when there
+ * retargets as it runs (the session's document follows only once the call has
+ * ended, and only inside the project). Answers `{}` when there
  * is no file (a scene modelled from scratch has never been saved) or when the
  * path is outside the project, because a record is better absent than wrong.
  */
@@ -1219,10 +1315,17 @@ export async function handleBlenderCommand(cmd: {
         // project's document is its own `src/models/<name>.blend`, and a
         // `blender-start` that named none is asking for the session this tab
         // is showing, not for a second file beside it.
+        // After a script's Save As to a file no Model lists, the session this tab
+        // shows holds that file (`unlistedFollow`), and a start naming none
+        // asks for it, not for the file the tab was opened on.
+        const shown =
+          unlistedFollow !== null && unlistedFollow.owner === session && unlistedFollow.from === (boundModel?.blend ?? DEFAULT_BLENDER_DOCUMENT)
+            ? unlistedFollow.document
+            : boundModel?.blend;
         const document =
           requestedDocument !== undefined
             ? requestedDocument
-            : (boundModel?.blend ?? DEFAULT_BLENDER_DOCUMENT);
+            : (shown ?? DEFAULT_BLENDER_DOCUMENT);
         return { ok: true, data: { ...(await session.start(project!, document)) } };
       }
       case 'blender-execute': {
@@ -1439,9 +1542,9 @@ export async function handleBlenderCommand(cmd: {
             // IT IS ASKED OF PYTHON, NOT OF `boundModel`, and that distinction
             // is a measurement rather than a preference. `boundModel` is the
             // document the TAB opened; a bake script opens its own file with
-            // `wm.open_mainfile`, which `bind_document` deliberately leaves
-            // alone (it retargets `bpy.data.filepath`, not the session's
-            // document). Measured 2026-09-19: reading `boundModel` recorded
+            // `wm.open_mainfile`, which retargets `bpy.data.filepath` at once,
+            // the tab only after the call (`followMovedDocument`), and never
+            // for a file outside the project. Measured 2026-09-19: reading `boundModel` recorded
             // the SAME `.blend` as the input of all three of first-person's
             // characters — whichever one the tab happened to show — which is
             // worse than no record, because it is a confident wrong answer.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/editor-blender",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only AND GPL-3.0-or-later",
-  "version": "0.1.132",
+  "version": "0.1.133",
   "publishConfig": {
     "access": "public"
   },
@@ -72,15 +72,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.1",
-    "@volter/blender-engine": "0.1.130",
-    "@volter/editor-threejs": "0.5.193",
+    "@volter/blender-engine": "0.1.131",
+    "@volter/editor-threejs": "0.5.194",
     "zod": "^4.3.6",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"
   },
   "peerDependencies": {
-    "@volter/editor-live": "0.5.193",
-    "@volter/editor-project": "0.5.193",
-    "@volter/editor-sdk": "0.5.193",
+    "@volter/editor-live": "0.5.194",
+    "@volter/editor-project": "0.5.194",
+    "@volter/editor-sdk": "0.5.194",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "three": "^0.180.0",