@pix3/cli 1.6.0 → 1.6.2

package/templates/recipe-blank-2d/files/scripts/ScoreHud.ts

@@ -1,110 +1,110 @@
-/**
- * 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.
- *
- * With `GameRules.timeLimitSec` at 0 there is no clock, and `time-changed` carries
- * ELAPSED seconds instead — the label counts up. Set a limit and it counts down.
- */
-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.
+ *
+ * With `GameRules.timeLimitSec` at 0 there is no clock, and `time-changed` carries
+ * ELAPSED seconds instead — the label counts up. Set a limit and it counts down.
+ */
+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-blank-2d/template.yaml

@@ -1,10 +1,10 @@
-id: recipe-blank-2d
-title: Blank 2D
-description: No mechanics on purpose — an empty field with score, lives, timer, a HUD and a win/lose overlay already wired. For an idea whose core loop is not what any other recipe ships (grid or turn-based movement, word/card/board games, builders, idle); the first increment builds the mechanic itself, controls included.
-projectType: 2d
-targetPlatform: universal
-viewport: { width: 1080, height: 1920 }
-# No `entryScene`: this recipe ships ONE scene, and the whole point is that nothing
-# stands between opening the project and the gameplay. Add a menu later (see
-# design/recipe.md → Extension points) and set it in Project Settings then.
-order: 64
+id: recipe-blank-2d
+title: Blank 2D
+description: No mechanics on purpose — an empty field with score, lives, timer, a HUD and a win/lose overlay already wired. For an idea whose core loop is not what any other recipe ships (grid or turn-based movement, word/card/board games, builders, idle); the first increment builds the mechanic itself, controls included.
+projectType: 2d
+targetPlatform: universal
+viewport: { width: 1080, height: 1920 }
+# No `entryScene`: this recipe ships ONE scene, and the whole point is that nothing
+# stands between opening the project and the gameplay. Add a menu later (see
+# design/recipe.md → Extension points) and set it in Project Settings then.
+order: 64

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

@@ -1,81 +1,81 @@
-# Bouncer 2D
-
-A playable skeleton: a ball under gravity, three bumpers, a paddle you steer,
-and a drain at the bottom that costs a life. It plays — and glows, pops and
-clicks — 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 (including the full pinball path), and what must not be
-renamed. Read it first.
-
-## The ball physics is in this project, by choice
-
-`scripts/ball-collision.ts` implements swept (continuous) circle-vs-segment and
-circle-vs-circle collision with fixed substeps — the ball's whole displacement
-is tested each substep, so no speed can skip a wall — and `scripts/BallBody.ts`
-builds the colliders every frame from the **live world transforms** of ordinary
-marker nodes. Rotate `paddle` in the inspector, animate it from a clip, or add
-flippers: the physics follows with no extra code. `core:Hitbox2D` is an
-axis-aligned overlap test that ignores rotation — never put it on the ball.
-
-The engine also ships a general 2D rigid-body solver (`core:PhysicsBody2D` +
-`core:Collider2D`, `scene.physics2d`) — reach for it when the game grows bodies
-that push each other (stacks, debris, several balls); one ball against static
-geometry is exactly what the swept solver here is for, and mixing the two on the
-same ball is a bug.
-
-Never `import` rapier here. It is a ~2 MB lazily-loaded wasm payload for 3D
-only, it is not needed for this, and it would blow the export budget.
-
-**Idle / builder variant (idle-pinball, plinko-tycoon):** the drain does not
-have to cost a life. Set `startingLives` high or make the drain relaunch the ball
-(`BallBody.resetBall()` after `ball-drained`) — a conveyor returning the ball
-forever — and let the player spend the hits' coins on more bumpers. The paddle
-can be deleted or hidden; the bumpers and the juice on `ball-hit` stay.
-
-## The neon look is three cheap ingredients
-
-1. **`post-fx` (a `PostProcess` node with `affect2D: true`)** — bloom picks up
-   whatever is already bright (the cyan `board-trim` strips, the bumper cores, the
-   gold paddle, the white ball) plus a light vignette. Bloom cannot invent
-   brightness: to make something glow, brighten its colour — don't just raise
-   `bloomIntensity`.
-2. **`bg-glow`** — `ColorRect2D` has no gradients, so the background glow is a
-   near-white radial-gradient PNG (`sprites/ph-bg.png`) tinted with `core:tint`,
-   sitting over the darkest `ColorRect2D`. The board floor is translucent so it
-   reads through the playfield.
-3. **`Label2D` glow** (`glowColor` / `glowStrength`) on the HUD. The HUD is a
-   `CanvasLayer2D`, which the runtime draws *after* post-processing and never
-   blooms — deliberately, so score text stays crisp. Its glow is canvas-drawn.
-
-Feel is engine one-liners, not code you have to write: `TouchRules` already calls
-`scene.audio.sfx` (procedural SFX — no audio assets in this project),
-`scene.juice.burst` / `floatText` / `punchScale` / `flash` / `shake` and
-`scene.time.hitstop` on contact, and `GameRules` plays a win/lose jingle. Spawn
-effects at board-space anchors: anything anchored to the HUD lands in the
-un-bloomed overlay band.
-
-## Layout
-
-```
-scenes/menu.pix3scene         entry / export scene   (menu-post-fx, glowing title)
-scenes/main.pix3scene         the GAME (editor startup scene — iterate here)
-scenes/ui/result.pix3scene    win/lose overlay, instanced into main hidden (editor-only)
-scripts/ball-collision.ts     pure swept-collision math (unit-tested)
-scripts/BallBody.ts           ball motion; colliders from marker world transforms
-scripts/PaddleController.ts   input → paddle             (swap this for flippers)
-scripts/TouchRules.ts         ball-hit → score / damage + sound, particles, popups
-scripts/ScoreHud.ts           signals → HUD widgets
-scripts/GameRules.ts          score / lives / win / lose / end flow + jingle
-scripts/MenuFlow.ts           menu PLAY button
-sprites/ph-*.png              near-white placeholders (tinted via core:tint)
-```
-
-Signals:
-
-```
-BallBody --ball-hit(kind,nodeId,speed,x,y)--> TouchRules
-TouchRules --touch-scored/touch-damaged--> GameRules --score-changed--> ScoreHud
-                                                     --lives-changed-->
-```
+# Bouncer 2D
+
+A playable skeleton: a ball under gravity, three bumpers, a paddle you steer,
+and a drain at the bottom that costs a life. It plays — and glows, pops and
+clicks — 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 (including the full pinball path), and what must not be
+renamed. Read it first.
+
+## The ball physics is in this project, by choice
+
+`scripts/ball-collision.ts` implements swept (continuous) circle-vs-segment and
+circle-vs-circle collision with fixed substeps — the ball's whole displacement
+is tested each substep, so no speed can skip a wall — and `scripts/BallBody.ts`
+builds the colliders every frame from the **live world transforms** of ordinary
+marker nodes. Rotate `paddle` in the inspector, animate it from a clip, or add
+flippers: the physics follows with no extra code. `core:Hitbox2D` is an
+axis-aligned overlap test that ignores rotation — never put it on the ball.
+
+The engine also ships a general 2D rigid-body solver (`core:PhysicsBody2D` +
+`core:Collider2D`, `scene.physics2d`) — reach for it when the game grows bodies
+that push each other (stacks, debris, several balls); one ball against static
+geometry is exactly what the swept solver here is for, and mixing the two on the
+same ball is a bug.
+
+Never `import` rapier here. It is a ~2 MB lazily-loaded wasm payload for 3D
+only, it is not needed for this, and it would blow the export budget.
+
+**Idle / builder variant (idle-pinball, plinko-tycoon):** the drain does not
+have to cost a life. Set `startingLives` high or make the drain relaunch the ball
+(`BallBody.resetBall()` after `ball-drained`) — a conveyor returning the ball
+forever — and let the player spend the hits' coins on more bumpers. The paddle
+can be deleted or hidden; the bumpers and the juice on `ball-hit` stay.
+
+## The neon look is three cheap ingredients
+
+1. **`post-fx` (a `PostProcess` node with `affect2D: true`)** — bloom picks up
+   whatever is already bright (the cyan `board-trim` strips, the bumper cores, the
+   gold paddle, the white ball) plus a light vignette. Bloom cannot invent
+   brightness: to make something glow, brighten its colour — don't just raise
+   `bloomIntensity`.
+2. **`bg-glow`** — `ColorRect2D` has no gradients, so the background glow is a
+   near-white radial-gradient PNG (`sprites/ph-bg.png`) tinted with `core:tint`,
+   sitting over the darkest `ColorRect2D`. The board floor is translucent so it
+   reads through the playfield.
+3. **`Label2D` glow** (`glowColor` / `glowStrength`) on the HUD. The HUD is a
+   `CanvasLayer2D`, which the runtime draws *after* post-processing and never
+   blooms — deliberately, so score text stays crisp. Its glow is canvas-drawn.
+
+Feel is engine one-liners, not code you have to write: `TouchRules` already calls
+`scene.audio.sfx` (procedural SFX — no audio assets in this project),
+`scene.juice.burst` / `floatText` / `punchScale` / `flash` / `shake` and
+`scene.time.hitstop` on contact, and `GameRules` plays a win/lose jingle. Spawn
+effects at board-space anchors: anything anchored to the HUD lands in the
+un-bloomed overlay band.
+
+## Layout
+
+```
+scenes/menu.pix3scene         entry / export scene   (menu-post-fx, glowing title)
+scenes/main.pix3scene         the GAME (editor startup scene — iterate here)
+scenes/ui/result.pix3scene    win/lose overlay, instanced into main hidden (editor-only)
+scripts/ball-collision.ts     pure swept-collision math (unit-tested)
+scripts/BallBody.ts           ball motion; colliders from marker world transforms
+scripts/PaddleController.ts   input → paddle             (swap this for flippers)
+scripts/TouchRules.ts         ball-hit → score / damage + sound, particles, popups
+scripts/ScoreHud.ts           signals → HUD widgets
+scripts/GameRules.ts          score / lives / win / lose / end flow + jingle
+scripts/MenuFlow.ts           menu PLAY button
+sprites/ph-*.png              near-white placeholders (tinted via core:tint)
+```
+
+Signals:
+
+```
+BallBody --ball-hit(kind,nodeId,speed,x,y)--> TouchRules
+TouchRules --touch-scored/touch-damaged--> GameRules --score-changed--> ScoreHud
+                                                     --lives-changed-->
+```