incanto 0.57.0 → 0.58.0

package/templates-app/platformer-2d/src/main.ts

@@ -0,0 +1,68 @@
+/**
+ * Castle Run — a polished 2D adventure PLATFORMER on Incanto. Run a medieval
+ * knight through a castle: A/D (or arrows) to run, Space/W to jump — tap again in
+ * the air to DOUBLE-JUMP, and the controller forgives you with coyote-time +
+ * jump-buffering. STOMP goblins from above (and chain-bounce), ride the moving
+ * platform and the lift, grab coins + gems, dodge the spikes and the pit, touch
+ * the Checkpoint flag so a fall sends you back there, and reach the gold flag to
+ * clear the castle. Three hearts per life, three lives.
+ *
+ * The level is JSON: StaticBody2D platforms, Patrol/Oscillate moving platforms +
+ * goblins, Pickup coins/gems, ScoreKeeper score/lives/win-lose, AudioPlayer SFX —
+ * all wired in `game.scene.json`. The custom TypeScript is the game FEEL the
+ * built-ins leave open: PlayerController (coyote/buffer/double-jump/variable
+ * height/stomp/knockback/checkpoint-respawn/platform-carry), GoblinSkin,
+ * FollowCam (follow + screen-shake), ParallaxLayer, HudUpdater.
+ */
+import { createGame2D } from 'incanto/2d';
+import goblinUrl from 'incanto/assets/characters/goblin.png';
+// Built-in sprite art ships in the package — import the URLs and inject them into
+// the scene's asset placeholders before boot (the engine clones the scene).
+import knightUrl from 'incanto/assets/characters/medieval-knight.png';
+import coinUrl from 'incanto/assets/items/coin.png';
+import gemUrl from 'incanto/assets/items/gem.png';
+import { FollowCam, GoblinSkin, HudUpdater, ParallaxLayer, PlayerController } from './behaviors';
+import sceneJson from './game.scene.json';
+
+// OPTIONAL looping music (large tracks aren't bundled). Point at any URL to loop.
+const MUSIC_URL = '';
+
+const behaviors = { PlayerController, GoblinSkin, FollowCam, ParallaxLayer, HudUpdater };
+
+const canvas = document.querySelector('canvas') as HTMLCanvasElement;
+
+const scene = structuredClone(sceneJson) as typeof sceneJson & {
+  assets: {
+    knight: { url: string };
+    goblin: { url: string };
+    coin: { url: string };
+    gem: { url: string };
+  };
+};
+scene.assets.knight.url = knightUrl;
+scene.assets.goblin.url = goblinUrl;
+scene.assets.coin.url = coinUrl;
+scene.assets.gem.url = gemUrl;
+
+const game = await createGame2D({
+  debug: import.meta.env.VITE_INCANTO_DEBUG === '1',
+  canvas,
+  scene,
+  behaviors,
+});
+
+document.querySelector('#loading')?.remove();
+
+if (MUSIC_URL) {
+  game.engine.music.play(MUSIC_URL, { loop: true, fadeIn: 1.5 });
+  game.engine.audio.music = 0.3;
+}
+
+// On-screen JUMP button (mobile + desktop parity); the joystick is auto-shown by
+// createGame2D on coarse pointers for the 'move' action.
+const jumpBtn = document.querySelector('#btn-jump');
+jumpBtn?.addEventListener('pointerdown', () => game.engine.input.handleKey('Space', true));
+jumpBtn?.addEventListener('pointerup', () => game.engine.input.handleKey('Space', false));
+
+// Console playground: game.scene.root.getNode('Player').position = [x, y]
+Object.assign(window, { game });

package/templates-app/platformer-2d/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "verify.ts"]
+}

package/templates-app/platformer-2d/verify.ts

@@ -0,0 +1,275 @@
+/**
+ * Headless proof that Castle Run actually PLAYS — the browserless half of the
+ * agent loop (author → VERIFY → fix). Drives the REAL `game.scene.json` through
+ * `incanto/test`'s `runScript` at a fixed, seeded timestep and asserts the whole
+ * composition end to end. The platformer FEEL lives in the custom PlayerController
+ * (coyote/buffer/double-jump/stomp/knockback/checkpoint-respawn), so the checks
+ * exercise it directly rather than the built-in controller:
+ *
+ *   RUN + JUMP — holding `move` right walks the knight; `jump` while grounded
+ *                leaves the floor (y rises) and gravity returns it to solid ground.
+ *   COIN       — overlapping a coin Area fires Pickup.collected → ScoreKeeper
+ *                addScore; the score climbs.
+ *   STOMP      — falling onto a goblin from above frees it and adds score.
+ *   HIT        — touching a goblin from the SIDE costs the player a heart.
+ *   CHECKPOINT — touching the flag then dying respawns the player AT the flag.
+ *   WIN        — touching the Goal sets the score to scoreToWin → `won`.
+ *   LOSE       — falling into the pit with the last life → `died`-equivalent →
+ *                ScoreKeeper.loseLife → `lost`.
+ *
+ * Run with `bun verify.ts` (or `bun run verify`).
+ */
+import { registerBehavior } from 'incanto';
+import { auditScene, registerAllNodes, runScript } from 'incanto/test';
+import {
+  FollowCam,
+  GoblinSkin,
+  HudUpdater,
+  ParallaxLayer,
+  PlayerController,
+} from './src/behaviors';
+import sceneJson from './src/game.scene.json';
+
+const behaviors = { PlayerController, GoblinSkin, FollowCam, ParallaxLayer, HudUpdater };
+
+const ok = (label: string, cond: boolean): void => {
+  if (!cond) {
+    console.error(`FAIL: ${label}`);
+    process.exitCode = 1;
+  } else {
+    console.log(`pass: ${label}`);
+  }
+};
+
+// ---- AUDIT ---------------------------------------------------------------------------
+// The check that fails on a WARNING, not just an error. Three of the five
+// shipped templates had no audit block, which is how every one of them came to
+// ship a scene whose saveable state had no uid to key it under: the save came
+// back empty, the load reported no problem, and nothing here asked.
+{
+  registerAllNodes();
+  for (const [name, ctor] of Object.entries(behaviors)) {
+    registerBehavior(name, ctor as never, { replace: true });
+  }
+  const warnings = auditScene(sceneJson as unknown as Parameters<typeof auditScene>[0]);
+  ok(`auditScene is clean (${warnings.length} warnings)`, warnings.length === 0);
+  for (const w of warnings) console.error(`  warn: ${w}`);
+}
+
+interface Body {
+  position: number[];
+  velocity: number[];
+}
+interface Player {
+  hearts: number;
+}
+
+// ---- RUN + JUMP --------------------------------------------------------------
+{
+  let startX = 0;
+  let startY = 0;
+  let leftGround = false;
+  let landedY = 0;
+
+  await runScript(sceneJson, {
+    durationMs: 2200,
+    seed: 1,
+    behaviors,
+    steps: [
+      {
+        atMs: 200,
+        label: 'capture spawn pose',
+        do: (ctx) => {
+          const p = ctx.getNode('Player') as unknown as Body;
+          startX = p.position[0] ?? 0;
+          startY = p.position[1] ?? 0;
+        },
+      },
+      { atMs: 250, vector: ['move', 1, 0] },
+      { atMs: 600, press: 'jump' },
+      { atMs: 660, release: 'jump' },
+      {
+        atMs: 820,
+        label: 'jump lifted the knight off the ground',
+        do: (ctx) => {
+          const p = ctx.getNode('Player') as unknown as Body;
+          if ((p.position[1] ?? 0) < startY - 18) leftGround = true;
+        },
+      },
+      { atMs: 900, vector: ['move', 0, 0] },
+      {
+        atMs: 2000,
+        label: 'capture settled pose',
+        do: (ctx) => {
+          landedY = (ctx.getNode('Player') as unknown as Body).position[1] ?? 0;
+        },
+      },
+      {
+        atMs: 2100,
+        label: 'knight ran right',
+        assert: (ctx) =>
+          ((ctx.getNode('Player') as unknown as Body).position[0] ?? 0) > startX + 50,
+      },
+    ],
+  });
+
+  ok('knight ran right from spawn', true);
+  ok('jump lifted the knight off the ground', leftGround);
+  ok('knight settled back onto solid ground', landedY > startY - 60 && landedY < startY + 60);
+}
+
+// ---- COIN + STOMP + HIT ------------------------------------------------------
+{
+  const scores: number[] = [];
+  let enemiesBefore = 0;
+  let enemiesAfterStomp = 0;
+  let heartsAfterHit = 3;
+
+  const result = await runScript(sceneJson, {
+    durationMs: 4000,
+    seed: 2,
+    behaviors,
+    steps: [
+      {
+        atMs: 100,
+        do: (ctx) => {
+          ctx.scene.root.on('scoreChanged', (s) => scores.push(s as number));
+          enemiesBefore = ctx.scene.tree.getNodesInGroup('enemy').length;
+        },
+      },
+      {
+        atMs: 300,
+        label: 'collect a coin: snap the knight onto Coin1',
+        do: (ctx) => {
+          const player = ctx.getNode('Player') as unknown as Body;
+          const coin = ctx.getNode('Coins/Coin1') as unknown as Body;
+          player.position = [...coin.position];
+          for (let i = 0; i < 3; i++) ctx.engine.step();
+        },
+      },
+      {
+        atMs: 900,
+        label: 'stomp: drop onto Gob1 from above',
+        do: (ctx) => {
+          const player = ctx.getNode('Player') as unknown as Body;
+          const gob = ctx.getNode('Gob1') as unknown as Body;
+          player.position = [gob.position[0] ?? 0, (gob.position[1] ?? 0) - 56];
+          player.velocity = [0, 220];
+          for (let i = 0; i < 8; i++) ctx.engine.step();
+          enemiesAfterStomp = ctx.scene.tree.getNodesInGroup('enemy').length;
+        },
+      },
+      {
+        atMs: 1600,
+        label: 'side hit: overlap Gob2 at the same height → lose a heart',
+        do: (ctx) => {
+          const player = ctx.getNode('Player') as unknown as Body;
+          const gob = ctx.getNode('Gob2') as unknown as Body;
+          player.position = [gob.position[0] ?? 0, gob.position[1] ?? 0];
+          player.velocity = [0, 0];
+          for (let i = 0; i < 3; i++) ctx.engine.step();
+          heartsAfterHit = (ctx.getNode('Player').behavior as unknown as Player).hearts;
+        },
+      },
+    ],
+  });
+
+  ok(
+    'a coin raised the score (Pickup → addScore)',
+    scores.some((s) => s >= 10),
+  );
+  ok('stomping a goblin removed it', enemiesBefore > 0 && enemiesAfterStomp === enemiesBefore - 1);
+  ok(
+    'a stomp also scored',
+    scores.some((s) => s >= 50),
+  );
+  ok('a side hit cost a heart', heartsAfterHit < 3);
+  ok('runScript reported no failures (coin/stomp/hit path)', result.ok);
+}
+
+// ---- CHECKPOINT + RESPAWN + WIN ----------------------------------------------
+{
+  let won = 0;
+  let respawnedAtCheckpoint = false;
+
+  const result = await runScript(sceneJson, {
+    durationMs: 4000,
+    seed: 3,
+    behaviors,
+    steps: [
+      { atMs: 100, do: (ctx) => ctx.scene.root.on('won', () => won++) },
+      {
+        atMs: 300,
+        label: 'touch the checkpoint flag',
+        do: (ctx) => {
+          const player = ctx.getNode('Player') as unknown as Body;
+          const cp = ctx.getNode('Checkpoint') as unknown as Body;
+          player.position = [...cp.position];
+          for (let i = 0; i < 3; i++) ctx.engine.step();
+        },
+      },
+      {
+        atMs: 900,
+        label: 'die in the pit (lives remain) → respawn at the checkpoint',
+        do: (ctx) => {
+          const player = ctx.getNode('Player') as unknown as Body;
+          const cp = ctx.getNode('Checkpoint') as unknown as Body;
+          player.position = [1400, 880]; // into the death plane
+          for (let i = 0; i < 4; i++) ctx.engine.step();
+          const p = (ctx.getNode('Player') as unknown as Body).position;
+          respawnedAtCheckpoint =
+            Math.abs((p[0] ?? 0) - (cp.position[0] ?? 0)) < 40 &&
+            Math.abs((p[1] ?? 0) - (cp.position[1] ?? 0)) < 60;
+        },
+      },
+      {
+        atMs: 1600,
+        label: 'reach the goal flag → WIN',
+        do: (ctx) => {
+          const player = ctx.getNode('Player') as unknown as Body;
+          const goal = ctx.getNode('Goal') as unknown as Body;
+          player.position = [...goal.position];
+          for (let i = 0; i < 4 && won === 0; i++) ctx.engine.step();
+        },
+      },
+    ],
+  });
+
+  ok('dying respawned the knight at the checkpoint', respawnedAtCheckpoint);
+  ok('reaching the goal emitted `won` once', won === 1);
+  ok('runScript reported no failures (checkpoint/win path)', result.ok);
+}
+
+// ---- LOSE (pit with the last life) -------------------------------------------
+{
+  let lost = 0;
+
+  const result = await runScript(sceneJson, {
+    durationMs: 2500,
+    seed: 4,
+    behaviors,
+    steps: [
+      {
+        atMs: 100,
+        do: (ctx) => {
+          (ctx.scene.root.behavior as unknown as { lives: number }).lives = 1;
+          ctx.scene.root.on('lost', () => lost++);
+        },
+      },
+      {
+        atMs: 400,
+        label: 'fall into the pit with the last life',
+        do: (ctx) => {
+          const player = ctx.getNode('Player') as unknown as Body;
+          player.position = [1400, 880];
+          for (let i = 0; i < 6 && lost === 0; i++) ctx.engine.step();
+        },
+      },
+    ],
+  });
+
+  ok('the last life lost the game (`lost`)', lost === 1);
+  ok('runScript reported no failures (lose path)', result.ok);
+}
+
+console.log(process.exitCode ? '\nVERIFY FAILED' : '\nVERIFY OK — Castle Run plays end to end');

package/templates-app/platformer-2d/vite.config.ts

@@ -0,0 +1,12 @@
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  base: './',
+  // Dev-server only, and both are why the editor is useful here:
+  // - incantoScenes(): validates every *.scene.json the moment you save it,
+  //   AND serves this project's scenes, so the editor (☰ debug ▸ edit this
+  //   scene ▸ scenes) can open, create and save any scene in the project.
+  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
+  plugins: [incantoScenes(), incantoLibrary()],
+});

package/templates-app/star-survivor/PROJECT/Context.md

@@ -0,0 +1,55 @@
+# Context — star-survivor (Incanto)
+
+## Project Overview
+
+**Hollow Horde** — a top-down SURVIVORS-LIKE (Vampire Survivors genre), the
+clone-and-modify starter for the survivor/roguelite arena. Move a knight with
+WASD/arrows; he AUTO-ATTACKS the nearest enemy. Goblins and faster ghosts pour in
+from every side and grow tougher over time; cut them down, vacuum up the XP shards
+they drop, and on each LEVEL-UP pick one of three upgrades (damage / fire-rate /
+extra bolt / pierce / move-speed / magnet / max-HP). Survive 90 seconds to WIN; let
+the horde drain your HP and you fall.
+
+The horde is BUILT-IN gameplay wired in `game.scene.json`; the SURVIVOR feel is the
+custom TypeScript.
+
+## Tech Stack
+
+_Exact versions are in `package.json`._
+
+- **Engine**: `incanto` + `incanto/2d` (createGame2D; CharacterBody2D/Area2D,
+  AnimatedSprite2D, ColorRect2D, Camera2D, AudioPlayer) + `incanto/gameplay`
+  (auto-registered Spawner, Chase, Health, DamageOnContact, ScoreKeeper, …).
+- **Art**: built-in animated sheets `medieval-knight` (player), `goblin` + `ghost`
+  (enemies), bundler-imported in `main.ts` and injected into the scene asset urls.
+  Arena/bolts/XP shards are `ColorRect2D`.
+- **Audio**: procedural SFX presets (shoot/coin/hurt/win/lose). HUD is DOM.
+- **Build/Lang**: Vite, TypeScript. **Headless verify**: `incanto/test` (`runScript`).
+
+## Critical Memory
+
+- READ THE SKILLS FIRST: `node_modules/incanto/skills/` —
+  `incanto-gameplay-behaviors.md`, `incanto-building-2d-games.md`,
+  `incanto-physics-and-input.md`.
+- TOP-DOWN: `physics.gravity` is `[0,0]`. The custom `Survivor` integrates its own
+  velocity (`moveAndSlide`); enemies move via built-in `Chase` (moveParent).
+- ONE SCRIPT PER NODE: the player node's script is `Survivor`, so its `Health` lives
+  on a child `Vitals` node — `DamageOnContact` finds it by searching the body's
+  descendants. Each enemy's `EnemyDrop`/`EnemyFace` are child scripts reading the
+  parent (whose script is `Health`).
+- HORDE: the engine clone path (`SpawnSource`) is internal, so two built-in
+  `Spawner`s clone hidden goblin/ghost templates and emit `spawned(clone)`; the
+  custom `Director` repositions each clone onto a RING around the player and ramps
+  spawn rate + enemy HP/speed over time. Spawners sit at the ORIGIN (clone local pos
+  = world).
+- LEVEL-UP PAUSE: `Survivor` freezes the world with `this.engine.stop()` while the
+  DOM upgrade overlay is shown, and `start()`s on pick. Headless (`verify`) drives
+  `engine.step()` (not the loop) and auto-applies an upgrade (guarded by `hasDom`).
+- MANY ENTITIES: bolts + XP shards are spawned `ColorRect2D`s MANAGED by `Survivor`
+  (moved + AABB-tested vs the `enemy`/`xp` groups each frame) — cloned nodes can't use
+  scene `connections`, so group + AABB is the pattern. WIN = `Survivor` sets the score
+  to `scoreToWin` at the survive-timer → `ScoreKeeper` `won`; LOSE = player `Health`
+  `died` → `loseLife` → `lost`.
+- `incanto/assets/*` dev imports need an `'incanto/assets'` alias in `vite.config.ts`.
+- `this.engine` is unavailable in `onReady` during `loadScene`; defer scene reads.
+- Node uids omitted (loader-generated). `window.game` exposes the Game handle.

package/templates-app/star-survivor/PROJECT/Requirements.md

@@ -0,0 +1,47 @@
+# Requirements — star-survivor (Incanto)
+
+## Coding Patterns
+
+- Game STRUCTURE belongs in `src/game.scene.json`. Prefer a BUILT-IN behavior over
+  custom logic — check `incanto-gameplay-behaviors.md` /
+  `incanto-physics-and-input.md` BEFORE writing a Behavior class.
+- TOP-DOWN setup: `physics.gravity [0,0]`. The horde is built-in: two `Spawner`s
+  (infinite `total 0`) clone hidden goblin/ghost templates; each enemy `Chase`s
+  `/root/Player` (`moveParent`); a `DamageOnContact` hitbox (`targetGroup: player`)
+  drains the player's `Health`. `ScoreKeeper(lives:1)` owns win/lose.
+- Custom logic (`src/behaviors.ts`), the survivor FEEL only:
+  - `Survivor` — move + facing/anim, AUTO-ATTACK (managed bolts, AABB vs `enemy`),
+    XP pickup + magnet (AABB vs `xp`), level-up (pause + 3 upgrade cards), survive
+    timer → win, DOM HUD.
+  - `Director` — ring-scatter each spawned clone around the player + escalate.
+  - `EnemyDrop` (death → XP shard + kill), `EnemyFace` (sprite facing).
+- ONE SCRIPT PER NODE: keep `Health` on a child `Vitals` (player) — DamageOnContact
+  searches descendants; keep `EnemyDrop`/`EnemyFace` on child nodes reading the
+  parent. Don't try to stack two scripts on one node.
+- CLONES CAN'T USE CONNECTIONS: spawned enemies/bolts/XP shards carry their behaviors
+  but NOT scene `connections`. Resolve interactions by GROUP + AABB in one owner
+  (`Survivor`), or by a behavior ON the clone (`EnemyDrop` listening to the parent).
+- SPAWN A HORDE without the internal clone API: built-in `Spawner` + a `Director`
+  that listens to `spawned(clone)` and repositions onto a ring (spawners at origin so
+  clone local = world). Escalate by mutating spawner `interval` + clone Health/Chase.
+- PAUSE for the level-up overlay with `this.engine.stop()` / `start()`; guard DOM use
+  with `hasDom` so headless `verify` auto-applies an upgrade.
+- VITE: `vite.config.ts` MUST alias `incanto/assets` → `../../packages/engine/assets`
+  (most-specific alias first) or the built-in sprite imports 500 in `bun run dev`.
+- `this.engine` is unavailable in `onReady` during `loadScene` — defer scene reads.
+- Omit node `uid`s (loader-generated). VERIFY headlessly (`bun run verify`) before
+  claiming it works.
+
+## Known Issues / Constraints
+
+- No collision LAYERS in v0; enemies overlap each other + the player freely (typical
+  for survivors). Damage is the enemy `Hit` Area → player `Health`; the player has
+  i-frames (`invulnerableFor`).
+- `Health` dies once (no revive), which is fine here — death = game over (`lost`), no
+  respawn. Enemies are `freeOnDeath`.
+- The clone path is internal, so spawning leans on built-in `Spawner` + `Director`
+  scatter; bolts/XP are managed `ColorRect2D`s (no per-projectile behavior).
+- Sprites: `medieval-knight`/`goblin` (192px frames), `ghost` (112×128). Swap a sheet
+  by changing only its asset entry + the import in `main.ts`.
+- Difficulty ramps with elapsed time (spawn rate + enemy HP/speed); tune in `Director`
+  and the `Survivor` constants. Music is OPTIONAL (`MUSIC_URL` empty; SFX need no files).

package/templates-app/star-survivor/PROJECT/Status.md

@@ -0,0 +1,44 @@
+# Status — star-survivor (Incanto)
+
+## Implemented
+
+- **Hollow Horde** — a top-down survivors-like. Full-window canvas + DOM HUD (HP/XP
+  bars, level, kills, survive-timer), a LEVEL-UP overlay with 3 upgrade cards, and a
+  win/lose banner.
+- `game.scene.json`: top-down (`gravity [0,0]`), `move` input, knight/goblin/ghost
+  spritesheets, `ScoreKeeper(lives 1)`, a dark arena, the `Player`
+  (`CharacterBody2D` + `Survivor`, `Health` on child `Vitals`), two built-in
+  `Spawner`s (goblin/ghost, infinite) with hidden templates (`Health` freeOnDeath +
+  `Chase` + `EnemyFace` + `DamageOnContact` + `EnemyDrop`), a `Director`, a
+  `FollowCamera`, and SFX players.
+- Custom `src/behaviors.ts`: `Survivor` (move + auto-attack managed bolts + XP magnet
+  + level-up/upgrades + pause via `engine.stop/start` + DOM HUD), `Director`
+  (ring-scatter spawns + time escalation), `EnemyDrop`, `EnemyFace`.
+- `main.ts` injects the three sheet urls; `vite.config.ts` aliases `incanto/assets`.
+
+## Works (verified)
+
+- `bun run check` → 1/1 scene valid. `bun run typecheck` / `bun run lint` clean.
+- `bun run verify` (headless `runScript`): 7/7 — move walks the player; the
+  auto-attack kills a spawned goblin which drops an XP shard + tallies a kill;
+  gaining XP raises the level; the survive-timer emits `won`; HP→0 emits `lost`.
+- Played in a real browser (Playwright): the horde streams in from all sides as real
+  animated **goblin + ghost** sprites; the knight auto-attacks the nearest enemy;
+  kills drop cyan XP shards that the magnet vacuums up; LEVEL-UP freezes the world and
+  shows 3 random upgrade cards (e.g. +Damage / +Fire rate / +Pierce / +Magnet / +Max
+  HP), and picking one applies it + resumes; difficulty escalates. 0 console errors.
+- HIT FEEDBACK: every bolt that connects pops an additive impact spark, shoves the
+  enemy back (knockback), and PUNCHES its sprite (scale-up + opacity dip via
+  EnemyFace on the `damaged` signal); a kill adds a colour POOF burst + SFX. The
+  ARENA is an INFINITE grid (`GridFloor`): a camera-following backdrop + grid lines
+  snapped to world multiples of `cell`, so it tiles forever with no visible border.
+
+## Not Included (on purpose — and next polish passes)
+
+- Bolts/XP are simple `ColorRect2D`s (swap for sprites/FX if desired); the grid floor
+  is procedural (no tile art).
+- No weapon VARIETY beyond the straight bolt (the upgrade pool tunes one weapon), no
+  boss, no meta-progression, no bundled music (SFX presets only).
+- Spawning leans on the built-in `Spawner` + `Director` scatter (the engine's clone
+  path is internal). Add enemy types by copying a template + spawner into the
+  `Director.spawners` list.

package/templates-app/star-survivor/PROJECT/Structure.md

@@ -0,0 +1,63 @@
+# Structure — star-survivor (Incanto)
+
+## `index.html`
+
+Full-window page: loading overlay, one `#game` canvas, the DOM HUD (`#hp-track`/
+`#hp-fill`/`#hp-text`, `#xp-track`/`#xp-fill`, `#level-text`, `#kills-text`,
+`#timer-text`, `#hint`), the LEVEL-UP overlay (`#levelup` → `#levelup-level` +
+`#levelup-cards`, populated by `Survivor`), a center `#banner`, and the iframe
+GAME_SIZE script. `Survivor` writes all of these (guarded for headless).
+
+## `src/game.scene.json`
+
+The arena + horde, mostly BUILT-INS:
+
+- header — `background`, `viewport` (`design [960,540]`, `fit: expand`),
+  `physics.gravity [0,0]` (top-down), `move` input (WASD+arrows), and the
+  `knight`/`goblin`/`ghost` spritesheet `assets` (urls injected in `main.ts`).
+- `Game` root — `ScoreKeeper` (`scoreToWin 1`, `lives 1`).
+- `Arena`/`ArenaPad`/`ArenaRing*` — dark `ColorRect2D` floor + a centre marker.
+- `Player` — `CharacterBody2D` (group `player`) + `Survivor`; children `Skin`
+  (`AnimatedSprite2D` knight) + `Vitals` (`Health`, the body's HP via a child).
+- `GoblinSpawner` / `GhostSpawner` — built-in `Spawner` (interval, max, `total 0`
+  = infinite) at the ORIGIN, each with a hidden `visible:false` template child:
+  - `GoblinTemplate` / `GhostTemplate` — `CharacterBody2D` (group `enemy`) +
+    `Health(freeOnDeath)`; children `Skin` (`AnimatedSprite2D`), `AI` (`Chase`
+    target `/root/Player`, `moveParent`), `Face` (`EnemyFace`), `Hit` (`Area2D` +
+    `DamageOnContact` targetGroup `player`), `Drop` (`EnemyDrop`).
+- `Director` — custom: listens to both spawners' `spawned`, ring-scatters each
+  clone around the player, ramps interval down + enemy HP/speed up.
+- `Camera` — `Camera2D` + `FollowCamera` (target player).
+- `SfxShoot/Xp/Hurt/Win/Lose` — `AudioPlayer` presets.
+- `connections` — `Player/Vitals died → /root loseLife`; `damaged → SfxHurt`;
+  root `won/lost → SfxWin/SfxLose`. (Auto-attack/XP/level/win-trigger are in code.)
+
+## `src/behaviors.ts`
+
+- `Survivor` — the player brain: top-down move + facing/anim, AUTO-ATTACK (managed
+  bolt list, AABB vs `enemy`), XP pickup + magnet (AABB vs `xp`), level-up (pause +
+  3 random upgrade cards + `engine.stop/start`), survive-timer win, and the DOM HUD.
+- `Director` — ring-spawn around the player + time escalation (see above).
+- `EnemyDrop` — on the parent enemy's `died`, drop an XP shard (`ColorRect2D` in
+  group `xp` with an `_xp` value) + `Survivor.addKill()`.
+- `EnemyFace` — flip the enemy sprite toward travel + play `move`.
+
+## `src/main.ts`
+
+Inject the knight/goblin/ghost urls, `createGame2D({ canvas, scene, behaviors })`,
+optional music, remove the loader, expose `window.game`.
+
+## `vite.config.ts`
+
+Aliases `incanto`, `incanto/2d`, AND `incanto/assets` (the last is REQUIRED for the
+built-in sprite imports to resolve in `bun run dev`).
+
+## `verify.ts`
+
+Headless `runScript` proof: move, auto-attack kills an enemy → XP shard drop + kill
+tally, XP → level-up, survive-timer → `won`, HP→0 → `lost`. Run with `bun run verify`.
+
+## `docs/project-2d-rules.md`
+
+The vibe-coding rules for this survivor template (one-script-per-node, horde-without-
+clone-API, engine pause, AABB-in-one-owner, the `incanto/assets` vite alias, …).

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

@@ -0,0 +1,53 @@
+<userRequest>
+YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template
+(Hollow Horde — a top-down survivors-like):
+
+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`
+   (Spawner/Chase/Health/DamageOnContact/ScoreKeeper) and
+   `incanto-physics-and-input.md` (2D bodies, the input map, units).
+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: two `Spawner`s clone
+   the enemy templates; each enemy `Chase`s the player; a `DamageOnContact` hitbox
+   drains the player's `Health`; `ScoreKeeper` owns lives/win-lose). Custom code is
+   the survivor FEEL the library leaves open: `Survivor` (move + AUTO-ATTACK +
+   XP/level-up/upgrades + the DOM HUD), `Director` (ring-spawn around the player +
+   escalation), `EnemyDrop` (XP shard + kill on death), `EnemyFace` (sprite facing).
+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"`.
+   The knight/goblin/ghost sheets are BUILT-INS imported in `main.ts` and injected
+   into the asset url placeholders before boot. ⚠️ For `incanto/assets/*` imports to
+   resolve in `bun run dev`, `vite.config.ts` needs an `'incanto/assets'` ALIAS to
+   `../../packages/engine/assets` (see this template's config).
+6. ⬆️ COORDINATES: y-down pixels, (0,0) top-left, clockwise degrees. This is TOP-DOWN
+   so `physics.gravity` is `[0, 0]` and `CharacterController2D` would use
+   `mode: 'topDown'` (the custom `Survivor` integrates its own move instead).
+7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "rect"|"circle"|"capsule", … }`
+   on a body node — never child shape nodes. Wrong shapes hard-fail at load.
+8. 🧩 ONE SCRIPT PER NODE: a node has exactly one `script`. So the player's `Health`
+   lives on a child `Vitals` node (the player node's script is `Survivor`);
+   `DamageOnContact` still finds it by searching the contacted body's DESCENDANTS.
+   Likewise each enemy's `EnemyDrop`/`EnemyFace` sit on child nodes that read the
+   parent (whose script is `Health`/that `Chase` moves).
+9. 🌀 SPAWN A HORDE WITHOUT A CLONE API: the engine's clone path (`SpawnSource`) is
+   internal, so spawn with the built-in `Spawner` (it clones a hidden `visible:false`
+   template child + emits `spawned(clone)`), and let a custom `Director` LISTEN to
+   `spawned` and reposition each clone onto a ring around the player. Keep spawners at
+   the ORIGIN so a clone's local position equals world (clones attach under the spawner).
+10. ⏸ PAUSE WITH `engine.stop()` / `engine.start()`: the level-up overlay freezes the
+    whole world via `this.engine.stop()` and resumes on pick with `start()`. Guard DOM
+    use with a `hasDom` check so the headless `verify` (which drives `engine.step()`,
+    not the loop) auto-applies an upgrade instead.
+11. 🧮 MANY ENTITIES = AABB IN ONE OWNER: bolts + XP shards are spawned `ColorRect2D`s
+    MANAGED by `Survivor` (moved each frame, AABB-tested vs the `enemy`/`xp` groups) —
+    scene `connections` are NOT cloned, so per-clone wiring won't work; group + AABB does.
+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 `fixedUpdate`.
+13. ✅ VERIFY LIKE A USER: `bun run check` (scene valid) → `bun run verify` (headless
+    move/auto-attack/XP-drop/level/win/lose proof) → `bun run dev`, open the browser,
+    and actually PLAY (kite the horde, watch the auto-attack, vacuum XP, take a
+    level-up) before declaring it done.
+</userRequest>