@pix3/cli 1.6.4 → 2.0.0-alpha.0

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

@@ -1,113 +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.
- *
- * 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 +0,0 @@
-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 +0,0 @@
-# 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 +0,0 @@
-# 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.

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

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

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

@@ -1,23 +0,0 @@
-{
-  "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-arena-2d/files/scenes/main.pix3scene

@@ -1,292 +0,0 @@
-# Pix3 Scene File (YAML)
-# Arena 2D — the GAME scene, and the editor's startup scene: this is the one to
-# iterate on and the one agents open and play directly. A full build boots the
-# MENU (see menu.pix3scene), whose PLAY button transitions here.
-#
-# Stable node ids (design/recipe.md is the contract — do not rename these):
-#   game-root, game-background, board, player,
-#   spawner-pickups, spawner-hazards,
-#   hud, score-label, time-label, lives-bar, menu-button,
-#   result-overlay, result-label, retry-button (scenes/ui/result.pix3scene)
-#
-# Full-screen UI lives in its own file under scenes/ui/ and is instanced here
-# hidden (`visible: false` = editor only), so opening this scene shows the game
-# rather than a menu or 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: Arena gameplay — spawners drop pickups and hazards into a bounded field
-root:
-  - 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: 12
-          timeLimitSec: 45
-          startingLives: 3
-          resultNode: result-overlay
-          resultLabel: result-label
-          winText: "YOU WIN!"
-          loseText: "GAME OVER"
-          retryButton: retry-button
-          menuButton: menu-button
-          menuScene: res://scenes/menu.pix3scene
-          gameScene: res://scenes/main.pix3scene
-          freezeNodes: spawner-pickups,spawner-hazards,player
-      - id: touch-rules
-        type: user:TouchRules
-        enabled: true
-        config:
-          playerNode: player
-          touchRadius: 62
-          rules: "pickup:score:1;hazard:damage:1"
-          consume: true
-          scoreSound: ""
-          damageSound: ""
-    children:
-      - id: game-background
-        type: ColorRect2D
-        name: Game Background
-        properties:
-          width: 1080
-          height: 1920
-          color: "#141a2e"
-          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: "#1d2743"
-              transform:
-                position: [0, 0]
-                scale: [1, 1]
-                rotation: 0
-            children: []
-          - id: spawner-pickups
-            type: Group2D
-            name: Spawner Pickups
-            properties:
-              width: 900
-              height: 60
-              transform:
-                position: [0, 690]
-                scale: [1, 1]
-                rotation: 0
-            components:
-              - id: pickup-spawner
-                type: user:Spawner
-                enabled: true
-                config:
-                  prefab: res://scenes/prefabs/pickup.pix3scene
-                  parentNode: ""
-                  intervalSec: 1.0
-                  intervalJitter: 0.35
-                  maxAlive: 10
-                  spawnWidth: 880
-                  spawnHeight: 60
-                  gridSnap: 0
-                  driftX: 0
-                  driftY: -300
-                  lifetimeSec: 7
-                  despawnRadius: 1450
-                  startDelaySec: 0.3
-            children: []
-          - id: spawner-hazards
-            type: Group2D
-            name: Spawner Hazards
-            properties:
-              width: 900
-              height: 60
-              transform:
-                position: [0, 690]
-                scale: [1, 1]
-                rotation: 0
-            components:
-              - id: hazard-spawner
-                type: user:Spawner
-                enabled: true
-                config:
-                  prefab: res://scenes/prefabs/hazard.pix3scene
-                  parentNode: ""
-                  intervalSec: 1.8
-                  intervalJitter: 0.6
-                  maxAlive: 8
-                  spawnWidth: 880
-                  spawnHeight: 60
-                  gridSnap: 0
-                  driftX: 0
-                  driftY: -380
-                  lifetimeSec: 6
-                  despawnRadius: 1450
-                  startDelaySec: 1.2
-            children: []
-          - id: player
-            type: Sprite2D
-            name: Player
-            properties:
-              texture: { type: 'texture', url: 'res://sprites/ph-avatar.png' }
-              width: 120
-              height: 120
-              effects:
-                - type: core:tint
-                  params: { color: "#ffffff", amount: 1 }
-              transform:
-                position: [0, -520]
-                scale: [1, 1]
-                rotation: 0
-            components:
-              - id: player-controller
-                type: user:PlayerController
-                enabled: true
-                config:
-                  mode: pointer
-                  speed: 620
-                  radius: 60
-                  boundsNode: board
-                  deadZone: 4
-            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: "45"
-              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: []
-          - id: menu-button
-            type: Button2D
-            name: Menu Button
-            properties:
-              width: 200
-              height: 72
-              label: "MENU"
-              labelFontSize: 30
-              labelColor: "#ffffff"
-              backgroundColor: "#2a3352"
-              hoverColor: "#3a446b"
-              pressedColor: "#1d2743"
-              buttonAction: back-to-menu
-              transform:
-                position: [-400, -880]
-                scale: [1, 1]
-                rotation: 0
-              layout:
-                enabled: true
-                horizontalAlign: left
-                verticalAlign: bottom
-            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