@volter/game-editor 0.5.65

package/template/src/bot/bot-station.ts

@@ -0,0 +1,192 @@
+/**
+ * The bot run's ONE store — status, trace, seat, and the operator directive.
+ *
+ * The resident QA tester (`src/bot/tester-station.ts`) plays this game from
+ * INSIDE the page, directed live from the REPL through `hireTester`. This module
+ * holds what it is doing so the game's Tester surface and `vgai eval`
+ * both watch one run, and it implements the operator controls the tester
+ * honors between steps. This module is plain application state and imports no
+ * vgai API; its exports are the whole control surface.
+ *
+ * `getBotStatus()` reads `{active, seat, goal, step, phase, progress,
+ * waitingOn, note, seed, directive}`. `pauseBot()`, `resumeBot()`,
+ * `abortBot()`, and `handoffBot()` are the operator's controls. Abort and
+ * handoff also clear virtual input immediately, so a human taking the seat
+ * back never inherits a held key.
+ *
+ * Resource ownership: THIS MODULE owns bot run state; its ONE writer is the
+ * tester (in-process, through `reportTesterRun`). The operator commands own
+ * `directive` and the writer never overwrites it — except at a run BOUNDARY:
+ * a patch that sets `active` (start or end) resets the directive, so a run
+ * neither starts under nor hands on a stale stop. The terminal patch
+ * (`active: false`) is the one teardown path that clears the run.
+ *
+ * ── THE SEAT ────────────────────────────────────────────────────────────────
+ * `status.seat` is the CONTROLLER, and it has exactly ONE owner at a time —
+ * the tester, or you ({@link seatTester}, {@link releaseTester} — nobody
+ * else may reason about `seat`). `hireTester` while a run is active refuses
+ * (two hands on one controller); `bot.handoff` returns the seat to the
+ * human's keyboard mid-run.
+ *
+ * Cost when idle: none. No timers, no frame work — reads are pull-only.
+ */
+
+import { clearVirtualActions } from '../input';
+
+/** This module feeds the game's Tester surface and its operator controls. */
+/** What the operator has asked the running bot to do. This module is the
+ *  authority, because it is the side that VALIDATES. */
+export type BotDirective = 'run' | 'pause' | 'abort' | 'handoff';
+
+/** Who holds the controller — see this module's SEAT section. `null` while
+ *  nothing is driving. */
+export type BotSeat = 'tester' | null;
+
+export interface BotStatus {
+  readonly active: boolean;
+  /** The controller's one owner right now. */
+  readonly seat: BotSeat;
+  /** The game-side tester's run: which behavior from its repertoire. */
+  readonly goal: string | null;
+  readonly step: string | null;
+  readonly phase: string | null;
+  /** Steps completed so far in this run. */
+  readonly progress: number;
+  /** What the tester is currently waiting on, when it is waiting. */
+  readonly waitingOn: string | null;
+  /** The tester's own live line — what it is doing, or why it stopped. */
+  readonly note: string | null;
+  readonly seed: number | null;
+  readonly directive: BotDirective;
+}
+
+const IDLE: BotStatus = {
+  active: false,
+  seat: null,
+  goal: null,
+  step: null,
+  phase: null,
+  progress: 0,
+  waitingOn: null,
+  note: null,
+  seed: null,
+  directive: 'run',
+};
+
+/** One patch, from either writer. Every field is optional: absent means
+ *  unchanged. The wire schema above is the DRIVER's half of this shape. */
+export interface BotPatch {
+  seat?: BotSeat | undefined;
+  goal?: string | null | undefined;
+  step?: string | null | undefined;
+  phase?: string | null | undefined;
+  progress?: number | undefined;
+  waitingOn?: string | null | undefined;
+  note?: string | null | undefined;
+  active?: boolean | undefined;
+  seed?: number | undefined;
+}
+
+let status: BotStatus = IDLE;
+
+/** A field an absent patch leaves alone. */
+function kept<T>(next: T | undefined, current: T): T {
+  return next === undefined ? current : next;
+}
+
+/** A field that also RESETS at a run boundary. Both writers omit each other's
+ *  fields, so without this a new run would wear the last one's identity. */
+function scoped<T>(next: T | undefined, current: T, boundary: boolean, empty: T): T {
+  if (next !== undefined) return next;
+  return boundary ? empty : current;
+}
+
+function applyPatch(patch: BotPatch): BotStatus {
+  // A run's own start and end are the only moments the operator's directive is
+  // reset — otherwise an abort would silently carry into the next run.
+  const boundary = patch.active !== undefined;
+  status = {
+    active: kept(patch.active, status.active),
+    // The tester names its seat on start; a run that ENDS empties the seat.
+    seat: patch.seat !== undefined ? patch.seat : boundary && !patch.active ? null : status.seat,
+    goal: scoped(patch.goal, status.goal, boundary, null),
+    step: kept(patch.step, status.step),
+    phase: kept(patch.phase, status.phase),
+    progress: scoped(patch.progress, status.progress, boundary, 0),
+    waitingOn: kept(patch.waitingOn, status.waitingOn),
+    note: scoped(patch.note, status.note, boundary, null),
+    seed: scoped(patch.seed, status.seed, boundary, null),
+    directive: boundary ? 'run' : status.directive,
+  };
+  return status;
+}
+
+/**
+ * The GAME-SIDE writer's door: the resident QA tester
+ * (`src/bot/tester-station.ts`) runs in this page, not over the wire, so it
+ * patches the store directly. Same store, same boundary rules — see the
+ * ownership note.
+ */
+export function reportTesterRun(patch: BotPatch): BotStatus {
+  return applyPatch(patch);
+}
+
+/** Seat the tester for one goal — it starts the run and owns it. */
+export function seatTester(goal: string): BotStatus {
+  return applyPatch({
+    goal,
+    step: null,
+    phase: 'drive',
+    note: null,
+    active: true,
+    seat: 'tester',
+    progress: 0,
+  });
+}
+
+/** The ONE teardown path for a tester run: ends it and empties the seat. */
+export function releaseTester(note: string | null): BotStatus {
+  return applyPatch({ goal: null, step: null, phase: null, note, active: false, seat: null });
+}
+
+export function getBotStatus(): BotStatus {
+  return status;
+}
+
+function setDirective(directive: BotDirective): BotStatus {
+  status = { ...status, directive };
+  return status;
+}
+
+function requireActiveRun(verb: string): void {
+  if (!status.active) {
+    throw new Error(`${verb}: no bot run is active — nothing is holding the controller.`);
+  }
+}
+
+/** Pause the running bot at its next gate — a step boundary or a wait poll. */
+export function pauseBot(): BotStatus {
+  requireActiveRun('bot.pause');
+  return setDirective('pause');
+}
+
+/** Resume a paused bot. */
+export function resumeBot(): BotStatus {
+  requireActiveRun('bot.resume');
+  return setDirective('run');
+}
+
+/** Stop the running bot and release its virtual input. */
+export function abortBot(): BotStatus {
+  requireActiveRun('bot.abort');
+  clearVirtualActions();
+  return setDirective('abort');
+}
+
+/** Stop the bot and give the seat back to the human immediately — the
+ *  keyboard has to be free the moment a person asks for it. */
+export function handoffBot(): BotStatus {
+  requireActiveRun('bot.handoff');
+  clearVirtualActions();
+  return setDirective('handoff');
+}

package/template/src/bot/tester-run.ts

@@ -0,0 +1,238 @@
+/**
+ * ONE tester run: a goal, the hands it plays with, and the per-tick stepping
+ * that honors the operator's directive.
+ *
+ * Kept out of the React component on purpose — this is the part with rules
+ * (the tester only ever writes virtual input; pause takes its hands off the
+ * controller; abort/handoff end the run), and rules deserve to be provable
+ * without a browser. `src/bot/QaTester.tsx` is the thin half: hooks, the frame
+ * callback, and the bridge store.
+ *
+ * Resource ownership: a run owns the virtual actions IT set, and nothing else.
+ * It records every actuation it makes so it can let go of exactly those on
+ * pause, on abort, and at the end — which is what makes `bot.handoff` hand a
+ * clean keyboard to the human. The engine's `clearVirtualActions()` (the
+ * bridge's own abort path) is the bigger hammer; a run never needs it.
+ */
+
+import type { TesterBehavior, TesterHands, TesterOutcome, TesterTick } from './behaviors';
+
+/** What the operator has asked the running bot to do — the union
+ *  `src/bot/bot-station.ts` validates and owns. */
+export type TesterDirective = 'run' | 'pause' | 'abort' | 'handoff';
+
+/** How a run ended. The behavior's own `done`/`failed`, plus `stopped` for the
+ *  operator ending it — a stopped run is not a failed game. */
+export type TesterRunStatus = 'running' | 'done' | 'failed' | 'stopped';
+
+/**
+ * The three `InputManager` methods the tester's hands need — the game's REAL
+ * input store satisfies this structurally, and a disposable REPL probe may
+ * pass a recorder. Typed narrowly here so this module never imports the engine, and
+ * so the surface a tester can reach is visible in one glance: virtual input,
+ * and nothing else.
+ */
+export interface TesterInputTarget {
+  actionNames(): string[];
+  setVirtualAction(
+    action: string,
+    value: boolean | number | { x: number; y: number },
+  ): { delivered: boolean; reason?: string };
+  tapVirtualAction(action: string): { delivered: boolean; reason?: string };
+}
+
+export interface TesterRunPatch {
+  readonly step?: string;
+  readonly progress?: number;
+  readonly note?: string;
+}
+
+export interface TesterRunOptions {
+  /** The behavior name from this game's repertoire, for reporting. */
+  readonly goal: string;
+  readonly behavior: TesterBehavior;
+  /** Already parsed against `behavior.params` by the caller. */
+  readonly params: unknown;
+  readonly input: TesterInputTarget;
+  /** Read fresh every tick, so pause/abort bite on the next tick. */
+  readonly directive: () => TesterDirective;
+  readonly report: (patch: TesterRunPatch) => void;
+}
+
+/** The "let go" value for whatever shape was last written. */
+function releasedValue(
+  value: boolean | number | { x: number; y: number },
+): boolean | number | { x: number; y: number } {
+  if (typeof value === 'boolean') return false;
+  if (typeof value === 'number') return 0;
+  return { x: 0, y: 0 };
+}
+
+class Hands implements TesterHands {
+  readonly #input: TesterInputTarget;
+  /** Every action this run is currently actuating, with its last value — the
+   *  ledger `release`/`suspend`/`resume` work from. */
+  readonly #held = new Map<string, boolean | number | { x: number; y: number }>();
+  #undelivered: string | null = null;
+
+  constructor(input: TesterInputTarget) {
+    this.#input = input;
+  }
+
+  actions(): readonly string[] {
+    return this.#input.actionNames();
+  }
+
+  set(action: string, value: boolean | number | { x: number; y: number }): void {
+    this.#note(this.#input.setVirtualAction(action, value));
+    this.#held.set(action, value);
+  }
+
+  tap(action: string): void {
+    this.#note(this.#input.tapVirtualAction(action));
+  }
+
+  release(): void {
+    this.#letGo();
+    this.#held.clear();
+  }
+
+  /** Pause: hands off the controller, ledger kept so `resume` can take it
+   *  back exactly as it was. */
+  suspend(): void {
+    this.#letGo();
+  }
+
+  resume(): void {
+    for (const [action, value] of this.#held) {
+      this.#note(this.#input.setVirtualAction(action, value));
+    }
+  }
+
+  /** The last actuation the engine refused (input gated), consumed by the
+   *  reader. A swallowed actuation must never look like a delivered one. */
+  takeUndelivered(): string | null {
+    const reason = this.#undelivered;
+    this.#undelivered = null;
+    return reason;
+  }
+
+  #letGo(): void {
+    for (const [action, value] of this.#held) {
+      this.#input.setVirtualAction(action, releasedValue(value));
+    }
+  }
+
+  #note(result: { delivered: boolean; reason?: string }): void {
+    if (!result.delivered) this.#undelivered = result.reason ?? 'actuation not delivered';
+  }
+}
+
+export class TesterRun {
+  readonly goal: string;
+  readonly #options: TesterRunOptions;
+  readonly #hands: Hands;
+  readonly #step: (tick: TesterTick) => TesterOutcome;
+  #status: TesterRunStatus = 'running';
+  #note: string | null = null;
+  #elapsed = 0;
+  #suspended = false;
+
+  constructor(options: TesterRunOptions) {
+    this.goal = options.goal;
+    this.#options = options;
+    this.#hands = new Hands(options.input);
+    this.#step = options.behavior.create(
+      {
+        hands: this.#hands,
+        report: (patch) => {
+          if (patch.note !== undefined) this.#note = patch.note;
+          options.report(patch);
+        },
+      },
+      options.params,
+    );
+  }
+
+  /** Sim seconds this run has been playing. */
+  get elapsed(): number {
+    return this.#elapsed;
+  }
+
+  /** The last thing the run said about itself — the terminal one is why it
+   *  ended. */
+  get note(): string | null {
+    return this.#note;
+  }
+
+  get status(): TesterRunStatus {
+    return this.#status;
+  }
+
+  /**
+   * Advance the run by one sim tick. Returns the run's status: anything but
+   * `running` means it is over and the caller should retire it.
+   */
+  step(dt: number): TesterRunStatus {
+    if (this.#status !== 'running') return this.#status;
+
+    const directive = this.#options.directive();
+    if (directive === 'abort' || directive === 'handoff') {
+      // The bridge's own command already released virtual input for the
+      // human; this drops the run's ledger so nothing can re-assert it.
+      this.#hands.release();
+      return this.#end('stopped', `stopped by bot.${directive}`);
+    }
+
+    if (directive === 'pause') {
+      if (!this.#suspended) {
+        this.#suspended = true;
+        this.#hands.suspend();
+        this.#report('paused — hands off the controller');
+      }
+      // Paused holds POSITION: the behavior is not stepped and no sim budget
+      // is charged against it, so resuming continues the same play.
+      return 'running';
+    }
+
+    if (this.#suspended) {
+      this.#suspended = false;
+      this.#hands.resume();
+      this.#report('resumed');
+    }
+
+    this.#elapsed += dt;
+
+    let outcome: TesterOutcome;
+    try {
+      outcome = this.#step({ dt, elapsed: this.#elapsed });
+    } catch (error) {
+      this.#hands.release();
+      return this.#end('failed', String(error));
+    }
+
+    const undelivered = this.#hands.takeUndelivered();
+    if (undelivered !== null) this.#report(`input not delivered — ${undelivered}`);
+
+    if (outcome === 'running') return 'running';
+    this.#hands.release();
+    return this.#end(outcome, this.#note ?? `behavior reported ${outcome}`);
+  }
+
+  #report(note: string): void {
+    this.#note = note;
+    this.#options.report({ note });
+  }
+
+  #end(status: TesterRunStatus, note: string): TesterRunStatus {
+    this.#status = status;
+    this.#note = note;
+    return status;
+  }
+}
+
+/** Start a goal. The behavior is created here, so anything it wants to read at
+ *  start (the declared action list, game state) is read before the first tick. */
+export function startTesterRun(options: TesterRunOptions): TesterRun {
+  return new TesterRun(options);
+}

package/template/src/bot/tester-station.ts

@@ -0,0 +1,193 @@
+/**
+ * The resident QA TESTER's run state and doors — the half of the live
+ * playtesting loop that actually plays the game.
+ *
+ * Two people build this game: the DEVELOPER (a coding agent at the REPL) and
+ * the TESTER. The developer arranges the situation with the game's own setup
+ * verbs and tunables, then says WHAT TO TEST in intent terms —
+ * `hireTester('sweep')` on this running module — and watches. The tester holds the
+ * controller from here on: it steps its goal once per sim tick
+ * (`src/bot/QaTester.tsx`'s frame hook calls {@link stepTester}), acting ONLY
+ * through this game's own input store, at the game's own timescale. A
+ * developer at conversation pace cannot honestly play a realtime game, which
+ * is exactly why the tester exists.
+ *
+ * Exported surface:
+ * - {@link hireTester} starts a named goal and is always callable;
+ * - {@link describeTester} returns the repertoire and the last run's outcome.
+ * The outcome lives here rather than in the run-scoped status because that
+ * status resets at exactly the moment the outcome exists.
+ *
+ * The SEAT — who may hold the controller — is `bot-station.ts`'s to define
+ * and enforce. This module takes
+ * (`seatTester`) and gives it back (`releaseTester`); it never reasons about
+ * the rule itself.
+ *
+ * No vgai import anywhere: the tester's hands are the project's own input
+ * store (`src/input.ts`), typed through `tester-run.ts`'s narrow
+ * `TesterInputTarget`.
+ */
+
+import { clearVirtualActions, gameActions, setVirtualAction } from '../input';
+import { describeTesterBehaviors, resolveTesterBehavior } from './behaviors';
+import { getBotStatus, releaseTester, reportTesterRun, seatTester } from './bot-station';
+import {
+  startTesterRun,
+  type TesterInputTarget,
+  type TesterRun,
+  type TesterRunStatus,
+} from './tester-run';
+
+/** How a finished job is remembered for the developer's next poll. */
+interface TesterJobRecord {
+  readonly goal: string;
+  readonly outcome: TesterRunStatus;
+  readonly note: string | null;
+  readonly simSeconds: number;
+}
+
+let currentRun: TesterRun | null = null;
+let lastJob: TesterJobRecord | null = null;
+const pendingTapReleases = new Set<string>();
+
+/** The tester's hands, over this game's OWN input store. `tap` is a set that
+ *  the behavior itself releases — the store keeps no tick scheduler the
+ *  neutral scaffold has no reader for. */
+const hands: TesterInputTarget = {
+  actionNames: () => [...gameActions],
+  setVirtualAction(action, value) {
+    try {
+      setVirtualAction(action, value);
+      return { delivered: true };
+    } catch (error) {
+      return { delivered: false, reason: String(error) };
+    }
+  },
+  tapVirtualAction(action) {
+    try {
+      setVirtualAction(action, true);
+      pendingTapReleases.add(action);
+      return { delivered: true };
+    } catch (error) {
+      return { delivered: false, reason: String(error) };
+    }
+  },
+};
+
+/** Release taps from the previous tick before the next behavior step. A tap
+ * therefore stays asserted while every later gameplay callback reads this
+ * frame, instead of becoming an invisible true→false write in one call. */
+function releasePendingTaps(): void {
+  for (const action of pendingTapReleases) setVirtualAction(action, false);
+  pendingTapReleases.clear();
+}
+
+/** The `paramsJson` argument, as typed at a REPL or into the Dev tab's field. */
+function parseGoalParams(raw: string | undefined): unknown {
+  if (raw === undefined || raw.trim() === '') return {};
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `hireTester: params are not valid JSON (${String(error)}). Pass an object literal, ` +
+        'e.g. \'{"holdSimSeconds": 1.5}\'.',
+    );
+  }
+}
+
+/** The Tester contribution and live REPL's discovery/readout body. */
+export function describeTester(): {
+  behaviors: ReturnType<typeof describeTesterBehaviors>;
+  running: string | null;
+  last: TesterJobRecord | null;
+} {
+  return {
+    behaviors: describeTesterBehaviors(),
+    running: currentRun?.goal ?? null,
+    last: lastJob,
+  };
+}
+
+/** Hire the tester for one goal. */
+export function hireTester(name: string, paramsJson?: string): { goal: string; summary: string } {
+  if (currentRun !== null) {
+    throw new Error(
+      `hireTester: the tester is already playing "${currentRun.goal}". ` +
+        'Let it finish, or call `abortBot()` first.',
+    );
+  }
+  const behavior = resolveTesterBehavior(name);
+  const params = behavior.params
+    ? behavior.params.parse(parseGoalParams(paramsJson))
+    : parseGoalParams(paramsJson);
+
+  // Takes the seat, starting a run of its own. `drive` is the honest phase
+  // tag: everything a tester does is player input. A `setup` cheat is the
+  // developer's move, never the tester's.
+  seatTester(name);
+  try {
+    currentRun = startTesterRun({
+      goal: name,
+      behavior,
+      params,
+      input: hands,
+      directive: () => getBotStatus().directive,
+      report: (patch) => reportTesterRun(patch),
+    });
+  } catch (error) {
+    // `create()` is game code and may throw (it reads game state at start).
+    // The seating above is already published, so give the seat back —
+    // otherwise it strands with no run behind it and the guard refuses every
+    // future `hireTester` call.
+    lastJob = { goal: name, outcome: 'failed', note: String(error), simSeconds: 0 };
+    releaseTester(String(error));
+    throw error;
+  }
+  return { goal: name, summary: behavior.summary };
+}
+
+/** One sim tick of the tester's hands — called by `QaTester.tsx`'s frame hook,
+ *  which runs before every game-logic hook so a virtual action is already
+ *  written when the first mechanic reads it. */
+export function stepTester(dt: number): void {
+  // Paused redraws must not consume a waypoint or release a pending tap.
+  if (dt <= 0) return;
+  releasePendingTaps();
+  const run = currentRun;
+  if (run === null) return;
+  const status = run.step(dt);
+  if (status === 'running') return;
+
+  currentRun = null;
+  lastJob = {
+    goal: run.goal,
+    outcome: status,
+    note: run.note,
+    simSeconds: Number(run.elapsed.toFixed(3)),
+  };
+  // The terminal patch: gives the seat back — to the human, or
+  // to nobody, ending the run this tester started.
+  releaseTester(run.note);
+}
+
+/**
+ * The world is unmounting (Play stopped): a run cannot outlive the frame that
+ * steps it. Ends the current run as `stopped`, releases the seat, and leaves
+ * the outcome on `last` — module state must never strand a dead run into the
+ * NEXT session, where `hireTester` would refuse every goal for a run nothing
+ * is stepping. `QaTester.tsx`'s unmount cleanup is the one caller.
+ */
+export function stopTesterForUnmount(): void {
+  releasePendingTaps();
+  clearVirtualActions();
+  const run = currentRun;
+  if (run === null) return;
+  currentRun = null;
+  lastJob = {
+    goal: run.goal,
+    outcome: 'stopped',
+    note: 'the world unmounted mid-run',
+    simSeconds: Number(run.elapsed.toFixed(3)),
+  };
+  releaseTester('the world unmounted mid-run');
+}

package/template/src/components/environment/DaylightSky.tsx

@@ -0,0 +1,54 @@
+import type { ThreeElements } from '@react-three/fiber';
+import { useEffect, useMemo, useState } from 'react';
+import * as THREE from 'three';
+
+interface DaylightShaderPair {
+  readonly vertex: string;
+  readonly fragment: string;
+}
+
+async function readShader(path: string, signal: AbortSignal): Promise<string> {
+  const response = await fetch(path, { signal });
+  if (!response.ok) throw new Error(`DaylightSky could not load ${path}: HTTP ${response.status}`);
+  return response.text();
+}
+
+/** Procedural daylight sky supporting the starter scene. */
+export function DaylightSky({ name = 'Daylight Sky', ...props }: ThreeElements['mesh']) {
+  const [shaders, setShaders] = useState<DaylightShaderPair | null>(null);
+  const uniforms = useMemo(
+    () => ({
+      uHorizonColor: { value: new THREE.Color('#badbe9') },
+      uZenithColor: { value: new THREE.Color('#297aba') },
+      uSunColor: { value: new THREE.Color('#fff0c2') },
+    }),
+    [],
+  );
+  useEffect(() => {
+    const controller = new AbortController();
+    void Promise.all([
+      readShader('/shaders/daylight-sky.vert.glsl', controller.signal),
+      readShader('/shaders/daylight-sky.frag.glsl', controller.signal),
+    ]).then(
+      ([vertex, fragment]) => setShaders({ vertex, fragment }),
+      (cause) => {
+        // biome-ignore lint/suspicious/noConsole: failed project assets must surface in the editor console.
+        if (!controller.signal.aborted) console.error(cause);
+      },
+    );
+    return () => controller.abort();
+  }, []);
+  if (!shaders) return null;
+  return (
+    <mesh name={name} scale={150} {...props}>
+      <sphereGeometry args={[1, 64, 32]} />
+      <shaderMaterial
+        side={THREE.BackSide}
+        depthWrite={false}
+        uniforms={uniforms}
+        vertexShader={shaders.vertex}
+        fragmentShader={shaders.fragment}
+      />
+    </mesh>
+  );
+}