@pix3/cli 1.6.3 → 2.0.0-alpha.0

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

@@ -1,256 +0,0 @@
-/**
- * GameFlow — the playable's phase driver: intro → playing → ended.
- *
- * Attach to `game-root`. While the intro overlay is visible, the first tap
- * hides it and starts the game (the tap also unlocks browser audio — the
- * engine's AudioService resumes its context on the first gesture). The end
- * screen is revealed either by calling `finish()` from game code or, as a
- * placeholder, after `autoWinAfterSec` seconds. Replace the timer with your
- * real win/lose condition.
- *
- * `skipIntro` starts the run already playing, gate hidden — a prototyping vent, so
- * that iterating on the game does not cost a tap per reload. Turn it back off before
- * shipping: in an ad container the first tap is what unlocks browser audio, so a
- * playable that never gates on one is a playable that plays silently.
- *
- * Two conventions here are worth keeping as you replace the placeholder:
- *
- * - **Intent-first handlers.** Every reaction to the player lives in a named
- *   public method marked `Intent:` (`start`, `finish`, `restart`), and the ones
- *   a test drives are registered as commands (`scene.commands`) that the event
- *   handler dispatches. Game code and automated tests then drive the game by
- *   intent instead of by simulated pixels — `scene.commands.dispatch('restart')`
- *   — the flow survives any relayout of the UI, and every raised intent is
- *   journalled with the frame it happened on.
- * - **A debug provider.** `registerGameDebug` publishes a JSON snapshot of the
- *   run so external tooling (the editor's debug bridge, DevTools, an agent) can
- *   read the phase instead of guessing it from the screen. Add your own fields
- *   as you add state — keep everything JSON-serialisable.
- */
-import { Script, playable, registerGameDebug, type PropertySchema } from '@pix3/runtime';
-
-export class GameFlow extends Script {
-  private phase: 'intro' | 'playing' | 'ended' = 'intro';
-  private elapsed = 0;
-  private disposeDebug: (() => void) | null = null;
-  private disposeCommands: (() => void)[] = [];
-
-  constructor(id: string, type: string) {
-    super(id, type);
-    this.config = {
-      // Node id/name of the tap-to-start overlay.
-      introNode: 'intro-overlay',
-      // Node id/name of the end screen with the CTA button.
-      endNode: 'end-screen',
-      // Placeholder auto-win timer in seconds (0 = never; call finish() instead).
-      autoWinAfterSec: 15,
-      // Prototyping vent: start in `playing` with the gate already gone.
-      skipIntro: false,
-    };
-  }
-
-  static getPropertySchema(): PropertySchema {
-    return {
-      nodeType: 'GameFlow',
-      properties: [
-        {
-          name: 'introNode',
-          type: 'string',
-          ui: { label: 'Intro Overlay', group: 'Flow' },
-          getValue: s => (s as GameFlow).config.introNode,
-          setValue: (s, v) => {
-            (s as GameFlow).config.introNode = typeof v === 'string' ? v : '';
-          },
-        },
-        {
-          name: 'endNode',
-          type: 'string',
-          ui: { label: 'End Screen', group: 'Flow' },
-          getValue: s => (s as GameFlow).config.endNode,
-          setValue: (s, v) => {
-            (s as GameFlow).config.endNode = typeof v === 'string' ? v : '';
-          },
-        },
-        {
-          name: 'autoWinAfterSec',
-          type: 'number',
-          ui: {
-            label: 'Auto Win After (s)',
-            description: 'Placeholder timer that reveals the end screen (0 = disabled)',
-            group: 'Flow',
-            min: 0,
-            step: 1,
-          },
-          getValue: s => (s as GameFlow).config.autoWinAfterSec,
-          setValue: (s, v) => {
-            (s as GameFlow).config.autoWinAfterSec = Math.max(0, Number(v) || 0);
-          },
-        },
-        {
-          name: 'skipIntro',
-          type: 'boolean',
-          ui: {
-            label: 'Skip Intro',
-            description:
-              'Start already playing, with the tap gate hidden. For prototyping only — a shipped playable needs the tap to unlock audio.',
-            group: 'Flow',
-          },
-          getValue: s => (s as GameFlow).config.skipIntro === true,
-          setValue: (s, v) => {
-            (s as GameFlow).config.skipIntro = v === true;
-          },
-        },
-      ],
-      groups: { Flow: { label: 'Game Flow', expanded: true } },
-    };
-  }
-
-  onStart(): void {
-    const commands = this.scene?.commands;
-    this.disposeCommands = [
-      commands?.register('start-game', () => this.start(), {
-        description: 'Leave the intro overlay and begin play.',
-      }),
-      // `finish` is registered for the same reason `start-game` is: a test (and the
-      // rest of the game) must be able to END the run by intent instead of waiting
-      // out the placeholder timer — and a routine that reached in and called
-      // `finish()` directly would prove the method works while skipping the wire
-      // from the player to it. Replace the timer with your win/lose condition and
-      // dispatch this from there.
-      commands?.register('finish', () => this.finish(), {
-        description: 'End the run and reveal the end screen.',
-      }),
-      commands?.register('restart', () => this.restart(), {
-        description: 'Return to the tap-to-start gate and arm a fresh run.',
-      }),
-    ].filter((dispose): dispose is () => void => dispose !== undefined);
-
-    this.disposeDebug = registerGameDebug({
-      name: 'playable-2d',
-      version: 1,
-      // The registry IS the action list — never a second, hand-kept copy.
-      actions: () => this.scene?.commands.list().map(command => command.name) ?? [],
-      // What "the start" means for this playable, so a test can put the game back
-      // without restarting the scene (a restart keeps whatever a script parked in
-      // module state; this does not). It is `restart()` plus the one thing that
-      // lives OUTSIDE the scene and would otherwise leak into the next run: the
-      // SDK's session `gameEnded` flag, which `playable.gameEnd()` latched.
-      // `seed` is accepted and ignored — the placeholder flow has no randomness,
-      // so this restores the same starting state, not the same sequence. Seed
-      // your own RNG here once you add one.
-      reset: () => {
-        this.restart();
-        playable.reset();
-      },
-      snapshot: () => ({
-        phase: this.phase,
-        elapsedSec: Math.round(this.elapsed * 100) / 100,
-        autoWinAfterSec: Number(this.config.autoWinAfterSec) || 0,
-        skipIntro: this.config.skipIntro === true,
-        introVisible: this.isNodeVisible(String(this.config.introNode ?? '')),
-        endVisible: this.isNodeVisible(String(this.config.endNode ?? '')),
-        // Set by playable.gameEnd() — the CTA button reports the session as over.
-        gameEnded: playable.hasGameEnded(),
-      }),
-    });
-
-    if (this.config.skipIntro === true) {
-      this.openTheGate();
-    }
-  }
-
-  onDetach(): void {
-    this.disposeDebug?.();
-    this.disposeDebug = null;
-    // The scene's registry is cleared on stop anyway; this covers the other
-    // case — this script being detached while the scene keeps running.
-    for (const dispose of this.disposeCommands) {
-      dispose();
-    }
-    this.disposeCommands = [];
-    super.onDetach();
-  }
-
-  onUpdate(dt: number): void {
-    if (this.phase === 'intro') {
-      const tapped = this.input?.pointerEvents.some(e => e.type === 'down') ?? false;
-      if (tapped) {
-        // Raised through the registry, so the tap-to-start gate shows up in the
-        // command journal exactly like a dispatched `start-game` would.
-        this.scene?.commands.dispatch('start-game');
-      }
-      return;
-    }
-
-    if (this.phase === 'playing') {
-      const autoWin = Number(this.config.autoWinAfterSec) || 0;
-      if (autoWin > 0) {
-        this.elapsed += dt;
-        if (this.elapsed >= autoWin) {
-          this.finish();
-        }
-      }
-    }
-  }
-
-  /** Intent: leave the intro overlay and begin play. Raised by the first tap. */
-  start(): void {
-    if (this.phase !== 'intro') {
-      return;
-    }
-    this.openTheGate();
-  }
-
-  /**
-   * Hide the gate and go to `playing`. Shared by the tap and by `skipIntro`, so the two
-   * cannot drift into two slightly different notions of "the run has begun".
-   */
-  private openTheGate(): void {
-    this.setNodeVisible(String(this.config.introNode ?? ''), false);
-    this.phase = 'playing';
-  }
-
-  /** Intent: end the run and reveal the end screen. Call this from game code on win/lose. */
-  finish(): void {
-    if (this.phase === 'ended') {
-      return;
-    }
-    this.phase = 'ended';
-    this.setNodeVisible(String(this.config.endNode ?? ''), true);
-  }
-
-  /**
-   * Intent: arm a fresh run — back at the tap-to-start gate, or straight into play when
-   * `skipIntro` is on. A restart that re-raised a gate the project has turned off would
-   * strand every routine that restarts between checks behind a tap nobody is going to make.
-   */
-  restart(): void {
-    this.phase = 'intro';
-    this.elapsed = 0;
-    this.setNodeVisible(String(this.config.endNode ?? ''), false);
-    this.setNodeVisible(String(this.config.introNode ?? ''), true);
-    if (this.config.skipIntro === true) {
-      this.openTheGate();
-    }
-  }
-
-  private setNodeVisible(query: string, visible: boolean): void {
-    if (!query) {
-      return;
-    }
-    const node = this.findNode(query);
-    if (node) {
-      node.visible = visible;
-    } else {
-      console.warn(`[GameFlow] Node "${query}" not found.`);
-    }
-  }
-
-  /** Own `visible` flag of a configured node, or null when it is not in the scene. */
-  private isNodeVisible(query: string): boolean | null {
-    if (!query) {
-      return null;
-    }
-    return this.findNode(query)?.visible ?? null;
-  }
-}

package/templates/playable-2d/template.yaml

@@ -1,9 +0,0 @@
-id: playable-2d
-title: Playable 2D
-description: Portrait 2D 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-playable-ad
-projectType: 2d
-targetPlatform: mobile
-viewport: { width: 1080, height: 1920 }
-order: 40

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

@@ -1,32 +0,0 @@
-# {{PROJECT_NAME}}
-
-A Pix3 project created from the **Playable 3D** 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 demo box and ground 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. `skipIntro: true` starts already playing while you iterate; turn it off before shipping, since that first tap is what unlocks audio.
-- **Bookkeeping, already built** (`scripts/GameRules.ts` + `scripts/ScoreHud.ts`) — score, lives, an optional clock, the win/lose decision and the HUD that shows them. Your mechanic calls `addScore(1)` / `loseLife()` / `finish(true)`, or emits `score-added` / `life-lost` on `hud-root`; don't write a second score counter or result screen.
-- **Readable state** — `GameFlow` publishes the one `registerGameDebug` snapshot (phase, timer, overlay visibility, session end, plus the rules' score/lives/time), so tooling reads the run's state instead of judging it from a screenshot. Add your own fields there — a second provider would silently replace this one.
-- **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.
-- **Canonical roots** — `game-root` holds the 3D scene, `hud-root` the 2D overlay layer (intro gate, HUD, end screen); routines and assertions address them by those ids.
-
-## 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-3d/files/design/recipe.md

@@ -1,127 +0,0 @@
-# Recipe: recipe-scene-3d
-
-## What this is
-
-The only **3D** recipe: a portrait scene with a real 3D stage — perspective
-`Camera3D`, a key light and an ambient fill, a ground slab and one hero solid —
-under a 2D UI layer with a tap-to-start gate and an end screen with a CTA.
-
-Reach for it whenever the idea is genuinely three-dimensional — a cube you carve,
-a stack you topple, a solid you inspect from all sides. Every other recipe is 2D,
-and a 3D idea faked with isometric sprites is not the same game.
-
-The gameplay is a placeholder — `hero-box` spinning on a `core:Rotate`, plus an
-auto-win timer. Replace both; keep the camera, the lights and the gate.
-
-**The bookkeeping is already built.** `GameRules` keeps score, lives and the clock and
-decides win/lose; `ScoreHud` displays them. Your first increment is the *mechanic*: call
-`addScore(1)` / `loseLife()` / `finish(true)`, or emit `score-added` / `life-lost` on
-`hud-root`. Never write a second score counter, HUD label or result screen.
-
-**Lighting is load-bearing.** Lit materials with no light render pure black, and
-the editor viewport hides that by adding fallback lights the running game has not.
-`key-light` and `ambient-light` are why this scene is visible — never delete them.
-A mesh that comes out black is reported by the scene lint (`sceneIssues` in
-`scene_tree` / `game_observe`).
-
-**Mobile is the default target.** Meshes use `material.type: lambert`
-(diffuse-only), not PBR: the shapes read the same at a fraction of the per-pixel
-cost, and new geometry inherits it. `standard` (PBR) is for a `desktop`
-`targetPlatform` — switch one mesh with `set_property <node> materialType
-standard` when the user asks for a high-end look. `basic` (unlit) is cheaper
-still and the one family that cannot render black for want of a light.
-
-## Node map
-
-| id | what |
-| --- | --- |
-| `game-root` | 3D scene root (`Node3D`) |
-| `main-camera` | `Camera3D`, perspective, looking down at the stage from `[0, 3, 8]` |
-| `key-light` | `DirectionalLightNode` — the shading light; angle it, don't remove it |
-| `ambient-light` | `AmbientLightNode` — the fill that keeps unlit faces readable |
-| `ground` | `GeometryMesh` box, 12×0.2×12, the floor slab |
-| `hero-box` | `GeometryMesh` box placeholder, spinning on `core:Rotate` |
-| `hud-root` | 2D UI layer (`Group2D`, stretched); hosts `GameFlow` (intro → playing → ended), `GameRules` (score/lives/win-lose) and `ScoreHud` (display only) |
-| `hud-label` | in-game text line |
-| `score-label` | `SCORE n`, driven by the `score-changed` signal |
-| `time-label` | seconds — counts up with no time limit, down with one |
-| `lives-bar` | `Bar2D` fed by `lives-changed` |
-| `intro-overlay` → `intro-dim`, `intro-label` | the tap gate (`scenes/ui/intro.pix3scene`, instanced into `hud-root`); the first tap hides it, starts the game, unlocks browser audio |
-| `end-screen` → `end-dim`, `end-label`, `cta-button` | end screen (`scenes/ui/end-screen.pix3scene`, instanced into `hud-root`), `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 |
-
-End a run with `GameRules.finish(won)` — it writes the outcome text and dispatches
-`GameFlow`'s `finish`. One end screen, one phase machine, one debug snapshot (the
-rules' numbers ride inside GameFlow's).
-
-## Placeholders
-
-| role | file | node |
-| --- | --- | --- |
-| hero | (none — `hero-box` is untextured geometry) | `hero-box` |
-
-## Tunables
-
-```yaml
-tunables:
-  autoWinAfterSec: { node: hud-root, component: "user:GameFlow", property: autoWinAfterSec, min: 0, max: 120, default: 15 }
-  introNode: { node: hud-root, component: "user:GameFlow", property: introNode, default: intro-overlay }
-  endNode: { node: hud-root, component: "user:GameFlow", property: endNode, default: end-screen }
-  skipIntro: { node: hud-root, component: "user:GameFlow", property: skipIntro, default: false }
-  winMode: { node: hud-root, component: "user:GameRules", property: winMode, default: score }
-  targetScore: { node: hud-root, component: "user:GameRules", property: targetScore, min: 1, max: 99999, default: 10 }
-  timeLimitSec: { node: hud-root, component: "user:GameRules", property: timeLimitSec, min: 0, max: 600, default: 0 }
-  startingLives: { node: hud-root, component: "user:GameRules", property: startingLives, min: 1, max: 20, default: 3 }
-  keyLightIntensity: { node: key-light, property: intensity, min: 0, max: 4, default: 1.2 }
-  ambientIntensity: { node: ambient-light, property: intensity, min: 0, max: 2, default: 0.5 }
-```
-
-`component` present → `set_component_property`; absent → `set_property`.
-
-`skipIntro: true` starts already playing, gate hidden — a prototyping vent, off before
-shipping: that first tap is what unlocks browser audio. Mesh colour is not a declared
-tunable — it lives under `material.color` and is edited with
-`set_property <node> color "#rrggbb"`.
-
-## Extension points
-
-- **Real geometry.** `create_node` more `GeometryMesh` nodes (`box`, `sphere`,
-  `cylinder`, …) with `position3`, or point `hero-box` at a `.glb` as a
-  `MeshInstance3D`. A grid or stack of solids is a loop over `create_node`.
-- **Picking.** 3D taps come from the raycast API, not 2D hit-testing: read the
-  pointer in a script and ray-test the meshes. That is the backbone of every
-  "tap the block" mechanic.
-- **Camera moves.** Orbit or pull back by animating `main-camera`'s transform, or
-  add a `VirtualCamera3D` rig if the game needs blends between framings.
-- **Real gameplay.** Set `autoWinAfterSec: 0` and let `GameRules` end the run:
-  `addScore`/`score-added`, `loseLife`/`life-lost`, and a win condition picked with
-  `winMode` + `targetScore` + `timeLimitSec` instead of one you write.
-
-## Do not touch
-
-- **`key-light` / `ambient-light`.** Deleting or disabling them makes every lit
-  mesh black. Re-colour and re-angle freely; keep at least one enabled light.
-- **`main-camera`.** A 3D scene with no enabled `Camera3D` draws nothing at all.
-- **The `hud-root` layout.** Stretched to the safe area on purpose; nest new UI
-  inside it, never add a second full-screen root.
-- **`GameFlow`'s `introNode` / `endNode` ids.** They address nodes by id: renaming a
-  node without updating them breaks the phase machine silently. Same for `ScoreHud`'s
-  `sourceNode` / label ids.
-- **The overlay instances.** `intro-overlay` / `end-screen` in `main.pix3scene` are
-  `instance:` nodes marked `visible: false` — an editor-only hide so the scene opens
-  on the stage. Keep it; `initiallyVisible` lives in the overlay file (`true` for
-  the gate, `false` for the end screen), never as an instance override.
-- **A second `registerGameDebug`.** `GameFlow` publishes the only one (rules' numbers
-  merged in); a second silently replaces it. Add fields to that snapshot.
-
-## Verify
-
-- `play_start`, then `game_observe` — check `sceneIssues` is **absent**. A
-  `lit-material-no-light` or `no-camera-3d` entry means the scene cannot draw.
-- Tap the gate: `game_input {type:'tap', target:'intro-overlay'}` and confirm
-  `intro-overlay` goes invisible and the game phase advances.
-- Read scoring back as data: the snapshot carries `score`, `lives`, `timeLeftSec`
-  and `outcome` next to `phase` — never judge a counter from a picture.
-- Judge the win with `game_run` and an `until` that names what success is (e.g.
-  `end-screen` visible), not with a screenshot — the editor viewport adds
-  fallback lights, so a picture cannot prove the running game is lit.

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

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

package/templates/playable-3d/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. GameFlow rides the 2D overlay layer (hud-root), above the 3D game-root.",
-  "scope": "scenes/main.pix3scene",
-  "params": {},
-  "uses": ["game-root", "hud-root", "intro-overlay", "end-screen", "cta-button", "hero-box"],
-  "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 }
-  ]
-}