@pix3/cli 1.6.0

package/templates/minigame-2d/files/scenes/menu.pix3scene

@@ -0,0 +1,118 @@
+# Pix3 Scene File (YAML)
+# Minigame 2D — the MENU scene. This is the project's ENTRY / export scene
+# (Project Settings → Default Export Scene Path): a full build and "Play Game (Entry Scene)"
+# boot here so you can debug the whole flow. PLAY transitions to the game scene
+# (main.pix3scene) via a fade; SETTINGS opens the settings-window prefab.
+# Wired by scripts/MenuFlow.ts.
+version: 1.0.0
+metadata:
+  author: Pix3 Template
+  description: Menu scene — entry point; PLAY transitions to the game
+root:
+  - id: menu-root
+    type: Group2D
+    name: Menu Root
+    properties:
+      width: 1920
+      height: 1080
+      layout:
+        enabled: true
+        horizontalAlign: stretch
+        verticalAlign: stretch
+    components:
+      - id: menu-flow
+        type: user:MenuFlow
+        enabled: true
+        config:
+          gameScene: res://scenes/main.pix3scene
+          settingsNode: settings-window
+          playButton: play-button
+          settingsButton: settings-button
+    children:
+      - id: menu-background
+        type: ColorRect2D
+        name: Menu Background
+        properties:
+          width: 1920
+          height: 1080
+          color: "#16213e"
+          transform:
+            position: [0, 0]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: stretch
+            verticalAlign: stretch
+        children: []
+      - id: menu-title
+        type: Label2D
+        name: Menu Title
+        properties:
+          label: "{{PROJECT_NAME}}"
+          labelFontSize: 96
+          labelColor: "#ffcf33"
+          labelAlign: center
+          transform:
+            position: [0, 250]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: center
+        children: []
+      - id: play-button
+        type: Button2D
+        name: Play Button
+        properties:
+          width: 420
+          height: 120
+          label: "PLAY"
+          labelFontSize: 48
+          labelColor: "#1a1a2e"
+          backgroundColor: "#ffcf33"
+          hoverColor: "#ffe066"
+          pressedColor: "#e6b800"
+          buttonAction: play
+          transform:
+            position: [0, 0]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: center
+        children: []
+      - id: settings-button
+        type: Button2D
+        name: Settings Button
+        properties:
+          width: 420
+          height: 120
+          label: "SETTINGS"
+          labelFontSize: 48
+          labelColor: "#ffffff"
+          backgroundColor: "#3a3a5e"
+          hoverColor: "#4a4a6e"
+          pressedColor: "#2a2a4e"
+          buttonAction: open-settings
+          transform:
+            position: [0, -170]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: center
+        children: []
+      # Settings modal — authored in scenes/ui/settings-window.pix3scene so this
+      # scene opens on the MENU, not on the modal. `visible: false` hides it in
+      # the EDITOR only; `initiallyVisible` (in the overlay file) is what play
+      # mode reads, and user:MenuFlow opens it at run time on SETTINGS. Tick the
+      # eye to preview it over the menu.
+      - id: settings-window
+        name: Settings Window
+        instance: res://scenes/ui/settings-window.pix3scene
+        properties:
+          visible: false

package/templates/minigame-2d/files/scenes/ui/settings-window.pix3scene

@@ -0,0 +1,138 @@
+# Pix3 Scene File (YAML)
+# Minigame 2D — the SETTINGS modal: a centered panel with Music/SFX checkboxes
+# (wired to the audio buses by user:SettingsWindow) and a CLOSE button. It lives
+# in its own file under scenes/ui/ so the menu scene opens clean. Host scenes
+# carry it as a one-line `instance:` reference marked `visible: false`, which
+# hides it in the EDITOR only; `initiallyVisible: false` on `settings-root`
+# below is what play mode reads, and `user:MenuFlow` shows it at run time.
+#
+# Edit it here, full-screen, in its own tab. To preview it composited over the
+# menu, tick the eye on `settings-window` in menu.pix3scene — just do not commit
+# that tick, or every iteration starts behind the settings modal again.
+#
+# Instance it from any scene:
+#   - id: settings-window
+#     instance: res://scenes/ui/settings-window.pix3scene
+#     properties:
+#       visible: false
+version: 1.0.0
+metadata:
+  author: Pix3 Template
+  description: Reusable settings window (music/SFX toggles)
+root:
+  - id: settings-root
+    type: Group2D
+    name: Settings Window
+    properties:
+      width: 640
+      height: 520
+      initiallyVisible: false
+      layout:
+        enabled: true
+        horizontalAlign: center
+        verticalAlign: center
+    components:
+      - id: settings-behavior
+        type: user:SettingsWindow
+        enabled: true
+        config:
+          musicToggle: music-toggle
+          sfxToggle: sfx-toggle
+          closeButton: close-button
+    children:
+      - id: settings-panel
+        type: ColorRect2D
+        name: Panel
+        properties:
+          width: 640
+          height: 520
+          color: "#1a1a2e"
+          opacity: 0.97
+          transform:
+            position: [0, 0]
+            scale: [1, 1]
+            rotation: 0
+        children: []
+      - id: settings-title
+        type: Label2D
+        name: Title
+        properties:
+          label: "SETTINGS"
+          labelFontSize: 48
+          labelColor: "#ffcf33"
+          labelAlign: center
+          transform:
+            position: [0, 190]
+            scale: [1, 1]
+            rotation: 0
+        children: []
+      - id: music-label
+        type: Label2D
+        name: Music Label
+        properties:
+          label: "Music"
+          labelFontSize: 36
+          labelColor: "#ffffff"
+          labelAlign: left
+          transform:
+            position: [-120, 70]
+            scale: [1, 1]
+            rotation: 0
+        children: []
+      - id: music-toggle
+        type: Checkbox2D
+        name: Music Toggle
+        properties:
+          size: 44
+          checked: true
+          checkedColor: "#ffcf33"
+          uncheckedColor: "#555577"
+          transform:
+            position: [150, 70]
+            scale: [1, 1]
+            rotation: 0
+        children: []
+      - id: sfx-label
+        type: Label2D
+        name: SFX Label
+        properties:
+          label: "Sound FX"
+          labelFontSize: 36
+          labelColor: "#ffffff"
+          labelAlign: left
+          transform:
+            position: [-120, -10]
+            scale: [1, 1]
+            rotation: 0
+        children: []
+      - id: sfx-toggle
+        type: Checkbox2D
+        name: SFX Toggle
+        properties:
+          size: 44
+          checked: true
+          checkedColor: "#ffcf33"
+          uncheckedColor: "#555577"
+          transform:
+            position: [150, -10]
+            scale: [1, 1]
+            rotation: 0
+        children: []
+      - id: close-button
+        type: Button2D
+        name: Close Button
+        properties:
+          width: 280
+          height: 88
+          label: "CLOSE"
+          labelFontSize: 36
+          labelColor: "#1a1a2e"
+          backgroundColor: "#ffcf33"
+          hoverColor: "#ffe066"
+          pressedColor: "#e6b800"
+          buttonAction: close-settings
+          transform:
+            position: [0, -180]
+            scale: [1, 1]
+            rotation: 0
+        children: []

package/templates/minigame-2d/files/scripts/GameFlow.ts

@@ -0,0 +1,133 @@
+/**
+ * GameFlow — drives the game scene (main.pix3scene).
+ *
+ * Attach to the game scene root. Wires the MENU button to transition back to the
+ * menu scene via a fade. Extend this with your win/lose flow — call
+ * `this.scene.changeScene('res://scenes/menu.pix3scene')` on game over
+ * to return to the menu, or transition to a results scene of your own.
+ *
+ * Two conventions in here are worth keeping as you build on this template:
+ *
+ * 1. **Intent-first handlers.** Every reaction to the UI lives in a named public
+ *    method marked `Intent:`, registered as a **command** (`scene.commands`)
+ *    that the signal handler dispatches. Tools (and you, from the console) then
+ *    trigger the behaviour with `scene.commands.dispatch('return-to-menu')`
+ *    instead of faking a click, and every raised intent is journalled with the
+ *    frame it happened on.
+ * 2. **A debug provider.** `registerGameDebug` publishes a JSON snapshot of the
+ *    game's state so agents and dev tooling can read what the game is doing
+ *    instead of guessing from pixels. Add YOUR state to `snapshot()` — score,
+ *    lives, level, whatever the game owns — and keep every value JSON-safe.
+ */
+import { Script, registerGameDebug, type PropertySchema } from '@pix3/runtime';
+
+/** Coarse state of the game scene; extend with your own phases (`won`, `lost`, …). */
+type GamePhase = 'idle' | 'playing' | 'leaving';
+
+export class GameFlow extends Script {
+  private phase: GamePhase = 'idle';
+  private menuButtonReady = false;
+  private disposeDebug: (() => void) | null = null;
+  private disposeCommands: (() => void)[] = [];
+
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      // res:// path of the scene the MENU button transitions to.
+      menuScene: 'res://scenes/menu.pix3scene',
+      // Node id/name of the button that returns to the menu.
+      menuButton: 'menu-button',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    const stringProp = (name: string, label: string) => ({
+      name,
+      type: 'string' as const,
+      ui: { label, group: 'Game' },
+      getValue: (s: unknown) => (s as GameFlow).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        (s as GameFlow).config[name] = typeof v === 'string' ? v : '';
+      },
+    });
+
+    return {
+      nodeType: 'GameFlow',
+      properties: [stringProp('menuScene', 'Menu Scene'), stringProp('menuButton', 'Menu Button')],
+      groups: { Game: { label: 'Game Flow', expanded: true } },
+    };
+  }
+
+  onStart(): void {
+    this.phase = 'playing';
+    const commands = this.scene?.commands;
+    this.disposeCommands = [
+      commands?.register('return-to-menu', () => this.returnToMenu(), {
+        description: 'Leave the game and transition back to the menu scene.',
+      }),
+    ].filter((dispose): dispose is () => void => dispose !== undefined);
+
+    this.disposeDebug = registerGameDebug({
+      name: 'minigame-2d',
+      version: 1,
+      // The registry IS the action list — never a second, hand-kept copy.
+      actions: () => this.scene?.commands.list().map(command => command.name) ?? [],
+      // What "the start" means for this scene, so a test can put the game back
+      // without restarting it. All this template owns is `phase`, and `playing`
+      // is the value `onStart` sets — a run that had already dispatched
+      // `return-to-menu` would otherwise be stuck in `leaving`. Reset YOUR state
+      // here as you add it (score, level, spawned things), and seed your RNG from
+      // `seed` if you want two runs to be comparable and not merely to start
+      // from the same values.
+      reset: () => {
+        this.phase = 'playing';
+      },
+      // Everything returned here must be JSON-serialisable — plain values only,
+      // never live nodes or Three.js objects. Add your own state as you build.
+      snapshot: () => ({
+        phase: this.phase,
+        menuScene: String(this.config.menuScene ?? ''),
+        menuButtonReady: this.menuButtonReady,
+      }),
+    });
+
+    const query = String(this.config.menuButton ?? '');
+    if (!query) {
+      return;
+    }
+    const button = this.findNode(query);
+    if (button) {
+      this.menuButtonReady = true;
+      // The button raises the intent through the registry, so a single tap in a
+      // test proves this binding and every later scenario can skip the tap.
+      button.connect('pressed', this, () => {
+        this.scene?.commands.dispatch('return-to-menu');
+      });
+    } else {
+      console.warn(`[GameFlow] Button "${query}" not found.`);
+    }
+  }
+
+  onDetach(): void {
+    this.disposeDebug?.();
+    this.disposeDebug = null;
+    for (const dispose of this.disposeCommands) {
+      dispose();
+    }
+    this.disposeCommands = [];
+    this.phase = 'idle';
+    this.menuButtonReady = false;
+    super.onDetach();
+  }
+
+  /** Intent: leave the game and transition back to the menu scene (also on game over). */
+  returnToMenu(): void {
+    const menuScene = String(this.config.menuScene ?? '');
+    if (!menuScene) {
+      console.warn('[GameFlow] No menu scene configured.');
+      return;
+    }
+    this.phase = 'leaving';
+    void this.scene?.changeScene(menuScene, { transition: 'fade', durationSec: 0.3 });
+  }
+}

package/templates/minigame-2d/files/scripts/MenuFlow.ts

@@ -0,0 +1,217 @@
+/**
+ * MenuFlow — drives the menu scene.
+ *
+ * Attach to the menu scene root. PLAY transitions to the game scene via a fade
+ * (`this.scene.changeScene`), SETTINGS shows the settings-window prefab instance.
+ * The game lives in its own scene (main.pix3scene) so it can be opened and played
+ * on its own; this menu is the entry point wired into the full build flow.
+ *
+ * Handlers here are **intent-first**: each button's behaviour lives in a named
+ * public method marked `Intent:`, and the intent is registered as a **command**
+ * (`scene.commands`) that the button's signal handler dispatches. Three things
+ * follow, all for free: a test drives the menu with
+ * `scene.commands.dispatch('start-game')` instead of a tap; every raised intent
+ * lands in `scene.commands.log` with the frame it happened on; and one real tap
+ * is enough to prove the button is still wired to the intent it claims.
+ *
+ * It also registers a debug provider, exactly like `GameFlow` does for the game
+ * scene. `registerGameDebug` is global and last-wins, and only the running
+ * scene's flow script registers one — so without this, every tool reading the
+ * game while the menu is up would get nothing (or stale game-scene state).
+ */
+import {
+  Checkbox2D,
+  NodeBase,
+  Script,
+  registerGameDebug,
+  type PropertySchema,
+} from '@pix3/runtime';
+
+export class MenuFlow extends Script {
+  private playButtonReady = false;
+  private settingsButtonReady = false;
+  private disposeDebug: (() => void) | null = null;
+  private disposeCommands: (() => void)[] = [];
+
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      // res:// path of the scene PLAY transitions to.
+      gameScene: 'res://scenes/main.pix3scene',
+      // Node id/name of the settings-window prefab instance to toggle.
+      settingsNode: 'settings-window',
+      playButton: 'play-button',
+      settingsButton: 'settings-button',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    const stringProp = (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: [
+        stringProp('gameScene', 'Game Scene'),
+        stringProp('settingsNode', 'Settings Window'),
+        stringProp('playButton', 'Play Button'),
+        stringProp('settingsButton', 'Settings Button'),
+      ],
+      groups: { Menu: { label: 'Menu Flow', expanded: true } },
+    };
+  }
+
+  onStart(): void {
+    // Register the intents first, then point the buttons at them: a button
+    // dispatches, it does not call the method, so the command journal is the
+    // whole truth about what the player asked for.
+    const commands = this.scene?.commands;
+    this.disposeCommands = [
+      commands?.register('start-game', () => this.startGame(), {
+        description: 'Leave the menu and transition into the game scene.',
+      }),
+      commands?.register(
+        'open-settings',
+        () => {
+          this.openSettings();
+          // Returning a reverse step is all it takes to make an intent
+          // undoable: `scene.commands.undo()` closes the window again.
+          return { undo: () => this.closeSettings() };
+        },
+        { description: 'Show the settings window over the menu.', undoable: true }
+      ),
+      commands?.register('close-settings', () => this.closeSettings(), {
+        description: 'Hide the settings window.',
+      }),
+    ].filter((dispose): dispose is () => void => dispose !== undefined);
+
+    this.playButtonReady = this.connectButton(String(this.config.playButton ?? ''), () => {
+      this.scene?.commands.dispatch('start-game');
+    });
+    this.settingsButtonReady = this.connectButton(String(this.config.settingsButton ?? ''), () => {
+      this.scene?.commands.dispatch('open-settings');
+    });
+
+    this.disposeDebug = registerGameDebug({
+      name: 'minigame-2d',
+      version: 1,
+      // The registry IS the action list — never a second, hand-kept copy.
+      actions: () => this.scene?.commands.list().map(command => command.name) ?? [],
+      // What "the start" means for the menu: the fresh menu has the settings
+      // window closed, and an earlier `open-settings` is the one piece of state a
+      // later run would inherit. Deliberately NOT reset here: the checkboxes
+      // inside the window, which are player settings — a reset that silently
+      // reverted someone's audio choice would be a worse lie than not resetting.
+      // `seed` is ignored; the menu has no randomness to seed.
+      reset: () => this.closeSettings(),
+      // Same `name` as GameFlow — one game, one identity; `scene` says which
+      // flow answered. Everything here must stay JSON-serialisable.
+      snapshot: () => ({
+        scene: 'menu',
+        gameScene: String(this.config.gameScene ?? ''),
+        playButtonReady: this.playButtonReady,
+        settingsButtonReady: this.settingsButtonReady,
+        settingsVisible: this.isSettingsVisible(),
+        // Checkbox state inside the settings window, keyed by node id
+        // (`music-toggle` / `sfx-toggle` in the shipped prefab).
+        settingsToggles: this.readSettingsToggles(),
+      }),
+    });
+  }
+
+  onDetach(): void {
+    // Safe in any order: the disposer clears the global only while it still
+    // holds *this* provider, so the game 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;
+    this.settingsButtonReady = false;
+    super.onDetach();
+  }
+
+  /** Intent: leave the menu and transition into the game scene. */
+  startGame(): void {
+    const gameScene = String(this.config.gameScene ?? '');
+    if (!gameScene) {
+      console.warn('[MenuFlow] No game scene configured.');
+      return;
+    }
+    void this.scene?.changeScene(gameScene, { transition: 'fade', durationSec: 0.3 });
+  }
+
+  /** Intent: show the settings window over the menu. */
+  openSettings(): void {
+    this.setNodeVisible(String(this.config.settingsNode ?? ''), true);
+  }
+
+  /** Intent: hide the settings window (its own CLOSE button does this too). */
+  closeSettings(): void {
+    this.setNodeVisible(String(this.config.settingsNode ?? ''), false);
+  }
+
+  /** Returns whether the button was found and wired (reported in the snapshot). */
+  private connectButton(query: string, handler: () => void): boolean {
+    if (!query) {
+      return false;
+    }
+    const button = this.findNode(query);
+    if (!button) {
+      console.warn(`[MenuFlow] Button "${query}" not found.`);
+      return false;
+    }
+    button.connect('pressed', this, handler);
+    return true;
+  }
+
+  private isSettingsVisible(): boolean {
+    const node = this.findNode(String(this.config.settingsNode ?? ''));
+    return node?.visible === true;
+  }
+
+  /** Every Checkbox2D under the settings window, by node id → checked. */
+  private readSettingsToggles(): Record<string, boolean> {
+    const toggles: Record<string, boolean> = {};
+    const root = this.findNode(String(this.config.settingsNode ?? ''));
+    if (!root) {
+      return toggles;
+    }
+    const visit = (node: NodeBase): void => {
+      if (node instanceof Checkbox2D) {
+        toggles[node.nodeId] = node.checked;
+      }
+      for (const child of node.children) {
+        // `children` also holds plain Three.js objects (visuals), not just nodes.
+        if (child instanceof NodeBase) {
+          visit(child);
+        }
+      }
+    };
+    visit(root);
+    return toggles;
+  }
+
+  private setNodeVisible(query: string, visible: boolean): void {
+    if (!query) {
+      return;
+    }
+    const node = this.findNode(query);
+    if (node) {
+      node.visible = visible;
+    } else {
+      console.warn(`[MenuFlow] Node "${query}" not found.`);
+    }
+  }
+}