@pix3/cli 1.6.0 → 1.6.3

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

@@ -1,106 +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,
-    });
-  }
-}
+/**
+ * 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,
+    });
+  }
+}

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

@@ -1,94 +1,94 @@
-/**
- * ScoreHud — signal-driven HUD. Display only, no game logic.
- *
- * Listens on `sourceNode` (the node carrying `GameRules`) for:
- *   `score-changed` (score)
- *   `lives-changed` (lives, maxLives)
- *   `time-changed`  (seconds)
- *
- * If a HUD widget is missing from the scene it is quietly skipped, so you can
- * delete the timer or the lives bar without touching any script.
- */
-import { Bar2D, Label2D, Script, type PropertySchema } from '@pix3/runtime';
-
-export class ScoreHud extends Script {
-  constructor(id: string, type: string) {
-    super(id, type);
-    this.config = {
-      // Node that emits the HUD signals (the GameRules host).
-      sourceNode: 'game-root',
-      scoreLabel: 'score-label',
-      scoreFormat: 'SCORE {value}',
-      timeLabel: 'time-label',
-      timeFormat: '{value}',
-      livesBar: 'lives-bar',
-    };
-  }
-
-  static getPropertySchema(): PropertySchema {
-    const str = (name: string, label: string, description?: string) => ({
-      name,
-      type: 'string' as const,
-      ui: { label, group: 'HUD', description },
-      getValue: (s: unknown) => (s as ScoreHud).config[name],
-      setValue: (s: unknown, v: unknown) => {
-        (s as ScoreHud).config[name] = typeof v === 'string' ? v : '';
-      },
-    });
-
-    return {
-      nodeType: 'ScoreHud',
-      properties: [
-        str('sourceNode', 'Source Node', 'Node that emits score-changed / lives-changed / time-changed'),
-        str('scoreLabel', 'Score Label'),
-        str('scoreFormat', 'Score Format', '{value} is replaced by the score'),
-        str('timeLabel', 'Time Label'),
-        str('timeFormat', 'Time Format', '{value} is replaced by whole seconds'),
-        str('livesBar', 'Lives Bar'),
-      ],
-      groups: { HUD: { label: 'HUD', expanded: true } },
-    };
-  }
-
-  onStart(): void {
-    const source = this.findNode(String(this.config.sourceNode ?? ''));
-    if (!source) {
-      console.warn(`[ScoreHud] Source node "${this.config.sourceNode}" not found.`);
-      return;
-    }
-    source.connect('score-changed', this, (...args: unknown[]) => this.setScore(Number(args[0]) || 0));
-    source.connect('time-changed', this, (...args: unknown[]) => this.setTime(Number(args[0]) || 0));
-    source.connect('lives-changed', this, (...args: unknown[]) =>
-      this.setLives(Number(args[0]) || 0, Number(args[1]) || 0)
-    );
-    // Ask for the opening values now that the listeners are live: GameRules
-    // starts before this HUD (parent components tick before children).
-    source.emit('hud-ready');
-  }
-
-  private setScore(score: number): void {
-    const label = this.findNode(String(this.config.scoreLabel ?? ''));
-    if (label instanceof Label2D) {
-      label.setText(String(this.config.scoreFormat ?? '{value}').replace('{value}', String(Math.round(score))));
-    }
-  }
-
-  private setTime(seconds: number): void {
-    const label = this.findNode(String(this.config.timeLabel ?? ''));
-    if (label instanceof Label2D) {
-      label.setText(
-        String(this.config.timeFormat ?? '{value}').replace('{value}', String(Math.max(0, Math.ceil(seconds))))
-      );
-    }
-  }
-
-  private setLives(lives: number, maxLives: number): void {
-    const bar = this.findNode(String(this.config.livesBar ?? ''));
-    if (bar instanceof Bar2D) {
-      if (maxLives > 0) {
-        bar.maxValue = maxLives;
-      }
-      bar.setValue(lives);
-    }
-  }
-}
+/**
+ * ScoreHud — signal-driven HUD. Display only, no game logic.
+ *
+ * Listens on `sourceNode` (the node carrying `GameRules`) for:
+ *   `score-changed` (score)
+ *   `lives-changed` (lives, maxLives)
+ *   `time-changed`  (seconds)
+ *
+ * If a HUD widget is missing from the scene it is quietly skipped, so you can
+ * delete the timer or the lives bar without touching any script.
+ */
+import { Bar2D, Label2D, Script, type PropertySchema } from '@pix3/runtime';
+
+export class ScoreHud extends Script {
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      // Node that emits the HUD signals (the GameRules host).
+      sourceNode: 'game-root',
+      scoreLabel: 'score-label',
+      scoreFormat: 'SCORE {value}',
+      timeLabel: 'time-label',
+      timeFormat: '{value}',
+      livesBar: 'lives-bar',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    const str = (name: string, label: string, description?: string) => ({
+      name,
+      type: 'string' as const,
+      ui: { label, group: 'HUD', description },
+      getValue: (s: unknown) => (s as ScoreHud).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        (s as ScoreHud).config[name] = typeof v === 'string' ? v : '';
+      },
+    });
+
+    return {
+      nodeType: 'ScoreHud',
+      properties: [
+        str('sourceNode', 'Source Node', 'Node that emits score-changed / lives-changed / time-changed'),
+        str('scoreLabel', 'Score Label'),
+        str('scoreFormat', 'Score Format', '{value} is replaced by the score'),
+        str('timeLabel', 'Time Label'),
+        str('timeFormat', 'Time Format', '{value} is replaced by whole seconds'),
+        str('livesBar', 'Lives Bar'),
+      ],
+      groups: { HUD: { label: 'HUD', expanded: true } },
+    };
+  }
+
+  onStart(): void {
+    const source = this.findNode(String(this.config.sourceNode ?? ''));
+    if (!source) {
+      console.warn(`[ScoreHud] Source node "${this.config.sourceNode}" not found.`);
+      return;
+    }
+    source.connect('score-changed', this, (...args: unknown[]) => this.setScore(Number(args[0]) || 0));
+    source.connect('time-changed', this, (...args: unknown[]) => this.setTime(Number(args[0]) || 0));
+    source.connect('lives-changed', this, (...args: unknown[]) =>
+      this.setLives(Number(args[0]) || 0, Number(args[1]) || 0)
+    );
+    // Ask for the opening values now that the listeners are live: GameRules
+    // starts before this HUD (parent components tick before children).
+    source.emit('hud-ready');
+  }
+
+  private setScore(score: number): void {
+    const label = this.findNode(String(this.config.scoreLabel ?? ''));
+    if (label instanceof Label2D) {
+      label.setText(String(this.config.scoreFormat ?? '{value}').replace('{value}', String(Math.round(score))));
+    }
+  }
+
+  private setTime(seconds: number): void {
+    const label = this.findNode(String(this.config.timeLabel ?? ''));
+    if (label instanceof Label2D) {
+      label.setText(
+        String(this.config.timeFormat ?? '{value}').replace('{value}', String(Math.max(0, Math.ceil(seconds))))
+      );
+    }
+  }
+
+  private setLives(lives: number, maxLives: number): void {
+    const bar = this.findNode(String(this.config.livesBar ?? ''));
+    if (bar instanceof Bar2D) {
+      if (maxLives > 0) {
+        bar.maxValue = maxLives;
+      }
+      bar.setValue(lives);
+    }
+  }
+}

package/templates/recipe-grid-3d/template.yaml

@@ -1,10 +1,10 @@
-id: recipe-grid-3d
-title: Grid 3D
-description: A solid block of cubes you carve by tapping — clear every cube except the hidden core ones. Voxel carving, 3D minesweeper, layer puzzles, tap-to-mine.
-projectType: 3d
-targetPlatform: mobile
-viewport: { width: 1080, height: 1920 }
-# The build/full-run entry scene (Project Settings → Default Export Scene Path).
-# The menu boots first; PLAY transitions to main.pix3scene (the board).
-entryScene: scenes/menu.pix3scene
-order: 63
+id: recipe-grid-3d
+title: Grid 3D
+description: A solid block of cubes you carve by tapping — clear every cube except the hidden core ones. Voxel carving, 3D minesweeper, layer puzzles, tap-to-mine.
+projectType: 3d
+targetPlatform: mobile
+viewport: { width: 1080, height: 1920 }
+# The build/full-run entry scene (Project Settings → Default Export Scene Path).
+# The menu boots first; PLAY transitions to main.pix3scene (the board).
+entryScene: scenes/menu.pix3scene
+order: 63

package/templates/recipe-tapper-2d/files/README.md

@@ -1,39 +1,39 @@
-# Tapper 2D
-
-A playable skeleton: objects fall into the field, tapping them is the whole
-game, one bad type punishes, and a countdown ends the run. It plays as
-shipped — press play in `scenes/main.pix3scene` before changing anything.
-
-**`design/recipe.md` is the contract.** Stable node ids, tunables with ranges,
-extension points and what must not be renamed. Read it first.
-
-## Layout
-
-```
-scenes/menu.pix3scene       entry / export scene — PLAY transitions to the game
-scenes/main.pix3scene       the GAME (editor startup scene — iterate here)
-scenes/ui/result.pix3scene  win/lose overlay, instanced into main hidden (editor-only)
-scenes/prefabs/*.pix3scene  what the spawners instantiate
-scripts/Spawner.ts          timed instantiate + drift + despawn
-scripts/TouchRules.ts       a tap → semantic signals
-scripts/ScoreHud.ts         signals → HUD widgets
-scripts/GameRules.ts        score / lives / timer / win / lose / end flow
-scripts/MenuFlow.ts         menu PLAY button
-sprites/ph-*.png            near-white placeholders (tinted via core:tint)
-```
-
-Same script names and roles as the other recipes — `Spawner`, `TouchRules`,
-`ScoreHud`, `GameRules` mean the same thing everywhere, only their contact
-source differs (here: a pointer-down hit-test instead of a proximity test).
-
-## The rule that keeps it workable
-
-One file, one responsibility, 70–140 lines. Small files can be edited
-surgically; monoliths get rewritten wholesale and lose the changes that were
-already working. When you add a mechanic, add a script.
-
-```
-TouchRules --touch-scored/touch-damaged--> GameRules --score-changed--> ScoreHud
-                                                     --lives-changed-->
-                                                     --time-changed-->
-```
+# Tapper 2D
+
+A playable skeleton: objects fall into the field, tapping them is the whole
+game, one bad type punishes, and a countdown ends the run. It plays as
+shipped — press play in `scenes/main.pix3scene` before changing anything.
+
+**`design/recipe.md` is the contract.** Stable node ids, tunables with ranges,
+extension points and what must not be renamed. Read it first.
+
+## Layout
+
+```
+scenes/menu.pix3scene       entry / export scene — PLAY transitions to the game
+scenes/main.pix3scene       the GAME (editor startup scene — iterate here)
+scenes/ui/result.pix3scene  win/lose overlay, instanced into main hidden (editor-only)
+scenes/prefabs/*.pix3scene  what the spawners instantiate
+scripts/Spawner.ts          timed instantiate + drift + despawn
+scripts/TouchRules.ts       a tap → semantic signals
+scripts/ScoreHud.ts         signals → HUD widgets
+scripts/GameRules.ts        score / lives / timer / win / lose / end flow
+scripts/MenuFlow.ts         menu PLAY button
+sprites/ph-*.png            near-white placeholders (tinted via core:tint)
+```
+
+Same script names and roles as the other recipes — `Spawner`, `TouchRules`,
+`ScoreHud`, `GameRules` mean the same thing everywhere, only their contact
+source differs (here: a pointer-down hit-test instead of a proximity test).
+
+## The rule that keeps it workable
+
+One file, one responsibility, 70–140 lines. Small files can be edited
+surgically; monoliths get rewritten wholesale and lose the changes that were
+already working. When you add a mechanic, add a script.
+
+```
+TouchRules --touch-scored/touch-damaged--> GameRules --score-changed--> ScoreHud
+                                                     --lives-changed-->
+                                                     --time-changed-->
+```