@pix3/cli 1.6.3 → 2.0.0-alpha.0

package/templates/playable-2d/files/README.md

@@ -1,30 +0,0 @@
-# {{PROJECT_NAME}}
-
-A Pix3 project created from the **Playable 2D** template — a portrait playable-ad blank.
-
-## What's included
-
-- **Tap-to-start intro** (`intro-overlay`, `scenes/ui/intro.pix3scene`) — the first tap unlocks browser audio and starts the game (`scripts/GameFlow.ts`).
-- **Gameplay placeholder** — replace the animated logo sprite in `main.pix3scene` with your game.
-- **End screen with CTA** (`end-screen`, `scenes/ui/end-screen.pix3scene`) — the PLAY NOW button reports game end (`playable.gameEnd()`) and logs the click. It opens nothing: the ad network decides the store target at delivery time (`mraid.open` / `dapi.openStoreUrl`), so wire its SDK in `CtaButton.ctaClick()` when you package the ad.
-- `GameFlow` shows the end screen automatically after `autoWinAfterSec` seconds — replace that with your real win/lose condition.
-- **Readable state** — `GameFlow` publishes a `registerGameDebug` snapshot (phase, timer, overlay visibility, session end), so tooling reads the run's state instead of judging it from a screenshot. Add your own fields as you add state.
-- **Intent-first handlers** — every reaction to the player is a named method (`GameFlow.start/finish/restart`, `CtaButton.ctaClick`) that the event handler merely calls; keep that shape and the game stays drivable by intent.
-
-## Project structure
-
-- `design/` — game design document and reference images
-- `design/tests/` — agent-testing material: `routines/*.json` (named step +
-  assertion scripts, written on the highest channel the game offers) and
-  `reachability.json` (controls proven reachable on a live run). The harness
-  that runs them is still in development; format and location are fixed now.
-- `scenes/` — scene files; `main.pix3scene` is the startup scene
-- `scenes/ui/` — the full-screen overlays (`intro.pix3scene`, `end-screen.pix3scene`),
-  instanced into `main.pix3scene` with `visible: false` so the editor opens on the
-  game. That flag is editor-only; `initiallyVisible` on each overlay's root is what
-  play mode reads. Edit an overlay in its own tab, or tick the eye on its instance
-  node to preview it composited — just don't save that tick.
-- `sprites/` — images and textures
-- `scripts/` — game scripts (`export class X extends Script`, used as `user:X`)
-- `audio/` — music and sound effects
-- `AGENTS.md` — rules and pointers for AI agents working on this project

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

@@ -1,83 +0,0 @@
-# Recipe: recipe-playable-ad
-
-## What this is
-
-The playable-ad shape: a portrait scene with a tap-to-start gate, a short piece
-of gameplay, and an end screen whose CTA button reports game end through the
-engine Playable SDK and logs the click. It opens no store page — the ad network
-picks that target at delivery time, so hook its SDK into `CtaButton.ctaClick()`
-when you package the ad. One scene, no menu — an ad has no menu.
-
-The gameplay itself is deliberately a placeholder (`hero-sprite` bobbing on a
-`core:Sine`) plus an auto-win timer. Replace both: keep the gate and the CTA,
-build the middle. If the brief needs real mechanics, start from `recipe-arena-2d`,
-`recipe-bouncer-2d` or `recipe-tapper-2d` and port this gate/CTA structure over.
-
-## Node map
-
-| id | what |
-| --- | --- |
-| `game-root` | scene root; hosts `GameFlow` (the phase driver: intro → playing → ended) |
-| `background` | full-screen `ColorRect2D` (palette background) |
-| `hero-sprite` | placeholder gameplay object, bobbing on a `core:Sine` |
-| `hud-label` | in-game text line |
-| `intro-overlay` → `intro-dim`, `intro-label` | the tap gate (`scenes/ui/intro.pix3scene`, instanced into main); the first tap hides it, starts the game, and unlocks browser audio |
-| `end-screen` → `end-dim`, `end-label`, `cta-button` | end screen (`scenes/ui/end-screen.pix3scene`, instanced into main), `initiallyVisible: false` |
-| `cta-button` | hosts `CtaButton` — `playable.gameEnd()` + a `[CtaButton] CTA clicked` log; the store call belongs to the ad network SDK, not to the template |
-
-`GameFlow.finish()` reveals the end screen; call it from your gameplay code for
-a real win/lose instead of the placeholder timer.
-
-## Placeholders
-
-| role | file | node |
-| --- | --- | --- |
-| hero | `sprites/pix3-logo.png` | `hero-sprite` |
-
-## Tunables
-
-```yaml
-tunables:
-  autoWinAfterSec: { node: game-root, component: "user:GameFlow", property: autoWinAfterSec, min: 0, max: 120, default: 15 }
-  introNode: { node: game-root, component: "user:GameFlow", property: introNode, default: intro-overlay }
-  endNode: { node: game-root, component: "user:GameFlow", property: endNode, default: end-screen }
-  skipIntro: { node: game-root, component: "user:GameFlow", property: skipIntro, default: false }
-  bgColor: { node: background, property: color, default: "#16213e" }
-```
-
-`component` present → `set_component_property`; absent → `set_property`.
-
-`skipIntro: true` starts the run already playing, with the tap gate hidden — a
-prototyping vent so iterating does not cost a tap per reload. Turn it back off
-before shipping: in an ad container that first tap is what unlocks browser audio.
-
-## Extension points
-
-- **Real gameplay.** Replace `hero-sprite` and set `autoWinAfterSec: 0`, then
-  call `finish()` on the `GameFlow` component from your own script when the
-  player wins or loses. Everything else (gate, end screen, CTA) stays.
-- **Fail state.** Add a `lose-label` inside `end-screen` and pick the text in
-  your `finish()` caller — a playable that can only be won reads as a demo.
-- **Second CTA.** Any `Button2D` with a `user:CtaButton` component works, so an
-  early "install now" banner is one node.
-- **Network requirements.** Keep everything self-contained: an ad bundle is a
-  single HTML file, so no external fetches, and prefer few, small textures.
-
-## Do not touch
-
-- The node ids above (rename `name`, never `id`).
-- `intro-overlay` must exist and be visible at start (`initiallyVisible: true` in
-  `scenes/ui/intro.pix3scene`): the first tap is what unlocks browser audio, so a
-  playable without a gate ships silent.
-- `end-screen` must keep `initiallyVisible: false` (in `scenes/ui/end-screen.pix3scene`).
-- The `visible: false` on both `instance:` nodes in `main.pix3scene` is an
-  editor-only hide so the scene opens on the game — keep it, and author
-  `initiallyVisible` in the overlay file, never as an instance override.
-- Do not import rapier — it would put a ~2 MB wasm payload in an ad bundle.
-
-## Verify
-
-1. `play_start` on `scenes/main.pix3scene`; `intro-overlay` is visible.
-2. `game_input` a tap → `intro-overlay` hides and `hero-sprite` starts bobbing.
-3. Wait `autoWinAfterSec` → `end-screen` becomes visible with `cta-button`.
-4. Press `cta-button` → the SDK reports game end and `[CtaButton] CTA clicked` appears in the console (nothing navigates away).

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

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

package/templates/playable-2d/files/design/tests/routines/intro-to-cta.json

@@ -1,32 +0,0 @@
-{
-  "name": "intro-to-cta",
-  "description": "Tap through the intro gate, end the run by intent, and press the CTA on the end screen.",
-  "note": "Run it with game_run {routine:'intro-to-cta'}. Steps are the game_input vocabulary (tap/key/keys/drag/hover/wait/invoke) plus {type:'command', name} for an intent the scene registered; `expect` holds the ordinary game_run predicates, ANDed and judged once after the last step. A step's `why` and this `note` are documentation — the runner ignores both — but they are why the routine also reads as a checklist. Note what is NOT here: no step calls a component method directly. Ending the run goes through the `finish` command, because a routine that called the handler would prove the handler works while skipping every wire between the player and it.",
-  "scope": "scenes/main.pix3scene",
-  "params": {},
-  "uses": ["game-root", "intro-overlay", "end-screen", "cta-button"],
-  "steps": [
-    {
-      "type": "tap",
-      "target": "intro-overlay",
-      "why": "The tap gate is the gesture under test: it hides the overlay and unlocks browser audio, so it is driven as a real tap rather than by dispatching start-game."
-    },
-    {
-      "type": "command",
-      "name": "finish",
-      "why": "Reveal the end screen by intent instead of waiting out autoWinAfterSec — the timer is a placeholder every real playable replaces, and 15 s of wall clock in every run is a budget nobody gets back."
-    },
-    {
-      "type": "tap",
-      "target": "cta-button",
-      "holdMs": 700,
-      "why": "Button2D needs a real press; this proves the button is on screen and hittable, not just present in the tree."
-    }
-  ],
-  "expect": [
-    { "kind": "gameState", "path": "phase", "op": "eq", "value": "ended" },
-    { "kind": "gameState", "path": "introVisible", "op": "eq", "value": false },
-    { "kind": "gameState", "path": "endVisible", "op": "eq", "value": true },
-    { "kind": "gameState", "path": "gameEnded", "op": "eq", "value": true }
-  ]
-}

package/templates/playable-2d/files/scenes/main.pix3scene

@@ -1,111 +0,0 @@
-# Pix3 Scene File (YAML)
-# Playable 2D blank (portrait 1080x1920): 2D gameplay placeholder plus a
-# tap-to-start intro overlay and an end screen with a CTA button.
-#
-# Full-screen UI lives in its own file under scenes/ui/ and is instanced here
-# hidden (`visible: false` = editor only; `initiallyVisible` in the overlay file
-# is what play mode reads), so opening this scene shows the game rather than a
-# dim or a CTA card:
-#   intro-overlay (intro-dim, intro-label)       scenes/ui/intro.pix3scene
-#   end-screen (end-dim, end-label, cta-button)  scenes/ui/end-screen.pix3scene
-# Instance children keep their ids, so `GameFlow`'s introNode/endNode and every
-# `findNode` still resolve. Node order in the tree is paint order.
-version: 1.0.0
-metadata:
-  author: Pix3 Template
-  description: Playable 2D blank with intro overlay and CTA end screen
-root:
-  - id: game-root
-    type: Group2D
-    name: Game Root
-    properties:
-      width: 1080
-      height: 1920
-      layout:
-        enabled: true
-        horizontalAlign: stretch
-        verticalAlign: stretch
-    components:
-      - id: game-flow
-        type: user:GameFlow
-        enabled: true
-        config:
-          introNode: intro-overlay
-          endNode: end-screen
-          autoWinAfterSec: 15
-    children:
-      - id: background
-        type: ColorRect2D
-        name: Background
-        properties:
-          width: 1080
-          height: 1920
-          color: "#16213e"
-          transform:
-            position: [0, 0]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: stretch
-            verticalAlign: stretch
-        children: []
-      - id: hero-sprite
-        type: Sprite2D
-        name: Hero Sprite
-        properties:
-          texture: { type: 'texture', url: 'res://sprites/pix3-logo.png' }
-          width: 242
-          height: 96
-          transform:
-            position: [0, 0]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        components:
-          - id: hero-bob
-            type: core:Sine
-            enabled: true
-            config:
-              amplitude: 40
-              frequency: 0.6
-              axis: y
-        children: []
-      - id: hud-label
-        type: Label2D
-        name: HUD Label
-        properties:
-          label: "PROTOTYPE"
-          labelFontSize: 40
-          labelColor: "#ffffff"
-          labelAlign: center
-          transform:
-            position: [0, 860]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: top
-        children: []
-      # Tap gate — authored in scenes/ui/intro.pix3scene so this scene opens on
-      # the GAME. `visible: false` hides it in the EDITOR only; `initiallyVisible`
-      # (in the overlay file) is what play mode reads. Tick the eye to preview it
-      # composited over the game.
-      - id: intro-overlay
-        name: Intro Overlay
-        instance: res://scenes/ui/intro.pix3scene
-        properties:
-          visible: false
-      # End screen — authored in scenes/ui/end-screen.pix3scene so this scene opens
-      # on the GAME. `visible: false` hides it in the EDITOR only; `initiallyVisible`
-      # (in the overlay file) is what play mode reads. Tick the eye to preview it
-      # composited over the game.
-      - id: end-screen
-        name: End Screen
-        instance: res://scenes/ui/end-screen.pix3scene
-        properties:
-          visible: false

package/templates/playable-2d/files/scenes/ui/end-screen.pix3scene

@@ -1,91 +0,0 @@
-# Pix3 Scene File (YAML)
-# Playable 2D — the END screen (result + CTA), in its own file so the game
-# scene opens clean. `main.pix3scene` carries it as a one-line `instance:`
-# reference marked `visible: false`, which hides it in the EDITOR only;
-# `initiallyVisible: false` below is what play mode reads, and `user:GameFlow`
-# reveals it on `finish()`.
-#
-# Edit it here, full-screen, in its own tab. To preview it composited over the
-# game, tick the eye on `end-screen` in main.pix3scene — just do not commit
-# that tick, or every iteration starts behind a CTA card again.
-#
-# Stable node ids (design/recipe.md is the contract — do not rename these):
-#   end-screen, end-dim, end-label, cta-button
-version: 1.0.0
-metadata:
-  author: Pix3 Template
-  description: End screen — dim, result headline and a PLAY NOW CTA button
-root:
-  - id: end-screen
-    type: Group2D
-    name: End Screen
-    properties:
-      width: 1080
-      height: 1920
-      initiallyVisible: false
-      layout:
-        enabled: true
-        horizontalAlign: stretch
-        verticalAlign: stretch
-    children:
-      - id: end-dim
-        type: ColorRect2D
-        name: End Dim
-        properties:
-          width: 1080
-          height: 1920
-          color: "#000000"
-          opacity: 0.75
-          transform:
-            position: [0, 0]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: stretch
-            verticalAlign: stretch
-        children: []
-      - id: end-label
-        type: Label2D
-        name: End Label
-        properties:
-          label: "GREAT RUN!"
-          labelFontSize: 84
-          labelColor: "#ffcf33"
-          labelAlign: center
-          transform:
-            position: [0, 220]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []
-      - id: cta-button
-        type: Button2D
-        name: CTA Button
-        properties:
-          width: 480
-          height: 140
-          label: "PLAY NOW"
-          labelFontSize: 56
-          labelColor: "#1a1a2e"
-          backgroundColor: "#ffcf33"
-          hoverColor: "#ffe066"
-          pressedColor: "#e6b800"
-          buttonAction: cta
-          transform:
-            position: [0, -120]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        components:
-          - id: cta-action
-            type: user:CtaButton
-            enabled: true
-            config: {}
-        children: []

package/templates/playable-2d/files/scenes/ui/intro.pix3scene

@@ -1,65 +0,0 @@
-# Pix3 Scene File (YAML)
-# Playable 2D — the tap-to-start INTRO overlay, in its own file so the
-# game scene opens clean. `main.pix3scene` carries it as a one-line `instance:`
-# reference marked `visible: false`, which hides it in the EDITOR only.
-# `initiallyVisible: true` below is what play mode reads, so the gate is UP at
-# t=0 — in an ad container that first tap is what unlocks browser audio.
-# `user:GameFlow` hides it on the first tap.
-#
-# Edit it here, full-screen, in its own tab. To preview it composited over the
-# game, tick the eye on `intro-overlay` in main.pix3scene — just do not commit
-# that tick, or every iteration starts behind the dim again.
-#
-# Stable node ids (design/recipe.md is the contract — do not rename these):
-#   intro-overlay, intro-dim, intro-label
-version: 1.0.0
-metadata:
-  author: Pix3 Template
-  description: Intro overlay — dim plus a TAP TO START label
-root:
-  - id: intro-overlay
-    type: Group2D
-    name: Intro Overlay
-    properties:
-      width: 1080
-      height: 1920
-      initiallyVisible: true
-      layout:
-        enabled: true
-        horizontalAlign: stretch
-        verticalAlign: stretch
-    children:
-      - id: intro-dim
-        type: ColorRect2D
-        name: Intro Dim
-        properties:
-          width: 1080
-          height: 1920
-          color: "#000000"
-          opacity: 0.65
-          transform:
-            position: [0, 0]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: stretch
-            verticalAlign: stretch
-        children: []
-      - id: intro-label
-        type: Label2D
-        name: Tap To Start
-        properties:
-          label: "TAP TO START"
-          labelFontSize: 72
-          labelColor: "#ffffff"
-          labelAlign: center
-          transform:
-            position: [0, 0]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []

package/templates/playable-2d/files/scripts/CtaButton.ts

@@ -1,55 +0,0 @@
-/**
- * CtaButton — the playable's call-to-action. Attach to a Button2D; on press it
- * reports game end and logs the click. It deliberately does NOT open a store
- * page: which URL a playable opens (and whether it opens one at all) is decided
- * by the ad network at delivery time via `mraid.open` / `dapi.openStoreUrl`, so
- * a hardcoded store URL in a template is a wrong default that ships a real
- * navigation out of the game on every tap. Wire the network SDK here when you
- * package the ad; until then the log is the whole contract.
- *
- * The press handler does nothing itself: it dispatches the named command
- * `cta-click`, whose handler is the intent method `ctaClick()`. Keep that shape
- * as you add buttons — a game whose reactions are named intents can be driven
- * and tested by `scene.commands.dispatch(...)` rather than by simulated taps,
- * the wiring survives any relayout of the UI, and one real tap is enough to
- * prove the button still raises the intent it claims.
- */
-import { Script, playable } from '@pix3/runtime';
-import type { NodeBase } from '@pix3/runtime';
-
-export class CtaButton extends Script {
-  private disposeCommands: (() => void)[] = [];
-
-  onAttach(node: NodeBase): void {
-    node.connect('pressed', this, this.handlePressed);
-  }
-
-  onStart(): void {
-    // Registered here rather than in onAttach: `scene` is injected once the
-    // graph is built, which is after components are attached during load.
-    const commands = this.scene?.commands;
-    this.disposeCommands = [
-      commands?.register('cta-click', () => this.ctaClick(), {
-        description: 'Accept the call to action: end the session and report the CTA click.',
-      }),
-    ].filter((dispose): dispose is () => void => dispose !== undefined);
-  }
-
-  onDetach(): void {
-    for (const dispose of this.disposeCommands) {
-      dispose();
-    }
-    this.disposeCommands = [];
-    super.onDetach();
-  }
-
-  /** Intent: the player accepted the call to action — end the session and report the click. */
-  ctaClick(): void {
-    playable.gameEnd();
-    console.info(`[CtaButton] CTA clicked (${this.node?.name ?? this.node?.id ?? 'unknown node'})`);
-  }
-
-  private handlePressed = (): void => {
-    this.scene?.commands.dispatch('cta-click');
-  };
-}