incanto 0.69.0 → 0.71.0

package/templates-app/molehill-2d/PROJECT/Context.md

@@ -0,0 +1,58 @@
+# Context — molehill-2d (Incanto)
+
+## Project Overview
+
+**Molehill** — a WHACK-A-MOLE you play with the mouse and nothing else. Nine
+holes in a turf field; a mole pops out of one of them and ducks back a little
+faster each time. Click it and you score; let it go and you have missed. Twelve
+moles wins, three misses loses.
+
+It is the clone-and-modify starter for **games you play by pointing**: match-3,
+tower defense, cards, point-and-click, RTS, board games, idle. Every other
+starter is a character you WALK, and that difference reaches further than it
+looks — there is no `CharacterController`, no `move` action, no gravity and no
+player body anywhere in the scene.
+
+The scoring, the lives, the sounds and the game-over are BUILT-IN gameplay wired
+in `game.scene.json`. The custom TypeScript is only the two things JSON cannot
+say: when a mole pops, and what the HUD shows.
+
+## Tech Stack
+
+_Exact versions are in `package.json`._
+
+- **Engine**: `incanto` + `incanto/2d` (createGame2D; Node2D, ColorRect2D,
+  AudioPlayer, HudLayer/UiText/UiBanner/UiButton) + `incanto/gameplay`
+  (auto-registered `Clickable`, `ScoreKeeper`).
+- **Art**: none. Every visual is a `ColorRect2D` — the field, the holes, the
+  moles. Swap in sprites by changing the node types and adding an `assets{}`
+  block; nothing in the logic knows what a mole looks like.
+- **Audio**: procedural presets (`coin` on a hit, `hurt` on a miss) — zero files.
+- **Input**: the pointer. `createGame2D({ pointer: { lockOnClick: false } })` —
+  locking would HIDE the cursor, which is exactly wrong for a game you aim.
+
+## The one thing to understand
+
+`Clickable` is a behaviour on each mole. It emits `clicked(node)` and nothing
+else, and the scene wires all nine of them to ONE handler:
+
+```jsonc
+{ "signal": "clicked", "from": "Field/Hole00/Mole", "to": "Field", "handler": "onMoleClicked" }
+```
+
+The signal carries the node it happened on, so one handler serves the whole
+board. A `Clickable` nobody listens to is reported by `incanto-check` — it can
+never do anything, and forgetting the wire is the mistake this genre makes.
+
+## Verifying it
+
+`bun run verify` drives the MOUSE, which is the only input this game has:
+
+```ts
+{ atMs: 1000, click: (ctx) => moleUp(ctx) }   // click whatever is up right now
+```
+
+`click` takes a node path, a point, or a function for the case a mouse game is
+usually in — the target cannot be named when the script is written. Headless
+there is no renderer and therefore no raycast, so `runScript` installs a
+geometric picker; a game with a picker of its own keeps it.

package/templates-app/molehill-2d/PROJECT/Requirements.md

@@ -0,0 +1,39 @@
+# Requirements — molehill-2d
+
+## The game
+
+- Nine holes in a 3×3 field. Exactly ONE mole is up at a time.
+- A mole stays up for `upSeconds`, minus `quicken` for every mole so far, floored
+  at 0.35 s — a run that goes long still ends.
+- Clicking the mole that is UP scores one and plays the `coin` preset. Clicking
+  anywhere else does nothing at all.
+- A mole whose time runs out is a MISS: it costs a life and plays `hurt`.
+- **12 whacks wins. 3 misses loses.** Both come from the built-in `ScoreKeeper`
+  (`scoreToWin: 12`, `lives: 3`), which emits `won` / `lost`.
+- The end of the game freezes the field — `won` and `lost` are both wired to
+  `Field.stop`, so no mole pops after the banner.
+- `PLAY AGAIN` resets the score, the lives and the field without a reload.
+
+## What it must NOT have
+
+- No character body, no `CharacterController`, no `move` action, no gravity. If
+  you find yourself adding one, you are writing a different starter.
+- No art files and no external URLs — every visual is a `ColorRect2D` and every
+  sound is a procedural preset. A starter you can run with no network.
+- No pointer LOCK. The cursor is the thing the player aims; hiding it is the one
+  unrecoverable mistake this genre can make.
+
+## What it must prove (`bun run verify`)
+
+| check | why |
+| --- | --- |
+| nine holes, and a mole up within the first second | the board exists and starts |
+| whacking scores | the `Clickable` → connection → `ScoreKeeper` path is live |
+| missing costs a life | the timeout half, which no click can prove |
+| three misses lose | `lives` is spendable more than once |
+| twelve whacks win | the goal is reachable |
+| the field stops when won | the game ending reaches the level |
+| a click on bare ground scores nothing | the picker is not answering "anything" |
+
+`auditScene` must be clean, and `coverage.json` answers the gate's two questions
+(`hurt: "afk"` — stand by and the moles get away; `lose: true`).

package/templates-app/molehill-2d/PROJECT/Status.md

@@ -0,0 +1,27 @@
+# Status — molehill-2d
+
+## Working
+
+- The full loop: pop → click or miss → score or life → win or lose → play again.
+- Nine `Clickable` moles wired to one handler; the built-in `ScoreKeeper` holds
+  the score, the lives and both end conditions.
+- Procedural audio on both outcomes; a hit flashes the mole before it drops, so
+  a hit reads as a hit rather than as the mole vanishing.
+- `bun run verify` — ten assertions, all driving the mouse.
+- `coverage.json` — the gate's two questions answered without a body.
+
+## Deliberately not here
+
+- **A difficulty curve beyond `quicken`.** One knob, so the ramp is legible.
+- **Multiple moles at once.** One mole is the clearest possible statement of the
+  loop; two is a design decision the person cloning this should make.
+- **Sprites.** The moles are rectangles on purpose — see Context.
+
+## Where to take it next
+
+- Swap `ColorRect2D` for `Sprite2D` and give the moles a sheet: nothing in
+  `behaviors.ts` knows what a mole looks like.
+- Golden mole worth three, bomb mole that costs a life when clicked — both are a
+  `tags` entry on the node and a branch in `onMoleClicked`.
+- Turn the field into a GRID of clickable cells and you have a match-3, a
+  minesweeper or a tower-defense build menu; the input path is identical.

package/templates-app/molehill-2d/PROJECT/Structure.md

@@ -0,0 +1,48 @@
+# Structure — molehill-2d
+
+```
+src/game.scene.json   the whole game's structure — holes, moles, HUD, wiring
+src/behaviors.ts      Molehill (when a mole pops) + Scoreboard (what the HUD says)
+src/main.ts           createGame2D, the pointer, the two behaviours
+verify.ts             the headless proof — drives the MOUSE
+coverage.json         the gate's two questions: can it hurt you, can it be lost
+```
+
+## The scene
+
+```
+Game            ScoreKeeper (scoreToWin 12, lives 3) — the score and the ending
+├── Sky/Turf    two ColorRect2D, the backdrop
+├── Field       Molehill — pops a mole, times it out
+│   └── Hole00…Hole22   nine Node2D, each with
+│       ├── Dirt        the hole (ColorRect2D)
+│       └── Mole        ColorRect2D + `Clickable`, `visible: false` until it pops
+├── Whack/Miss  two AudioPlayer, procedural presets
+└── Hud         HudLayer + Scoreboard
+    ├── Score / Lives   UiText
+    ├── Banner          UiBanner (the ending)
+    └── Again           UiButton, hidden until the game is over
+```
+
+## The wiring, all of it in JSON
+
+| from | signal | to | handler |
+| --- | --- | --- | --- |
+| every `Mole` | `clicked` | `Field` | `onMoleClicked` |
+| `Field` | `whacked` | `.` (the ScoreKeeper) | `addScore` |
+| `Field` | `escaped` | `.` | `loseLife` |
+| `Field` | `whacked` / `escaped` | `Whack` / `Miss` | `play` |
+| `.` | `scoreChanged` / `livesChanged` | `Hud` | `onScore` / `onLives` |
+| `.` | `won` / `lost` | `Hud` | `onWon` / `onLost` |
+| `.` | `won` / `lost` | `Field` | `stop` |
+| `Hud/Again` | `pressed` | `Hud` | `onAgain` |
+
+Nine moles, one handler: `clicked` carries the node it happened on.
+
+## The two behaviours
+
+- **`Molehill`** — the only timing in the game. Emits `whacked` and `escaped`
+  and reaches for nothing: the scoring, the sound and the ending are wires.
+  `holeCount` is a read for the harness.
+- **`Scoreboard`** — writes the HUD from the ScoreKeeper's signals, and owns the
+  `PLAY AGAIN` reset.

package/templates-app/molehill-2d/docs/project-2d-rules.md

@@ -0,0 +1,44 @@
+<userRequest>
+YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template
+(Molehill — a whack-a-mole you play with the MOUSE):
+
+1. 📖 READ THE SKILLS FIRST: `node_modules/incanto/skills/` is the engine manual,
+   version-pinned to what is installed. Start with `incanto-building-2d-games.md`
+   and `incanto-scene-json-authoring.md`, then `incanto-gameplay-behaviors.md`
+   (Clickable/ScoreKeeper) and `incanto-hud.md` (the HUD is scene JSON, not DOM).
+2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and connections
+   live in `src/game.scene.json`. Add content there, NOT ad-hoc in code.
+3. 🧠 LOGIC IS BEHAVIORS: prefer a BUILT-IN behavior (here: `Clickable` on each
+   mole reports being clicked; `ScoreKeeper` owns the score, the misses and
+   win/lose). Custom code is what the library leaves open: `Molehill` (which mole
+   is up, for how long, and what a miss costs) and `Scoreboard` (the HUD).
+4. 🔑 UIDS ARE GENERATED: omit `uid` and the loader assigns one. Never hand-invent.
+5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference as `"$key"`.
+   This template ships NO art on purpose — every mole is `ColorRect2D` blocks, so
+   the game is readable before any asset exists. Swap in sprites by changing only
+   the `assets{}` entry.
+6. 🖱 THE MOUSE IS THE INPUT: there is no character, no keyboard and no gravity.
+   `pointer: { lockOnClick: false }` at boot — locking would HIDE the cursor, which
+   is exactly wrong for a game you play by pointing. The scene declares no `input`
+   actions at all, and that is not an omission.
+7. ⬆️ COORDINATES: y-down pixels, (0,0) top-left, clockwise degrees.
+8. 🧲 COLLIDERS ARE PROPS when you add physics — `"collider": { "shape": … }` on a
+   body node, never child shape nodes. This template has no bodies: a mole is a
+   drawn rectangle that answers a click, which is all a board game needs.
+9. 🧩 ONE SCRIPT PER NODE: a node has exactly one `script`. `Clickable` lives on
+   the mole itself; anything else about that mole goes on a child node.
+10. 🎯 CLICKS ARE SIGNALS: `Clickable` emits `clicked`, `hovered` and `unhovered`
+    and nothing else — wire them in `connections[]`. A `Clickable` nobody listens
+    to is a pick every frame that can never do anything, and `incanto-check` says
+    so.
+11. 🖥 THE HUD IS NODES: `HudLayer` + `UiText`/`UiBanner`/`UiButton` in the scene.
+    Do not reach for `document` — the widgets work headlessly, so `bun run verify`
+    can read the score the player reads.
+12. 🎬 DELTA DISCIPLINE: only write props that differ from defaults (unknown props
+    hard-fail). 🧭 `this.engine` is NOT available in `onReady` during `loadScene` —
+    defer scene reads to the first `update`/`fixedUpdate`.
+13. ✅ VERIFY LIKE A USER: `bun run check` (scene valid) → `bun run verify`
+    (headless proof that a click scores, a miss costs a life, and both endings
+    fire) → `bun run dev`, open the browser, and actually PLAY before declaring
+    it done.
+</userRequest>

package/templates-app/molehill-2d/index.html

@@ -0,0 +1,73 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><rect width=%22100%22 height=%22100%22 rx=%2220%22 fill=%22%23a9714b%22/><text x=%2250%22 y=%2270%22 font-size=%2258%22 text-anchor=%22middle%22 font-family=%22Arial%22 font-weight=%22bold%22 fill=%22%23101a2b%22>M</text></svg>" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>Molehill — Incanto whack-a-mole</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+        overflow: hidden;
+        font-family: Arial, sans-serif;
+        background: #101a2b;
+        color: #f4f4f4;
+      }
+      canvas {
+        display: block;
+        width: 100%;
+        height: 100%;
+        /* The cursor IS the controller — never hide it, and make it read as
+           something you aim rather than something you drag text with. */
+        cursor: crosshair;
+      }
+      /* The HUD is scene JSON (HudLayer), not markup: the only DOM this game
+         owns is the loading card, which the engine removes once it boots. */
+      #loading {
+        position: fixed;
+        inset: 0;
+        z-index: 50;
+        display: flex;
+        flex-direction: column;
+        gap: 14px;
+        align-items: center;
+        justify-content: center;
+        background: #101a2b;
+      }
+      #loading .title {
+        font-size: 22px;
+        letter-spacing: 0.14em;
+        color: #ffd166;
+      }
+      #loading .hint {
+        font-size: 13px;
+        color: #8b93a7;
+      }
+      #loading .spinner {
+        width: 34px;
+        height: 34px;
+        border: 3px solid #2a3550;
+        border-top-color: #ffd166;
+        border-radius: 50%;
+        animation: spin 0.9s linear infinite;
+      }
+      @keyframes spin {
+        to {
+          transform: rotate(360deg);
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div id="loading">
+      <div class="title">MOLEHILL</div>
+      <div class="spinner"></div>
+      <div class="hint">click the moles — twelve to win, three misses and they win</div>
+    </div>
+    <canvas id="game"></canvas>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates-app/molehill-2d/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "molehill-2d",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "check": "incanto-check src --behaviors src/behaviors.ts",
+    "verify": "bun verify.ts"
+  },
+  "dependencies": {
+    "@dimforge/rapier2d-compat": "0.19.3",
+    "incanto": "^0.71.0",
+    "three": "^0.184.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/three": "^0.184.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  }
+}

package/templates-app/molehill-2d/src/behaviors.ts

@@ -0,0 +1,198 @@
+/**
+ * Molehill — the mouse is the whole game.
+ *
+ * No character body, no keyboard, no gravity: nine holes, a mole that pops out
+ * of one of them, and a cursor. The engine's own `Clickable` turns each mole
+ * into a node that reports being clicked, the built-in `ScoreKeeper` holds the
+ * score and the misses, and the wiring between them is scene JSON.
+ *
+ * This is the starter for an entire family the other templates do not cover —
+ * match-3, tower defense, cards, point-and-click, RTS, board games, idle — all
+ * of which are played by pointing at things.
+ */
+
+import type { UiBanner, UiButton, UiText } from 'incanto';
+import { Behavior, type Node } from 'incanto';
+
+/** Holes across the field, mirrored by `game.scene.json`. */
+const HOLES = 9;
+const MOLES_TO_WIN = 12;
+const MISSES_ALLOWED = 3;
+
+/** A mole node, as this game drives it. */
+interface Mole extends Node {
+  visible: boolean;
+  color: string;
+  scale: number[];
+}
+
+const UP = '#a9714b';
+const HIT = '#ffd166';
+
+/**
+ * The field: pops a mole, waits, and calls it a miss if you were too slow.
+ *
+ * It emits rather than reaches — `whacked` and `escaped` are wired in the scene
+ * to `ScoreKeeper.addScore` / `loseLife` and to the two `AudioPlayer`s, so the
+ * scoring, the sound and the game-over all live in JSON.
+ */
+export class Molehill extends Behavior {
+  static readonly props = {
+    /** Seconds a mole stays up at the start. */
+    upSeconds: { default: 1.4 },
+    /** Seconds between one mole going away and the next arriving. */
+    gapSeconds: { default: 0.55 },
+    /** Every mole is this much quicker than the one before (0 = no ramp). */
+    quicken: { default: 0.04 },
+  };
+  static readonly signals: readonly string[] = ['whacked', 'escaped'];
+
+  upSeconds = 1.4;
+  gapSeconds = 0.55;
+  quicken = 0.04;
+
+  /** The mole that is up right now, or null between moles. */
+  private up: Mole | null = null;
+  private timer = 0;
+  private popped = 0;
+  private running = true;
+  /** The mole showing its hit colour, and how long it has left to show it. */
+  private flashing: Mole | null = null;
+  private flash = 0;
+
+  override onReady(): void {
+    this.timer = this.gapSeconds;
+    for (const mole of this.moles()) mole.visible = false;
+  }
+
+  /** Freeze the field — wired to the ScoreKeeper's `won` and `lost`. */
+  stop(): void {
+    this.running = false;
+    this.hide();
+  }
+
+  /** Start over, from the button on the HUD. */
+  restart(): void {
+    this.running = true;
+    this.popped = 0;
+    this.timer = this.gapSeconds;
+    this.hide();
+  }
+
+  override update(dt: number): void {
+    if (this.flashing) {
+      this.flash -= dt;
+      if (this.flash <= 0) {
+        this.flashing.color = UP;
+        this.flashing.visible = false;
+        this.flashing = null;
+      }
+    }
+    if (!this.running) return;
+    this.timer -= dt;
+    if (this.timer > 0) return;
+    if (this.up) {
+      // Its time ran out with nobody clicking it — that is the miss.
+      this.hide();
+      this.timer = this.gapSeconds;
+      this.emit('escaped');
+      return;
+    }
+    this.pop();
+  }
+
+  onMoleClicked(mole: Node): void {
+    // Only the mole that is UP counts: a click on one already going down is a
+    // click on nothing, which is what the player sees.
+    if (!this.running || mole !== (this.up as unknown as Node)) return;
+    // It flashes before it goes, so a hit reads as a hit rather than as the
+    // mole simply vanishing.
+    const hit = this.up;
+    if (!hit) return;
+    hit.color = HIT;
+    this.flashing = hit;
+    this.flash = 0.09;
+    this.up = null;
+    this.timer = this.gapSeconds;
+    this.emit('whacked', 1);
+  }
+
+  private pop(): void {
+    const moles = this.moles();
+    if (moles.length === 0) return;
+    const next = moles[Math.floor(this.engine.rng.next() * moles.length)];
+    if (!next) return;
+    next.visible = true;
+    next.color = UP;
+    this.up = next;
+    this.popped += 1;
+    // Quicker every time, so a run that goes long still ends.
+    this.timer = Math.max(0.35, this.upSeconds - this.popped * this.quicken);
+  }
+
+  private hide(): void {
+    if (this.up) this.up.visible = false;
+    if (this.flashing) {
+      this.flashing.color = UP;
+      this.flashing.visible = false;
+      this.flashing = null;
+    }
+    this.up = null;
+  }
+
+  private moles(): Mole[] {
+    const out: Mole[] = [];
+    for (const hole of this.node.children) {
+      const mole = hole.getNodeOrNull('Mole');
+      if (mole) out.push(mole as unknown as Mole);
+    }
+    return out;
+  }
+
+  /** How many holes this field found — read by the harness. */
+  get holeCount(): number {
+    return this.node.children.length;
+  }
+}
+
+/** The HUD, driven entirely by the ScoreKeeper's signals. */
+export class Scoreboard extends Behavior {
+  private text(name: string): UiText {
+    return this.node.getNode(name) as unknown as UiText;
+  }
+
+  onScore(score: number): void {
+    this.text('Score').text = `Moles ${score} / ${MOLES_TO_WIN}`;
+  }
+
+  onLives(lives: number): void {
+    this.text('Lives').text = `Misses left ${lives}`;
+  }
+
+  onWon(): void {
+    this.finish(`ALL ${MOLES_TO_WIN} WHACKED`, '#ffd166');
+  }
+
+  onLost(): void {
+    this.finish('THEY GOT AWAY', '#ef4444');
+  }
+
+  onAgain(): void {
+    const game = this.node.getNode('/root');
+    (game.behavior as unknown as { setScore(n: number): void; lives: number }).setScore(0);
+    (game.behavior as unknown as { lives: number }).lives = MISSES_ALLOWED;
+    (this.node.getNode('/root/Field').behavior as unknown as { restart(): void }).restart();
+    (this.node.getNode('Banner') as unknown as UiBanner).clear();
+    (this.node.getNode('Again') as unknown as UiButton).visible = false;
+    this.onScore(0);
+    this.onLives(MISSES_ALLOWED);
+  }
+
+  private finish(text: string, color: string): void {
+    (this.node.getNode('Banner') as unknown as UiBanner).show(text, { color, seconds: 0 });
+    (this.node.getNode('Again') as unknown as UiButton).visible = true;
+  }
+}
+
+/** Holes the field expects, for a harness that wants to check the board. */
+export const FIELD_SIZE = HOLES;