@pix3/cli 1.6.0 → 1.6.2

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

@@ -1,132 +1,132 @@
-# Recipe: recipe-tapper-2d
-
-## What this is
-
-Objects fall into a field; tapping them is the whole game. One "bad" type
-punishes instead of scoring. A countdown ends the run and a target score decides
-win or lose. Playable before any edit.
-
-Same script names and roles as the other recipes — `Spawner`, `TouchRules`,
-`ScoreHud`, `GameRules` — so what you learn here transfers.
-
-## Node map
-
-| id | what |
-| --- | --- |
-| `game-root` | root; hosts `GameRules` + `TouchRules`; all HUD signals emitted here |
-| `game-background` | full-screen `ColorRect2D` (palette background) |
-| `board` | the field (`Group2D`) |
-| `board-floor` | the field's visible plate |
-| `spawner-targets` | spawn band for tappable things; hosts `Spawner` |
-| `spawner-hazards` | spawn band for the bad type; hosts `Spawner` |
-| `hud` | `CanvasLayer2D` overlay, hosts `ScoreHud` |
-| `score-label` / `time-label` / `lives-bar` / `menu-button` | HUD |
-| `result-overlay` / `result-label` / `retry-button` | end screen in `scenes/ui/result.pix3scene`, instanced into main hidden (`visible: false` is editor-only) |
-
-Signals: `TouchRules` emits `touch-scored` / `touch-damaged` on `game-root`;
-`GameRules` answers `score-changed`, `lives-changed`, `time-changed`,
-`game-won` / `game-lost`.
-
-## Placeholders
-
-Near-white PNGs carrying a `core:tint` effect: set `effects[0].params.color` and
-the multiply gives you that palette colour.
-
-| role | file | node/prefab |
-| --- | --- | --- |
-| collectible | `sprites/ph-target.png` | `prefabs/target.pix3scene` |
-| threat | `sprites/ph-hazard.png` | `prefabs/hazard.pix3scene` |
-
-## Tunables
-
-```yaml
-tunables:
-  targetRate: { node: spawner-targets, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 0.85 }
-  targetMaxAlive: { node: spawner-targets, component: "user:Spawner", property: maxAlive, min: 1, max: 200, default: 8 }
-  targetFallSpeed: { node: spawner-targets, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -230 }
-  targetLifetime: { node: spawner-targets, component: "user:Spawner", property: lifetimeSec, min: 0, max: 120, default: 8 }
-  hazardRate: { node: spawner-hazards, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 2.2 }
-  hazardFallSpeed: { node: spawner-hazards, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -260 }
-  tapRadius: { node: game-root, component: "user:TouchRules", property: tapRadius, min: 0, max: 400, default: 40 }
-  missPenalty: { node: game-root, component: "user:TouchRules", property: missPenalty, min: 0, max: 10, default: 0 }
-  touchRules: { node: game-root, component: "user:TouchRules", property: rules, default: "target:score:1;hazard:damage:1" }
-  winMode: { node: game-root, component: "user:GameRules", property: winMode, default: time }
-  targetScore: { node: game-root, component: "user:GameRules", property: targetScore, min: 1, max: 99999, default: 18 }
-  timeLimitSec: { node: game-root, component: "user:GameRules", property: timeLimitSec, min: 0, max: 600, default: 30 }
-  startingLives: { node: game-root, component: "user:GameRules", property: startingLives, min: 1, max: 20, default: 3 }
-  bgColor: { node: game-background, property: color, default: "#141a2e" }
-  boardColor: { node: board-floor, property: color, default: "#1d2743" }
-```
-
-`component` present → `set_component_property`; absent → `set_property`. The
-schema clamps out-of-range values rather than rejecting them.
-
-## Extension points
-
-- **Popping instead of falling (whack-a-mole).** Set `targetFallSpeed: 0` and
-  `targetLifetime` to ~1.2 s: things appear in place and vanish if not tapped.
-  Set `gridSnap` on the spawner (e.g. 220) and raise `spawnHeight` to get a mole
-  grid instead of a band.
-- **Combos / multipliers.** A new script on `hud` that listens for
-  `touch-scored` on `game-root`, counts hits inside a time window, and adds
-  only the **extra** points: `game-root.emit('touch-scored', amount * (m - 1), x, y)`
-  under a re-entrancy guard (`if (this.emitting) return; this.emitting = true;
-  try { emit(...) } finally { this.emitting = false; }`). `GameRules` already
-  counted the base `amount` and needs no change. Show the multiplier through a
-  signal of its own (`combo-changed`), never through `touch-scored`.
-  **The trap:** a listener on `touch-scored` that emits `touch-scored` on the
-  same node is called again by its own emit — without the guard, the first tap
-  recurses until the stack overflows (and re-emitting the *full* amount would
-  double-count the base). No offline check sees it: `pix3 check` and
-  `pix3 smoke` are green, because smoke taps nothing. Say so, and have the human
-  tap three targets in a row.
-- **A third type.** Copy a prefab, give its `core:Hitbox2D` a new group, add a
-  node with a third `Spawner` (`create_node` + `add_component`), and append
-  `<group>:score:5` to `touchRules`.
-- **Punish misses.** Raise `missPenalty` — a tap that hits nothing then costs a
-  life, which turns a relaxed collector into a precision game.
-- **Sudden death.** `startingLives: 1`, or `winMode: survive` with a longer
-  `timeLimitSec` so surviving the clock is the win.
-
-Replacing a whole script the list above names is expected: use `fs_write` with
-`overwrite: true` and a short `reason` (the size guard only blocks *silent*
-wholesale rewrites).
-
-## Ending a run belongs to GameRules
-
-The result overlay and RETRY are **owned by `GameRules`**: it hides the overlay on
-start and keeps `retry-button` **disabled**, then `finish(won)` shows the overlay,
-writes the result text, enables RETRY and freezes the `freezeNodes` subtrees
-(every component on them and on what they spawned). For a custom
-win/lose condition call `finish(true|false)` on that component — do NOT show the
-overlay yourself. A hand-rolled ending leaves RETRY on screen with its handler bound
-and `enabled: false`, i.e. a button that can never be pressed (`game_observe` reports
-`control: { enabled: false }`; that is the tell).
-
-## Do not touch
-
-- The node ids above (rename `name`, never `id`), and the signal names.
-- Component config on a **prefab instance** — the editor locks it. Prefabs carry
-  fixed defaults only (their hitbox group); tunables live on plain nodes in
-  `main.pix3scene`.
-- The prefab hitbox groups must stay in sync with `touchRules`; the group is the
-  only thing that separates "good" from "bad".
-
-## Playtest contract
-
-terminalVisual: static
-terminalRestartRoutine: terminal-retry
-
-After the result overlay appears, the screen should remain still until RETRY. The
-playtest samples five rendered frames at 15-frame intervals after the terminal
-phase has held for 120 frames. The `terminal-retry` routine physically taps RETRY
-and checks that the game returns to its playing phase.
-
-## Verify
-
-1. `play_start` on `scenes/main.pix3scene`.
-2. After ~2 s, children exist under `spawner-targets` and are falling.
-3. `game_input` a tap on one of them → it disappears, `score-label` climbs, and
-   the punch-scale fires.
-4. Tap three hazards → `lives-bar` empties and `result-overlay` shows
-   `GAME OVER`; `retry-button` restarts the scene.
+# Recipe: recipe-tapper-2d
+
+## What this is
+
+Objects fall into a field; tapping them is the whole game. One "bad" type
+punishes instead of scoring. A countdown ends the run and a target score decides
+win or lose. Playable before any edit.
+
+Same script names and roles as the other recipes — `Spawner`, `TouchRules`,
+`ScoreHud`, `GameRules` — so what you learn here transfers.
+
+## Node map
+
+| id | what |
+| --- | --- |
+| `game-root` | root; hosts `GameRules` + `TouchRules`; all HUD signals emitted here |
+| `game-background` | full-screen `ColorRect2D` (palette background) |
+| `board` | the field (`Group2D`) |
+| `board-floor` | the field's visible plate |
+| `spawner-targets` | spawn band for tappable things; hosts `Spawner` |
+| `spawner-hazards` | spawn band for the bad type; hosts `Spawner` |
+| `hud` | `CanvasLayer2D` overlay, hosts `ScoreHud` |
+| `score-label` / `time-label` / `lives-bar` / `menu-button` | HUD |
+| `result-overlay` / `result-label` / `retry-button` | end screen in `scenes/ui/result.pix3scene`, instanced into main hidden (`visible: false` is editor-only) |
+
+Signals: `TouchRules` emits `touch-scored` / `touch-damaged` on `game-root`;
+`GameRules` answers `score-changed`, `lives-changed`, `time-changed`,
+`game-won` / `game-lost`.
+
+## Placeholders
+
+Near-white PNGs carrying a `core:tint` effect: set `effects[0].params.color` and
+the multiply gives you that palette colour.
+
+| role | file | node/prefab |
+| --- | --- | --- |
+| collectible | `sprites/ph-target.png` | `prefabs/target.pix3scene` |
+| threat | `sprites/ph-hazard.png` | `prefabs/hazard.pix3scene` |
+
+## Tunables
+
+```yaml
+tunables:
+  targetRate: { node: spawner-targets, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 0.85 }
+  targetMaxAlive: { node: spawner-targets, component: "user:Spawner", property: maxAlive, min: 1, max: 200, default: 8 }
+  targetFallSpeed: { node: spawner-targets, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -230 }
+  targetLifetime: { node: spawner-targets, component: "user:Spawner", property: lifetimeSec, min: 0, max: 120, default: 8 }
+  hazardRate: { node: spawner-hazards, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 2.2 }
+  hazardFallSpeed: { node: spawner-hazards, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -260 }
+  tapRadius: { node: game-root, component: "user:TouchRules", property: tapRadius, min: 0, max: 400, default: 40 }
+  missPenalty: { node: game-root, component: "user:TouchRules", property: missPenalty, min: 0, max: 10, default: 0 }
+  touchRules: { node: game-root, component: "user:TouchRules", property: rules, default: "target:score:1;hazard:damage:1" }
+  winMode: { node: game-root, component: "user:GameRules", property: winMode, default: time }
+  targetScore: { node: game-root, component: "user:GameRules", property: targetScore, min: 1, max: 99999, default: 18 }
+  timeLimitSec: { node: game-root, component: "user:GameRules", property: timeLimitSec, min: 0, max: 600, default: 30 }
+  startingLives: { node: game-root, component: "user:GameRules", property: startingLives, min: 1, max: 20, default: 3 }
+  bgColor: { node: game-background, property: color, default: "#141a2e" }
+  boardColor: { node: board-floor, property: color, default: "#1d2743" }
+```
+
+`component` present → `set_component_property`; absent → `set_property`. The
+schema clamps out-of-range values rather than rejecting them.
+
+## Extension points
+
+- **Popping instead of falling (whack-a-mole).** Set `targetFallSpeed: 0` and
+  `targetLifetime` to ~1.2 s: things appear in place and vanish if not tapped.
+  Set `gridSnap` on the spawner (e.g. 220) and raise `spawnHeight` to get a mole
+  grid instead of a band.
+- **Combos / multipliers.** A new script on `hud` that listens for
+  `touch-scored` on `game-root`, counts hits inside a time window, and adds
+  only the **extra** points: `game-root.emit('touch-scored', amount * (m - 1), x, y)`
+  under a re-entrancy guard (`if (this.emitting) return; this.emitting = true;
+  try { emit(...) } finally { this.emitting = false; }`). `GameRules` already
+  counted the base `amount` and needs no change. Show the multiplier through a
+  signal of its own (`combo-changed`), never through `touch-scored`.
+  **The trap:** a listener on `touch-scored` that emits `touch-scored` on the
+  same node is called again by its own emit — without the guard, the first tap
+  recurses until the stack overflows (and re-emitting the *full* amount would
+  double-count the base). No offline check sees it: `pix3 check` and
+  `pix3 smoke` are green, because smoke taps nothing. Say so, and have the human
+  tap three targets in a row.
+- **A third type.** Copy a prefab, give its `core:Hitbox2D` a new group, add a
+  node with a third `Spawner` (`create_node` + `add_component`), and append
+  `<group>:score:5` to `touchRules`.
+- **Punish misses.** Raise `missPenalty` — a tap that hits nothing then costs a
+  life, which turns a relaxed collector into a precision game.
+- **Sudden death.** `startingLives: 1`, or `winMode: survive` with a longer
+  `timeLimitSec` so surviving the clock is the win.
+
+Replacing a whole script the list above names is expected: use `fs_write` with
+`overwrite: true` and a short `reason` (the size guard only blocks *silent*
+wholesale rewrites).
+
+## Ending a run belongs to GameRules
+
+The result overlay and RETRY are **owned by `GameRules`**: it hides the overlay on
+start and keeps `retry-button` **disabled**, then `finish(won)` shows the overlay,
+writes the result text, enables RETRY and freezes the `freezeNodes` subtrees
+(every component on them and on what they spawned). For a custom
+win/lose condition call `finish(true|false)` on that component — do NOT show the
+overlay yourself. A hand-rolled ending leaves RETRY on screen with its handler bound
+and `enabled: false`, i.e. a button that can never be pressed (`game_observe` reports
+`control: { enabled: false }`; that is the tell).
+
+## Do not touch
+
+- The node ids above (rename `name`, never `id`), and the signal names.
+- Component config on a **prefab instance** — the editor locks it. Prefabs carry
+  fixed defaults only (their hitbox group); tunables live on plain nodes in
+  `main.pix3scene`.
+- The prefab hitbox groups must stay in sync with `touchRules`; the group is the
+  only thing that separates "good" from "bad".
+
+## Playtest contract
+
+terminalVisual: static
+terminalRestartRoutine: terminal-retry
+
+After the result overlay appears, the screen should remain still until RETRY. The
+playtest samples five rendered frames at 15-frame intervals after the terminal
+phase has held for 120 frames. The `terminal-retry` routine physically taps RETRY
+and checks that the game returns to its playing phase.
+
+## Verify
+
+1. `play_start` on `scenes/main.pix3scene`.
+2. After ~2 s, children exist under `spawner-targets` and are falling.
+3. `game_input` a tap on one of them → it disappears, `score-label` climbs, and
+   the punch-scale fires.
+4. Tap three hazards → `lives-bar` empties and `result-overlay` shows
+   `GAME OVER`; `retry-button` restarts the scene.

package/templates/recipe-tapper-2d/files/design/tests/reachability.json

@@ -1,4 +1,4 @@
-{
-  "version": 1,
-  "proven": []
-}
+{
+  "version": 1,
+  "proven": []
+}

package/templates/recipe-tapper-2d/files/design/tests/routines/terminal-retry.json

@@ -1,23 +1,23 @@
-{
-  "name": "terminal-retry",
-  "description": "From the result screen, physically tap RETRY and check that play resumes.",
-  "scope": "scenes/main.pix3scene",
-  "params": {},
-  "uses": ["result-overlay", "retry-button"],
-  "steps": [
-    {
-      "type": "tap",
-      "target": "retry-button",
-      "holdMs": 200,
-      "why": "A real pointer press proves the button is visible, enabled and reachable."
-    },
-    {
-      "type": "wait",
-      "frames": 30,
-      "why": "Let the scene transition finish before reading the new game's phase."
-    }
-  ],
-  "expect": [
-    { "kind": "gameState", "path": "phase", "op": "eq", "value": "playing" }
-  ]
-}
+{
+  "name": "terminal-retry",
+  "description": "From the result screen, physically tap RETRY and check that play resumes.",
+  "scope": "scenes/main.pix3scene",
+  "params": {},
+  "uses": ["result-overlay", "retry-button"],
+  "steps": [
+    {
+      "type": "tap",
+      "target": "retry-button",
+      "holdMs": 200,
+      "why": "A real pointer press proves the button is visible, enabled and reachable."
+    },
+    {
+      "type": "wait",
+      "frames": 30,
+      "why": "Let the scene transition finish before reading the new game's phase."
+    }
+  ],
+  "expect": [
+    { "kind": "gameState", "path": "phase", "op": "eq", "value": "playing" }
+  ]
+}