@pix3/cli 1.6.0 → 1.6.2

package/templates/playable-3d/files/scripts/ScoreHud.ts

@@ -1,113 +1,113 @@
-/**
- * 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.
- *
- * Identical to the one the 2D blank recipe ships, down to the signal names: the HUD is
- * 2D in both, because a 3D game's score is still read on a flat overlay.
- */
-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: 'hud-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.
+ *
+ * Identical to the one the 2D blank recipe ships, down to the signal names: the HUD is
+ * 2D in both, because a 3D game's score is still read on a flat overlay.
+ */
+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: 'hud-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/playable-3d/template.yaml

@@ -1,9 +1,9 @@
-id: playable-3d
-title: Playable 3D
-description: Portrait 3D playable-ad blank — tap-to-start intro (unlocks audio), gameplay placeholder, end screen with a store CTA button.
-# Flow recipe this template serves (see design/recipe.md).
-recipeId: recipe-scene-3d
-projectType: 3d
-targetPlatform: mobile
-viewport: { width: 1080, height: 1920 }
-order: 30
+id: playable-3d
+title: Playable 3D
+description: Portrait 3D playable-ad blank — tap-to-start intro (unlocks audio), gameplay placeholder, end screen with a store CTA button.
+# Flow recipe this template serves (see design/recipe.md).
+recipeId: recipe-scene-3d
+projectType: 3d
+targetPlatform: mobile
+viewport: { width: 1080, height: 1920 }
+order: 30

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

@@ -1,48 +1,48 @@
-# Arena 2D
-
-A playable skeleton: an avatar in a bounded field, two spawners dripping
-pickups and hazards, touch resolved into score or damage, lives + a timer, and a
-win/lose screen with RETRY / MENU. It plays as shipped — press play in
-`scenes/main.pix3scene` before changing anything.
-
-**`design/recipe.md` is the contract.** It lists the stable node ids, the
-tunables (with their ranges), the extension points and what must not be renamed.
-Read it first; tools and agents grep it.
-
-## 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
-scenes/prefabs/*.pix3scene  what the spawners instantiate
-scripts/PlayerController.ts how the avatar moves          (swap this file whole)
-scripts/Spawner.ts          timed instantiate + drift + despawn
-scripts/TouchRules.ts       contact → 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)
-```
-
-Full-screen UI lives in its own scene file, never inline in the game scene.
-`main.pix3scene` carries the end screen as a one-line `instance:` marked
-`visible: false` — that hides it in the **editor** only, so opening the project
-shows the game instead of a GAME OVER card. What play mode reads is
-`initiallyVisible`, authored in `scenes/ui/result.pix3scene`. Edit the overlay
-full-screen in its own tab (right-click → Open Prefab); tick the eye in
-`main.pix3scene` to preview it composited, and untick it before saving.
-
-## The rule that keeps it workable
-
-One file, one responsibility. Each script is 70–140 lines on purpose: 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.
-
-Signals are the seam between them:
-
-```
-TouchRules --touch-scored/touch-damaged--> GameRules --score-changed--> ScoreHud
-                                                     --lives-changed-->
-                                                     --time-changed-->
-```
+# Arena 2D
+
+A playable skeleton: an avatar in a bounded field, two spawners dripping
+pickups and hazards, touch resolved into score or damage, lives + a timer, and a
+win/lose screen with RETRY / MENU. It plays as shipped — press play in
+`scenes/main.pix3scene` before changing anything.
+
+**`design/recipe.md` is the contract.** It lists the stable node ids, the
+tunables (with their ranges), the extension points and what must not be renamed.
+Read it first; tools and agents grep it.
+
+## 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
+scenes/prefabs/*.pix3scene  what the spawners instantiate
+scripts/PlayerController.ts how the avatar moves          (swap this file whole)
+scripts/Spawner.ts          timed instantiate + drift + despawn
+scripts/TouchRules.ts       contact → 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)
+```
+
+Full-screen UI lives in its own scene file, never inline in the game scene.
+`main.pix3scene` carries the end screen as a one-line `instance:` marked
+`visible: false` — that hides it in the **editor** only, so opening the project
+shows the game instead of a GAME OVER card. What play mode reads is
+`initiallyVisible`, authored in `scenes/ui/result.pix3scene`. Edit the overlay
+full-screen in its own tab (right-click → Open Prefab); tick the eye in
+`main.pix3scene` to preview it composited, and untick it before saving.
+
+## The rule that keeps it workable
+
+One file, one responsibility. Each script is 70–140 lines on purpose: 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.
+
+Signals are the seam between them:
+
+```
+TouchRules --touch-scored/touch-damaged--> GameRules --score-changed--> ScoreHud
+                                                     --lives-changed-->
+                                                     --time-changed-->
+```

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

@@ -1,127 +1,127 @@
-# Recipe: recipe-arena-2d
-
-## What this is
-
-An avatar in a bounded field; two spawners drip things in; touching a thing
-resolves through a group→outcome map into score or damage. Lives, timer,
-win/lose screen with RETRY / MENU. Playable before any edit — start from what
-runs. This is the **fallback recipe**: anything shaped like "steer something
-around a space while stuff comes at you" starts here.
-
-## Node map
-
-| id | what |
-| --- | --- |
-| `game-root` | root; hosts `GameRules` + `TouchRules`; all HUD signals are emitted here |
-| `game-background` | full-screen `ColorRect2D` (palette background) |
-| `board` | the field (`Group2D`); its rect clamps the avatar |
-| `board-floor` | the field's visible plate |
-| `player` | avatar (`Sprite2D`), hosts `PlayerController` |
-| `spawner-pickups` / `spawner-hazards` | spawn bands, one `Spawner` each |
-| `hud` | `CanvasLayer2D` overlay, hosts `ScoreHud` |
-| `score-label` / `time-label` / `lives-bar` | HUD widgets, signal-driven only |
-| `menu-button` | back to the menu scene |
-| `result-overlay` / `result-label` / `retry-button` | end screen — authored in `scenes/ui/result.pix3scene`, instanced into `hud` with `visible: false` so the editor opens on the game; `initiallyVisible` and `GameRules` own it at run time |
-
-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 |
-| --- | --- | --- |
-| avatar | `sprites/ph-avatar.png` | `player` |
-| collectible | `sprites/ph-pickup.png` | `prefabs/pickup.pix3scene` |
-| threat | `sprites/ph-hazard.png` | `prefabs/hazard.pix3scene` |
-
-## Tunables
-
-```yaml
-tunables:
-  playerMode: { node: player, component: "user:PlayerController", property: mode, default: pointer }
-  playerSpeed: { node: player, component: "user:PlayerController", property: speed, min: 60, max: 2000, default: 620 }
-  playerRadius: { node: player, component: "user:PlayerController", property: radius, min: 4, max: 400, default: 60 }
-  pickupRate: { node: spawner-pickups, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 1.0 }
-  pickupMaxAlive: { node: spawner-pickups, component: "user:Spawner", property: maxAlive, min: 1, max: 200, default: 10 }
-  pickupFallSpeed: { node: spawner-pickups, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -300 }
-  hazardRate: { node: spawner-hazards, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 1.8 }
-  hazardFallSpeed: { node: spawner-hazards, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -380 }
-  touchRadius: { node: game-root, component: "user:TouchRules", property: touchRadius, min: 4, max: 600, default: 62 }
-  touchRules: { node: game-root, component: "user:TouchRules", property: rules, default: "pickup:score:1;hazard:damage:1" }
-  winMode: { node: game-root, component: "user:GameRules", property: winMode, default: score }
-  targetScore: { node: game-root, component: "user:GameRules", property: targetScore, min: 1, max: 99999, default: 12 }
-  timeLimitSec: { node: game-root, component: "user:GameRules", property: timeLimitSec, min: 0, max: 600, default: 45 }
-  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
-
-- **Different locomotion → replace `scripts/PlayerController.ts` wholesale.** It
-  is the only file that reads input and writes `player.position`. A grid stepper,
-  a jumper (velocity + gravity) or an auto-runner all drop in as long as the file
-  still exports a `PlayerController` class and keeps the node inside `board`.
-  Write it in ONE call — `fs_write` with `overwrite: true` and a `reason` (the
-  size guard refuses a silent wholesale rewrite; this one is sanctioned).
-- **Trail / body behind the avatar.** Add a `segment` prefab (`Sprite2D` +
-  `core:Hitbox2D` in a hazard group). In the locomotion script, on each completed
-  step `scene.instantiate` a segment at the vacated position into a `segments`
-  node and `queueFree` the tail once the trail exceeds its length. Self-collision
-  then falls out of the existing rules — the segment's group is already in
-  `touchRules`, so hitting your own trail costs a life with no new code. Grow the
-  trail by skipping the tail free on a `touch-scored` frame.
-- **A third kind of thing.** Copy a prefab, give its `core:Hitbox2D` a new group,
-  `create_node` + `add_component` a third `Spawner`, append `<group>:score:5` to
-  `touchRules`. Chasers: a script on the prefab that steers toward `player`'s
-  world position — contact is already punished. Spawn it under a spawner (the
-  default `parentNode`) listed in `freezeNodes`: `finish()` freezes that whole
-  subtree, so the chaser stops on game over. Parented elsewhere, it keeps
-  crawling over the result card — list that parent in `freezeNodes` too.
-- **More juice.** `scene.juice.punchScale/shake/flash` + `scene.time.hitstop` are
-  already called in `TouchRules`; raise the numbers there.
-
-## 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.
-- `visible: false` on the `result-overlay` instance in `main.pix3scene`. Tick the
-  eye to preview the end screen over the field, but never save it on: it is what
-  keeps every iteration from starting behind a GAME OVER card. Run-time
-  visibility is `initiallyVisible` in `scenes/ui/result.pix3scene`, not this.
-- 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`.
-- Do not import rapier: there is no rigidbody solver here and none is needed.
-
-## Playtest contract
-
-terminalVisual: static
-terminalRestartRoutine: terminal-retry
-
-## Verify
-
-1. `play_start` on `scenes/main.pix3scene`.
-2. `game_input` a pointer drag across the lower board — `player`'s position
-   changes between two `game_observe` calls.
-3. After ~3 s: children exist under `spawner-pickups`, and `score-label` climbs
-   above `SCORE 0` once the avatar meets one.
-4. Set `targetScore: 1`, replay, collect one → `result-overlay` visible with
-   `YOU WIN!`; `retry-button` restarts the scene.
+# Recipe: recipe-arena-2d
+
+## What this is
+
+An avatar in a bounded field; two spawners drip things in; touching a thing
+resolves through a group→outcome map into score or damage. Lives, timer,
+win/lose screen with RETRY / MENU. Playable before any edit — start from what
+runs. This is the **fallback recipe**: anything shaped like "steer something
+around a space while stuff comes at you" starts here.
+
+## Node map
+
+| id | what |
+| --- | --- |
+| `game-root` | root; hosts `GameRules` + `TouchRules`; all HUD signals are emitted here |
+| `game-background` | full-screen `ColorRect2D` (palette background) |
+| `board` | the field (`Group2D`); its rect clamps the avatar |
+| `board-floor` | the field's visible plate |
+| `player` | avatar (`Sprite2D`), hosts `PlayerController` |
+| `spawner-pickups` / `spawner-hazards` | spawn bands, one `Spawner` each |
+| `hud` | `CanvasLayer2D` overlay, hosts `ScoreHud` |
+| `score-label` / `time-label` / `lives-bar` | HUD widgets, signal-driven only |
+| `menu-button` | back to the menu scene |
+| `result-overlay` / `result-label` / `retry-button` | end screen — authored in `scenes/ui/result.pix3scene`, instanced into `hud` with `visible: false` so the editor opens on the game; `initiallyVisible` and `GameRules` own it at run time |
+
+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 |
+| --- | --- | --- |
+| avatar | `sprites/ph-avatar.png` | `player` |
+| collectible | `sprites/ph-pickup.png` | `prefabs/pickup.pix3scene` |
+| threat | `sprites/ph-hazard.png` | `prefabs/hazard.pix3scene` |
+
+## Tunables
+
+```yaml
+tunables:
+  playerMode: { node: player, component: "user:PlayerController", property: mode, default: pointer }
+  playerSpeed: { node: player, component: "user:PlayerController", property: speed, min: 60, max: 2000, default: 620 }
+  playerRadius: { node: player, component: "user:PlayerController", property: radius, min: 4, max: 400, default: 60 }
+  pickupRate: { node: spawner-pickups, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 1.0 }
+  pickupMaxAlive: { node: spawner-pickups, component: "user:Spawner", property: maxAlive, min: 1, max: 200, default: 10 }
+  pickupFallSpeed: { node: spawner-pickups, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -300 }
+  hazardRate: { node: spawner-hazards, component: "user:Spawner", property: intervalSec, min: 0.05, max: 20, default: 1.8 }
+  hazardFallSpeed: { node: spawner-hazards, component: "user:Spawner", property: driftY, min: -3000, max: 3000, default: -380 }
+  touchRadius: { node: game-root, component: "user:TouchRules", property: touchRadius, min: 4, max: 600, default: 62 }
+  touchRules: { node: game-root, component: "user:TouchRules", property: rules, default: "pickup:score:1;hazard:damage:1" }
+  winMode: { node: game-root, component: "user:GameRules", property: winMode, default: score }
+  targetScore: { node: game-root, component: "user:GameRules", property: targetScore, min: 1, max: 99999, default: 12 }
+  timeLimitSec: { node: game-root, component: "user:GameRules", property: timeLimitSec, min: 0, max: 600, default: 45 }
+  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
+
+- **Different locomotion → replace `scripts/PlayerController.ts` wholesale.** It
+  is the only file that reads input and writes `player.position`. A grid stepper,
+  a jumper (velocity + gravity) or an auto-runner all drop in as long as the file
+  still exports a `PlayerController` class and keeps the node inside `board`.
+  Write it in ONE call — `fs_write` with `overwrite: true` and a `reason` (the
+  size guard refuses a silent wholesale rewrite; this one is sanctioned).
+- **Trail / body behind the avatar.** Add a `segment` prefab (`Sprite2D` +
+  `core:Hitbox2D` in a hazard group). In the locomotion script, on each completed
+  step `scene.instantiate` a segment at the vacated position into a `segments`
+  node and `queueFree` the tail once the trail exceeds its length. Self-collision
+  then falls out of the existing rules — the segment's group is already in
+  `touchRules`, so hitting your own trail costs a life with no new code. Grow the
+  trail by skipping the tail free on a `touch-scored` frame.
+- **A third kind of thing.** Copy a prefab, give its `core:Hitbox2D` a new group,
+  `create_node` + `add_component` a third `Spawner`, append `<group>:score:5` to
+  `touchRules`. Chasers: a script on the prefab that steers toward `player`'s
+  world position — contact is already punished. Spawn it under a spawner (the
+  default `parentNode`) listed in `freezeNodes`: `finish()` freezes that whole
+  subtree, so the chaser stops on game over. Parented elsewhere, it keeps
+  crawling over the result card — list that parent in `freezeNodes` too.
+- **More juice.** `scene.juice.punchScale/shake/flash` + `scene.time.hitstop` are
+  already called in `TouchRules`; raise the numbers there.
+
+## 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.
+- `visible: false` on the `result-overlay` instance in `main.pix3scene`. Tick the
+  eye to preview the end screen over the field, but never save it on: it is what
+  keeps every iteration from starting behind a GAME OVER card. Run-time
+  visibility is `initiallyVisible` in `scenes/ui/result.pix3scene`, not this.
+- 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`.
+- Do not import rapier: there is no rigidbody solver here and none is needed.
+
+## Playtest contract
+
+terminalVisual: static
+terminalRestartRoutine: terminal-retry
+
+## Verify
+
+1. `play_start` on `scenes/main.pix3scene`.
+2. `game_input` a pointer drag across the lower board — `player`'s position
+   changes between two `game_observe` calls.
+3. After ~3 s: children exist under `spawner-pickups`, and `score-label` climbs
+   above `SCORE 0` once the avatar meets one.
+4. Set `targetScore: 1`, replay, collect one → `result-overlay` visible with
+   `YOU WIN!`; `retry-button` restarts the scene.