@pix3/cli 1.6.0

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

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

@@ -0,0 +1,169 @@
+# 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

@@ -0,0 +1,100 @@
+# 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

@@ -0,0 +1,105 @@
+# 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: []