@pix3/cli 1.6.4 → 2.0.0-alpha.0

package/templates/recipe-grid-3d/files/design/recipe.md

@@ -1,110 +0,0 @@
-# Recipe: recipe-grid-3d
-
-## What this is
-
-The 3D carving shape: a solid block of cubes, a perspective camera looking at
-it, and a tap that removes one cube. Some cubes are **core** — hitting one costs
-a life. Clear every non-core cube and the run is won.
-
-Voxel carving, 3D minesweeper, layer puzzles, tap-to-mine, "chip away to reveal
-the shape". If the idea is a 3D thing you touch, start here; if it is a flat
-board of tiles, `recipe-tapper-2d` is the cheaper shape.
-
-**The cubes are generated, not authored.** `GridBoard` builds them under
-`board-anchor` on start, so the board size is a config number
-(`sizeX`/`sizeY`/`sizeZ`), not a scene edit. Do not hand-place cubes in the
-scene — they would not be in the board's map and taps would ignore them.
-
-**Picking is a 3D raycast.** `GridBoard` converts the pointer to normalized
-device coordinates and calls `scene.raycastViewport(nx, ny)`. There are no
-`Hitbox2D` groups on a mesh, so the 2D collision helpers do nothing here.
-
-**Lighting is load-bearing.** `key-light` + `fill-light` are why the block is
-visible; lit materials with no light render pure black, and the editor viewport
-hides that by adding fallback lights the running game does not have. If
-something comes out black, read `sceneIssues` in `scene_tree` / `game_observe`.
-
-**Mobile is the default target.** Every cube is `material.type: lambert` — a
-4×4×4 board is 64 meshes, and PBR at that count is a phone's whole frame budget.
-Past ~8³ move to an `InstancedMesh3D` before you reach for prettier materials.
-
-## Node map
-
-| id | what |
-| --- | --- |
-| `game-root` | 3D scene root; hosts **both** `GridBoard` and `GridRules` |
-| `main-camera` | `Camera3D`, perspective, framed on the block from `[6, 6, 8]` |
-| `key-light` | `DirectionalLightNode` — the shading light |
-| `fill-light` | `HemisphereLightNode` — keeps unlit faces readable |
-| `board-anchor` | empty `Node3D` the generated cubes are parented to; the board centres itself on it |
-| `hud-root` | 2D UI layer; hosts `ScoreHud` |
-| `score-label` | cleared-cube counter |
-| `lives-bar` | `Bar2D` driven by `lives-changed` |
-| `result-overlay` → `result-dim`, `result-label`, `retry-button`, `menu-button` | end screen; own file `scenes/ui/result.pix3scene`, instanced into main with `visible: false` (editor-only hide — `GridRules` shows it) |
-
-Signals, all emitted on `game-root` by `GridBoard` and consumed by `GridRules`:
-`board-built` (clearable, cores) · `cell-cleared` (remaining) · `core-hit`
-(remaining) · `board-cleared`.
-
-## Placeholders
-
-| role | file | node |
-| --- | --- | --- |
-| cube | (none — generated `GeometryMesh`, coloured by `cellColor`) | `board-anchor` children |
-
-## Tunables
-
-```yaml
-tunables:
-  sizeX: { node: game-root, component: "user:GridBoard", property: sizeX, min: 1, max: 10, default: 4 }
-  sizeY: { node: game-root, component: "user:GridBoard", property: sizeY, min: 1, max: 10, default: 4 }
-  sizeZ: { node: game-root, component: "user:GridBoard", property: sizeZ, min: 1, max: 10, default: 4 }
-  coreCount: { node: game-root, component: "user:GridBoard", property: coreCount, min: 0, max: 40, default: 6 }
-  cellSize: { node: game-root, component: "user:GridBoard", property: cellSize, min: 0.1, max: 3, default: 0.9 }
-  spacing: { node: game-root, component: "user:GridBoard", property: spacing, min: 0.1, max: 4, default: 1 }
-  cellColor: { node: game-root, component: "user:GridBoard", property: cellColor, default: "#3ee6c1" }
-  coreColor: { node: game-root, component: "user:GridBoard", property: coreColor, default: "#ff6b6b" }
-  revealCores: { node: game-root, component: "user:GridBoard", property: revealCores, default: false }
-  startingLives: { node: game-root, component: "user:GridRules", property: startingLives, min: 1, max: 9, default: 3 }
-  timeLimitSec: { node: game-root, component: "user:GridRules", property: timeLimitSec, min: 0, max: 600, default: 0 }
-```
-
-`component` present → `set_component_property`; absent → `set_property`.
-
-## Extension points
-
-- **A shape inside the block.** `pickCoreKeys` chooses cores at random from the
-  interior; replace it with a lookup into your own voxel shape and the game
-  becomes "carve until the statue appears".
-- **Layer rules.** `GridBoard.removeCell` is the one place a removal happens —
-  add a cascade (remove neighbours), a combo counter, or a rule that only
-  exposed cubes may be tapped, all from there.
-- **Camera moves.** Animate `main-camera`'s transform, or add a
-  `VirtualCamera3D` rig, to let the player orbit the block between taps.
-- **Feel.** `clearSound` / `coreSound` take a `res://` audio path; the punch and
-  the red flash are already wired through `scene.juice`.
-
-## Do not touch
-
-- **`key-light` / `fill-light`.** Remove them and every cube renders black.
-- **`main-camera`.** No enabled `Camera3D` means nothing 3D is drawn at all, and
-  the raycast has no camera to shoot through — taps stop working too.
-- **`board-anchor`'s id.** `GridBoard.boardAnchor` addresses it by name; renaming
-  one without the other leaves the board unbuilt (it logs a warning and stops).
-- **The `game-root` id.** Portable tests and routines address the run through it.
-
-## Verify
-
-- `play_start`, then `game_observe` — `sceneIssues` must be **absent**, and
-  `game.snapshot()` carries `remaining` (cubes still to clear).
-- Tap the block: `game_input {type:'tap', x:0, y:0}` and assert `remaining` went
-  **down** in `game.changed`. That is the proof a tap reached the board — not a
-  screenshot, which the editor's fallback lighting can flatter. Note the units:
-  tap coordinates are 2D world space, which is **centred on the origin**, so the
-  middle of the screen is `(0, 0)` and not `(540, 960)`.
-- Win: set `sizeX/sizeY/sizeZ: 1` and `coreCount: 0`, then one tap clears the
-  board. Read the *transition*, not the end state: the win overlay appears on the
-  pointer-DOWN that clears the last cube, so the matching pointer-UP can land on
-  the RETRY button underneath the finger and start a fresh run before you look.
-  Assert on `board-cleared` / `game-won`, or tap a last cube that is not under
-  the end screen's buttons.

package/templates/recipe-grid-3d/files/scenes/main.pix3scene

@@ -1,169 +0,0 @@
-# Pix3 Scene File (YAML)
-# Grid 3D — the carving board. The cubes are NOT authored here: GridBoard builds
-# them under `board-anchor` at start, so the board size is a tunable, not a
-# hand-edited tree. Everything else (camera, lights, HUD) is authored here; the
-# end screen lives in scenes/ui/result.pix3scene and is instanced in hidden
-# (`visible: false` = editor only), so this scene opens on the board.
-#
-# Stable node ids (design/recipe.md is the contract — do not rename these):
-#   game-root, main-camera, key-light, fill-light, board-anchor,
-#   hud-root, score-label, lives-bar,
-#   result-overlay, result-label, retry-button, menu-button (scenes/ui/result.pix3scene)
-version: 1.0.0
-metadata:
-  author: Pix3 Template
-  description: Tap-to-carve 3D grid with a hidden core
-root:
-  - id: game-root
-    type: Node3D
-    name: Game Root
-    properties:
-      transform:
-        position: [0, 0, 0]
-        rotationEuler: [0, 0, 0]
-        scale: [1, 1, 1]
-    components:
-      - id: grid-board
-        type: user:GridBoard
-        enabled: true
-        config:
-          boardAnchor: board-anchor
-          sizeX: 4
-          sizeY: 4
-          sizeZ: 4
-          cellSize: 0.9
-          spacing: 1
-          coreCount: 6
-          cellColor: "#3ee6c1"
-          coreColor: "#ff6b6b"
-          revealCores: false
-      - id: grid-rules
-        type: user:GridRules
-        enabled: true
-        config:
-          startingLives: 3
-          timeLimitSec: 0
-          resultNode: result-overlay
-          resultLabel: result-label
-          retryButton: retry-button
-          menuButton: menu-button
-    children:
-      - id: main-camera
-        type: Camera3D
-        name: Main Camera
-        properties:
-          projection: perspective
-          fov: 50
-          near: 0.1
-          far: 200
-          # Aimed exactly at the origin, where the board centres itself. Solved for the engine's
-          # XYZ Euler order (R = Rx·Ry), NOT the yaw-then-pitch YXZ order the numbers would have
-          # under a camera rig: pitch = -asin(0.6) = -36.87°, yaw = asin(6/|[6,6,8]|) = 30.96°.
-          # Swap the two and the view tilts off target — invisible on a full board (some cube
-          # still catches the centre ray) and fatal on a 1x1x1 one, which is why the recipe's
-          # Verify section shrinks the board.
-          transform:
-            position: [6, 6, 8]
-            rotationEuler: [-36.87, 30.96, 0]
-            scale: [1, 1, 1]
-        children: []
-      - id: key-light
-        type: DirectionalLightNode
-        name: Key Light
-        properties:
-          intensity: 1.1
-          color: "#ffffff"
-          transform:
-            position: [6, 9, 4]
-            rotationEuler: [-50, 30, 0]
-            scale: [1, 1, 1]
-        children: []
-      - id: fill-light
-        type: HemisphereLightNode
-        name: Fill Light
-        properties:
-          skyColor: "#e9f5ff"
-          groundColor: "#717786"
-          intensity: 0.7
-          transform:
-            position: [0, 0, 0]
-            rotationEuler: [0, 0, 0]
-            scale: [1, 1, 1]
-        children: []
-      - id: board-anchor
-        type: Node3D
-        name: Board Anchor
-        properties:
-          transform:
-            position: [0, 0, 0]
-            rotationEuler: [0, 0, 0]
-            scale: [1, 1, 1]
-        children: []
-
-  - id: hud-root
-    type: Group2D
-    name: HUD Root
-    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: "CLEARED {value}"
-          timeLabel: ""
-          livesBar: lives-bar
-    children:
-      - id: score-label
-        type: Label2D
-        name: Score Label
-        properties:
-          label: "CLEARED 0"
-          labelFontSize: 48
-          labelColor: "#f2f2f2"
-          labelAlign: center
-          transform:
-            position: [0, 820]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: top
-        children: []
-      - id: lives-bar
-        type: Bar2D
-        name: Lives Bar
-        properties:
-          width: 360
-          height: 26
-          value: 3
-          maxValue: 3
-          barColor: "#ff6b6b"
-          backBackgroundColor: "#1b1f2a"
-          transform:
-            position: [0, 740]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: top
-        children: []
-      # Win/lose screen — authored in scenes/ui/result.pix3scene so this scene
-      # opens on the BOARD, not on an end card. `visible: false` hides it in the
-      # EDITOR only; `initiallyVisible` (in the overlay file) is what play mode
-      # reads, and GridRules reveals it on the win/lose transition. Tick the eye
-      # to preview it composited over the board.
-      - id: result-overlay
-        name: Result Overlay
-        instance: res://scenes/ui/result.pix3scene
-        properties:
-          visible: false

package/templates/recipe-grid-3d/files/scenes/menu.pix3scene

@@ -1,100 +0,0 @@
-# Pix3 Scene File (YAML)
-# Grid 3D — the MENU scene. This is the project's ENTRY / export scene
-# (Project Settings → Default Export Scene Path): a full build and "Play Game (Entry Scene)"
-# boot here. PLAY transitions to the game scene (main.pix3scene) via a fade.
-# Wired by scripts/MenuFlow.ts. Iterate on the GAME in main.pix3scene.
-version: 1.0.0
-metadata:
-  author: Pix3 Recipe
-  description: Menu scene — entry point; PLAY transitions to the carving board
-root:
-  - id: menu-root
-    type: Group2D
-    name: Menu Root
-    properties:
-      width: 1080
-      height: 1920
-      layout:
-        enabled: true
-        horizontalAlign: stretch
-        verticalAlign: stretch
-    components:
-      - id: menu-flow
-        type: user:MenuFlow
-        enabled: true
-        config:
-          gameScene: res://scenes/main.pix3scene
-          playButton: play-button
-    children:
-      - id: menu-background
-        type: ColorRect2D
-        name: Menu Background
-        properties:
-          width: 1080
-          height: 1920
-          color: "#1b1f2a"
-          transform:
-            position: [0, 0]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: stretch
-            verticalAlign: stretch
-        children: []
-      - id: title-label
-        type: Label2D
-        name: Title Label
-        properties:
-          label: "{{PROJECT_NAME}}"
-          labelFontSize: 96
-          labelColor: "#ffffff"
-          labelAlign: center
-          transform:
-            position: [0, 420]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []
-      - id: subtitle-label
-        type: Label2D
-        name: Subtitle Label
-        properties:
-          label: "CARVE THE BLOCK. SPARE THE CORE."
-          labelFontSize: 40
-          labelColor: "#93a3c9"
-          labelAlign: center
-          transform:
-            position: [0, 300]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []
-      - id: play-button
-        type: Button2D
-        name: Play Button
-        properties:
-          width: 480
-          height: 140
-          label: "PLAY"
-          labelFontSize: 56
-          labelColor: "#141a2e"
-          backgroundColor: "#f5ae39"
-          hoverColor: "#ffc862"
-          pressedColor: "#d4922a"
-          buttonAction: play
-          transform:
-            position: [0, -60]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []

package/templates/recipe-grid-3d/files/scenes/ui/result.pix3scene

@@ -1,105 +0,0 @@
-# Pix3 Scene File (YAML)
-# Grid 3D — the RESULT overlay (win/lose), in its own file so the board scene
-# opens clean. `main.pix3scene` carries it as a one-line `instance:` reference
-# marked `visible: false`, which hides it in the EDITOR only; `user:GridRules`
-# reveals it at run time by setting `visible`.
-#
-# Edit it here, full-screen, in its own tab. To preview it composited over the
-# board, tick the eye on `result-overlay` in main.pix3scene — just do not commit
-# that tick, or every iteration starts behind an end screen again.
-#
-# Stable node ids (design/recipe.md is the contract — do not rename these):
-#   result-overlay, result-label, retry-button, menu-button
-version: 1.0.0
-metadata:
-  author: Pix3 Template
-  description: Result overlay — dim, win/lose headline, RETRY and MENU buttons
-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: "#0b0e14"
-          opacity: 0.78
-          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: "SHAPE REVEALED"
-          labelFontSize: 76
-          labelColor: "#3ee6c1"
-          labelAlign: center
-          transform:
-            position: [0, 220]
-            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: 52
-          labelColor: "#0b0e14"
-          backgroundColor: "#3ee6c1"
-          hoverColor: "#63f0d3"
-          pressedColor: "#2bbfa0"
-          transform:
-            position: [0, -60]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []
-      - id: menu-button
-        type: Button2D
-        name: Menu Button
-        properties:
-          width: 420
-          height: 110
-          label: "MENU"
-          labelFontSize: 44
-          labelColor: "#f2f2f2"
-          backgroundColor: "#1b1f2a"
-          hoverColor: "#2a3040"
-          pressedColor: "#141821"
-          transform:
-            position: [0, -220]
-            scale: [1, 1]
-            rotation: 0
-          layout:
-            enabled: true
-            horizontalAlign: center
-            verticalAlign: center
-        children: []