@volter/play 0.5.211 → 0.5.213

package/contributions/levels.finder.ts

@@ -0,0 +1,43 @@
+/**
+ * A STD GAME'S LEVELS AS ITS DOCUMENTS: each level component, `levels/<Name>Level.tsx`, is a document of its own
+ * (`std-level`, drawn by `std-level.document.tsx` as the game draws it), named as its component is less `Level`, as a level is the
+ * document an engine opens. Its source is its record: its own code, or the `levels/<name>.blend` std's export writes
+ * it from, as a model's `.blend` is the source of the component the game places. The project opens on its main level.
+ */
+import { z } from 'zod';
+import { CODE_LEVEL, sceneLevelOf } from '../src/std-level-files';
+
+export const finder = {
+  name: 'stdLevelDocuments',
+  // (paths only: whether a component is a Blender level's is read from the files beside it)
+  reads: 'files',
+  schema: z
+    .object({
+      finder: z.literal('stdLevelDocuments'),
+      include: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("Project-relative globs of the levels' files (`levels/**/*.tsx`, and `levels/**/*.blend` to know which components a Blender level writes)"),
+    })
+    .strict(),
+  run(_selection: { finder: 'stdLevelDocuments'; include: readonly string[] }, input: { files?: readonly string[] }) {
+    const files = input.files ?? [];
+    const entries = files
+      .filter((path) => CODE_LEVEL.test(path))
+      .map((path) => ({
+        id: `level:${path}`,
+        // (named as an engine names its levels: `MainLevel` is Main)
+        label: CODE_LEVEL.exec(path)?.[1]?.replace(/Level$/, '') ?? path,
+        kind: 'std-level',
+        region: null,
+        authorable: false,
+        reach: { kind: 'root-mount' as const },
+        // (the level's source: a Blender level's `.blend`, else its own code)
+        source: { path: sceneLevelOf(path, files) ?? path },
+      }));
+    // (the project opens on its level, as an engine opens its main level: the game's Main, else the level last worked
+    // on, the files coming newest first)
+    const opened = entries.find((entry) => entry.label === 'Main') ?? entries[0];
+    return { entries, notes: [] as string[], ...(opened === undefined ? {} : { default: opened.id }) };
+  },
+} as const;

package/contributions/play.page.tsx

@@ -0,0 +1,93 @@
+/**
+ * PLAY'S PAGE HALF (`contributes.volter.page`, `docs/adr/plugin-apis.md`): Play, the project's. It registers its Game
+ * panel through editor-blender's API (`registerPlay`, whose bottom area shows it), which play declares in
+ * `extensionDependencies`, and keeps the project's run (`../src/game-view.tsx`): Play runs the project's volter-ai/std
+ * game whatever document is in front, its own dev pages each a player's (`../src/std-game.ts`), in the Game view.
+ */
+import type { BlenderPageApi, PlayTool } from '@volter/editor-blender/api';
+import { registerVerbCommands, registerViewCommands } from '@volter/sdk/commands';
+import type { PluginContext } from '@volter/sdk/plugins';
+import { onProjectChange } from '@volter/sdk/active-project';
+import { editorHost } from '@volter/sdk/host';
+import type { ThreePageApi } from '@volter/editor-threejs/api';
+import { setGameFailure, subscribeGame } from '../src/game-run';
+import { keepEditSave, savedEdit } from '../src/game-controls';
+import { type GameRunner, keepGameRuns } from '../src/game-view';
+import { beginPlayLog } from '../src/play-log';
+import { isStdGame, runStdGame, STD_DEV, stdGameNow, subscribeStdGame } from '../src/std-game';
+import { keepEditorBlender } from '../src/editor-blender';
+import { keepEditorThreejs } from '../src/editor-threejs';
+import { startStdLevels, stdLevelsSettled } from '../src/std-level';
+import { GamePanel, PLAY_VIEW_VERBS } from './game-panel';
+import { playVerbs } from './play.verbs';
+
+const NOT_STD = 'This project is not a std game: it has no std.json, or no @volter-ai/std-dev among its packages (`cyclotron add-play` makes it one).';
+
+const EDITOR_BLENDER = 'volter.@volter/editor-blender';
+const EDITOR_THREEJS = 'volter.@volter/editor-threejs';
+
+/** The game run in the Game view's stage, once the edit Play saved first has saved (and exported). */
+const runGame: GameRunner = (stage) => {
+  const failed = (title: string, failure: string) => {
+    const run = beginPlayLog(STD_DEV);
+    run.append('play', 'script-error', { phase: 'stage', message: `${title}: ${failure}` });
+    run.end({ reason: 'stage-failed' });
+    setGameFailure(`${title}: ${failure}`);
+    stage.report(title, failure);
+  };
+  const saved = savedEdit().then((failure) => {
+    if (failure !== null) editorHost().console.warn(`Play's save failed, so the game plays its last export: ${failure}`, 'play');
+  });
+  // (asked now: a project add-play has just made a std game plays without a reload)
+  let stopped = false, stop: (() => void) | null = null;
+  void stdGameNow().then((std) => {
+    if (stopped) return;
+    if (std) stop = runStdGame(stage, failed, saved);
+    else failed('The game could not be started', NOT_STD);
+  });
+  return () => { stopped = true; stop?.(); };
+};
+
+export function activate(context: PluginContext) {
+  // Declared in `extensionDependencies`, so it is active before this runs.
+  const blender = context.extensions.getExtension<BlenderPageApi>(EDITOR_BLENDER)?.exports;
+  if (!blender) throw new Error(`${EDITOR_BLENDER} answered no API.`);
+  // (the edit Play saves first: the `.blend` Blender holds, whichever document is in front, and std's export of it)
+  keepEditSave(() => {
+    const held = blender.modelDocument.held();
+    return (held === null ? Promise.resolve() : blender.modelDocument.flush(held))
+      .then(() => stdLevelsSettled())
+      .then(() => null, (error: unknown) => error instanceof Error ? error.message : String(error));
+  });
+  const tool: PlayTool = {
+    Panel: GamePanel,
+    hasGame: () => isStdGame() ?? null,
+    subscribe(listener) {
+      const stopGame = subscribeGame(listener), stopProject = onProjectChange(listener), stopStd = subscribeStdGame(listener);
+      return () => { stopGame(); stopProject(); stopStd(); };
+    },
+  };
+  keepEditorBlender(blender);
+  // (a std level in code is drawn in editor-threejs's viewport, `std-level.document.tsx`; declared in `extensionDependencies`)
+  const three = context.extensions.getExtension<ThreePageApi>(EDITOR_THREEJS)?.exports;
+  if (!three) throw new Error(`${EDITOR_THREEJS} answered no API.`);
+  keepEditorThreejs(three);
+  const unregister = blender.registerPlay(tool);
+  // (the project's run: Play opens the Game view and runs the game there, whatever document is in front)
+  const stopGameRuns = keepGameRuns(runGame);
+  // A std game's levels exported on save, and its prefabs a linked asset library (`std-level.ts`).
+  const stopStdLevels = startStdLevels(blender);
+  // The session verbs and the Game panel's verbs, as the Code-OSS commands package.json declares.
+  registerVerbCommands(context, playVerbs);
+  registerViewCommands(context, 'play', PLAY_VIEW_VERBS);
+  context.subscriptions.push({
+    dispose() {
+      stopGameRuns();
+      unregister();
+      stopStdLevels();
+      keepEditSave(null);
+      keepEditorBlender(null);
+      keepEditorThreejs(null);
+    },
+  });
+}

package/contributions/play.verbs.ts

@@ -0,0 +1,74 @@
+/**
+ * THE PLAY VERBS of the session wire (`@volter/sdk/commands`): each the Code-OSS command `volter.<verb>`, registered by
+ * play's page half (`play.page.tsx`), with its budget on its `contributes.commands` entry.
+ *
+ * `play-log`, the read behind `cyclotron play-log` and `editor.contributedVerb('play-log')` in `eval`, answers the game's
+ * play log (`../src/play-log.ts`) — the current run's, or the last one's after Stop — filtered by `since` (game seconds,
+ * inclusive) and `kind`. A read only: no play gate, since an empty log is the honest answer when nothing has played.
+ *
+ * `play`, the agent's tool for Play (declared in this package's `contributes.languageModelTools`), runs the Game panel's
+ * own view verbs, the ones `volter.play.<action>` runs (`game-panel.tsx`), so an agent drives the run the person sees
+ * and answers with the game's state. Its `play` and `restart` answer as `cyclotron play play` does: once a player's page
+ * has joined the run, or with why the game didn't start (`started`), never at "playing" alone.
+ */
+import type { VerbHandler } from '@volter/sdk/commands';
+import { executeCommand } from '@volter/sdk/editor-commands';
+import { readPlayLog } from '../src/play-log';
+import { gameClock, gamePlaying, subscribeGame, subscribeGameClock } from '../src/game-run';
+
+const ACTIONS = ['state', 'play', 'stop', 'pause', 'resume', 'restart'] as const;
+
+/** The actions that start a run, which answer once it runs. */
+const STARTS: ReadonlySet<string> = new Set(['play', 'restart']);
+
+/**
+ * THE RUN STARTED, OR WHY NOT: resolved once a player's page has joined it (`GameClock.running`), rejected with the
+ * run's failure or with Play switched off first, as the CLI's `play` reads the run. No deadline of its own: the run
+ * starts on drawn frames, which a hidden tab doesn't draw, so a healthy start can take as long as the tab stays hidden;
+ * a relayed call (`eval`, the limited view) ends at `volter.play`'s budget, its `timeoutMs`.
+ */
+function started(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const stops: (() => void)[] = [];
+    const settle = (): void => {
+      const clock = gameClock();
+      const failure = clock.failure !== null && clock.failure !== '' ? clock.failure : null;
+      if (failure === null && gamePlaying() && !clock.running) return;
+      for (const stop of stops) stop();
+      if (failure !== null) reject(new Error(`Play did not start: ${failure}. The play log has the entry (play-log, kind script-error).`));
+      else if (!gamePlaying()) reject(new Error('Play switched itself off before a game started.'));
+      else resolve();
+    };
+    stops.push(subscribeGame(settle), subscribeGameClock(settle));
+    settle();
+  });
+}
+
+export const playVerbs: Readonly<Record<string, VerbHandler>> = {
+  play: async (command) => {
+    const action = command['action'];
+    if (typeof action !== 'string' || !(ACTIONS as readonly string[]).includes(action))
+      return { ok: false, error: `play's action is one of ${ACTIONS.join(', ')}; it was given ${JSON.stringify(action)}.` };
+    const answer = await executeCommand(`volter.play.${action}`, {});
+    if (!STARTS.has(action)) return { ok: true, data: { result: answer ?? null } };
+    try {
+      await started();
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    return { ok: true, data: { result: (await executeCommand('volter.play.state', {})) ?? null } };
+  },
+  'play-log': (command) => {
+    const since = command['since'];
+    const kind = command['kind'];
+    if (since !== undefined && (typeof since !== 'number' || !Number.isFinite(since)))
+      return { ok: false, error: `play-log's since is game seconds, a number; it was given ${JSON.stringify(since)}.` };
+    if (kind !== undefined && typeof kind !== 'string')
+      return { ok: false, error: `play-log's kind is an entry kind, a string; it was given ${JSON.stringify(kind)}.` };
+    const reading = readPlayLog({
+      ...(since === undefined ? {} : { since }),
+      ...(kind === undefined ? {} : { kind }),
+    });
+    return { ok: true, data: { ...reading } };
+  },
+};