@pix3/cli 1.6.0

package/templates/recipe-bouncer-2d/files/scenes/menu.pix3scene

@@ -0,0 +1,191 @@
+# Pix3 Scene File (YAML)
+# Bouncer 2D — 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.
+#
+# Same neon recipe as the game scene: darkest ColorRect + a tinted radial
+# gradient placeholder, a `PostProcess` node so bright accents bloom, and
+# Label2D's own glow on the text. Nothing here is a CanvasLayer2D, so the title
+# gets BOTH the canvas glow and the bloom — keep `menuBloomIntensity` modest or
+# large white type turns to mush.
+version: 1.0.0
+metadata:
+  author: Pix3 Recipe
+  description: Menu scene — entry point; PLAY transitions to the game
+root:
+  - id: menu-post-fx
+    type: PostProcess
+    name: Menu Post FX
+    properties:
+      affect2D: true
+      bloomEnabled: true
+      bloomIntensity: 0.7
+      bloomThreshold: 0.6
+      bloomSmoothing: 0.2
+      bloomRadius: 0.8
+      vignetteEnabled: true
+      vignetteOffset: 0.28
+      vignetteDarkness: 0.55
+      chromaticAberrationEnabled: false
+    children: []
+  - 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: "#05030f"
+          transform:
+            position: [0, 0]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: stretch
+            verticalAlign: stretch
+        children: []
+      - id: menu-bg-glow
+        type: Sprite2D
+        name: Menu Background Glow
+        properties:
+          texture: { type: 'texture', url: 'res://sprites/ph-bg.png' }
+          width: 1080
+          height: 1920
+          effects:
+            - type: core:tint
+              params: { color: "#5a2df0", amount: 1 }
+          transform:
+            position: [0, 0]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: stretch
+            verticalAlign: stretch
+        children: []
+      # The project title is patched into this node on project creation — keep
+      # the id. `width` is set so a long title WRAPS instead of running off
+      # screen (Label2D word-wraps to its box; 0 would auto-size and overflow).
+      - id: title-label
+        type: Label2D
+        name: Title Label
+        properties:
+          label: "{{PROJECT_NAME}}"
+          labelFontSize: 112
+          labelColor: "#ffffff"
+          labelAlign: center
+          width: 960
+          glowColor: "#2ef2ff"
+          glowStrength: 2.5
+          transform:
+            position: [0, 420]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: center
+        components:
+          - id: title-pop
+            type: core:PopIn
+            enabled: true
+            config:
+              from: 0.55
+              duration: 0.5
+              easing: backOut
+              playOnStart: true
+              triggerEvent: ""
+          - id: title-breathe
+            type: core:Sine
+            enabled: true
+            config:
+              amplitude: 12
+              frequency: 0.28
+              axis: y
+        children: []
+      - id: title-rule
+        type: ColorRect2D
+        name: Title Rule
+        properties:
+          width: 520
+          height: 6
+          color: "#2ef2ff"
+          transform:
+            position: [0, 352]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: center
+        children: []
+      - id: subtitle-label
+        type: Label2D
+        name: Subtitle Label
+        properties:
+          label: "KEEP THE BALL ALIVE."
+          labelFontSize: 40
+          labelColor: "#8ffcff"
+          labelAlign: center
+          glowColor: "#2ef2ff"
+          glowStrength: 1
+          transform:
+            position: [0, 280]
+            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: "#0d0724"
+          backgroundColor: "#ffd23f"
+          hoverColor: "#ffe98a"
+          pressedColor: "#d49a1f"
+          buttonAction: play
+          transform:
+            position: [0, -60]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: center
+        components:
+          - id: play-pop
+            type: core:PopIn
+            enabled: true
+            config:
+              from: 0.7
+              duration: 0.45
+              easing: backOut
+              playOnStart: true
+              triggerEvent: ""
+        children: []

package/templates/recipe-bouncer-2d/files/scenes/ui/result.pix3scene

@@ -0,0 +1,87 @@
+# Pix3 Scene File (YAML)
+# Bouncer 2D — the RESULT overlay (win/lose), in its own file so the gameplay
+# scene opens clean. `main.pix3scene` carries it as a one-line
+# `instance:` reference marked `visible: false`, which hides it in the EDITOR
+# only; `user:GameRules` reveals it at run time by setting `visible`.
+#
+# Edit it here, full-screen, in its own tab. To preview it composited over the
+# game, tick the eye on `result-overlay` in main.pix3scene — just do not commit
+# that tick, or every iteration starts behind a GAME OVER screen again.
+#
+# Stable node ids (design/recipe.md is the contract — do not rename these):
+#   result-overlay, result-label, retry-button
+version: 1.0.0
+metadata:
+  author: Pix3 Recipe
+  description: Result overlay — dim, glowing win/lose headline and a RETRY button
+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: "#05030f"
+          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: "GAME OVER"
+          labelFontSize: 96
+          labelColor: "#ffffff"
+          labelAlign: center
+          glowColor: "#2ef2ff"
+          glowStrength: 2.5
+          transform:
+            position: [0, 160]
+            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: 50
+          labelColor: "#0d0724"
+          backgroundColor: "#ffd23f"
+          hoverColor: "#ffe98a"
+          pressedColor: "#d49a1f"
+          buttonAction: retry
+          transform:
+            position: [0, -60]
+            scale: [1, 1]
+            rotation: 0
+          layout:
+            enabled: true
+            horizontalAlign: center
+            verticalAlign: center
+        children: []

package/templates/recipe-bouncer-2d/files/scripts/BallBody.ts

@@ -0,0 +1,298 @@
+/**
+ * BallBody — the ball's motion and collisions.
+ *
+ * The engine ships no rigidbody solver, and `core:Hitbox2D` is an axis-aligned
+ * overlap test that ignores rotation — useless for a fast ball and impossible
+ * for an angled paddle. So this component runs the swept solver in
+ * `ball-collision.ts` and builds its colliders every frame from the LIVE WORLD
+ * TRANSFORMS of ordinary marker nodes:
+ *
+ *   `wallsNode` / `paddlesNode` children → oriented boxes (4 segments each),
+ *                                          so a rotated paddle or flipper works
+ *   `bumpersNode` children              → circles
+ *   `drainNode`                         → trigger box: entering it loses a ball
+ *
+ * Because the geometry is re-read each frame, rotating or moving a marker node
+ * (from a script, an AnimationPlayer clip, or the inspector) just works.
+ *
+ * On contact it emits `ball-hit` (kind, nodeId, speed, x, y) on its own node,
+ * and `ball-drained` when it is lost. TouchRules turns those into score/damage.
+ * Never import rapier: it is a ~2 MB lazy wasm payload this does not need.
+ */
+import { NodeBase, Script, type PropertySchema } from '@pix3/runtime';
+
+import {
+  stepBall,
+  type BallOptions,
+  type BallState,
+  type CircleCollider,
+  type SegmentCollider,
+} from './ball-collision';
+
+/** Oriented box in world space: centre, unit axes, half extents. */
+interface Obb {
+  cx: number;
+  cy: number;
+  ux: number;
+  uy: number;
+  hw: number;
+  hh: number;
+}
+
+/** Any 2D node that carries a size (ColorRect2D, Sprite2D, Group2D, …). */
+interface Sized {
+  width?: number;
+  height?: number;
+}
+
+function readObb(node: NodeBase): Obb {
+  node.updateWorldMatrix(true, false);
+  const e = node.matrixWorld.elements;
+  const scaleX = Math.hypot(e[0], e[1]) || 1;
+  const scaleY = Math.hypot(e[4], e[5]) || 1;
+  const sized = node as unknown as Sized;
+  return {
+    cx: e[12],
+    cy: e[13],
+    ux: e[0] / scaleX,
+    uy: e[1] / scaleX,
+    hw: ((Number(sized.width) || 0) / 2) * scaleX,
+    hh: ((Number(sized.height) || 0) / 2) * scaleY,
+  };
+}
+
+function obbSegments(obb: Obb, restitution: number, id: string, out: SegmentCollider[]): void {
+  // Perpendicular of (ux, uy) is (-uy, ux) — the box's local Y axis in world space.
+  const ax = obb.ux * obb.hw;
+  const ay = obb.uy * obb.hw;
+  const bx = -obb.uy * obb.hh;
+  const by = obb.ux * obb.hh;
+  const corners = [
+    [obb.cx - ax - bx, obb.cy - ay - by],
+    [obb.cx + ax - bx, obb.cy + ay - by],
+    [obb.cx + ax + bx, obb.cy + ay + by],
+    [obb.cx - ax + bx, obb.cy - ay + by],
+  ];
+  for (let i = 0; i < 4; i++) {
+    const from = corners[i];
+    const to = corners[(i + 1) % 4];
+    out.push({ ax: from[0], ay: from[1], bx: to[0], by: to[1], restitution, id });
+  }
+}
+
+function pointInObb(obb: Obb, x: number, y: number): boolean {
+  const dx = x - obb.cx;
+  const dy = y - obb.cy;
+  const along = dx * obb.ux + dy * obb.uy;
+  const across = dx * -obb.uy + dy * obb.ux;
+  return Math.abs(along) <= obb.hw && Math.abs(across) <= obb.hh;
+}
+
+function childNodes(parent: NodeBase | null): NodeBase[] {
+  if (!parent) {
+    return [];
+  }
+  return parent.children.filter((child): child is NodeBase => child instanceof NodeBase);
+}
+
+export class BallBody extends Script {
+  private readonly state: BallState = { x: 0, y: 0, vx: 0, vy: 0 };
+  private readonly segments: SegmentCollider[] = [];
+  private readonly circles: CircleCollider[] = [];
+  private readonly kinds = new Map<string, string>();
+  private homeX = 0;
+  private homeY = 0;
+  private respawnIn = 0;
+
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      radius: 30,
+      gravity: -2400,
+      maxSpeed: 2600,
+      minSpeed: 420,
+      damping: 0.999,
+      substeps: 4,
+      launchSpeed: 1150,
+      launchAngleDeg: 72,
+      wallsNode: 'walls',
+      paddlesNode: 'paddles',
+      bumpersNode: 'bumpers',
+      drainNode: 'drain',
+      wallRestitution: 1,
+      paddleRestitution: 1.05,
+      bumperRestitution: 1.3,
+      resetDelaySec: 0.7,
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    const num = (name: string, label: string, min: number, max: number, step: number, group: string) => ({
+      name,
+      type: 'number' as const,
+      ui: { label, group, min, max, step, slider: true },
+      getValue: (s: unknown) => (s as BallBody).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        const n = Number(v);
+        (s as BallBody).config[name] = Math.min(max, Math.max(min, Number.isFinite(n) ? n : min));
+      },
+    });
+    const str = (name: string, label: string) => ({
+      name,
+      type: 'string' as const,
+      ui: { label, group: 'Colliders' },
+      getValue: (s: unknown) => (s as BallBody).config[name],
+      setValue: (s: unknown, v: unknown) => {
+        (s as BallBody).config[name] = typeof v === 'string' ? v : '';
+      },
+    });
+
+    return {
+      nodeType: 'BallBody',
+      properties: [
+        num('radius', 'Radius', 2, 400, 1, 'Body'),
+        num('gravity', 'Gravity (px/s²)', -12000, 12000, 50, 'Body'),
+        num('maxSpeed', 'Max Speed', 100, 12000, 50, 'Body'),
+        num('minSpeed', 'Min Speed', 0, 4000, 10, 'Body'),
+        num('damping', 'Damping', 0.9, 1, 0.001, 'Body'),
+        num('substeps', 'Substeps', 1, 16, 1, 'Body'),
+        num('launchSpeed', 'Launch Speed', 0, 6000, 25, 'Launch'),
+        num('launchAngleDeg', 'Launch Angle (°)', 5, 175, 1, 'Launch'),
+        num('resetDelaySec', 'Reset Delay (s)', 0, 5, 0.1, 'Launch'),
+        num('wallRestitution', 'Wall Bounce', 0, 2, 0.01, 'Bounce'),
+        num('paddleRestitution', 'Paddle Bounce', 0, 2, 0.01, 'Bounce'),
+        num('bumperRestitution', 'Bumper Bounce', 0, 3, 0.01, 'Bounce'),
+        str('wallsNode', 'Walls Node'),
+        str('paddlesNode', 'Paddles Node'),
+        str('bumpersNode', 'Bumpers Node'),
+        str('drainNode', 'Drain Node'),
+      ],
+      groups: {
+        Body: { label: 'Body', expanded: true },
+        Launch: { label: 'Launch', expanded: true },
+        Bounce: { label: 'Bounce', expanded: true },
+        Colliders: { label: 'Collider Sources', expanded: false },
+      },
+    };
+  }
+
+  onStart(): void {
+    const node = this.node;
+    if (!node) {
+      return;
+    }
+    node.updateWorldMatrix(true, false);
+    this.homeX = node.matrixWorld.elements[12];
+    this.homeY = node.matrixWorld.elements[13];
+    this.launch();
+  }
+
+  onUpdate(dt: number): void {
+    const node = this.node;
+    if (!node || dt <= 0) {
+      return;
+    }
+    if (this.respawnIn > 0) {
+      this.respawnIn -= dt;
+      if (this.respawnIn <= 0) {
+        this.launch();
+      }
+      return;
+    }
+
+    this.rebuildColliders();
+    const options: BallOptions = {
+      radius: Math.max(1, Number(this.config.radius) || 1),
+      gravity: Number(this.config.gravity) || 0,
+      maxSpeed: Number(this.config.maxSpeed) || 0,
+      minSpeed: Number(this.config.minSpeed) || 0,
+      damping: Number(this.config.damping) || 1,
+      substeps: Number(this.config.substeps) || 1,
+    };
+
+    for (const hit of stepBall(this.state, options, this.segments, this.circles, dt)) {
+      node.emit('ball-hit', this.kinds.get(hit.id) ?? 'wall', hit.id, hit.speed, hit.x, hit.y);
+    }
+    this.writeBackPosition();
+    this.checkDrain();
+  }
+
+  /** Send the ball on its way (also used after a drain). Override the angle for a plunger. */
+  launch(): void {
+    const speed = Math.max(0, Number(this.config.launchSpeed) || 0);
+    const angle = ((Number(this.config.launchAngleDeg) || 90) * Math.PI) / 180;
+    const dir = Math.random() < 0.5 ? -1 : 1;
+    this.state.x = this.homeX;
+    this.state.y = this.homeY;
+    this.state.vx = Math.cos(angle) * speed * dir;
+    this.state.vy = Math.sin(angle) * speed;
+    this.writeBackPosition();
+    this.node?.emit('ball-launched');
+  }
+
+  private rebuildColliders(): void {
+    this.segments.length = 0;
+    this.circles.length = 0;
+    this.kinds.clear();
+
+    const wallBounce = Number(this.config.wallRestitution) || 1;
+    for (const child of childNodes(this.findNode(String(this.config.wallsNode ?? '')))) {
+      obbSegments(readObb(child), wallBounce, child.nodeId, this.segments);
+      this.kinds.set(child.nodeId, 'wall');
+    }
+
+    const paddleBounce = Number(this.config.paddleRestitution) || 1;
+    for (const child of childNodes(this.findNode(String(this.config.paddlesNode ?? '')))) {
+      obbSegments(readObb(child), paddleBounce, child.nodeId, this.segments);
+      this.kinds.set(child.nodeId, 'paddle');
+    }
+
+    const bumperBounce = Number(this.config.bumperRestitution) || 1;
+    for (const child of childNodes(this.findNode(String(this.config.bumpersNode ?? '')))) {
+      const obb = readObb(child);
+      this.circles.push({ cx: obb.cx, cy: obb.cy, r: Math.max(1, obb.hw), restitution: bumperBounce, id: child.nodeId });
+      this.kinds.set(child.nodeId, 'bumper');
+    }
+  }
+
+  private checkDrain(): void {
+    const drain = this.findNode(String(this.config.drainNode ?? ''));
+    if (!drain) {
+      return;
+    }
+    const obb = readObb(drain);
+    const below = this.state.y < obb.cy - obb.hh;
+    if (!below && !pointInObb(obb, this.state.x, this.state.y)) {
+      return;
+    }
+    const node = this.node;
+    node?.emit('ball-hit', 'drain', drain.nodeId, Math.hypot(this.state.vx, this.state.vy), this.state.x, this.state.y);
+    node?.emit('ball-drained');
+    this.state.vx = 0;
+    this.state.vy = 0;
+    this.respawnIn = Math.max(0.05, Number(this.config.resetDelaySec) || 0.05);
+  }
+
+  /** World simulation → the ball node's parent-local position. */
+  private writeBackPosition(): void {
+    const node = this.node;
+    const parent = node?.parentNode ?? null;
+    if (!node) {
+      return;
+    }
+    if (!parent) {
+      node.position.set(this.state.x, this.state.y, node.position.z);
+      return;
+    }
+    parent.updateWorldMatrix(true, false);
+    const e = parent.matrixWorld.elements;
+    const dx = this.state.x - e[12];
+    const dy = this.state.y - e[13];
+    const det = e[0] * e[5] - e[1] * e[4];
+    if (Math.abs(det) < 1e-8) {
+      node.position.set(dx, dy, node.position.z);
+      return;
+    }
+    node.position.set((e[5] * dx - e[4] * dy) / det, (e[0] * dy - e[1] * dx) / det, node.position.z);
+  }
+}