@pix3/cli 1.6.4 → 2.0.0-alpha.0

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

@@ -1,263 +0,0 @@
-/**
- * TouchRules — turns ball contacts into meaning, and into feel.
- *
- * Same role (and the same `rules` format) as in the other recipes; only the
- * source of the contact differs. Here it listens to `BallBody`'s `ball-hit`
- * signal instead of running its own overlap test, because the swept solver
- * already knows exactly what was hit and how hard.
- *
- * `ball-hit` payload: (kind, nodeId, speed, x, y) where kind is `wall`,
- * `paddle`, `bumper` or `drain`. `x`/`y` are WORLD coordinates, which is why the
- * particles and the score popup can be spawned straight at the contact point.
- *
- * It emits the same semantic signals every recipe uses, on `game-root`:
- *   `touch-scored`  (amount, x, y)
- *   `touch-damaged` (amount, x, y)
- *
- * `rules` format: `kind:outcome:amount`, entries separated by `;`.
- *
- * The feel is all engine one-liners — copy them next to whatever mechanic you
- * add, they cost nothing to call:
- *   `scene.audio.sfx('score')`        procedural SFX, no asset needed
- *   `scene.juice.burst({x, y})`       2D particles that free themselves
- *   `scene.juice.floatText('+100')`   score popup
- *   `scene.juice.punchScale(node)` / `flash` / `shake` / `scene.time.hitstop`
- * Spawn them at BOARD-space anchors (a node or the hit point) rather than on the
- * HUD: the HUD is a CanvasLayer2D drawn after post-processing, so effects
- * parented there never bloom.
- */
-import { Script, type PropertySchema } from '@pix3/runtime';
-
-type TouchOutcome = 'score' | 'damage';
-
-interface TouchRule {
-  kind: string;
-  outcome: TouchOutcome;
-  amount: number;
-}
-
-function parseRules(text: string): Map<string, TouchRule> {
-  const rules = new Map<string, TouchRule>();
-  for (const entry of text.split(';')) {
-    const parts = entry.trim().split(':');
-    if (parts.length < 2 || !parts[0].trim()) {
-      continue;
-    }
-    const amount = Number(parts[2] ?? 1);
-    rules.set(parts[0].trim(), {
-      kind: parts[0].trim(),
-      outcome: parts[1].trim() === 'damage' ? 'damage' : 'score',
-      amount: Number.isFinite(amount) && amount > 0 ? amount : 1,
-    });
-  }
-  return rules;
-}
-
-export class TouchRules extends Script {
-  constructor(id: string, type: string) {
-    super(id, type);
-    this.config = {
-      // Node carrying BallBody.
-      ballNode: 'ball',
-      // kind:outcome:amount pairs, separated by ';'.
-      rules: 'bumper:score:100;paddle:score:10;drain:damage:1',
-      // Ignore contacts softer than this (px/s) so a resting ball scores nothing.
-      minImpactSpeed: 60,
-      // Feel. Raise for arcade, drop to 0 to switch a piece of it off.
-      punchAmount: 0.34,
-      hitstopMs: 50,
-      burstCount: 18,
-      popupFormat: '+{value}',
-      feedbackColor: '#ffe066',
-      sfxEnabled: true,
-      // Optional asset overrides. When set they REPLACE the synth preset.
-      scoreSound: '',
-      damageSound: '',
-    };
-  }
-
-  static getPropertySchema(): PropertySchema {
-    const str = (name: string, label: string, group: string, editor?: 'audio-resource') => ({
-      name,
-      type: 'string' as const,
-      ui: { label, group, editor },
-      getValue: (s: unknown) => (s as TouchRules).config[name],
-      setValue: (s: unknown, v: unknown) => {
-        (s as TouchRules).config[name] = typeof v === 'string' ? v : '';
-      },
-    });
-    const num = (name: string, label: string, min: number, max: number, step: number) => ({
-      name,
-      type: 'number' as const,
-      ui: { label, group: 'Feel', min, max, step, slider: true },
-      getValue: (s: unknown) => (s as TouchRules).config[name],
-      setValue: (s: unknown, v: unknown) => {
-        const n = Number(v);
-        (s as TouchRules).config[name] = Math.min(max, Math.max(min, Number.isFinite(n) ? n : min));
-      },
-    });
-
-    return {
-      nodeType: 'TouchRules',
-      properties: [
-        str('ballNode', 'Ball Node', 'Contact'),
-        str('rules', 'Rules', 'Contact'),
-        {
-          name: 'minImpactSpeed',
-          type: 'number',
-          ui: { label: 'Min Impact Speed', group: 'Contact', min: 0, max: 2000, step: 10, slider: true },
-          getValue: s => (s as TouchRules).config.minImpactSpeed,
-          setValue: (s, v) => {
-            const n = Number(v);
-            (s as TouchRules).config.minImpactSpeed = Math.min(2000, Math.max(0, Number.isFinite(n) ? n : 0));
-          },
-        },
-        num('punchAmount', 'Punch Scale', 0, 1, 0.01),
-        num('hitstopMs', 'Hitstop (ms)', 0, 200, 5),
-        num('burstCount', 'Burst Particles', 0, 120, 1),
-        str('popupFormat', 'Score Popup', 'Feel'),
-        str('feedbackColor', 'Feedback Colour', 'Feel'),
-        {
-          name: 'sfxEnabled',
-          type: 'boolean',
-          ui: { label: 'Sound', group: 'Feedback' },
-          getValue: s => (s as TouchRules).config.sfxEnabled,
-          setValue: (s, v) => {
-            (s as TouchRules).config.sfxEnabled = Boolean(v);
-          },
-        },
-        str('scoreSound', 'Score Sound', 'Feedback', 'audio-resource'),
-        str('damageSound', 'Damage Sound', 'Feedback', 'audio-resource'),
-      ],
-      groups: {
-        Contact: { label: 'Contact', expanded: true },
-        Feel: { label: 'Feel', expanded: true },
-        Feedback: { label: 'Sound', expanded: false },
-      },
-    };
-  }
-
-  onStart(): void {
-    const ball = this.findNode(String(this.config.ballNode ?? ''));
-    if (!ball) {
-      console.warn(`[TouchRules] Ball node "${this.config.ballNode}" not found.`);
-      return;
-    }
-    ball.connect('ball-hit', this, (...args: unknown[]) =>
-      this.resolve(String(args[0] ?? ''), String(args[1] ?? ''), Number(args[2]) || 0, Number(args[3]) || 0, Number(args[4]) || 0)
-    );
-  }
-
-  private resolve(kind: string, nodeId: string, speed: number, x: number, y: number): void {
-    const scene = this.scene;
-    const owner = this.node;
-    if (!scene || !owner) {
-      return;
-    }
-    // A resting ball rattling on the paddle must not score — or click.
-    if (kind !== 'drain' && speed < Math.max(0, Number(this.config.minImpactSpeed) || 0)) {
-      return;
-    }
-
-    const rule = parseRules(String(this.config.rules ?? '')).get(kind);
-    // Every contact is audible, including the walls the rules say nothing about.
-    this.playContactSound(kind, rule?.outcome ?? null, speed);
-    if (!rule) {
-      return;
-    }
-
-    if (rule.outcome === 'damage') {
-      owner.emit('touch-damaged', rule.amount, x, y);
-      scene.juice.flash({ color: '#ff2d6f', intensity: 0.45, durationSec: 0.24 });
-      // The board is safe to shake here: BallBody freezes the ball for
-      // `resetDelaySec` after a drain, so no collider moves under a live ball.
-      scene.juice.shake('board', { amplitude: 26, frequency: 22, duration: 0.3 });
-      this.burst(x, y, { colors: ['#ff2d6f', '#ffffff'], scale: 1, speed: 320 });
-      return;
-    }
-
-    owner.emit('touch-scored', rule.amount, x, y);
-    const target = nodeId ? this.findNode(nodeId) : null;
-    if (target) {
-      const amount = Math.max(0, Number(this.config.punchAmount) || 0);
-      if (amount > 0) {
-        scene.juice.punchScale(target, { amount, duration: 0.24 });
-      }
-    }
-    // Hitstop is the bumper's weight — the paddle is touched constantly and
-    // would stutter the whole run.
-    if (kind === 'bumper') {
-      scene.time.hitstop(Math.max(0, Number(this.config.hitstopMs) || 0));
-    }
-    const accent = this.accentColor();
-    this.burst(x, y, {
-      colors: ['#ffffff', accent],
-      scale: kind === 'bumper' ? 1 : 0.5,
-      speed: kind === 'bumper' ? 420 : 260,
-    });
-    this.popup(rule.amount, x, y, accent);
-  }
-
-  private accentColor(): string {
-    const color = String(this.config.feedbackColor ?? '').trim();
-    return color.length > 0 ? color : '#ffe066';
-  }
-
-  /** Contact particles at the hit point (world space, so they bloom with the board). */
-  private burst(
-    x: number,
-    y: number,
-    options: { colors: string[]; scale: number; speed: number }
-  ): void {
-    const count = Math.round(Math.max(0, Number(this.config.burstCount) || 0) * options.scale);
-    if (count <= 0) {
-      return;
-    }
-    this.scene?.juice.burst(
-      { x, y },
-      { count, colors: options.colors, speed: options.speed, sizePx: 12, lifeSec: 0.45 }
-    );
-  }
-
-  /** "+100" rising off the contact. Empty `popupFormat` switches it off. */
-  private popup(amount: number, x: number, y: number, color: string): void {
-    const format = String(this.config.popupFormat ?? '');
-    if (!format) {
-      return;
-    }
-    this.scene?.juice.floatText(format.replace('{value}', String(Math.round(amount))), {
-      at: { x, y },
-      color,
-      fontSizePx: 42,
-      glow: true,
-      glowStrength: 2,
-    });
-  }
-
-  /**
-   * An asset wins when one is authored; otherwise the procedural preset plays,
-   * so a fresh project has sound with no audio files at all. Bounces are
-   * pitched by impact speed — the cheapest "harder hit = brighter sound" there is.
-   */
-  private playContactSound(kind: string, outcome: TouchOutcome | null, speed: number): void {
-    if (this.config.sfxEnabled === false) {
-      return;
-    }
-    const damage = outcome === 'damage';
-    const asset = String((damage ? this.config.damageSound : this.config.scoreSound) ?? '');
-    if (asset && (damage || outcome === 'score')) {
-      void this.scene?.audio.play(asset, { bus: 'sfx', pitchVariation: 0.08 });
-      return;
-    }
-    if (damage) {
-      this.scene?.audio.sfx('lose', { volume: 0.9 });
-      return;
-    }
-    if (kind === 'bumper') {
-      this.scene?.audio.sfx('score', { pitch: 1 + Math.random() * 0.12 });
-      return;
-    }
-    const pitch = Math.min(1.5, Math.max(0.8, 0.85 + speed / 3200));
-    this.scene?.audio.sfx('bounce', { pitch, volume: 0.8 });
-  }
-}

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

@@ -1,307 +0,0 @@
-/**
- * ball-collision — swept (continuous) circle physics. Pure math, no engine
- * imports, so it is unit-testable and cheap to reason about.
- *
- * Why this exists: the engine has NO rigidbody solver, and `core:Hitbox2D` is an
- * axis-aligned overlap test (rotation ignored). A ball that moves 900 px in a
- * frame would tunnel straight through a wall under any discrete overlap test,
- * and a rotated paddle/flipper cannot be described by an AABB at all. So the
- * recipe carries its own: every collider is a SEGMENT (four per oriented box) or
- * a CIRCLE, and each substep sweeps the ball's whole displacement against them,
- * takes the earliest time of impact, reflects, and continues with what is left
- * of the step. No amount of speed can skip a collider.
- */
-
-export interface SegmentCollider {
-  ax: number;
-  ay: number;
-  bx: number;
-  by: number;
-  /** 1 = perfect bounce, <1 absorbs, >1 kicks (bumpers). */
-  restitution: number;
-  /** Caller-defined tag, handed back on every hit. */
-  id: string;
-}
-
-export interface CircleCollider {
-  cx: number;
-  cy: number;
-  r: number;
-  restitution: number;
-  id: string;
-}
-
-export interface BallState {
-  x: number;
-  y: number;
-  vx: number;
-  vy: number;
-}
-
-export interface BallOptions {
-  radius: number;
-  /** Vertical acceleration in px/s² (negative pulls down — Y is up). */
-  gravity: number;
-  maxSpeed: number;
-  /** Re-energise the ball if it drops below this (0 = off). */
-  minSpeed: number;
-  /** Fraction of speed kept per second (1 = frictionless). */
-  damping: number;
-  /** Collision substeps per frame. More = more stable, never needed for tunneling. */
-  substeps: number;
-}
-
-export interface BallHit {
-  id: string;
-  x: number;
-  y: number;
-  /** Impact speed along the contact normal (always positive). */
-  speed: number;
-}
-
-interface SweepHit {
-  t: number;
-  nx: number;
-  ny: number;
-}
-
-const EPS = 1e-9;
-/** Pushed out this far along the normal after a hit so it cannot re-hit at t=0. */
-const SKIN = 0.01;
-const MAX_ITERATIONS = 6;
-
-function closestPointOnSegment(
-  px: number,
-  py: number,
-  ax: number,
-  ay: number,
-  bx: number,
-  by: number
-): { x: number; y: number } {
-  const ex = bx - ax;
-  const ey = by - ay;
-  const len2 = ex * ex + ey * ey;
-  if (len2 < EPS) {
-    return { x: ax, y: ay };
-  }
-  const s = Math.min(1, Math.max(0, ((px - ax) * ex + (py - ay) * ey) / len2));
-  return { x: ax + ex * s, y: ay + ey * s };
-}
-
-/** Sweep a moving circle against a static point (the endpoint caps of a segment). */
-function sweepCirclePoint(
-  px: number,
-  py: number,
-  vx: number,
-  vy: number,
-  r: number,
-  cx: number,
-  cy: number
-): SweepHit | null {
-  const mx = px - cx;
-  const my = py - cy;
-  const a = vx * vx + vy * vy;
-  if (a < EPS) {
-    return null;
-  }
-  const b = 2 * (mx * vx + my * vy);
-  const c = mx * mx + my * my - r * r;
-  const disc = b * b - 4 * a * c;
-  if (disc < 0) {
-    return null;
-  }
-  const root = Math.sqrt(disc);
-  const t = (-b - root) / (2 * a);
-  if (t < 0 || t > 1) {
-    return null;
-  }
-  const hx = px + vx * t - cx;
-  const hy = py + vy * t - cy;
-  const len = Math.hypot(hx, hy) || 1;
-  return { t, nx: hx / len, ny: hy / len };
-}
-
-/** Sweep a moving circle against a static segment. Returns the approaching hit only. */
-export function sweepCircleSegment(
-  px: number,
-  py: number,
-  vx: number,
-  vy: number,
-  r: number,
-  ax: number,
-  ay: number,
-  bx: number,
-  by: number
-): SweepHit | null {
-  const ex = bx - ax;
-  const ey = by - ay;
-  const len2 = ex * ex + ey * ey;
-  if (len2 < EPS) {
-    return approaching(sweepCirclePoint(px, py, vx, vy, r, ax, ay), vx, vy);
-  }
-  const len = Math.sqrt(len2);
-  const nx = -ey / len;
-  const ny = ex / len;
-  const d0 = (px - ax) * nx + (py - ay) * ny;
-  const dv = vx * nx + vy * ny;
-  const side = d0 >= 0 ? 1 : -1;
-
-  // Face hit: the moment the centre reaches distance r from the infinite line,
-  // provided the contact point lies within the segment span.
-  if (dv * side < -EPS) {
-    const t = (side * r - d0) / dv;
-    if (t >= 0 && t <= 1) {
-      const hx = px + vx * t;
-      const hy = py + vy * t;
-      const s = ((hx - ax) * ex + (hy - ay) * ey) / len2;
-      if (s >= 0 && s <= 1) {
-        return approaching({ t, nx: nx * side, ny: ny * side }, vx, vy);
-      }
-    }
-  }
-
-  // Otherwise the only possible contacts are the rounded endpoints.
-  const ha = sweepCirclePoint(px, py, vx, vy, r, ax, ay);
-  const hb = sweepCirclePoint(px, py, vx, vy, r, bx, by);
-  const best = ha && hb ? (ha.t <= hb.t ? ha : hb) : (ha ?? hb);
-  return approaching(best, vx, vy);
-}
-
-/** Sweep a moving circle against a static circle. */
-export function sweepCircleCircle(
-  px: number,
-  py: number,
-  vx: number,
-  vy: number,
-  r: number,
-  cx: number,
-  cy: number,
-  cr: number
-): SweepHit | null {
-  return approaching(sweepCirclePoint(px, py, vx, vy, r + cr, cx, cy), vx, vy);
-}
-
-/** Drop hits whose normal points along the motion (already separating). */
-function approaching(hit: SweepHit | null, vx: number, vy: number): SweepHit | null {
-  if (!hit) {
-    return null;
-  }
-  return vx * hit.nx + vy * hit.ny < -EPS ? hit : null;
-}
-
-/** Push the ball out of anything it already overlaps (authored overlaps, rounding). */
-function depenetrate(
-  ball: BallState,
-  radius: number,
-  segments: readonly SegmentCollider[],
-  circles: readonly CircleCollider[]
-): void {
-  for (const seg of segments) {
-    const p = closestPointOnSegment(ball.x, ball.y, seg.ax, seg.ay, seg.bx, seg.by);
-    const dx = ball.x - p.x;
-    const dy = ball.y - p.y;
-    const dist = Math.hypot(dx, dy);
-    if (dist < radius && dist > EPS) {
-      ball.x = p.x + (dx / dist) * (radius + SKIN);
-      ball.y = p.y + (dy / dist) * (radius + SKIN);
-    }
-  }
-  for (const circle of circles) {
-    const dx = ball.x - circle.cx;
-    const dy = ball.y - circle.cy;
-    const dist = Math.hypot(dx, dy);
-    const min = radius + circle.r;
-    if (dist < min && dist > EPS) {
-      ball.x = circle.cx + (dx / dist) * (min + SKIN);
-      ball.y = circle.cy + (dy / dist) * (min + SKIN);
-    }
-  }
-}
-
-/**
- * Advance the ball by `dt` seconds, resolving every collider continuously.
- * Mutates `ball`; returns one entry per contact resolved this frame.
- */
-export function stepBall(
-  ball: BallState,
-  options: BallOptions,
-  segments: readonly SegmentCollider[],
-  circles: readonly CircleCollider[],
-  dt: number
-): BallHit[] {
-  const hits: BallHit[] = [];
-  if (dt <= 0) {
-    return hits;
-  }
-  const substeps = Math.max(1, Math.min(16, Math.round(options.substeps) || 1));
-  const radius = Math.max(0.001, options.radius);
-  const subDt = dt / substeps;
-
-  for (let step = 0; step < substeps; step++) {
-    ball.vy += options.gravity * subDt;
-    if (options.damping < 1) {
-      const keep = Math.pow(Math.max(0, options.damping), subDt);
-      ball.vx *= keep;
-      ball.vy *= keep;
-    }
-    clampSpeed(ball, options);
-    depenetrate(ball, radius, segments, circles);
-
-    let remaining = subDt;
-    for (let iteration = 0; iteration < MAX_ITERATIONS && remaining > EPS; iteration++) {
-      const dx = ball.vx * remaining;
-      const dy = ball.vy * remaining;
-
-      let best: SweepHit | null = null;
-      let bestId = '';
-      let bestRestitution = 1;
-      for (const seg of segments) {
-        const hit = sweepCircleSegment(ball.x, ball.y, dx, dy, radius, seg.ax, seg.ay, seg.bx, seg.by);
-        if (hit && (!best || hit.t < best.t)) {
-          best = hit;
-          bestId = seg.id;
-          bestRestitution = seg.restitution;
-        }
-      }
-      for (const circle of circles) {
-        const hit = sweepCircleCircle(ball.x, ball.y, dx, dy, radius, circle.cx, circle.cy, circle.r);
-        if (hit && (!best || hit.t < best.t)) {
-          best = hit;
-          bestId = circle.id;
-          bestRestitution = circle.restitution;
-        }
-      }
-
-      if (!best) {
-        ball.x += dx;
-        ball.y += dy;
-        remaining = 0;
-        break;
-      }
-
-      ball.x += dx * best.t + best.nx * SKIN;
-      ball.y += dy * best.t + best.ny * SKIN;
-
-      const vn = ball.vx * best.nx + ball.vy * best.ny;
-      const impact = Math.abs(vn);
-      ball.vx -= (1 + bestRestitution) * vn * best.nx;
-      ball.vy -= (1 + bestRestitution) * vn * best.ny;
-      clampSpeed(ball, options);
-
-      hits.push({ id: bestId, x: ball.x, y: ball.y, speed: impact });
-      remaining *= 1 - best.t;
-    }
-  }
-  return hits;
-}
-
-function clampSpeed(ball: BallState, options: BallOptions): void {
-  const speed = Math.hypot(ball.vx, ball.vy);
-  if (options.maxSpeed > 0 && speed > options.maxSpeed) {
-    ball.vx = (ball.vx / speed) * options.maxSpeed;
-    ball.vy = (ball.vy / speed) * options.maxSpeed;
-  } else if (options.minSpeed > 0 && speed > EPS && speed < options.minSpeed) {
-    ball.vx = (ball.vx / speed) * options.minSpeed;
-    ball.vy = (ball.vy / speed) * options.minSpeed;
-  }
-}

package/templates/recipe-bouncer-2d/template.yaml

@@ -1,10 +0,0 @@
-id: recipe-bouncer-2d
-title: Bouncer 2D
-description: A ball under gravity bounces off walls, bumpers and a paddle you steer; hits score, a bottom drain costs a life. Continuous (swept) collision, so nothing tunnels at speed — arkanoid, pong, plinko, pinball.
-projectType: 2d
-targetPlatform: universal
-viewport: { width: 1080, height: 1920 }
-# The build/full-run entry scene (Project Settings → Default Export Scene Path).
-# The menu boots first; PLAY transitions to main.pix3scene (the game).
-entryScene: scenes/menu.pix3scene
-order: 61

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

@@ -1,22 +0,0 @@
-# Grid 3D
-
-A playable skeleton for tap-to-carve 3D puzzles: 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 to win.
-
-It plays as shipped — press play in `scenes/main.pix3scene` before changing
-anything, so you know what "working" looked like.
-
-- `scenes/menu.pix3scene` — entry scene; PLAY transitions to the board.
-- `scenes/main.pix3scene` — the board: camera, lights, `board-anchor`, HUD.
-- `scenes/ui/result.pix3scene` — the end screen (RETRY / MENU), instanced into
-  main hidden (`visible: false` is editor-only; `GridRules` shows it at run time).
-- `scripts/GridBoard.ts` — builds the cubes and turns a tap into a removal.
-- `scripts/GridRules.ts` — score, lives, win/lose, the debug provider.
-- `scripts/ScoreHud.ts`, `scripts/MenuFlow.ts` — display and menu, shared with
-  the other recipes.
-
-The cubes are generated, not authored: board size lives in `GridBoard`'s config
-(`sizeX/sizeY/sizeZ`), so a bigger block is one number, not a scene edit.
-
-Read `design/recipe.md` for the node map, the tunables and what not to touch.