@pix3/cli 1.6.0

package/templates/recipe-grid-3d/files/scripts/GridBoard.ts

@@ -0,0 +1,319 @@
+/**
+ * GridBoard — the block you carve.
+ *
+ * Builds a solid `sizeX × sizeY × sizeZ` grid of cubes under `boardAnchor` at start, then turns a
+ * tap into the removal of one cube. Some cubes are secretly CORE: hitting one costs a life instead
+ * of scoring. Clear every non-core cube to finish the board.
+ *
+ * It emits the semantic signals the rules script listens for, on `game-root`:
+ *   `cell-cleared`  (remaining)
+ *   `core-hit`      (remaining)
+ *   `board-cleared` ()
+ *
+ * **Picking is a 3D raycast, not a 2D hit test.** 2D nodes are hit-tested against `Hitbox2D`
+ * groups; a mesh in a perspective frustum has no such thing, so the contact comes from
+ * `scene.raycastViewport(nx, ny)` with the pointer converted to normalized device coordinates. That
+ * conversion is the part everyone gets wrong — Y is flipped, and the divisor is the INPUT surface
+ * (`input.width/height`), not the window.
+ *
+ * **Mobile budget.** Every cube is a `GeometryMesh` with `material.type: 'lambert'`: this recipe
+ * ships hundreds of them, and PBR on a phone at this count is the difference between a smooth board
+ * and a slideshow. A 4×4×4 board is 64 draw calls — if you grow it past ~8³, move to an
+ * `InstancedMesh3D` before you move to prettier materials.
+ */
+import { GeometryMesh, Script, type NodeBase, type PropertySchema } from '@pix3/runtime';
+
+/** Cube metadata, kept in a map rather than on the node so nothing depends on node naming. */
+interface Cell {
+  node: GeometryMesh;
+  isCore: boolean;
+}
+
+export class GridBoard extends Script {
+  private cells = new Map<string, Cell>();
+  private remaining = 0;
+  private cleared = false;
+
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      // Node the cubes are parented to (kept separate from game-root so clearing is one subtree).
+      boardAnchor: 'board-anchor',
+      sizeX: 4,
+      sizeY: 4,
+      sizeZ: 4,
+      cellSize: 0.9,
+      // Centre-to-centre spacing; > cellSize leaves visible seams between cubes.
+      spacing: 1,
+      // How many cubes are core (a life each). Never more than a third of the board.
+      coreCount: 6,
+      cellColor: '#3ee6c1',
+      coreColor: '#ff6b6b',
+      // Reveal core cubes in their own colour instead of hiding them (debug / tutorial).
+      revealCores: false,
+      clearSound: '',
+      coreSound: '',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    const num = (name: string, label: string, min: number, max: number, step: number) => ({
+      name,
+      type: 'number' as const,
+      ui: { label, group: 'Board', min, max, step, slider: true },
+      getValue: (s: unknown) => (s as GridBoard).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        const n = Number(v);
+        (s as GridBoard).config[name] = Math.min(max, Math.max(min, Number.isFinite(n) ? n : min));
+      },
+    });
+    const str = (name: string, label: string, group: string, editor?: 'audio-resource') => ({
+      name,
+      type: 'string' as const,
+      ui: { label, group, ...(editor ? { editor } : {}) },
+      getValue: (s: unknown) => (s as GridBoard).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        (s as GridBoard).config[name] = typeof v === 'string' ? v : '';
+      },
+    });
+    const color = (name: string, label: string) => ({
+      name,
+      type: 'color' as const,
+      ui: { label, group: 'Look' },
+      getValue: (s: unknown) => (s as GridBoard).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        (s as GridBoard).config[name] = typeof v === 'string' ? v : '#ffffff';
+      },
+    });
+
+    return {
+      nodeType: 'GridBoard',
+      properties: [
+        str('boardAnchor', 'Board Anchor', 'Board'),
+        num('sizeX', 'Size X', 1, 10, 1),
+        num('sizeY', 'Size Y', 1, 10, 1),
+        num('sizeZ', 'Size Z', 1, 10, 1),
+        num('cellSize', 'Cell Size', 0.1, 3, 0.05),
+        num('spacing', 'Spacing', 0.1, 4, 0.05),
+        num('coreCount', 'Core Cubes', 0, 40, 1),
+        color('cellColor', 'Cell Colour'),
+        color('coreColor', 'Core Colour'),
+        {
+          name: 'revealCores',
+          type: 'boolean' as const,
+          ui: { label: 'Reveal Cores', group: 'Look' },
+          getValue: (s: unknown) => (s as GridBoard).config.revealCores,
+          setValue: (s: unknown, v: unknown) => {
+            (s as GridBoard).config.revealCores = Boolean(v);
+          },
+        },
+        str('clearSound', 'Clear Sound', 'Feedback', 'audio-resource'),
+        str('coreSound', 'Core Sound', 'Feedback', 'audio-resource'),
+      ],
+      groups: {
+        Board: { label: 'Board', expanded: true },
+        Look: { label: 'Look', expanded: true },
+        Feedback: { label: 'Feedback', expanded: false },
+      },
+    };
+  }
+
+  onStart(): void {
+    this.build();
+  }
+
+  /**
+   * One removal per finger that landed this frame.
+   *
+   * Taps over the HUD are ignored the same way every recipe does it, so a thumb parked on a button
+   * cannot carve the board underneath it.
+   */
+  onUpdate(): void {
+    const input = this.input;
+    if (this.cleared || !input || !this.scene) {
+      return;
+    }
+    for (const event of input.pointerEvents) {
+      if (event.type !== 'down') {
+        continue;
+      }
+      const overUI =
+        input.pointerDownCount > 0 ? input.isPointerOverUI(event.pointerId) : input.isHoveringUI;
+      if (overUI) {
+        continue;
+      }
+      this.resolveTap(event.x, event.y);
+    }
+  }
+
+  /** Live board state, for the rules script and for tests. */
+  getRemaining(): number {
+    return this.remaining;
+  }
+
+  private build(): void {
+    const anchor = this.findAnchor();
+    if (!anchor) {
+      console.warn('[GridBoard] No board anchor node — nothing was built.');
+      return;
+    }
+    const sizeX = this.intConfig('sizeX', 1, 10);
+    const sizeY = this.intConfig('sizeY', 1, 10);
+    const sizeZ = this.intConfig('sizeZ', 1, 10);
+    const cellSize = Math.max(0.1, Number(this.config.cellSize) || 0.9);
+    const spacing = Math.max(cellSize, Number(this.config.spacing) || 1);
+    const total = sizeX * sizeY * sizeZ;
+    // A board that is mostly core is not a puzzle, it is a minefield.
+    const coreCount = Math.min(this.intConfig('coreCount', 0, 40), Math.floor(total / 3));
+    const coreKeys = this.pickCoreKeys(sizeX, sizeY, sizeZ, coreCount);
+    const reveal = Boolean(this.config.revealCores);
+    const cellColor = String(this.config.cellColor ?? '#3ee6c1');
+    const coreColor = String(this.config.coreColor ?? '#ff6b6b');
+
+    // Centre the board on the anchor so the camera framing survives a size change.
+    const offset = (n: number) => ((n - 1) * spacing) / 2;
+
+    for (let x = 0; x < sizeX; x++) {
+      for (let y = 0; y < sizeY; y++) {
+        for (let z = 0; z < sizeZ; z++) {
+          const key = `${x},${y},${z}`;
+          const isCore = coreKeys.has(key);
+          const cube = new GeometryMesh({
+            id: `cell-${key}`,
+            name: `Cell ${key}`,
+            geometry: 'box',
+            size: [cellSize, cellSize, cellSize],
+            material: {
+              type: 'lambert',
+              color: isCore && reveal ? coreColor : cellColor,
+            },
+          });
+          cube.position.set(
+            x * spacing - offset(sizeX),
+            y * spacing - offset(sizeY),
+            z * spacing - offset(sizeZ)
+          );
+          anchor.add(cube);
+          this.cells.set(key, { node: cube, isCore });
+        }
+      }
+    }
+    this.remaining = total - coreCount;
+    this.node?.emit('board-built', this.remaining, coreCount);
+  }
+
+  /**
+   * Resolve one contact against the board.
+   *
+   * The hit object is a three.js `Mesh` inside the cube node, so walk up to the `GeometryMesh` the
+   * cell map is keyed by — the raycaster reports what it struck, not what owns it.
+   */
+  private resolveTap(screenX: number, screenY: number): void {
+    const scene = this.scene;
+    const input = this.input;
+    if (!scene || !input) {
+      return;
+    }
+    const width = input.width;
+    const height = input.height;
+    if (!(width > 0) || !(height > 0)) {
+      return;
+    }
+    const hit = scene.raycastViewport((screenX / width) * 2 - 1, 1 - (screenY / height) * 2);
+    if (!hit) {
+      return;
+    }
+    const entry = this.findCell(hit.node);
+    if (!entry) {
+      return;
+    }
+    this.removeCell(entry[0], entry[1]);
+  }
+
+  private removeCell(key: string, cell: Cell): void {
+    this.cells.delete(key);
+    const owner = this.node;
+    if (cell.isCore) {
+      this.scene?.juice.flash({ color: '#ff4d6d', intensity: 0.45, durationSec: 0.22 });
+      this.playSound(String(this.config.coreSound ?? ''));
+      cell.node.queueFree();
+      owner?.emit('core-hit', this.remaining);
+      return;
+    }
+    this.remaining = Math.max(0, this.remaining - 1);
+    this.scene?.juice.punchScale(cell.node, { amount: 0.35, duration: 0.16 });
+    this.playSound(String(this.config.clearSound ?? ''));
+    cell.node.queueFree();
+    owner?.emit('cell-cleared', this.remaining);
+    if (this.remaining === 0 && !this.cleared) {
+      this.cleared = true;
+      owner?.emit('board-cleared');
+    }
+  }
+
+  /** Walk from the raycast hit up to the cube node this board owns. */
+  private findCell(hitNode: NodeBase): [string, Cell] | null {
+    let current: NodeBase | null = hitNode;
+    while (current) {
+      for (const [key, cell] of this.cells) {
+        if (cell.node === current) {
+          return [key, cell];
+        }
+      }
+      current = (current.parent as NodeBase | null) ?? null;
+    }
+    return null;
+  }
+
+  private findAnchor(): NodeBase | null {
+    const name = String(this.config.boardAnchor ?? '').trim();
+    if (!name) {
+      return this.node ?? null;
+    }
+    // `findNode` is the Script helper (scene-global by name/id), the same one Spawner uses.
+    return this.findNode(name) ?? this.node ?? null;
+  }
+
+  /**
+   * Choose which cubes are core.
+   *
+   * Cores are drawn from the INTERIOR when the board has one: a core on the surface can be tapped
+   * before the player has learned anything, which reads as an unfair loss rather than a puzzle.
+   * Small boards have no interior, so they fall back to the whole set.
+   */
+  private pickCoreKeys(sizeX: number, sizeY: number, sizeZ: number, count: number): Set<string> {
+    const interior: string[] = [];
+    const all: string[] = [];
+    for (let x = 0; x < sizeX; x++) {
+      for (let y = 0; y < sizeY; y++) {
+        for (let z = 0; z < sizeZ; z++) {
+          const key = `${x},${y},${z}`;
+          all.push(key);
+          const inner =
+            x > 0 && x < sizeX - 1 && y > 0 && y < sizeY - 1 && z > 0 && z < sizeZ - 1;
+          if (inner) {
+            interior.push(key);
+          }
+        }
+      }
+    }
+    const pool = interior.length >= count ? interior : all;
+    const chosen = new Set<string>();
+    while (chosen.size < count && chosen.size < pool.length) {
+      chosen.add(pool[Math.floor(Math.random() * pool.length)]);
+    }
+    return chosen;
+  }
+
+  private intConfig(name: string, min: number, max: number): number {
+    const value = Math.round(Number(this.config[name]));
+    return Math.min(max, Math.max(min, Number.isFinite(value) ? value : min));
+  }
+
+  private playSound(path: string): void {
+    if (!path) {
+      return;
+    }
+    void this.scene?.audio.play(path, { bus: 'sfx', pitchVariation: 0.08 });
+  }
+}

package/templates/recipe-grid-3d/files/scripts/GridRules.ts

@@ -0,0 +1,278 @@
+/**
+ * GridRules — score, lives and the end of the run for a carving board.
+ *
+ * Same shape as the other recipes' `GameRules`, with the win condition the board dictates: you win
+ * by clearing every non-core cube (`board-cleared`), you lose by running out of lives. The optional
+ * clock is a deadline, not a mode of its own.
+ *
+ * Listens on its own node (`game-root`) for what `GridBoard` emits:
+ *   `cell-cleared`  (remaining) → +1 score
+ *   `core-hit`      (remaining) → −1 life
+ *   `board-cleared` ()          → win
+ *   `board-built`   (clearable, cores) → the target for the HUD
+ *
+ * The end-screen buttons dispatch the commands `restart` and `return-to-menu` (`scene.commands`)
+ * rather than calling methods, so a test can replay the end flow without hunting for buttons.
+ *
+ * It publishes the run through `registerGameDebug`: `remaining` is the number that matters here —
+ * an agent proving "the tap removed a cube" reads it instead of comparing screenshots.
+ */
+import { Button2D, Label2D, Script, registerGameDebug, type PropertySchema } from '@pix3/runtime';
+
+function roundHundredths(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+export class GridRules extends Script {
+  private score = 0;
+  private lives = 3;
+  private remaining = 0;
+  private clearable = 0;
+  private elapsed = 0;
+  private over = false;
+  private won = false;
+  private disposeDebug: (() => void) | null = null;
+  private disposeCommands: (() => void)[] = [];
+
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      startingLives: 3,
+      // 0 = no clock. With a limit, running it out loses.
+      timeLimitSec: 0,
+      resultNode: 'result-overlay',
+      resultLabel: 'result-label',
+      retryButton: 'retry-button',
+      menuButton: 'menu-button',
+      winText: 'SHAPE REVEALED',
+      loseText: 'CORE DESTROYED',
+      gameScene: 'res://scenes/main.pix3scene',
+      menuScene: 'res://scenes/menu.pix3scene',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    const num = (name: string, label: string, min: number, max: number) => ({
+      name,
+      type: 'number' as const,
+      ui: { label, group: 'Rules', min, max, step: 1, slider: true },
+      getValue: (s: unknown) => (s as GridRules).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        const n = Number(v);
+        (s as GridRules).config[name] = Math.min(max, Math.max(min, Number.isFinite(n) ? n : min));
+      },
+    });
+    const str = (name: string, label: string, group: string) => ({
+      name,
+      type: 'string' as const,
+      ui: { label, group },
+      getValue: (s: unknown) => (s as GridRules).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        (s as GridRules).config[name] = typeof v === 'string' ? v : '';
+      },
+    });
+
+    return {
+      nodeType: 'GridRules',
+      properties: [
+        num('startingLives', 'Starting Lives', 1, 9),
+        num('timeLimitSec', 'Time Limit (s)', 0, 600),
+        str('resultNode', 'Result Overlay', 'End'),
+        str('resultLabel', 'Result Label', 'End'),
+        str('retryButton', 'Retry Button', 'End'),
+        str('menuButton', 'Menu Button', 'End'),
+        str('winText', 'Win Text', 'End'),
+        str('loseText', 'Lose Text', 'End'),
+        str('gameScene', 'Game Scene', 'Scenes'),
+        str('menuScene', 'Menu Scene', 'Scenes'),
+      ],
+      groups: {
+        Rules: { label: 'Rules', expanded: true },
+        End: { label: 'End Screen', expanded: false },
+        Scenes: { label: 'Scenes', expanded: false },
+      },
+    };
+  }
+
+  onStart(): void {
+    this.lives = Math.max(1, Number(this.config.startingLives) || 1);
+    const commands = this.scene?.commands;
+    this.disposeCommands = [
+      commands?.register('restart', () => this.restart(), {
+        description: 'Reload the game scene for a fresh board.',
+      }),
+      commands?.register('return-to-menu', () => this.toMenu(), {
+        description: 'Leave the run and go back to the menu scene.',
+      }),
+    ].filter((dispose): dispose is () => void => dispose !== undefined);
+
+    this.disposeDebug = registerGameDebug({
+      name: 'recipe-grid-3d',
+      version: 1,
+      actions: () => this.scene?.commands.list().map(command => command.name) ?? [],
+      snapshot: () => ({
+        scene: 'game',
+        phase: this.over ? (this.won ? 'won' : 'lost') : 'playing',
+        score: this.score,
+        lives: this.lives,
+        // The board's own number: cubes still to clear. This is what proves a tap landed.
+        remaining: this.remaining,
+        clearable: this.clearable,
+        elapsedSec: roundHundredths(this.elapsed),
+        timeLeftSec: this.timeLeftSec(),
+      }),
+    });
+
+    const owner = this.node;
+    owner?.connect('board-built', this, (...args: unknown[]) => {
+      this.clearable = Number(args[0]) || 0;
+      this.remaining = this.clearable;
+      this.broadcast();
+    });
+    owner?.connect('cell-cleared', this, (...args: unknown[]) => this.onCellCleared(Number(args[0]) || 0));
+    owner?.connect('core-hit', this, () => this.takeDamage(1));
+    owner?.connect('board-cleared', this, () => this.finish(true));
+    owner?.connect('hud-ready', this, () => this.broadcast());
+
+    // Components start in scene order, and the board is listed first — so by now it has already
+    // built and already emitted `board-built`, into a signal nobody was connected to yet. Pull the
+    // number as well as listening for it: the connect above covers a later rebuild (or a scene that
+    // lists the components the other way round), this covers the first one.
+    this.adoptBoardCount();
+
+    this.setNodeVisible(String(this.config.resultNode ?? ''), false);
+    // Both end-screen buttons start disabled, because in THIS recipe the menu button lives inside
+    // the hidden `result-overlay` (the 2D recipes park theirs in the always-visible HUD, where
+    // enabling it is right). Leaving it enabled read as "you can leave mid-run" while the control
+    // was invisible and sitting over the middle of the board.
+    this.bindButton(String(this.config.retryButton ?? ''), () => this.scene?.commands.dispatch('restart'), false);
+    this.bindButton(String(this.config.menuButton ?? ''), () => this.scene?.commands.dispatch('return-to-menu'), false);
+    this.broadcast();
+  }
+
+  onUpdate(dt: number): void {
+    if (this.over) {
+      return;
+    }
+    this.elapsed += dt;
+    const limit = Math.max(0, Number(this.config.timeLimitSec) || 0);
+    this.node?.emit('time-changed', limit > 0 ? Math.max(0, limit - this.elapsed) : this.elapsed);
+    if (this.lives <= 0) {
+      this.finish(false);
+      return;
+    }
+    if (limit > 0 && this.elapsed >= limit) {
+      this.finish(false);
+    }
+  }
+
+  onDetach(): void {
+    this.disposeDebug?.();
+    this.disposeDebug = null;
+    for (const dispose of this.disposeCommands) {
+      dispose();
+    }
+    this.disposeCommands = [];
+    super.onDetach();
+  }
+
+  /** End the run. Public so a custom rule can call it. */
+  finish(won: boolean): void {
+    if (this.over) {
+      return;
+    }
+    this.over = true;
+    this.won = won;
+    const label = this.findNode(String(this.config.resultLabel ?? ''));
+    if (label instanceof Label2D) {
+      label.setText(String((won ? this.config.winText : this.config.loseText) ?? ''));
+    }
+    this.setNodeVisible(String(this.config.resultNode ?? ''), true);
+    this.setButtonEnabled(String(this.config.retryButton ?? ''), true);
+    this.setButtonEnabled(String(this.config.menuButton ?? ''), true);
+    this.node?.emit(won ? 'game-won' : 'game-lost', this.score);
+  }
+
+  /**
+   * Read the live cube count off whichever sibling component owns the board.
+   *
+   * Duck-typed rather than importing `GridBoard`: a project that swaps in its own board keeps
+   * working as long as it answers `getRemaining()`.
+   */
+  private adoptBoardCount(): void {
+    if (this.clearable > 0) {
+      return;
+    }
+    for (const component of this.node?.components ?? []) {
+      const getRemaining = (component as { getRemaining?: unknown }).getRemaining;
+      if (typeof getRemaining === 'function') {
+        const value = Number((getRemaining as () => number).call(component));
+        if (Number.isFinite(value) && value > 0) {
+          this.clearable = value;
+          this.remaining = value;
+          return;
+        }
+      }
+    }
+  }
+
+  private onCellCleared(remaining: number): void {
+    if (this.over) {
+      return;
+    }
+    this.remaining = remaining;
+    this.score += 1;
+    this.node?.emit('score-changed', this.score);
+  }
+
+  private takeDamage(amount: number): void {
+    if (this.over) {
+      return;
+    }
+    this.lives = Math.max(0, this.lives - Math.max(1, amount));
+    this.node?.emit('lives-changed', this.lives, Math.max(1, Number(this.config.startingLives) || 1));
+  }
+
+  private broadcast(): void {
+    const owner = this.node;
+    owner?.emit('score-changed', this.score);
+    owner?.emit('lives-changed', this.lives, Math.max(1, Number(this.config.startingLives) || 1));
+    const limit = Math.max(0, Number(this.config.timeLimitSec) || 0);
+    owner?.emit('time-changed', limit > 0 ? Math.max(0, limit - this.elapsed) : this.elapsed);
+  }
+
+  private timeLeftSec(): number | null {
+    const limit = Math.max(0, Number(this.config.timeLimitSec) || 0);
+    return limit > 0 ? roundHundredths(Math.max(0, limit - this.elapsed)) : null;
+  }
+
+  private restart(): void {
+    void this.scene?.changeScene(String(this.config.gameScene ?? ''), { transition: 'fade' });
+  }
+
+  private toMenu(): void {
+    void this.scene?.changeScene(String(this.config.menuScene ?? ''), { transition: 'fade' });
+  }
+
+  private bindButton(query: string, handler: () => void, enabled: boolean): void {
+    const button = this.findNode(query);
+    if (button instanceof Button2D) {
+      button.enabled = enabled;
+      button.connect('pressed', this, handler);
+    }
+  }
+
+  private setButtonEnabled(query: string, enabled: boolean): void {
+    const button = this.findNode(query);
+    if (button instanceof Button2D) {
+      button.enabled = enabled;
+    }
+  }
+
+  private setNodeVisible(query: string, visible: boolean): void {
+    const node = this.findNode(query);
+    if (node) {
+      node.visible = visible;
+    }
+  }
+}

package/templates/recipe-grid-3d/files/scripts/MenuFlow.ts

@@ -0,0 +1,106 @@
+/**
+ * MenuFlow — drives the menu scene (the project's entry/export scene).
+ *
+ * PLAY transitions to the game scene with a fade. That is all it does: keep the
+ * menu dumb so the game scene stays directly playable on its own (agents and
+ * the editor open `main.pix3scene` and press play without going through here).
+ *
+ * PLAY does not call `startGame()` directly: it dispatches the command
+ * `start-game` (`scene.commands`). A test can then leave the menu without a tap,
+ * every raised intent lands in `scene.commands.log` with its frame, and one real
+ * tap is enough to prove the button is still wired to the intent it claims.
+ *
+ * It registers a debug provider too. `registerGameDebug` is global and
+ * last-wins, and only the running scene's flow script registers one — so
+ * without this, everything a tool reads while the menu is up would come back
+ * empty (or, worse, stale from the previous scene).
+ */
+import { Script, registerGameDebug, type PropertySchema } from '@pix3/runtime';
+
+export class MenuFlow extends Script {
+  private playButtonReady = false;
+  private disposeDebug: (() => void) | null = null;
+  private disposeCommands: (() => void)[] = [];
+
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      gameScene: 'res://scenes/main.pix3scene',
+      playButton: 'play-button',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    const str = (name: string, label: string) => ({
+      name,
+      type: 'string' as const,
+      ui: { label, group: 'Menu' },
+      getValue: (s: unknown) => (s as MenuFlow).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        (s as MenuFlow).config[name] = typeof v === 'string' ? v : '';
+      },
+    });
+
+    return {
+      nodeType: 'MenuFlow',
+      properties: [str('gameScene', 'Game Scene'), str('playButton', 'Play Button')],
+      groups: { Menu: { label: 'Menu Flow', expanded: true } },
+    };
+  }
+
+  onStart(): void {
+    const commands = this.scene?.commands;
+    this.disposeCommands = [
+      commands?.register('start-game', () => this.startGame(), {
+        description: 'Leave the menu and transition into the game scene.',
+      }),
+    ].filter((dispose): dispose is () => void => dispose !== undefined);
+
+    this.disposeDebug = registerGameDebug({
+      name: 'recipe-grid-3d',
+      version: 1,
+      // The registry IS the action list — never a second, hand-kept copy.
+      actions: () => this.scene?.commands.list().map(command => command.name) ?? [],
+      // `scene` is what tells a reader which flow answered: the game scene's
+      // GameRules publishes under the same name.
+      snapshot: () => ({
+        scene: 'menu',
+        gameScene: String(this.config.gameScene ?? ''),
+        playButtonReady: this.playButtonReady,
+      }),
+    });
+
+    const button = this.findNode(String(this.config.playButton ?? ''));
+    if (!button) {
+      console.warn(`[MenuFlow] Button "${this.config.playButton}" not found.`);
+      return;
+    }
+    this.playButtonReady = true;
+    button.connect('pressed', this, () => {
+      this.scene?.commands.dispatch('start-game');
+    });
+  }
+
+  onDetach(): void {
+    // Safe in any order: the disposer clears the global only while it still
+    // holds *this* provider, so the next scene's registration is never wiped.
+    this.disposeDebug?.();
+    this.disposeDebug = null;
+    // The scene's registry is cleared on stop anyway; this covers the other
+    // case — this script being detached while the scene keeps running.
+    for (const dispose of this.disposeCommands) {
+      dispose();
+    }
+    this.disposeCommands = [];
+    this.playButtonReady = false;
+    super.onDetach();
+  }
+
+  /** Transition into the game scene. */
+  startGame(): void {
+    void this.scene?.changeScene(String(this.config.gameScene ?? ''), {
+      transition: 'fade',
+      durationSec: 0.3,
+    });
+  }
+}