@pix3/cli 1.6.0

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

@@ -0,0 +1,230 @@
+# Pix3 Scene File (YAML)
+# Playable 3D blank (portrait 1080x1920): 3D gameplay placeholder plus a 2D UI
+# layer with a tap-to-start intro overlay, a score/lives/time HUD, and an end
+# screen with a CTA button. `hud-root` carries all three components: GameFlow
+# (phases), GameRules (score/lives/win-lose) and ScoreHud (display only).
+#
+# Full-screen UI lives in its own file under scenes/ui/ and is instanced into
+# `hud-root` hidden (`visible: false` = editor only; `initiallyVisible` in the
+# overlay file is what play mode reads), so opening this scene shows the stage
+# 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,
+# `GameRules`' resultLabel and every `findNode` still resolve.
+version: 1.0.0
+metadata:
+  author: Pix3 Template
+  description: Playable 3D blank with intro overlay and CTA end screen
+root:
+  - id: game-root
+    type: Node3D
+    name: Game Root
+    properties:
+      transform:
+        position: [0, 0, 0]
+        rotationEuler: [0, 0, 0]
+        scale: [1, 1, 1]
+    children:
+      - id: main-camera
+        type: Camera3D
+        name: Main Camera
+        properties:
+          projection: perspective
+          fov: 60
+          near: 0.1
+          far: 1000
+          transform:
+            position: [0, 3, 8]
+            rotationEuler: [-15, 0, 0]
+            scale: [1, 1, 1]
+        children: []
+      - id: key-light
+        type: DirectionalLightNode
+        name: Key Light
+        properties:
+          intensity: 1.2
+          color: "#ffffff"
+          transform:
+            position: [5, 8, 3]
+            rotationEuler: [-45, 35, 0]
+            scale: [1, 1, 1]
+        children: []
+      - id: ambient-light
+        type: AmbientLightNode
+        name: Ambient Light
+        properties:
+          intensity: 0.5
+          color: "#ffffff"
+          transform:
+            position: [0, 0, 0]
+            rotationEuler: [0, 0, 0]
+            scale: [1, 1, 1]
+        children: []
+      - id: ground
+        type: GeometryMesh
+        name: Ground
+        properties:
+          geometry: box
+          size: [12, 0.2, 12]
+          material:
+            type: lambert
+            color: "#2a2a3e"
+          transform:
+            position: [0, -0.1, 0]
+            rotationEuler: [0, 0, 0]
+            scale: [1, 1, 1]
+        children: []
+      - id: hero-box
+        type: GeometryMesh
+        name: Hero Box
+        properties:
+          geometry: box
+          size: [1, 1, 1]
+          material:
+            type: lambert
+            color: "#ffcf33"
+          transform:
+            position: [0, 0.5, 0]
+            rotationEuler: [0, 45, 0]
+            scale: [1, 1, 1]
+        components:
+          - id: hero-rotate
+            type: core:Rotate
+            enabled: true
+            config: {}
+        children: []
+
+  - id: hud-root
+    type: Group2D
+    name: HUD 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
+          skipIntro: false
+      - id: game-rules
+        type: user:GameRules
+        enabled: true
+        config:
+          winMode: score
+          targetScore: 10
+          timeLimitSec: 0
+          startingLives: 3
+          resultLabel: end-label
+          winText: "YOU WIN!"
+          loseText: "GAME OVER"
+          # The run starts when GameFlow leaves the tap gate, not when the scene loads.
+          startWithFlow: true
+      - id: score-hud
+        type: user:ScoreHud
+        enabled: true
+        config:
+          sourceNode: hud-root
+          scoreLabel: score-label
+          scoreFormat: "SCORE {value}"
+          timeLabel: time-label
+          timeFormat: "{value}"
+          livesBar: lives-bar
+    children:
+      - id: hud-label
+        type: Label2D
+        name: HUD Label
+        properties:
+          label: "PROTOTYPE"
+          labelFontSize: 40
+          labelColor: "#ffffff"
+          labelAlign: center
+          transform:
+            position: [0, 780]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: top
+        children: []
+      - id: score-label
+        type: Label2D
+        name: Score Label
+        properties:
+          label: "SCORE 0"
+          labelFontSize: 44
+          labelColor: "#ffffff"
+          labelAlign: left
+          transform:
+            position: [-340, 880]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: left
+            verticalAlign: top
+        children: []
+      - id: time-label
+        type: Label2D
+        name: Time Label
+        properties:
+          label: "0"
+          labelFontSize: 44
+          labelColor: "#f5ae39"
+          labelAlign: center
+          transform:
+            position: [0, 880]
+            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, 885]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: right
+            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 stage.
+      - 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 stage.
+      - id: end-screen
+        name: End Screen
+        instance: res://scenes/ui/end-screen.pix3scene
+        properties:
+          visible: false

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

@@ -0,0 +1,91 @@
+# Pix3 Scene File (YAML)
+# Playable 3D — 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-3d/files/scenes/ui/intro.pix3scene

@@ -0,0 +1,65 @@
+# Pix3 Scene File (YAML)
+# Playable 3D — 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-3d/files/scripts/CtaButton.ts

@@ -0,0 +1,55 @@
+/**
+ * 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');
+  };
+}