@pix3/cli 1.6.0 → 1.6.2

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

@@ -1,174 +1,174 @@
-/**
- * TouchRules — turns contact into meaning.
- *
- * Every frame it overlap-tests a circle around the player against the
- * `core:Hitbox2D` groups listed in `rules`, and for each hit emits a SEMANTIC
- * signal on its own node (`game-root`):
- *
- *   `touch-scored`  (amount, x, y)
- *   `touch-damaged` (amount, x, y)
- *
- * It never touches the score, the lives or the HUD — `GameRules` owns those and
- * listens for these two signals. Add an outcome by adding a rule here and a
- * listener there; nothing else has to change.
- *
- * `rules` format: `group:outcome:amount`, entries separated by `;`.
- * Outcomes: `score` | `damage`. Example: `pickup:score:1;hazard:damage:1`.
- */
-import { Script, type PropertySchema } from '@pix3/runtime';
-
-type TouchOutcome = 'score' | 'damage';
-
-interface TouchRule {
-  group: string;
-  outcome: TouchOutcome;
-  amount: number;
-}
-
-function parseRules(text: string): TouchRule[] {
-  const rules: TouchRule[] = [];
-  for (const entry of text.split(';')) {
-    const parts = entry.trim().split(':');
-    if (parts.length < 2 || !parts[0].trim()) {
-      continue;
-    }
-    const outcome: TouchOutcome = parts[1].trim() === 'damage' ? 'damage' : 'score';
-    const amount = Number(parts[2] ?? 1);
-    rules.push({
-      group: parts[0].trim(),
-      outcome,
-      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 id/name whose world position is the centre of the overlap test.
-      playerNode: 'player',
-      // Radius of the overlap test, in logical pixels.
-      touchRadius: 62,
-      // group:outcome:amount pairs, separated by ';'.
-      rules: 'pickup:score:1;hazard:damage:1',
-      // Free the touched node after resolving it.
-      consume: true,
-      // res:// audio paths; empty = silent.
-      scoreSound: '',
-      damageSound: '',
-    };
-  }
-
-  static getPropertySchema(): PropertySchema {
-    return {
-      nodeType: 'TouchRules',
-      properties: [
-        {
-          name: 'playerNode',
-          type: 'string',
-          ui: { label: 'Player Node', group: 'Contact' },
-          getValue: s => (s as TouchRules).config.playerNode,
-          setValue: (s, v) => {
-            (s as TouchRules).config.playerNode = typeof v === 'string' ? v : '';
-          },
-        },
-        {
-          name: 'touchRadius',
-          type: 'number',
-          ui: { label: 'Touch Radius', group: 'Contact', min: 4, max: 600, step: 1, slider: true },
-          getValue: s => (s as TouchRules).config.touchRadius,
-          setValue: (s, v) => {
-            const n = Number(v);
-            (s as TouchRules).config.touchRadius = Math.min(600, Math.max(4, Number.isFinite(n) ? n : 4));
-          },
-        },
-        {
-          name: 'rules',
-          type: 'string',
-          ui: {
-            label: 'Rules',
-            description: "group:outcome:amount, ';'-separated. Outcome is score or damage.",
-            group: 'Contact',
-          },
-          getValue: s => (s as TouchRules).config.rules,
-          setValue: (s, v) => {
-            (s as TouchRules).config.rules = typeof v === 'string' ? v : '';
-          },
-        },
-        {
-          name: 'consume',
-          type: 'boolean',
-          ui: { label: 'Consume On Touch', group: 'Contact' },
-          getValue: s => (s as TouchRules).config.consume,
-          setValue: (s, v) => {
-            (s as TouchRules).config.consume = Boolean(v);
-          },
-        },
-        {
-          name: 'scoreSound',
-          type: 'string',
-          ui: { label: 'Score Sound', group: 'Feedback', editor: 'audio-resource' },
-          getValue: s => (s as TouchRules).config.scoreSound,
-          setValue: (s, v) => {
-            (s as TouchRules).config.scoreSound = typeof v === 'string' ? v : '';
-          },
-        },
-        {
-          name: 'damageSound',
-          type: 'string',
-          ui: { label: 'Damage Sound', group: 'Feedback', editor: 'audio-resource' },
-          getValue: s => (s as TouchRules).config.damageSound,
-          setValue: (s, v) => {
-            (s as TouchRules).config.damageSound = typeof v === 'string' ? v : '';
-          },
-        },
-      ],
-      groups: {
-        Contact: { label: 'Contact', expanded: true },
-        Feedback: { label: 'Feedback', expanded: false },
-      },
-    };
-  }
-
-  onUpdate(): void {
-    const scene = this.scene;
-    const owner = this.node;
-    const player = this.findNode(String(this.config.playerNode ?? ''));
-    if (!scene || !owner || !player) {
-      return;
-    }
-
-    player.updateWorldMatrix(true, false);
-    const px = player.matrixWorld.elements[12];
-    const py = player.matrixWorld.elements[13];
-    const radius = Math.max(1, Number(this.config.touchRadius) || 1);
-    const consume = Boolean(this.config.consume);
-
-    for (const rule of parseRules(String(this.config.rules ?? ''))) {
-      for (const hit of scene.collision2d.overlapCircle(px, py, radius, rule.group)) {
-        if (rule.outcome === 'damage') {
-          owner.emit('touch-damaged', rule.amount, hit.x, hit.y);
-          scene.juice.shake(player, { amplitude: 16, duration: 0.25 });
-          scene.juice.flash({ color: '#ff4d6d', intensity: 0.4, durationSec: 0.22 });
-          this.playSound(String(this.config.damageSound ?? ''));
-        } else {
-          owner.emit('touch-scored', rule.amount, hit.x, hit.y);
-          scene.juice.punchScale(player, { amount: 0.22, duration: 0.22 });
-          this.playSound(String(this.config.scoreSound ?? ''));
-        }
-        if (consume) {
-          hit.node.queueFree();
-        }
-      }
-    }
-  }
-
-  private playSound(path: string): void {
-    if (!path) {
-      return;
-    }
-    void this.scene?.audio.play(path, { bus: 'sfx', pitchVariation: 0.08 });
-  }
-}
+/**
+ * TouchRules — turns contact into meaning.
+ *
+ * Every frame it overlap-tests a circle around the player against the
+ * `core:Hitbox2D` groups listed in `rules`, and for each hit emits a SEMANTIC
+ * signal on its own node (`game-root`):
+ *
+ *   `touch-scored`  (amount, x, y)
+ *   `touch-damaged` (amount, x, y)
+ *
+ * It never touches the score, the lives or the HUD — `GameRules` owns those and
+ * listens for these two signals. Add an outcome by adding a rule here and a
+ * listener there; nothing else has to change.
+ *
+ * `rules` format: `group:outcome:amount`, entries separated by `;`.
+ * Outcomes: `score` | `damage`. Example: `pickup:score:1;hazard:damage:1`.
+ */
+import { Script, type PropertySchema } from '@pix3/runtime';
+
+type TouchOutcome = 'score' | 'damage';
+
+interface TouchRule {
+  group: string;
+  outcome: TouchOutcome;
+  amount: number;
+}
+
+function parseRules(text: string): TouchRule[] {
+  const rules: TouchRule[] = [];
+  for (const entry of text.split(';')) {
+    const parts = entry.trim().split(':');
+    if (parts.length < 2 || !parts[0].trim()) {
+      continue;
+    }
+    const outcome: TouchOutcome = parts[1].trim() === 'damage' ? 'damage' : 'score';
+    const amount = Number(parts[2] ?? 1);
+    rules.push({
+      group: parts[0].trim(),
+      outcome,
+      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 id/name whose world position is the centre of the overlap test.
+      playerNode: 'player',
+      // Radius of the overlap test, in logical pixels.
+      touchRadius: 62,
+      // group:outcome:amount pairs, separated by ';'.
+      rules: 'pickup:score:1;hazard:damage:1',
+      // Free the touched node after resolving it.
+      consume: true,
+      // res:// audio paths; empty = silent.
+      scoreSound: '',
+      damageSound: '',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    return {
+      nodeType: 'TouchRules',
+      properties: [
+        {
+          name: 'playerNode',
+          type: 'string',
+          ui: { label: 'Player Node', group: 'Contact' },
+          getValue: s => (s as TouchRules).config.playerNode,
+          setValue: (s, v) => {
+            (s as TouchRules).config.playerNode = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'touchRadius',
+          type: 'number',
+          ui: { label: 'Touch Radius', group: 'Contact', min: 4, max: 600, step: 1, slider: true },
+          getValue: s => (s as TouchRules).config.touchRadius,
+          setValue: (s, v) => {
+            const n = Number(v);
+            (s as TouchRules).config.touchRadius = Math.min(600, Math.max(4, Number.isFinite(n) ? n : 4));
+          },
+        },
+        {
+          name: 'rules',
+          type: 'string',
+          ui: {
+            label: 'Rules',
+            description: "group:outcome:amount, ';'-separated. Outcome is score or damage.",
+            group: 'Contact',
+          },
+          getValue: s => (s as TouchRules).config.rules,
+          setValue: (s, v) => {
+            (s as TouchRules).config.rules = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'consume',
+          type: 'boolean',
+          ui: { label: 'Consume On Touch', group: 'Contact' },
+          getValue: s => (s as TouchRules).config.consume,
+          setValue: (s, v) => {
+            (s as TouchRules).config.consume = Boolean(v);
+          },
+        },
+        {
+          name: 'scoreSound',
+          type: 'string',
+          ui: { label: 'Score Sound', group: 'Feedback', editor: 'audio-resource' },
+          getValue: s => (s as TouchRules).config.scoreSound,
+          setValue: (s, v) => {
+            (s as TouchRules).config.scoreSound = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'damageSound',
+          type: 'string',
+          ui: { label: 'Damage Sound', group: 'Feedback', editor: 'audio-resource' },
+          getValue: s => (s as TouchRules).config.damageSound,
+          setValue: (s, v) => {
+            (s as TouchRules).config.damageSound = typeof v === 'string' ? v : '';
+          },
+        },
+      ],
+      groups: {
+        Contact: { label: 'Contact', expanded: true },
+        Feedback: { label: 'Feedback', expanded: false },
+      },
+    };
+  }
+
+  onUpdate(): void {
+    const scene = this.scene;
+    const owner = this.node;
+    const player = this.findNode(String(this.config.playerNode ?? ''));
+    if (!scene || !owner || !player) {
+      return;
+    }
+
+    player.updateWorldMatrix(true, false);
+    const px = player.matrixWorld.elements[12];
+    const py = player.matrixWorld.elements[13];
+    const radius = Math.max(1, Number(this.config.touchRadius) || 1);
+    const consume = Boolean(this.config.consume);
+
+    for (const rule of parseRules(String(this.config.rules ?? ''))) {
+      for (const hit of scene.collision2d.overlapCircle(px, py, radius, rule.group)) {
+        if (rule.outcome === 'damage') {
+          owner.emit('touch-damaged', rule.amount, hit.x, hit.y);
+          scene.juice.shake(player, { amplitude: 16, duration: 0.25 });
+          scene.juice.flash({ color: '#ff4d6d', intensity: 0.4, durationSec: 0.22 });
+          this.playSound(String(this.config.damageSound ?? ''));
+        } else {
+          owner.emit('touch-scored', rule.amount, hit.x, hit.y);
+          scene.juice.punchScale(player, { amount: 0.22, duration: 0.22 });
+          this.playSound(String(this.config.scoreSound ?? ''));
+        }
+        if (consume) {
+          hit.node.queueFree();
+        }
+      }
+    }
+  }
+
+  private playSound(path: string): void {
+    if (!path) {
+      return;
+    }
+    void this.scene?.audio.play(path, { bus: 'sfx', pitchVariation: 0.08 });
+  }
+}

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

@@ -1,10 +1,10 @@
-id: recipe-arena-2d
-title: Arena 2D
-description: An avatar you steer inside a bounded field while spawners drip pickups and hazards; touch turns into score or damage, with lives, a timer and a win/lose flow. Dodgers, collectors, top-down survival, and (by swapping the movement script) runners. Its steering is continuous, so a grid or turn-based game (snake, sokoban) starts from Blank 2D instead.
-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: 60
+id: recipe-arena-2d
+title: Arena 2D
+description: An avatar you steer inside a bounded field while spawners drip pickups and hazards; touch turns into score or damage, with lives, a timer and a win/lose flow. Dodgers, collectors, top-down survival, and (by swapping the movement script) runners. Its steering is continuous, so a grid or turn-based game (snake, sokoban) starts from Blank 2D instead.
+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: 60

package/templates/recipe-blank-2d/files/README.md

@@ -1,61 +1,61 @@
-# Blank 2D
-
-Everything a run needs **except the mechanic**: a bounded field, a HUD, score /
-lives / timer bookkeeping, and a win/lose screen with RETRY. Press play in
-`scenes/main.pix3scene` and you get an empty field with `SCORE 0` — that is
-correct, and it is the point.
-
-Use this when the game's core loop is not what another recipe ships (grid or
-turn-based movement, word / card / board games, builders, idle). The first thing
-to build is the mechanic itself, controls included; building it here beats
-deleting somebody else's mechanic first. A falling, bouncing ball is the bouncer
-recipe's job — do not rebuild that here.
-
-The field is not grey: `post-fx` blooms anything bright and `bg-glow` lights the
-background, and `sprites/ph-*.png` is a shape library (disc, orb, ring, star,
-capsule) tinted with the palette at T0. Build the mechanic out of those shapes,
-not out of `ColorRect2D` squares — see `design/recipe.md` → Placeholders.
-
-**`design/recipe.md` is the contract.** It lists the stable node ids, the
-tunables (with their ranges), the extension points and what must not be renamed.
-Read it first; tools and agents grep it.
-
-## Layout
-
-```
-scenes/main.pix3scene    the game — open and build here. There is no menu on purpose.
-scenes/ui/result.pix3scene  win/lose overlay, instanced into main hidden (editor-only)
-scripts/GameRules.ts     score / lives / timer / win / lose / end flow / restart
-scripts/ScoreHud.ts      signals → HUD widgets (display only)
-sprites/ph-*.png         shape library (near-white, tinted via core:tint)
-design/recipe.md         the contract
-design/tests/            reachability ledger + one example routine (a format seed)
-```
-
-## How your mechanic plugs in
-
-Write a script, attach it to a node inside `board`, and score through
-`GameRules` — either by emitting on `game-root`:
-
-```ts
-this.findNode('game-root')?.emit('score-added', 1);
-this.findNode('game-root')?.emit('life-lost', 1);
-```
-
-…or by calling the component directly (`addScore`, `loseLife`, `finish`). The
-HUD, the end screen and RETRY then work with no further wiring.
-
-## The rule that keeps it workable
-
-One file, one responsibility. Keep each script in the 70–140 line range: small
-files can be edited surgically; monoliths get rewritten wholesale and lose the
-comments that explained them. When a mechanic outgrows its file, split it rather
-than growing it.
-
-## No menu yet
-
-A menu is a screen between you and the thing you are working on. Add one only
-once the game is fun: create `scenes/menu.pix3scene`, have its PLAY button
-`scene.changeScene('res://scenes/main.pix3scene', {transition: 'fade'})`, then
-point Project Settings → Default Export Scene Path at it. `Play Scene` keeps
-running whatever scene is open, so the menu never gets in the way again.
+# Blank 2D
+
+Everything a run needs **except the mechanic**: a bounded field, a HUD, score /
+lives / timer bookkeeping, and a win/lose screen with RETRY. Press play in
+`scenes/main.pix3scene` and you get an empty field with `SCORE 0` — that is
+correct, and it is the point.
+
+Use this when the game's core loop is not what another recipe ships (grid or
+turn-based movement, word / card / board games, builders, idle). The first thing
+to build is the mechanic itself, controls included; building it here beats
+deleting somebody else's mechanic first. A falling, bouncing ball is the bouncer
+recipe's job — do not rebuild that here.
+
+The field is not grey: `post-fx` blooms anything bright and `bg-glow` lights the
+background, and `sprites/ph-*.png` is a shape library (disc, orb, ring, star,
+capsule) tinted with the palette at T0. Build the mechanic out of those shapes,
+not out of `ColorRect2D` squares — see `design/recipe.md` → Placeholders.
+
+**`design/recipe.md` is the contract.** It lists the stable node ids, the
+tunables (with their ranges), the extension points and what must not be renamed.
+Read it first; tools and agents grep it.
+
+## Layout
+
+```
+scenes/main.pix3scene    the game — open and build here. There is no menu on purpose.
+scenes/ui/result.pix3scene  win/lose overlay, instanced into main hidden (editor-only)
+scripts/GameRules.ts     score / lives / timer / win / lose / end flow / restart
+scripts/ScoreHud.ts      signals → HUD widgets (display only)
+sprites/ph-*.png         shape library (near-white, tinted via core:tint)
+design/recipe.md         the contract
+design/tests/            reachability ledger + one example routine (a format seed)
+```
+
+## How your mechanic plugs in
+
+Write a script, attach it to a node inside `board`, and score through
+`GameRules` — either by emitting on `game-root`:
+
+```ts
+this.findNode('game-root')?.emit('score-added', 1);
+this.findNode('game-root')?.emit('life-lost', 1);
+```
+
+…or by calling the component directly (`addScore`, `loseLife`, `finish`). The
+HUD, the end screen and RETRY then work with no further wiring.
+
+## The rule that keeps it workable
+
+One file, one responsibility. Keep each script in the 70–140 line range: small
+files can be edited surgically; monoliths get rewritten wholesale and lose the
+comments that explained them. When a mechanic outgrows its file, split it rather
+than growing it.
+
+## No menu yet
+
+A menu is a screen between you and the thing you are working on. Add one only
+once the game is fun: create `scenes/menu.pix3scene`, have its PLAY button
+`scene.changeScene('res://scenes/main.pix3scene', {transition: 'fade'})`, then
+point Project Settings → Default Export Scene Path at it. `Play Scene` keeps
+running whatever scene is open, so the menu never gets in the way again.