@pix3/cli 1.6.3 → 2.0.0-alpha.0

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

@@ -1,85 +0,0 @@
-# Pix3 Scene File (YAML)
-# Blank 2D — the RESULT overlay (win/lose), in its own file so the gameplay
-# scene opens clean. `main.pix3scene` carries it as a one-line
-# `instance:` reference marked `visible: false`, which hides it in the EDITOR
-# only; `user:GameRules` reveals it at run time by setting `visible`.
-#
-# Edit it here, full-screen, in its own tab. To preview it composited over the
-# field, tick the eye on `result-overlay` in main.pix3scene — just do not commit
-# that tick, or every iteration starts behind a GAME OVER screen again.
-#
-# Stable node ids (design/recipe.md is the contract — do not rename these):
-#   result-overlay, result-dim, result-label, retry-button
-version: 1.0.0
-metadata:
-  author: Pix3 Recipe
-  description: Result overlay — dim, win/lose headline and a RETRY button
-root:
-  - id: result-overlay
-    type: Group2D
-    name: Result Overlay
-    properties:
-      width: 1080
-      height: 1920
-      initiallyVisible: false
-      layout:
-        enabled: true
-        horizontalAlign: stretch
-        verticalAlign: stretch
-    children:
-      - id: result-dim
-        type: ColorRect2D
-        name: Result Dim
-        properties:
-          width: 1080
-          height: 1920
-          color: "#000000"
-          opacity: 0.7
-          transform:
-            position: [0, 0]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: stretch
-            verticalAlign: stretch
-        children: []
-      - id: result-label
-        type: Label2D
-        name: Result Label
-        properties:
-          label: "GAME OVER"
-          labelFontSize: 88
-          labelColor: "#ffffff"
-          labelAlign: center
-          transform:
-            position: [0, 160]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []
-      - id: retry-button
-        type: Button2D
-        name: Retry Button
-        properties:
-          width: 420
-          height: 130
-          label: "RETRY"
-          labelFontSize: 50
-          labelColor: "#12141c"
-          backgroundColor: "#f5ae39"
-          hoverColor: "#ffc862"
-          pressedColor: "#d4922a"
-          buttonAction: retry
-          transform:
-            position: [0, -60]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []

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

@@ -1,350 +0,0 @@
-/**
- * GameRules — score, lives, timer, win/lose and the end flow.
- *
- * This is the blank recipe's only piece of game logic, and it is deliberately
- * about the *outcome* of a run, never about its mechanic. It owns:
- *   - the run state (score, lives, clock, outcome),
- *   - the HUD signals (`score-changed`, `lives-changed`, `time-changed`),
- *   - the result overlay and RETRY,
- *   - the `restart` intent,
- *   - the debug snapshot every verification tool reads.
- *
- * Your mechanic talks to it in either of two ways, whichever suits the script:
- *   1. call the methods — `rules.addScore(1)`, `rules.loseLife()`, `rules.finish(true)`;
- *   2. emit on the node that carries this component — `node.emit('score-added', 1)`
- *      or `node.emit('life-lost', 1)` — which needs no reference at all.
- *
- * Win modes:
- *   `score`   — reach `targetScore`; a non-zero time limit is a deadline.
- *   `time`    — play until the clock ends, then win if `targetScore` was reached.
- *   `survive` — stay alive until the clock ends; reaching it is the win.
- * In every mode, running out of lives loses. `timeLimitSec: 0` means no clock,
- * so the HUD's time label counts elapsed seconds up instead of down.
- *
- * RETRY dispatches the `restart` command (`scene.commands`) rather than calling a
- * method: a test replays the end flow without hunting for buttons, and one real
- * tap proves the binding once.
- */
-import {
-  Button2D,
-  Label2D,
-  NodeBase,
-  Script,
-  registerGameDebug,
-  type PropertySchema,
-} from '@pix3/runtime';
-
-type WinMode = 'score' | 'time' | 'survive';
-
-/** Snapshot numbers are read by humans and diffed by tools — keep them short. */
-function roundHundredths(value: number): number {
-  return Math.round(value * 100) / 100;
-}
-
-export class GameRules extends Script {
-  private score = 0;
-  private lives = 3;
-  private elapsed = 0;
-  private over = false;
-  private won = false;
-  private disposeDebug: (() => void) | null = null;
-  private disposeCommands: (() => void)[] = [];
-  /** Components `finish()` switched off, so `resetRun()` revives exactly those. */
-  private frozen: { enabled: boolean }[] = [];
-
-  constructor(id: string, type: string) {
-    super(id, type);
-    this.config = {
-      winMode: 'score',
-      targetScore: 10,
-      // No clock by default: a blank recipe that ended runs on a deadline nobody
-      // asked for would look like a bug in the mechanic being built.
-      timeLimitSec: 0,
-      startingLives: 3,
-      resultNode: 'result-overlay',
-      resultLabel: 'result-label',
-      winText: 'YOU WIN!',
-      loseText: 'GAME OVER',
-      retryButton: 'retry-button',
-      gameScene: 'res://scenes/main.pix3scene',
-      // Comma-separated node ids frozen on game over: every component on the node
-      // and on everything under it is disabled. Add your mechanic's nodes here as you build them — a spawner that
-      // keeps running behind the result screen is the classic leak.
-      freezeNodes: '',
-    };
-  }
-
-  static getPropertySchema(): PropertySchema {
-    const num = (name: string, label: string, min: number, max: number, step: number) => ({
-      name,
-      type: 'number' as const,
-      ui: { label, group: 'Rules', min, max, step, slider: true },
-      getValue: (s: unknown) => (s as GameRules).config[name],
-      setValue: (s: unknown, v: unknown) => {
-        const n = Number(v);
-        (s as GameRules).config[name] = Math.min(max, Math.max(min, Number.isFinite(n) ? n : min));
-      },
-    });
-    const str = (name: string, label: string, group: string) => ({
-      name,
-      type: 'string' as const,
-      ui: { label, group },
-      getValue: (s: unknown) => (s as GameRules).config[name],
-      setValue: (s: unknown, v: unknown) => {
-        (s as GameRules).config[name] = typeof v === 'string' ? v : '';
-      },
-    });
-
-    return {
-      nodeType: 'GameRules',
-      properties: [
-        {
-          name: 'winMode',
-          type: 'select',
-          ui: { label: 'Win Mode', group: 'Rules', options: ['score', 'time', 'survive'] },
-          getValue: s => (s as GameRules).config.winMode,
-          setValue: (s, v) => {
-            (s as GameRules).config.winMode = v === 'time' || v === 'survive' ? v : 'score';
-          },
-        },
-        num('targetScore', 'Target Score', 1, 99999, 1),
-        num('timeLimitSec', 'Time Limit (s)', 0, 600, 1),
-        num('startingLives', 'Starting Lives', 1, 20, 1),
-        str('winText', 'Win Text', 'Result'),
-        str('loseText', 'Lose Text', 'Result'),
-        str('resultNode', 'Result Overlay', 'Result'),
-        str('resultLabel', 'Result Label', 'Result'),
-        str('retryButton', 'Retry Button', 'Flow'),
-        str('gameScene', 'Game Scene', 'Flow'),
-        str('freezeNodes', 'Freeze Nodes', 'Flow'),
-      ],
-      groups: {
-        Rules: { label: 'Rules', expanded: true },
-        Result: { label: 'Result Screen', expanded: true },
-        Flow: { label: 'Flow', expanded: false },
-      },
-    };
-  }
-
-  onStart(): void {
-    this.lives = Math.max(1, Number(this.config.startingLives) || 1);
-    const dispose = this.scene?.commands.register('restart', () => this.restart(), {
-      description: 'Reload the game scene for a fresh run.',
-    });
-    this.disposeCommands = dispose ? [dispose] : [];
-
-    this.disposeDebug = registerGameDebug({
-      name: 'recipe-blank-2d',
-      version: 1,
-      // The registry IS the action list — never a second, hand-kept copy.
-      actions: () => this.scene?.commands.list().map(command => command.name) ?? [],
-      reset: () => this.resetRun(),
-      snapshot: () => ({
-        scene: 'game',
-        phase: this.over ? (this.won ? 'won' : 'lost') : 'playing',
-        score: this.score,
-        lives: this.lives,
-        winMode: String(this.config.winMode ?? 'score'),
-        targetScore: Math.max(1, Number(this.config.targetScore) || 1),
-        elapsedSec: roundHundredths(this.elapsed),
-        // null when the run has no clock at all.
-        timeLeftSec: this.timeLeftSec(),
-      }),
-    });
-
-    const owner = this.node;
-    // The signal channel: a mechanic script can score without holding a reference
-    // to this component. Same effect as calling the methods below.
-    owner?.connect('score-added', this, (...args: unknown[]) =>
-      this.addScore(Number(args[0]) || 0)
-    );
-    owner?.connect('life-lost', this, (...args: unknown[]) => this.loseLife(Number(args[0]) || 1));
-    // The HUD announces itself once it is connected, so it never misses the
-    // opening values (its onStart runs after this one).
-    owner?.connect('hud-ready', this, () => this.broadcast());
-
-    this.setNodeVisible(String(this.config.resultNode ?? ''), false);
-    this.bindButton(
-      String(this.config.retryButton ?? ''),
-      () => this.scene?.commands.dispatch('restart'),
-      false
-    );
-    this.broadcast();
-  }
-
-  onUpdate(dt: number): void {
-    if (this.over) {
-      return;
-    }
-    this.elapsed += dt;
-    const limit = Math.max(0, Number(this.config.timeLimitSec) || 0);
-    this.node?.emit('time-changed', limit > 0 ? Math.max(0, limit - this.elapsed) : this.elapsed);
-
-    if (this.lives <= 0) {
-      this.finish(false);
-      return;
-    }
-    const raw = String(this.config.winMode ?? 'score');
-    const mode: WinMode = raw === 'time' ? 'time' : raw === 'survive' ? 'survive' : 'score';
-    const target = Math.max(1, Number(this.config.targetScore) || 1);
-    const timeUp = limit > 0 && this.elapsed >= limit;
-
-    if (mode === 'score') {
-      if (this.score >= target) this.finish(true);
-      else if (timeUp) this.finish(false);
-    } else if (mode === 'time') {
-      if (timeUp) this.finish(this.score >= target);
-    } else if (timeUp) {
-      this.finish(true);
-    }
-  }
-
-  onDetach(): void {
-    // Clearing is safe in any order: the disposer only clears the global when it
-    // still holds *this* provider, so a scene that already registered its own wins.
-    this.disposeDebug?.();
-    this.disposeDebug = null;
-    for (const dispose of this.disposeCommands) {
-      dispose();
-    }
-    this.disposeCommands = [];
-    super.onDetach();
-  }
-
-  /** Seconds left on the clock, or `null` when this run has no time limit. */
-  private timeLeftSec(): number | null {
-    const limit = Math.max(0, Number(this.config.timeLimitSec) || 0);
-    return limit > 0 ? roundHundredths(Math.max(0, limit - this.elapsed)) : null;
-  }
-
-  /** Score. Call it from your mechanic, or emit `score-added` on this node. */
-  addScore(amount: number): void {
-    if (this.over) return;
-    this.score += amount;
-    this.node?.emit('score-changed', this.score);
-  }
-
-  /** Lose lives. Call it from your mechanic, or emit `life-lost` on this node. */
-  loseLife(amount = 1): void {
-    if (this.over) return;
-    this.lives = Math.max(0, this.lives - Math.max(1, amount));
-    this.node?.emit(
-      'lives-changed',
-      this.lives,
-      Math.max(1, Number(this.config.startingLives) || 1)
-    );
-  }
-
-  private broadcast(): void {
-    const owner = this.node;
-    owner?.emit('score-changed', this.score);
-    owner?.emit('lives-changed', this.lives, Math.max(1, Number(this.config.startingLives) || 1));
-    const limit = Math.max(0, Number(this.config.timeLimitSec) || 0);
-    owner?.emit('time-changed', limit > 0 ? Math.max(0, limit - this.elapsed) : this.elapsed);
-  }
-
-  /** End the run. This is the ONLY sanctioned way to show the result screen. */
-  finish(won: boolean): void {
-    if (this.over) return;
-    this.over = true;
-    this.won = won;
-
-    const label = this.findNode(String(this.config.resultLabel ?? ''));
-    if (label instanceof Label2D) {
-      label.setText(String((won ? this.config.winText : this.config.loseText) ?? ''));
-    }
-    this.setNodeVisible(String(this.config.resultNode ?? ''), true);
-    this.setButtonEnabled(String(this.config.retryButton ?? ''), true);
-
-    // A freeze node freezes its whole subtree: the spawners' own components AND
-    // every instance they spawned under themselves (a chaser's script, a pickup's
-    // pop-in), so nothing keeps moving over the result card.
-    for (const id of String(this.config.freezeNodes ?? '').split(',')) {
-      const root = this.findNode(id.trim());
-      if (!root) continue;
-      root.traverse(object => {
-        if (!(object instanceof NodeBase)) return;
-        for (const component of object.components) {
-          // Only remember what WE switched off: reviving everything on reset would
-          // silently enable a component the scene author had left disabled.
-          if (!component.enabled) continue;
-          component.enabled = false;
-          this.frozen.push(component);
-        }
-      });
-    }
-    this.node?.emit(won ? 'game-won' : 'game-lost', this.score);
-  }
-
-  private restart(): void {
-    void this.scene?.changeScene(String(this.config.gameScene ?? ''), { transition: 'fade' });
-  }
-
-  /**
-   * Back to the state `onStart` left behind: score, lives, clock and outcome, the
-   * result overlay hidden, the freeze `finish()` applied lifted, and anything a
-   * `freezeNodes` component still has on the field dropped. Those leftovers are
-   * state too — a run that begins amid the previous run's objects did not begin
-   * from the start.
-   *
-   * Public because it is useful on its own (an in-run "try again" that skips the
-   * scene reload); the debug provider's `reset` is this method.
-   */
-  resetRun(): void {
-    for (const component of this.frozen) {
-      component.enabled = true;
-    }
-    this.frozen = [];
-    this.clearSpawned();
-
-    this.score = 0;
-    this.lives = Math.max(1, Number(this.config.startingLives) || 1);
-    this.elapsed = 0;
-    this.over = false;
-    this.won = false;
-
-    this.setNodeVisible(String(this.config.resultNode ?? ''), false);
-    this.setButtonEnabled(String(this.config.retryButton ?? ''), false);
-    this.broadcast();
-  }
-
-  /**
-   * Ask every component on a `freezeNodes` node that owns spawned instances to
-   * drop them. Duck-typed on purpose: the freeze list is whatever you wrote there,
-   * so a spawner you write yourself joins in by offering a `clear()` method.
-   */
-  private clearSpawned(): void {
-    for (const id of String(this.config.freezeNodes ?? '').split(',')) {
-      const node = this.findNode(id.trim());
-      if (!node) continue;
-      for (const component of node.components) {
-        const clear = (component as { clear?: unknown }).clear;
-        if (typeof clear === 'function') {
-          (clear as () => void).call(component);
-        }
-      }
-    }
-  }
-
-  private bindButton(query: string, handler: () => void, enabled: boolean): void {
-    const button = this.findNode(query);
-    if (button instanceof Button2D) {
-      button.enabled = enabled;
-      button.connect('pressed', this, handler);
-    }
-  }
-
-  private setButtonEnabled(query: string, enabled: boolean): void {
-    const button = this.findNode(query);
-    if (button instanceof Button2D) {
-      button.enabled = enabled;
-    }
-  }
-
-  private setNodeVisible(query: string, visible: boolean): void {
-    const node = this.findNode(query);
-    if (node) {
-      node.visible = visible;
-    }
-  }
-}

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

@@ -1,110 +0,0 @@
-/**
- * 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 +0,0 @@
-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 +0,0 @@
-# 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-->
-```