@pix3/cli 1.6.0

package/templates/recipe-arena-2d/files/scripts/TouchRules.ts

@@ -0,0 +1,174 @@
+/**
+ * TouchRules — turns contact into meaning.
+ *
+ * Every frame it overlap-tests a circle around the player against the
+ * `core:Hitbox2D` groups listed in `rules`, and for each hit emits a SEMANTIC
+ * signal on its own node (`game-root`):
+ *
+ *   `touch-scored`  (amount, x, y)
+ *   `touch-damaged` (amount, x, y)
+ *
+ * It never touches the score, the lives or the HUD — `GameRules` owns those and
+ * listens for these two signals. Add an outcome by adding a rule here and a
+ * listener there; nothing else has to change.
+ *
+ * `rules` format: `group:outcome:amount`, entries separated by `;`.
+ * Outcomes: `score` | `damage`. Example: `pickup:score:1;hazard:damage:1`.
+ */
+import { Script, type PropertySchema } from '@pix3/runtime';
+
+type TouchOutcome = 'score' | 'damage';
+
+interface TouchRule {
+  group: string;
+  outcome: TouchOutcome;
+  amount: number;
+}
+
+function parseRules(text: string): TouchRule[] {
+  const rules: TouchRule[] = [];
+  for (const entry of text.split(';')) {
+    const parts = entry.trim().split(':');
+    if (parts.length < 2 || !parts[0].trim()) {
+      continue;
+    }
+    const outcome: TouchOutcome = parts[1].trim() === 'damage' ? 'damage' : 'score';
+    const amount = Number(parts[2] ?? 1);
+    rules.push({
+      group: parts[0].trim(),
+      outcome,
+      amount: Number.isFinite(amount) && amount > 0 ? amount : 1,
+    });
+  }
+  return rules;
+}
+
+export class TouchRules extends Script {
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      // Node id/name whose world position is the centre of the overlap test.
+      playerNode: 'player',
+      // Radius of the overlap test, in logical pixels.
+      touchRadius: 62,
+      // group:outcome:amount pairs, separated by ';'.
+      rules: 'pickup:score:1;hazard:damage:1',
+      // Free the touched node after resolving it.
+      consume: true,
+      // res:// audio paths; empty = silent.
+      scoreSound: '',
+      damageSound: '',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    return {
+      nodeType: 'TouchRules',
+      properties: [
+        {
+          name: 'playerNode',
+          type: 'string',
+          ui: { label: 'Player Node', group: 'Contact' },
+          getValue: s => (s as TouchRules).config.playerNode,
+          setValue: (s, v) => {
+            (s as TouchRules).config.playerNode = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'touchRadius',
+          type: 'number',
+          ui: { label: 'Touch Radius', group: 'Contact', min: 4, max: 600, step: 1, slider: true },
+          getValue: s => (s as TouchRules).config.touchRadius,
+          setValue: (s, v) => {
+            const n = Number(v);
+            (s as TouchRules).config.touchRadius = Math.min(600, Math.max(4, Number.isFinite(n) ? n : 4));
+          },
+        },
+        {
+          name: 'rules',
+          type: 'string',
+          ui: {
+            label: 'Rules',
+            description: "group:outcome:amount, ';'-separated. Outcome is score or damage.",
+            group: 'Contact',
+          },
+          getValue: s => (s as TouchRules).config.rules,
+          setValue: (s, v) => {
+            (s as TouchRules).config.rules = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'consume',
+          type: 'boolean',
+          ui: { label: 'Consume On Touch', group: 'Contact' },
+          getValue: s => (s as TouchRules).config.consume,
+          setValue: (s, v) => {
+            (s as TouchRules).config.consume = Boolean(v);
+          },
+        },
+        {
+          name: 'scoreSound',
+          type: 'string',
+          ui: { label: 'Score Sound', group: 'Feedback', editor: 'audio-resource' },
+          getValue: s => (s as TouchRules).config.scoreSound,
+          setValue: (s, v) => {
+            (s as TouchRules).config.scoreSound = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'damageSound',
+          type: 'string',
+          ui: { label: 'Damage Sound', group: 'Feedback', editor: 'audio-resource' },
+          getValue: s => (s as TouchRules).config.damageSound,
+          setValue: (s, v) => {
+            (s as TouchRules).config.damageSound = typeof v === 'string' ? v : '';
+          },
+        },
+      ],
+      groups: {
+        Contact: { label: 'Contact', expanded: true },
+        Feedback: { label: 'Feedback', expanded: false },
+      },
+    };
+  }
+
+  onUpdate(): void {
+    const scene = this.scene;
+    const owner = this.node;
+    const player = this.findNode(String(this.config.playerNode ?? ''));
+    if (!scene || !owner || !player) {
+      return;
+    }
+
+    player.updateWorldMatrix(true, false);
+    const px = player.matrixWorld.elements[12];
+    const py = player.matrixWorld.elements[13];
+    const radius = Math.max(1, Number(this.config.touchRadius) || 1);
+    const consume = Boolean(this.config.consume);
+
+    for (const rule of parseRules(String(this.config.rules ?? ''))) {
+      for (const hit of scene.collision2d.overlapCircle(px, py, radius, rule.group)) {
+        if (rule.outcome === 'damage') {
+          owner.emit('touch-damaged', rule.amount, hit.x, hit.y);
+          scene.juice.shake(player, { amplitude: 16, duration: 0.25 });
+          scene.juice.flash({ color: '#ff4d6d', intensity: 0.4, durationSec: 0.22 });
+          this.playSound(String(this.config.damageSound ?? ''));
+        } else {
+          owner.emit('touch-scored', rule.amount, hit.x, hit.y);
+          scene.juice.punchScale(player, { amount: 0.22, duration: 0.22 });
+          this.playSound(String(this.config.scoreSound ?? ''));
+        }
+        if (consume) {
+          hit.node.queueFree();
+        }
+      }
+    }
+  }
+
+  private playSound(path: string): void {
+    if (!path) {
+      return;
+    }
+    void this.scene?.audio.play(path, { bus: 'sfx', pitchVariation: 0.08 });
+  }
+}

package/templates/recipe-arena-2d/template.yaml

@@ -0,0 +1,10 @@
+id: recipe-arena-2d
+title: Arena 2D
+description: An avatar you steer inside a bounded field while spawners drip pickups and hazards; touch turns into score or damage, with lives, a timer and a win/lose flow. Dodgers, collectors, top-down survival, and (by swapping the movement script) runners. Its steering is continuous, so a grid or turn-based game (snake, sokoban) starts from Blank 2D instead.
+projectType: 2d
+targetPlatform: universal
+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 game).
+entryScene: scenes/menu.pix3scene
+order: 60

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

@@ -0,0 +1,61 @@
+# Blank 2D
+
+Everything a run needs **except the mechanic**: a bounded field, a HUD, score /
+lives / timer bookkeeping, and a win/lose screen with RETRY. Press play in
+`scenes/main.pix3scene` and you get an empty field with `SCORE 0` — that is
+correct, and it is the point.
+
+Use this when the game's core loop is not what another recipe ships (grid or
+turn-based movement, word / card / board games, builders, idle). The first thing
+to build is the mechanic itself, controls included; building it here beats
+deleting somebody else's mechanic first. A falling, bouncing ball is the bouncer
+recipe's job — do not rebuild that here.
+
+The field is not grey: `post-fx` blooms anything bright and `bg-glow` lights the
+background, and `sprites/ph-*.png` is a shape library (disc, orb, ring, star,
+capsule) tinted with the palette at T0. Build the mechanic out of those shapes,
+not out of `ColorRect2D` squares — see `design/recipe.md` → Placeholders.
+
+**`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/main.pix3scene    the game — open and build here. There is no menu on purpose.
+scenes/ui/result.pix3scene  win/lose overlay, instanced into main hidden (editor-only)
+scripts/GameRules.ts     score / lives / timer / win / lose / end flow / restart
+scripts/ScoreHud.ts      signals → HUD widgets (display only)
+sprites/ph-*.png         shape library (near-white, tinted via core:tint)
+design/recipe.md         the contract
+design/tests/            reachability ledger + one example routine (a format seed)
+```
+
+## How your mechanic plugs in
+
+Write a script, attach it to a node inside `board`, and score through
+`GameRules` — either by emitting on `game-root`:
+
+```ts
+this.findNode('game-root')?.emit('score-added', 1);
+this.findNode('game-root')?.emit('life-lost', 1);
+```
+
+…or by calling the component directly (`addScore`, `loseLife`, `finish`). The
+HUD, the end screen and RETRY then work with no further wiring.
+
+## The rule that keeps it workable
+
+One file, one responsibility. Keep each script in the 70–140 line range: small
+files can be edited surgically; monoliths get rewritten wholesale and lose the
+comments that explained them. When a mechanic outgrows its file, split it rather
+than growing it.
+
+## No menu yet
+
+A menu is a screen between you and the thing you are working on. Add one only
+once the game is fun: create `scenes/menu.pix3scene`, have its PLAY button
+`scene.changeScene('res://scenes/main.pix3scene', {transition: 'fade'})`, then
+point Project Settings → Default Export Scene Path at it. `Play Scene` keeps
+running whatever scene is open, so the menu never gets in the way again.

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

@@ -0,0 +1,148 @@
+# Recipe: recipe-blank-2d
+
+## What this is
+
+**Nothing plays yet, on purpose.** A bounded field, a HUD, and score / lives /
+timer / win-lose bookkeeping that already works — and no mechanic of any kind,
+including controls.
+
+Pick this recipe when the idea's core loop is not what another recipe ships:
+grid or turn-based movement (snake, sokoban, match-3), word / card / board games,
+builders, idle games without a ball. **Your first increment is the core
+mechanic itself, controls included** — that is the trade being made here, and it
+beats spending the first increment deleting somebody else's mechanic.
+
+Everything *around* the mechanic is done: you never hand-roll a score counter, a
+lives bar, a timer, an end screen or a retry. The look is done too: `post-fx`
+blooms anything bright and `bg-glow` lights the field, so a sprite tinted with a
+palette accent already glows on the first frame.
+
+## Node map
+
+| id | what |
+| --- | --- |
+| `post-fx` | `PostProcess` (`affect2D`): bloom + vignette — tune, never delete |
+| `game-root` | root; hosts `GameRules`; every HUD signal is emitted here |
+| `game-background` | full-screen `ColorRect2D` (palette background) |
+| `bg-glow` | full-screen `Sprite2D`, the tinted radial gradient over it |
+| `board` | the play field (`Group2D`) — **build your mechanic inside this** |
+| `board-floor` | the field's visible plate; its rect is the field's extent |
+| `hud` | `CanvasLayer2D` overlay, hosts `ScoreHud` |
+| `score-label` / `time-label` / `lives-bar` | HUD widgets, signal-driven only |
+| `result-overlay` / `result-dim` / `result-label` / `retry-button` | end screen, own file `scenes/ui/result.pix3scene`; instanced into main with `visible: false` (editor-only hide — `GameRules` shows it) |
+
+Signals on `game-root`: your mechanic emits `score-added` (amount) and
+`life-lost` (amount); `GameRules` answers `score-changed`, `lives-changed`,
+`time-changed`, and `game-won` / `game-lost`.
+
+There is **one gameplay scene** (`scenes/main.pix3scene`) and no menu — see
+Extension points if the game eventually needs one.
+
+## Placeholders
+
+A **shape library**, not entities: near-white PNGs already tinted with the
+palette at T0 (the role column decides the colour). Put them on a `Sprite2D`
+sized to the thing they stand for, and recolour with `effects: [{type: core:tint,
+params: {color}}]` when you need another accent. **A round thing is
+`ph-circle`/`ph-orb`, a coin or bumper is `ph-ring`, a bar or paddle is
+`ph-capsule`, a spark or star is `ph-star`.** A `ColorRect2D` is for panels,
+floors and bars — never for a ball, a coin, an enemy or anything the player
+looks at: a square ball on the first frame is what the user remembers. Real art
+replaces these through `generate_asset` in the art pass.
+
+| role | file | node/prefab |
+| --- | --- | --- |
+| background | `sprites/ph-bg.png` | `bg-glow` (radial gradient) |
+| player | `sprites/ph-circle.png` | (library — a solid disc with a soft edge) |
+| avatar | `sprites/ph-orb.png` | (library — a disc with a bright rim) |
+| collectible | `sprites/ph-ring.png` | (library — a ring; bumpers, coins, targets) |
+| hazard | `sprites/ph-star.png` | (library — a four-point spark) |
+| ui | `sprites/ph-capsule.png` | (library — a rounded bar; paddles, platforms, pills) |
+
+## Tunables
+
+```yaml
+tunables:
+  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: 10 }
+  timeLimitSec: { node: game-root, component: "user:GameRules", property: timeLimitSec, min: 0, max: 600, default: 0 }
+  startingLives: { node: game-root, component: "user:GameRules", property: startingLives, min: 1, max: 20, default: 3 }
+  bgColor: { node: game-background, property: color, default: "#12141c" }
+  boardColor: { node: board-floor, property: color, default: "#1d212e" }
+  bloomIntensity: { node: post-fx, property: bloomIntensity, min: 0, max: 3, default: 0.8 }
+```
+
+`component` present → `set_component_property`; absent → `set_property`. The
+schema clamps out-of-range values rather than rejecting them.
+
+`timeLimitSec: 0` means **no clock**: the run ends on the target score or on
+running out of lives, and `time-label` counts elapsed seconds up. Set a limit and
+it counts down and becomes a deadline (see `winMode`).
+
+## Extension points
+
+- **The mechanic.** Write a script under `scripts/`, attach it to a node inside
+  `board`, and let it own input and movement. It scores through `GameRules` —
+  either `node.emit('score-added', 1)` on `game-root`, or a direct
+  `addScore(1)` / `loseLife()` / `finish(true)` on the component. Nothing else in
+  the project needs to change for the HUD and the end screen to work.
+- **Collision, when the mechanic needs it.** Three tiers, cheapest first. Overlap
+  queries with no response: `scene.collision2d` + `core:Hitbox2D` (axis-aligned).
+  Bouncing, pushing, gravity, sensors: the engine's own 2D rigid-body solver —
+  `core:PhysicsBody2D` + `core:Collider2D` on the same node (a `core:Collider2D`
+  alone is static world geometry), `scene.physics2d.getBody(node)` for
+  `applyImpulse` / `setVelocity` / `teleport`, `setGravity(0, 0)` for top-down.
+  **Never hand-write a 2D solver, and do not import rapier** (3D only, ~2 MB wasm).
+  Grid games usually need no collision at all — compare cell coordinates.
+- **Spawning.** `scene.instantiate` a prefab into a container node, `queueFree`
+  it when it leaves the field, and add that container to `GameRules.freezeNodes`
+  so it — and every instance under it — stops on game over. Give your spawner a `clear()` method and `resetRun()`
+  will empty the field for you.
+- **Juice is one-liners — add it WITH the mechanic, never as a later pass.**
+  `scene.juice.burst({x, y})`, `floatText('+5', {at: node})`, `punchScale` /
+  `shake` / `flash`, `scene.audio.sfx('score')`, `scene.time.hitstop(50)` on a
+  contact START; `scene.juice.trail(ball)` for a light streak; `scene.tween.to(node,
+  {scale: 1.2}, {durationSec: 0.15, yoyo: true, repeat: 1})` / `crossFade(a, b)` for any
+  motion or panel switch instead of hand-lerping. Bright sprites bloom through `post-fx`
+  by themselves.
+- **A menu, later.** Create `scenes/menu.pix3scene` with a root carrying a script
+  that calls `scene.changeScene('res://scenes/main.pix3scene', {transition: 'fade'})`
+  on PLAY, then set Project Settings → Default Export Scene Path to it. Do this
+  **after** the game is fun, never before: while iterating, the menu is a screen
+  between you and the thing you are working on.
+
+## 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` nodes. For a
+custom win/lose condition call `finish(true|false)` — 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.
+- `GameRules`' ownership of `result-overlay` and `retry-button`.
+- `post-fx`: keep the id and `affect2D: true` — without it a 2D scene gets no
+  bloom. Tune the values, don't delete the node.
+- Do not import rapier, and do not add a menu scene early.
+
+## Playtest contract
+
+terminalVisual: static
+terminalRestartRoutine: terminal-retry
+
+## Verify
+
+1. `play_start` on `scenes/main.pix3scene` — `game_observe` reports the snapshot
+   with `phase: playing`, `score: 0`, `lives: 3`. That is the baseline, before any
+   mechanic exists.
+2. After the first mechanic increment, prove it by **state delta**, not by a
+   screenshot: `game_input` the real input with `observe:` on the node that should
+   react, and read `moved` / `activity` / the `game.changed` diff.
+3. Scoring is proven the same way: one real input, then `score` up in the snapshot
+   (and `score-label` reading `SCORE 1`).
+4. `targetScore: 1`, replay, score once → `result-overlay` visible with `YOU WIN!`;
+   `retry-button` (or the `restart` intent) starts a fresh run.

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

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

package/templates/recipe-blank-2d/files/design/tests/routines/restart.json

@@ -0,0 +1,27 @@
+{
+  "name": "restart",
+  "description": "Dispatch the run's `restart` intent and confirm a fresh run came back up.",
+  "note": "This is a FORMAT SEED, not a real test of your game — there is no mechanic here yet to test. Keep it (restart stays worth proving after a scene reload) and add a routine per mechanic next to it: run one with game_run {routine:'<name>'}. Steps are the game_input vocabulary plus {type:'command'} for a registered intent; `expect` holds the ordinary game_run predicates, ANDed and judged once after the last step against the frame pair around the run. Only a STEP takes a `why`. Prefer a `gameState` predicate over a node one wherever GameRules already publishes the value — it survives every relayout of the HUD.",
+  "scope": "scenes/main.pix3scene",
+  "params": {},
+  "uses": ["game-root", "result-overlay", "retry-button"],
+  "steps": [
+    {
+      "type": "command",
+      "name": "restart",
+      "why": "The intent RETRY dispatches, taken at the highest channel: it proves the wire without depending on where the button sits, and the dispatch is journalled with the frame it happened on."
+    }
+  ],
+  "expect": [
+    { "kind": "command", "name": "restart" },
+    { "kind": "gameState", "path": "phase", "op": "eq", "value": "playing" },
+    { "kind": "gameState", "path": "score", "op": "eq", "value": 0 },
+    {
+      "kind": "nodeProperty",
+      "name": "result-overlay",
+      "path": "visible",
+      "op": "eq",
+      "value": false
+    }
+  ]
+}

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

@@ -0,0 +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" }
+  ]
+}

package/templates/recipe-blank-2d/files/scenes/main.pix3scene

@@ -0,0 +1,224 @@
+# Pix3 Scene File (YAML)
+# Blank 2D — the GAME scene, and the one to build in. There is no menu scene on
+# purpose: nothing should stand between opening the project and the gameplay
+# while the mechanic is still being found.
+#
+# What is already wired: score / lives / timer bookkeeping, the HUD that shows
+# them, and a win/lose overlay with RETRY. What is NOT here: any mechanic at all,
+# including controls. That is your first increment — build it inside `board`.
+#
+# Stable node ids (design/recipe.md is the contract — do not rename these):
+#   post-fx, game-root, game-background, bg-glow, board, board-floor,
+#   hud, score-label, time-label, lives-bar,
+#   result-overlay, result-dim, result-label, retry-button (scenes/ui/result.pix3scene)
+#
+# The look is two cheap ingredients, the same ones the bouncer recipe uses:
+#   1. `post-fx` (PostProcess, affect2D) — bloom picks up whatever is bright, so
+#      a bright sprite glows for free. `bloomIntensity` is a recipe tunable the
+#      Flow theme pack turns up for neon and down for pastel.
+#   2. `bg-glow` — a near-white radial-gradient placeholder (`sprites/ph-bg.png`)
+#      tinted with the palette background, over the darkest ColorRect. It is what
+#      keeps an empty field from reading as a grey slab.
+#
+# The win/lose overlay lives in its own file under scenes/ui/ and is instanced
+# here hidden (`visible: false` = editor only), so opening this scene shows the
+# field rather than a GAME OVER card.
+#
+# 2D coordinates: origin at the canvas centre, X right, Y UP. Node order in the
+# tree is paint order (later/deeper draws on top).
+version: 1.0.0
+metadata:
+  author: Pix3 Recipe
+  description: Blank gameplay field — bookkeeping, HUD and win/lose only; the mechanic is yours
+root:
+  - id: post-fx
+    type: PostProcess
+    name: Post FX
+    properties:
+      affect2D: true
+      bloomEnabled: true
+      bloomIntensity: 0.8
+      bloomThreshold: 0.6
+      bloomSmoothing: 0.2
+      bloomRadius: 0.75
+      vignetteEnabled: true
+      vignetteOffset: 0.3
+      vignetteDarkness: 0.45
+      chromaticAberrationEnabled: false
+    children: []
+  - id: game-root
+    type: Group2D
+    name: Game Root
+    properties:
+      width: 1080
+      height: 1920
+      layout:
+        enabled: true
+        horizontalAlign: stretch
+        verticalAlign: stretch
+    components:
+      - id: game-rules
+        type: user:GameRules
+        enabled: true
+        config:
+          winMode: score
+          targetScore: 10
+          timeLimitSec: 0
+          startingLives: 3
+          resultNode: result-overlay
+          resultLabel: result-label
+          winText: "YOU WIN!"
+          loseText: "GAME OVER"
+          retryButton: retry-button
+          gameScene: res://scenes/main.pix3scene
+          # Add your mechanic's nodes here (comma-separated) so they stop on game over.
+          freezeNodes: ""
+    children:
+      - id: game-background
+        type: ColorRect2D
+        name: Game Background
+        properties:
+          width: 1080
+          height: 1920
+          color: "#12141c"
+          transform:
+            position: [0, 0]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: stretch
+            verticalAlign: stretch
+        children: []
+      # Radial glow over the flat background. Near-white PNG + core:tint, so the
+      # T0 palette recolours it (role `background` in design/recipe.md).
+      - id: bg-glow
+        type: Sprite2D
+        name: Background Glow
+        properties:
+          texture: { type: 'texture', url: 'res://sprites/ph-bg.png' }
+          width: 1080
+          height: 1920
+          opacity: 0.85
+          effects:
+            - type: core:tint
+              params: { color: "#3a2f7a", amount: 1 }
+          transform:
+            position: [0, 0]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: stretch
+            verticalAlign: stretch
+        children: []
+      - id: board
+        type: Group2D
+        name: Board
+        properties:
+          width: 980
+          height: 1480
+          transform:
+            position: [0, -80]
+            scale: [1, 1]
+            rotation: 0
+        children:
+          - id: board-floor
+            type: ColorRect2D
+            name: Board Floor
+            properties:
+              width: 980
+              height: 1480
+              color: "#1d212e"
+              transform:
+                position: [0, 0]
+                scale: [1, 1]
+                rotation: 0
+            children: []
+      - id: hud
+        type: CanvasLayer2D
+        name: HUD
+        properties:
+          width: 1080
+          height: 1920
+          layout:
+            enabled: true
+            horizontalAlign: stretch
+            verticalAlign: stretch
+        components:
+          - id: score-hud
+            type: user:ScoreHud
+            enabled: true
+            config:
+              sourceNode: game-root
+              scoreLabel: score-label
+              scoreFormat: "SCORE {value}"
+              timeLabel: time-label
+              timeFormat: "{value}"
+              livesBar: lives-bar
+        children:
+          - id: score-label
+            type: Label2D
+            name: Score Label
+            properties:
+              label: "SCORE 0"
+              labelFontSize: 44
+              labelColor: "#ffffff"
+              labelAlign: left
+              transform:
+                position: [-340, 850]
+                scale: [1, 1]
+                rotation: 0
+              layout:
+                enabled: true
+                horizontalAlign: left
+                verticalAlign: top
+            children: []
+          - id: time-label
+            type: Label2D
+            name: Time Label
+            properties:
+              label: "0"
+              labelFontSize: 44
+              labelColor: "#f5ae39"
+              labelAlign: center
+              transform:
+                position: [0, 850]
+                scale: [1, 1]
+                rotation: 0
+              layout:
+                enabled: true
+                horizontalAlign: center
+                verticalAlign: top
+            children: []
+          - id: lives-bar
+            type: Bar2D
+            name: Lives Bar
+            properties:
+              width: 240
+              height: 28
+              minValue: 0
+              maxValue: 3
+              value: 3
+              barColor: "#ff4d6d"
+              backBackgroundColor: "#2a3352"
+              showBorder: false
+              transform:
+                position: [340, 855]
+                scale: [1, 1]
+                rotation: 0
+              layout:
+                enabled: true
+                horizontalAlign: right
+                verticalAlign: top
+            children: []
+          # Win/lose screen — authored in scenes/ui/result.pix3scene so this
+          # scene opens on the GAME, not on a GAME OVER card. `visible: false`
+          # hides it in the EDITOR only; `initiallyVisible` (in the overlay
+          # file) is what play mode reads, and GameRules reveals it on the
+          # win/lose transition. Tick the eye to preview it over the field.
+          - id: result-overlay
+            name: Result Overlay
+            instance: res://scenes/ui/result.pix3scene
+            properties:
+              visible: false