incanto 0.11.0 → 0.13.0

package/templates-app/beacon-isle-3d/src/main.ts

@@ -0,0 +1,33 @@
+/**
+ * Beacon Isle — the incanto 3D template: a generated island (terrain, sea,
+ * groves, grass, flowers), a quest with a real NPC, shades that HUNT you
+ * across the surface via terrain navigation, melee with a bone-mounted sword,
+ * golden-hour grade + bloom, touch controls on phones — regenerate the whole
+ * world with `bun run world`, the game logic never changes.
+ */
+import { assetUrls, preloadUrls } from 'incanto';
+import { createGame3D } from 'incanto/3d';
+import { BEHAVIORS } from './behaviors';
+import gameJson from './game.scene.json';
+
+const fill = document.querySelector('#progress') as HTMLElement | null;
+const text = document.querySelector('#progress-text') as HTMLElement | null;
+await preloadUrls(assetUrls(gameJson.assets), (done, total) => {
+  const pct = total > 0 ? Math.round((done / total) * 100) : 100;
+  if (fill) fill.style.width = `${pct}%`;
+  if (text) text.textContent = `${pct}%`;
+});
+
+const canvas = document.querySelector('canvas') as HTMLCanvasElement;
+const game = await createGame3D({
+  debug: import.meta.env.VITE_INCANTO_DEBUG === '1',
+  canvas,
+  scene: gameJson,
+  behaviors: BEHAVIORS,
+  pointer: true,
+});
+
+document.querySelector('#loading')?.remove();
+
+// console-poking handle for playtesting
+(window as unknown as { game: typeof game }).game = game;

package/templates-app/beacon-isle-3d/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/beacon-isle-3d/verify.ts

@@ -0,0 +1,285 @@
+/**
+ * Beacon Isle plays headlessly: audit → full quest E2E (talk → accept → clear
+ * shades → relight 3 wards → report → win) → shades hunt on the terrain nav →
+ * death respawns with quest progress kept → record/replay bit-identical.
+ * Run with `bun verify.ts`.
+ */
+import type { UiDialogue, UiText } from 'incanto';
+import { Engine, loadScene, registerBehavior, replay, startRecording } from 'incanto';
+import { enablePhysics3D } from 'incanto/3d';
+import { auditScene, registerAllNodes, runScript } from 'incanto/test';
+import { BEHAVIORS, quest, resetQuest } from './src/behaviors';
+import gameJson from './src/game.scene.json';
+
+interface Vec {
+  position: number[];
+}
+
+const ok = (label: string, cond: boolean): void => {
+  if (!cond) {
+    console.error(`FAIL: ${label}`);
+    process.exitCode = 1;
+  } else {
+    console.log(`pass: ${label}`);
+  }
+};
+
+// ---- AUDIT -------------------------------------------------------------------------
+{
+  registerAllNodes();
+  for (const [name, ctor] of Object.entries(BEHAVIORS)) {
+    registerBehavior(name, ctor, { replace: true });
+  }
+  const warnings = auditScene(gameJson 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}`);
+}
+
+// ---- QUEST E2E ---------------------------------------------------------------------
+{
+  resetQuest();
+  const keeper = { x: 0, z: 0 };
+
+  const result = await runScript(gameJson, {
+    durationMs: 90000,
+    seed: 11,
+    behaviors: BEHAVIORS,
+    steps: [
+      {
+        atMs: 200,
+        label: 'talk to the keeper, accept the quest',
+        do: (ctx) => {
+          const k = ctx.getNode('/root/Keeper') as unknown as Vec;
+          keeper.x = k.position[0] ?? 0;
+          keeper.z = k.position[2] ?? 0;
+          const player = ctx.getNode('/root/Player') as unknown as Vec;
+          player.position = [keeper.x + 1.5, (k.position[1] ?? 0) + 1.2, keeper.z + 1.5];
+          for (let i = 0; i < 5; i++) ctx.engine.step();
+          ctx.engine.input.pressAction('interact');
+          ctx.engine.step();
+          ctx.engine.input.releaseAction('interact');
+          const talk = ctx.getNode('/root/HUD/Dialogue') as UiDialogue;
+          if (!talk.active) throw new Error('dialogue did not open');
+          for (let i = 0; i < 200; i++) ctx.engine.step();
+          talk.advance();
+          for (let i = 0; i < 260; i++) ctx.engine.step();
+          talk.choose(0);
+          ctx.engine.step();
+          if (!quest.accepted) throw new Error('quest not accepted');
+          // the E2E teleports through shade packs — don't die mid-script
+          (ctx.getNode('/root/Player').behavior as unknown as { current: number }).current = 99999;
+        },
+      },
+      {
+        atMs: 5000,
+        label: 'shades hunt the player across the terrain nav',
+        do: (ctx) => {
+          const shade = ctx.getNode('/root/Shade1_1') as unknown as Vec;
+          const player = ctx.getNode('/root/Player') as unknown as Vec;
+          // stand 6m from the shade (inside aggro)
+          player.position = [
+            (shade.position[0] ?? 0) + 6,
+            (shade.position[1] ?? 0) + 0.4,
+            shade.position[2] ?? 0,
+          ];
+          const gap = () =>
+            Math.hypot(
+              (shade.position[0] ?? 0) - (player.position[0] ?? 0),
+              (shade.position[2] ?? 0) - (player.position[2] ?? 0),
+            );
+          let reached = false;
+          for (let i = 0; i < 700 && !reached; i++) {
+            player.position = [
+              player.position[0] ?? 0,
+              player.position[1] ?? 0,
+              player.position[2] ?? 0,
+            ];
+            ctx.engine.step();
+            reached = gap() < 1.6;
+          }
+          if (!reached) throw new Error(`shade never closed in (gap ${gap().toFixed(1)})`);
+        },
+      },
+      {
+        atMs: 12000,
+        label: 'clear the guards and relight all three wards',
+        do: (ctx) => {
+          const engine = ctx.engine;
+          const live = () => {
+            const root = engine.scene?.tree.root;
+            if (!root) throw new Error('no scene');
+            return root;
+          };
+          for (let w = 1; w <= 3; w++) {
+            const ward = live().getNode(`Ward${w}`) as unknown as Vec;
+            // kill this ward's guards (one strike each)
+            for (let round = 0; round < 4; round++) {
+              const guards = engine.scene?.tree.getNodesInGroup(`shade-ward${w}`) ?? [];
+              const target = guards[0] as unknown as Vec | undefined;
+              if (!target) break;
+              const player = live().getNode('Player') as unknown as Vec;
+              player.position = [
+                (target.position[0] ?? 0) + 0.9,
+                (target.position[1] ?? 0) + 0.3,
+                (target.position[2] ?? 0) + 0.9,
+              ];
+              engine.step();
+              engine.input.pressAction('attack');
+              engine.step();
+              engine.input.releaseAction('attack');
+              for (let i = 0; i < 42; i++) engine.step();
+            }
+            const left = engine.scene?.tree.getNodesInGroup(`shade-ward${w}`).length ?? -1;
+            if (left !== 0) throw new Error(`ward ${w}: ${left} shades survived`);
+            // stand at the ward and relight
+            const player = live().getNode('Player') as unknown as Vec;
+            player.position = [
+              (ward.position[0] ?? 0) + 1,
+              (ward.position[1] ?? 0) + 1,
+              ward.position[2] ?? 0,
+            ];
+            for (let i = 0; i < 4; i++) engine.step();
+            engine.input.pressAction('interact');
+            engine.step();
+            engine.input.releaseAction('interact');
+            for (let i = 0; i < 5; i++) engine.step();
+            if (!quest.lit.has(w)) throw new Error(`ward ${w} did not light`);
+          }
+          if (quest.lit.size !== 3) throw new Error('not all wards lit');
+          if (!quest.bossRisen) throw new Error('the Shadeheart never rose');
+        },
+      },
+      {
+        atMs: 25000,
+        label: 'five strikes fell the Shadeheart',
+        do: (ctx) => {
+          const engine = ctx.engine;
+          const root = engine.scene?.tree.root;
+          if (!root) throw new Error('no scene');
+          for (let i = 0; i < 60; i++) engine.step(); // boss wakes + starts hunting
+          const player = root.getNode('Player') as unknown as Vec;
+          for (let round = 0; round < 7 && !quest.bossDown; round++) {
+            const boss = engine.scene?.tree.getNodesInGroup('boss')[0] as unknown as
+              | Vec
+              | undefined;
+            if (!boss) break;
+            player.position = [
+              (boss.position[0] ?? 0) + 1.2,
+              (boss.position[1] ?? 0) + 0.3,
+              (boss.position[2] ?? 0) + 1.2,
+            ];
+            engine.step();
+            engine.input.pressAction('attack');
+            engine.step();
+            engine.input.releaseAction('attack');
+            for (let i = 0; i < 42; i++) engine.step();
+          }
+          if (!quest.bossDown) throw new Error('the Shadeheart survived 7 rounds');
+          if ((engine.scene?.tree.getNodesInGroup('boss').length ?? -1) !== 0)
+            throw new Error('boss node not freed');
+        },
+      },
+      {
+        atMs: 30000,
+        label: 'report back — quest complete + win banner',
+        do: (ctx) => {
+          const engine = ctx.engine;
+          const root = engine.scene?.tree.root;
+          if (!root) throw new Error('no scene');
+          const player = root.getNode('Player') as unknown as Vec;
+          const k = root.getNode('Keeper') as unknown as Vec;
+          player.position = [
+            (k.position[0] ?? 0) + 1.5,
+            (k.position[1] ?? 0) + 1.2,
+            (k.position[2] ?? 0) + 1.5,
+          ];
+          for (let i = 0; i < 5; i++) engine.step();
+          engine.input.pressAction('interact');
+          engine.step();
+          engine.input.releaseAction('interact');
+          const talk = root.getNode('HUD/Dialogue') as UiDialogue;
+          for (let i = 0; i < 400; i++) engine.step();
+          talk.advance();
+          for (let i = 0; i < 500; i++) engine.step();
+          talk.advance();
+          for (let i = 0; i < 80; i++) engine.step(); // dialogueFinished + fireworks timer
+          if (!quest.done) throw new Error('quest never completed');
+          const line = (root.getNode('HUD/Quest') as UiText).text;
+          if (!line.includes('safe')) throw new Error(`quest line: ${line}`);
+        },
+      },
+    ],
+  });
+  ok('QUEST: full loop (keeper → hunt → 3 wards → win)', result.ok);
+  for (const f of result.failures) console.error(`  ${f.label}: ${f.message}`);
+}
+
+// ---- DEATH keeps progress ------------------------------------------------------------
+{
+  resetQuest();
+  quest.accepted = true;
+  quest.lit.add(1); // pretend ward 1 was lit before dying
+  const result = await runScript(gameJson, {
+    durationMs: 60000,
+    seed: 5,
+    behaviors: BEHAVIORS,
+    steps: [
+      {
+        atMs: 300,
+        label: 'death → respawn keeps lit wards',
+        do: (ctx) => {
+          const engine = ctx.engine;
+          const health = () =>
+            engine.scene?.tree.root?.getNode('Player')?.behavior as unknown as { current: number };
+          for (let i = 0; i < 4000 && (health()?.current ?? 0) > 0; i++) {
+            const shades = engine.scene?.tree.getNodesInGroup('shade') ?? [];
+            const s = shades[0] as unknown as Vec | undefined;
+            if (!s) throw new Error('no shades');
+            const p = engine.scene?.tree.root?.getNode('Player') as unknown as Vec;
+            p.position = [s.position[0] ?? 0, (s.position[1] ?? 0) + 0.1, s.position[2] ?? 0];
+            engine.step();
+          }
+          if ((health()?.current ?? 1) > 0) throw new Error('shades never killed the player');
+          for (let i = 0; i < 130; i++) engine.step(); // respawn countdown
+          if ((health()?.current ?? 0) < 100) throw new Error('respawn did not reset HP');
+          if (!quest.lit.has(1)) throw new Error('respawn lost the lit ward');
+          const shadeCount = engine.scene?.tree.getNodesInGroup('shade').length ?? 0;
+          if (shadeCount !== 6) throw new Error(`respawn spawned ${shadeCount} shades`);
+        },
+      },
+    ],
+  });
+  ok('DEATH: respawn keeps quest progress', result.ok);
+  for (const f of result.failures) console.error(`  ${f.label}: ${f.message}`);
+}
+
+// ---- REPLAY determinism --------------------------------------------------------------
+{
+  resetQuest();
+  const boot = async (): Promise<Engine> => {
+    const engine = new Engine({ seed: 42, scheduler: () => () => {} });
+    engine.setScene(loadScene(structuredClone(gameJson) as Parameters<typeof loadScene>[0]));
+    await enablePhysics3D(engine);
+    return engine;
+  };
+  const a = await boot();
+  const rec = startRecording(a);
+  for (let frame = 0; frame <= 240; frame++) {
+    if (frame === 20) a.input.handleKey('KeyW', true);
+    if (frame === 140) a.input.handleKey('KeyA', true);
+    if (frame === 200) a.input.handleKey('KeyW', false);
+    a.tick(frame * (1000 / 60));
+  }
+  const recording = rec.stop();
+  const posA = (a.scene?.tree.root?.getNode('Player') as unknown as Vec).position;
+  resetQuest();
+  const b = await boot();
+  replay(b, recording);
+  const posB = (b.scene?.tree.root?.getNode('Player') as unknown as Vec).position;
+  ok(
+    `REPLAY: bit-identical after 240 replayed frames (${posA.map((v) => v.toFixed(3)).join(', ')})`,
+    posA.length === 3 && posA.every((v, i) => v === posB[i]),
+  );
+}
+
+console.log(process.exitCode ? '\nVERIFY FAILED' : '\nVERIFY OK');

package/templates-app/beacon-isle-3d/vite.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  base: './',
+});

package/templates-app/tps-3d/PROJECT/Context.md

@@ -0,0 +1,49 @@
+# Context — tps-3d (Incanto)
+
+## Project Overview
+
+"Vanguard" — a 3D THIRD-PERSON shooter. The camera rides over your soldier's
+shoulder (you SEE your character); the crosshair is where the hitscan rifle
+fires. Move with WASD, look with the mouse (click locks the pointer), Shift to
+sprint, Space to jump, click / F to fire, R to reload. Survive and clear three
+escalating waves of chasing enemies to **SECURE THE AREA**; let them drain your
+HP to 0 and the **MISSION FAILS**.
+
+The entire loop is composed from `incanto/gameplay` built-ins wired in
+`src/game.scene.json` — the same gameplay spine as the `fps-3d` example, but with
+`CharacterController3D`'s `view: 'free'` third-person rig and a VISIBLE character.
+The only custom TypeScript is `Shoot` (hitscan + face-aim) and `HudUpdater`.
+
+## Tech Stack
+
+_Exact versions are in `package.json`._
+
+- **Game engine**: `incanto` + `incanto/3d` (CharacterController3D free-view rig,
+  MeshInstance3D, Terrain/Tree3D, environment sky/fog/shadows, spatial audio) +
+  `incanto/gameplay` (Health, Chase, WaveSpawner, DamageOnContact, ScoreKeeper).
+- **Build / Lang**: Vite, TypeScript. No React — a single canvas + HTML HUD.
+
+## Critical Memory
+
+- READ THE SKILLS FIRST: `node_modules/incanto/skills/incanto-3d-character.md`
+  (the controller + camera rigs), `incanto-building-3d-games.md`,
+  `incanto-gameplay-behaviors.md`, `incanto-environment.md`, `incanto-audio.md`.
+- **THIRD-PERSON = `view: 'free'`.** The controller OWNS the scene's current
+  Camera3D and orbits it behind+above the player (`camDistance` 4.2, `eyeHeight`
+  1.1), looking at the pivot. Do NOT add a FollowCamera — it would fight the rig.
+- **The character is a real GLB model.** The `Player/Skin` is a `ModelInstance3D`
+  (`base-model.glb` + mixamo idle/walk/run/jump clips, declared in scene `assets`).
+  The controller mounts it at 180° and yaw-rotates it toward the MOVE direction;
+  `Shoot.onReady` maps `movementStateChanged` → the matching clip, and
+  `Shoot.faceAim()` snaps the model to the AIM direction on each shot so the
+  soldier turns to shoot where you look. (No held-weapon bone attachment yet — the
+  shot reads via the crosshair + tracer + muzzle flash.)
+- Aim is the CAMERA look direction: `Shoot` reads `controller.yaw/pitch`, computes
+  a forward vector, and hitscans the nearest enemy in the crosshair cone. The
+  shot originates at the player + `eyeHeight` (chest).
+- ONE owner of authority per concern: enemies are spawned clones — `Health` has
+  `freeOnDeath: true` (scene `connections` are NOT cloned, so death cleanup must
+  be node-local). Friendly fire is gated by `DamageOnContact.targetGroup`.
+- The HUD + crosshair + banner are plain DOM (`index.html`); `HudUpdater` writes
+  the numbers (guarded so headless runs are a no-op).
+- `window.game` is exposed for console poking.

package/templates-app/tps-3d/PROJECT/Requirements.md

@@ -0,0 +1,38 @@
+# Requirements — tps-3d (Incanto)
+
+## Coding Patterns
+
+- Game STRUCTURE belongs in `src/game.scene.json` (nodes, props, input map,
+  environment, the player + enemy template, waves). Add nodes there or with
+  `npx incanto-editor`, NOT ad-hoc in code.
+- Game LOGIC: reach for a BUILT-IN gameplay behavior first (Health, Chase,
+  WaveSpawner, DamageOnContact, ScoreKeeper). This game's ONLY custom behaviors
+  are `Shoot` (the click-to-fire hitscan + face-aim, which no built-in can be —
+  it reads the camera angle and the mouse) and `HudUpdater` (DOM presentation).
+- THIRD-PERSON camera is declarative: `CharacterController3D` `view: 'free'` +
+  `camDistance`/`eyeHeight`. The controller drives the scene's `current` Camera3D
+  — never also attach a FollowCamera to that camera.
+- The VISIBLE character is a `ModelInstance3D` named `Skin`, sibling of the
+  Controller (the controller rotates `../Skin`). It loads a GLB (`$characters/base`)
+  sized by `targetHeight` and animated by mixamo `$anims/*` clips (declared in
+  scene `assets`, fetched from the CDN; mixamo retargets onto the model
+  automatically). `Shoot.onReady` drives the clip from `movementStateChanged`.
+- Enemies are a hidden `EnemyTemplate` the `WaveSpawner` clones: `Health`
+  (`freeOnDeath: true`) on the root, `Chase` (`moveParent: true`) on a child,
+  `DamageOnContact` (`targetGroup: 'player'`) on an Area3D hitbox.
+- Generate every node uid with the engine's `newUid()` (or let the editor assign
+  them) — NEVER hand-write readable uid strings.
+
+## Known Issues / Constraints
+
+- Movement-facing vs aim-facing: the controller turns the soldier toward the MOVE
+  direction; `Shoot.faceAim()` overrides that toward the AIM on each shot, so the
+  character reads as "aim while standing, run-face while moving". A full
+  strafe-aim rig (always face the camera) would be a custom controller tweak.
+- Mouse look needs POINTER LOCK (click the canvas). A free cursor never spins the
+  camera (deltas only accumulate while locked or a button is held).
+- HUD is DOM, not nodes: 3D scenes have no 2D `UILayer`/`Label`. The crosshair,
+  HUD and banner live in `index.html`; `HudUpdater` fills them (guarded for
+  headless). The crosshair marks the camera aim point, not the gun barrel.
+- Zero-asset: arena, soldier and enemies are primitives; SFX are procedural
+  presets; the music is a bundled clip. Nothing is fetched at boot.

package/templates-app/tps-3d/PROJECT/Status.md

@@ -0,0 +1,41 @@
+# Status — tps-3d (Incanto)
+
+## Implemented
+
+- `src/game.scene.json`: third-person arena — atmosphere sky/fog/shadows, a
+  48×48 walled floor with cover blocks + pillars + a ramp + a conifer `Grove`,
+  sun + fill light.
+  - **Player** (RigidBody3D, group `player`, `Health` max 100 / 0.6s i-frames):
+    `Controller` (CharacterController3D `view: 'free'`, camDistance 4.2, eyeHeight
+    1.1, maxSpeed 4.2, `Shoot` script); a real GLB `Skin` (ModelInstance3D
+    `base-model.glb` + mixamo idle/walk/run/jump clips); a `Muzzle` Node3D
+    (shot/kill/empty SFX + flash light).
+  - **Spawner** (WaveSpawner, 3 waves of 4/6/8) cloning a hidden `EnemyTemplate`
+    (CharacterBody3D, group `enemy`, `Health` 30 freeOnDeath, red capsule + glow
+    eye, `Chase` moveParent AI, `DamageOnContact` hitbox, spatial growl).
+  - Camera3D (current), HurtSfx, `Hud` (HudUpdater). Connections: Player.died →
+    `/root.loseLife`, Player.damaged → HurtSfx, Spawner.allCleared → Hud.
+- `src/behaviors.ts`: `Shoot` (18-round clip, hitscan within a ~9° crosshair cone
+  to 70 m, tracer + muzzle flash, face-aim on fire, reload) and `HudUpdater`
+  (HP/Kills/Wave/Ammo + health bar + SECURE/FAILED banner).
+- `src/main.ts`: preloads the GLB + animation assets with a progress bar
+  (`preloadUrls(assetUrls(scene.assets))`), then `createGame3D` with
+  `pointer: true`, looping music, on-screen FIRE/JUMP buttons, `window.game`.
+- `index.html`: canvas + center crosshair + HUD overlay + banner + mobile buttons.
+
+## Works (verified)
+
+- `bun run check` — scene valid. `bun run verify` — 9/9 headless checks (move,
+  waves spawn, Chase closes in, hitscan scores, all-clear WIN, contact-damage LOSE).
+- **Verified by playing in the browser (Playwright)**: over-the-shoulder camera
+  frames the soldier (back to camera, `skinRotationY` 180); enemies spawn + chase
+  + reach the player; holding fire cleared a wave (Kills 0→4) with visible tracers;
+  HP drained to 0 under a swarm → "MISSION FAILED" banner. HUD updates live.
+
+## Not Included (on purpose)
+
+- No held-weapon bone attachment (the model has no rifle in-hand — the shot reads
+  via crosshair + tracer + muzzle flash); no dedicated shoot/reload/aim clips
+  (the CDN set is idle/walk/run/jump).
+- No cover/peek mechanic, no projectile-drop weapons (hitscan only). Co-op
+  multiplayer lives in the sibling `examples/tps-3d-multiplay`.

package/templates-app/tps-3d/PROJECT/Structure.md

@@ -0,0 +1,44 @@
+# Structure — tps-3d (Incanto)
+
+## `index.html`
+
+Full-window canvas + the DOM overlays a 3D scene can't host as nodes: the center
+crosshair (camera aim point), the HUD (wave / HP + bar / kills / ammo), the
+win-lose banner, on-screen FIRE/JUMP buttons, the loading overlay, and the
+iframe-embed GAME_SIZE harness.
+
+## `src/game.scene.json`
+
+THE game. Header: atmosphere `environment` (sky/fog/shadows/exposure/ambient),
+physics gravity, and the input map (move/jump/sprint/fire/reload). Tree:
+- `Arena` — walled floor, cover blocks, pillars, a ramp, sun + fill light, a
+  conifer `Grove` (Tree3D).
+- `Player` (RigidBody3D, `Health`) → `Controller` (CharacterController3D
+  `view: 'free'` + `Shoot`), the visible `Skin` soldier (primitive parts), and a
+  `Muzzle` (SFX + flash).
+- `Camera` (Camera3D, current — driven by the controller each frame).
+- `Spawner` (WaveSpawner) → hidden `EnemyTemplate` (Health/Chase/DamageOnContact/
+  growl + red skin).
+- `Hud` (HudUpdater). Plus top-level `connections` for death/damage/all-clear.
+Open it with `npx incanto-editor`.
+
+## `src/behaviors.ts`
+
+The only custom code. `Shoot` — hitscan rifle on the CharacterController3D: reads
+its yaw/pitch for aim, raycasts the nearest enemy in the crosshair cone, applies
+`Health.damage`, scores kills via ScoreKeeper, spawns a tracer + muzzle flash,
+owns the ammo clip/reload, and `faceAim()`s the soldier to the shot direction.
+`HudUpdater` — reads ScoreKeeper/Health/Shoot/wave each frame into the HTML HUD
+and flips the banner (guarded so headless runs are a no-op).
+
+## `src/main.ts`
+
+Boot: `createGame3D({ scene, behaviors: { Shoot, HudUpdater }, pointer: true })`,
+loop the bundled music, wire the on-screen buttons, expose `window.game`.
+
+## `verify.ts`
+
+Headless proof (`bun run verify`) that the loop plays end to end — move, waves,
+Chase closing in, the autopilot aiming + firing the hitscan to clear all waves
+(WIN), and an enemy hitbox draining the player to 0 (LOSE) — via `incanto/test`'s
+`runScript` at a seeded fixed timestep.

package/templates-app/tps-3d/docs/project-3d-rules.md

@@ -0,0 +1,38 @@
+<userRequest>
+YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
+
+1. 📖 READ THE SKILLS FIRST: `node_modules/incanto/skills/` is the engine
+   manual, version-pinned to what is installed. Start with
+   `incanto-building-3d-games.md`, `incanto-3d-character.md`,
+   `incanto-gameplay-behaviors.md`, `incanto-environment.md` and
+   `incanto-audio.md` — this template composes all five.
+2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
+   replication all live in `src/game.scene.json`. Add nodes there (or with
+   `npx incanto-editor`), NOT by constructing them ad-hoc in code.
+3. 🧠 LOGIC IS BEHAVIORS: gameplay code = small TypeScript Behavior classes,
+   registered with `registerBehavior('Name', Class)` and attached in JSON via
+   `"script": { "name": "Name" }`. Reach for a BUILT-IN gameplay behavior
+   (Health, Chase, WaveSpawner, DamageOnContact, ScoreKeeper…) before writing
+   your own — this game's only custom behaviors are `Shoot` and `HudUpdater`.
+4. 🔑 UIDS ARE GENERATED: every node uid comes from
+   `import { newUid } from 'incanto'`. NEVER invent readable uid strings.
+5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference
+   them as `"$key"`. Free extra key-values are preserved — use them to leave
+   notes for yourself (license, palette, source prompt).
+6. ⬆️ Y IS UP: 3D space is y-UP meters, +Z is "south", rotations are degrees
+   (Euler XYZ). Negative gravity falls.
+7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "box"|"sphere"|"capsule", … }`
+   on a body node — never child shape nodes. Wrong shapes hard-fail at load.
+8. 🖥️ THE HUD IS DOM, NOT NODES: 3D scenes have no 2D `UILayer`/`Label` nodes
+   (those are `incanto/2d`). The HUD + crosshair + banner are plain HTML in
+   `index.html`; `HudUpdater` writes the live numbers into them (guarded so
+   headless runs are a no-op).
+9. 🐛 DEBUG WHEN UNSURE: `physics.debugDraw = true` (the object
+   `enablePhysics3D` returns) draws every collider in the running game; or boot
+   with `?incanto_debug=1` for the live Explorer/Inspector/Stats overlay.
+10. 🎬 DELTA DISCIPLINE: only write props that differ from defaults — the
+    loader treats unknown/garbage props as hard errors, which is your friend.
+11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
+    proves the loop headlessly, then `bun run dev` and actually PLAY what you
+    changed (move, shoot, clear a wave) before declaring it done.
+</userRequest>