incanto 0.12.0 → 0.13.0

package/templates-app/tps-3d/src/main.ts

@@ -0,0 +1,64 @@
+/**
+ * Vanguard — a 3D THIRD-PERSON shooter built on Incanto. Move with WASD, look
+ * with the mouse (click locks the pointer), Shift to sprint, Space to jump,
+ * left-click / F to fire your hitscan rifle, R to reload. The camera rides over
+ * your soldier's shoulder (CharacterController3D `view: 'free'`); the crosshair
+ * is where you shoot. Clear three waves of chasing enemies to SECURE THE AREA;
+ * let them drain your HP to 0 and the MISSION FAILS.
+ *
+ * The whole loop is composed from built-in gameplay behaviors wired in
+ * `game.scene.json` (third-person movement+camera, enemy AI via Chase, contact
+ * damage, WaveSpawner, Health, ScoreKeeper). The only custom TypeScript is
+ * `Shoot` (the click-to-fire hitscan + face-aim) and `HudUpdater` (the HUD +
+ * win/lose banner).
+ */
+import { assetUrls, preloadUrls } from 'incanto';
+import { createGame3D } from 'incanto/3d';
+// A bundled clip looped as low ambience (no large music files ship in the
+// package — see incanto-audio.md). vite resolves + hashes the real file.
+import musicUrl from 'incanto/assets/audio/spells_cast.mp3';
+import { HudUpdater, Shoot } from './behaviors';
+import sceneJson from './game.scene.json';
+
+// The soldier is a real GLB character (base-model.glb) animated by mixamo clips
+// (idle/walk/run/jump) — declared in the scene `assets`. Warm the HTTP cache with
+// a progress bar before booting; the arena, enemies, SFX + music stay zero-fetch.
+const fill = document.querySelector('#progress') as HTMLElement | null;
+const text = document.querySelector('#progress-text') as HTMLElement | null;
+await preloadUrls(assetUrls(sceneJson.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;
+// createGame3D boots everything: register (gameplay behaviors auto-registered) →
+// load → physics (auto; the scene has bodies) → keyboard + pointer-lock look →
+// renderer → start. We pass the two custom behaviors.
+const game = await createGame3D({
+  debug: import.meta.env.VITE_INCANTO_DEBUG === '1',
+  canvas,
+  scene: sceneJson,
+  behaviors: { Shoot, HudUpdater },
+  pointer: true, // pointer-lock mouse look (lockOnClick) — drives the free-view yaw/pitch
+});
+
+document.querySelector('#loading')?.remove();
+
+// Looping background music on the music bus (a calm tense pad). The engine
+// auto-resumes a gesture-blocked track on the first click/keypress.
+game.engine.music.play(musicUrl, { loop: true, fadeIn: 1.5 });
+game.engine.audio.music = 0.3;
+
+// On-screen FIRE / JUMP buttons (mobile + desktop parity).
+for (const [id, code] of [
+  ['btn-fire', 'KeyF'],
+  ['btn-jump', 'Space'],
+] as const) {
+  const el = document.querySelector(`#${id}`);
+  el?.addEventListener('pointerdown', () => game.engine.input.handleKey(code, true));
+  el?.addEventListener('pointerup', () => game.engine.input.handleKey(code, false));
+}
+
+// Console playground for vibe-coding: game.scene.root.getNode('Player') …
+Object.assign(window, { game });

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

@@ -0,0 +1,167 @@
+/**
+ * Headless proof that Vanguard actually PLAYS — the browserless half of the
+ * agent loop (author → VERIFY → fix). Runs the real `game.scene.json` through
+ * `incanto/test`'s `runScript` at a fixed, seeded timestep and asserts the whole
+ * built-in + custom composition end to end:
+ *
+ *   MOVE: holding 'move' walks the player (CharacterController3D `view: 'free'`).
+ *   WIN : WaveSpawner drips enemies that Chase the player; an autopilot aims the
+ *         third-person camera at the nearest enemy and fires the hitscan `Shoot`
+ *         rifle — each kill frees the enemy (Health.freeOnDeath) and scores (+1).
+ *         Clearing all three waves emits Spawner.allCleared → HudUpdater
+ *         .onAllCleared → AREA SECURED.
+ *   LOSE: an enemy hitbox (DamageOnContact targetGroup 'player') drains the
+ *         player's Health to 0 → `died` → ScoreKeeper.loseLife → `lost`.
+ *
+ * Run with `bun verify.ts` (or `bun run verify`). Audio + rendering are no-ops
+ * headlessly, so this isolates the gameplay logic.
+ */
+import type { Node } from 'incanto';
+import { runScript } from 'incanto/test';
+import { HudUpdater, Shoot } from './src/behaviors';
+import sceneJson from './src/game.scene.json';
+
+const behaviors = { Shoot, HudUpdater };
+
+interface Vec {
+  position: number[];
+}
+interface Ctl {
+  yaw: number;
+  pitch: number;
+  eyeHeight: number;
+}
+
+function liveEnemies(ctx: { scene: { tree: { getNodesInGroup(g: string): Node[] } } }): Node[] {
+  return ctx.scene.tree.getNodesInGroup('enemy');
+}
+
+const ok = (label: string, cond: boolean): void => {
+  if (!cond) {
+    console.error(`FAIL: ${label}`);
+    process.exitCode = 1;
+  } else {
+    console.log(`pass: ${label}`);
+  }
+};
+
+// ---- MOVE + WIN path ----------------------------------------------------------
+{
+  let won = 0;
+  let moved = false;
+  let sawEnemy = false;
+  let chaseClosedIn = false;
+  let maxScore = 0;
+
+  const result = await runScript(sceneJson, {
+    durationMs: 60000,
+    seed: 1,
+    behaviors,
+    steps: [
+      {
+        atMs: 100,
+        label: 'subscribe to win + prove movement',
+        do: (ctx) => {
+          ctx.getNode('/root/Spawner').on('allCleared', () => won++);
+          const player = ctx.getNode('/root/Player') as unknown as Vec;
+          const x0 = player.position[0] ?? 0;
+          ctx.engine.input.setActionVector('move', 1, 0);
+          for (let i = 0; i < 30; i++) ctx.engine.step();
+          moved = Math.abs((player.position[0] ?? 0) - x0) > 0.2;
+          ctx.engine.input.setActionVector('move', 0, 0);
+          player.position = [0, 1.4, 16];
+        },
+      },
+      {
+        atMs: 2500,
+        label: 'enemies spawn, chase, and the hitscan rifle clears every wave → WIN',
+        do: (ctx) => {
+          const player = ctx.getNode('/root/Player') as unknown as Vec;
+          const ctl = ctx.getNode('/root/Player/Controller') as unknown as Ctl;
+
+          const first = liveEnemies(ctx)[0] as unknown as Vec | undefined;
+          if (first) {
+            sawEnemy = true;
+            const d0 = Math.hypot((first.position[0] ?? 0) - 0, (first.position[2] ?? 0) - 16);
+            for (let i = 0; i < 20; i++) ctx.engine.step();
+            const d1 = Math.hypot((first.position[0] ?? 0) - 0, (first.position[2] ?? 0) - 16);
+            chaseClosedIn = d1 < d0;
+          }
+
+          const shoot = ctx.getNode('/root/Player/Controller').behavior as unknown as {
+            ammo: number;
+            reloading: boolean;
+          };
+          for (let i = 0; i < 5000 && won === 0; i++) {
+            player.position = [0, 1.4, 16];
+            const enemies = liveEnemies(ctx);
+            if (enemies.length) {
+              const ex = (enemies[0] as unknown as Vec).position;
+              const dx = (ex[0] ?? 0) - 0;
+              const dy = (ex[1] ?? 0) - (1.4 + ctl.eyeHeight);
+              const dz = (ex[2] ?? 0) - 16;
+              // Invert the forward() mapping to point the camera at the target.
+              ctl.yaw = Math.atan2(-dx, -dz);
+              ctl.pitch = Math.atan2(-dy, Math.hypot(dx, dz));
+            }
+            if (shoot.ammo <= 0 && !shoot.reloading) {
+              ctx.engine.input.pressAction('reload');
+              ctx.engine.step();
+              ctx.engine.input.releaseAction('reload');
+            } else {
+              ctx.engine.input.pressAction('fire');
+              ctx.engine.step();
+              ctx.engine.input.releaseAction('fire');
+            }
+            ctx.engine.step();
+            const score = (ctx.getNode('/root').behavior as unknown as { score: number }).score;
+            if (score > maxScore) maxScore = score;
+          }
+        },
+      },
+    ],
+  });
+
+  ok('holding move walked the player', moved);
+  ok('a wave produced enemies', sawEnemy);
+  ok('an enemy closed in on the player (Chase.moveParent)', chaseClosedIn);
+  ok('hitscan kills scored points', maxScore >= 5);
+  ok('clearing all waves emitted allCleared (WIN)', won === 1);
+  ok('runScript reported no failures (WIN path)', result.ok);
+}
+
+// ---- LOSE path ----------------------------------------------------------------
+{
+  let lost = 0;
+  let damaged = 0;
+
+  const result = await runScript(sceneJson, {
+    durationMs: 8000,
+    seed: 2,
+    behaviors,
+    steps: [
+      {
+        atMs: 3000,
+        label: 'enemy contact drains the player to 0 HP → LOSE',
+        do: (ctx) => {
+          ctx.getNode('/root').on('lost', () => lost++);
+          ctx.getNode('/root/Player').on('damaged', () => damaged++);
+          const enemy = liveEnemies(ctx)[0];
+          if (!enemy) return;
+          const hitbox = enemy.findChild('Hit') as Node;
+          const player = ctx.getNode('/root/Player');
+          for (let i = 0; i < 60 && lost === 0; i++) {
+            hitbox.emit('triggerEnter', player);
+            for (let f = 0; f < 40; f++) ctx.engine.step();
+          }
+        },
+      },
+    ],
+  });
+
+  ok('player took repeated damage', damaged >= 3);
+  ok('player death emitted `lost` once (ScoreKeeper.loseLife)', lost === 1);
+  ok('runScript reported no failures (LOSE path)', result.ok);
+}
+
+console.log(process.exitCode ? '\nVERIFY FAILED' : '\nVERIFY OK — Vanguard plays end to end');

package/templates-app/tps-3d/vite.config.ts

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

package/templates-app/village-quest-3d/PROJECT/Context.md

@@ -0,0 +1,39 @@
+# Emberwood — Context
+
+A 3D quest vignette and the **0.8 feature showcase**: every headline capability
+that shipped in incanto 0.8 is load-bearing here, in one small, readable game.
+
+## What it plays like
+
+Third-person hero in a sunset village. The Elder (walk up, press **E**) runs a
+typewriter dialogue with a real choice; accepting opens the north gate. Through
+the gate (fade transition) lies a hedge-maze grove at dusk where three
+red-eyed wolves walk patrol routes. Sword-strike them (**click/F** — a glowing
+arc), watch them poof, take the portal home, report back: QUEST COMPLETE, play
+again button.
+
+## Why it exists (dogfooding map)
+
+| 0.8 feature | Where it carries weight |
+|---|---|
+| `UiDialogue` + choices | the Elder conversation IS the quest state machine |
+| `UiButton` | the play-again button |
+| `findPath` + `PathFollow` | wolf patrol rings through the hedge maze |
+| `Trail3D` | sword arc + sprint dash trail |
+| `engine.sfx.startVoice('wind')` | live ambience that rises as you run |
+| `goToScene` | village ⇄ grove, with the black fade |
+| controller `animations` map | idle/walk/run/sprint/jump — zero animation code |
+| `startRecording`/`replay` | verify.ts proves bit-identical determinism |
+| `auditScene` | both scenes assert zero semantic warnings |
+| `parseCells`+`mergeSolidRects` | ONE grid string builds hedge colliders AND routes the wolves |
+
+## Design notes
+
+- The grove maze exists exactly once, as `GROVE_GRID` in behaviors.ts. The
+  hedge bodies, the wolves' A* pathfinding and the spawn cells all read that
+  one string — change the maze by editing text.
+- Cross-scene quest state lives in `src/quest.ts` (a module singleton survives
+  `goToScene`; the node tree does not).
+- Custom code is three behaviors: VillageDirector, GroveDirector, SwordStrike.
+  Movement, camera, animation, NPC proximity, patrol walking, dialogue, HUD —
+  all engine built-ins wired in scene JSON.

package/templates-app/village-quest-3d/PROJECT/Requirements.md

@@ -0,0 +1,36 @@
+# Emberwood — Requirements
+
+## Functional
+
+1. **Quest arc**: talk → accept (choice) → gate opens → clear 3 wolves →
+   return → report → QUEST COMPLETE + play-again.
+2. **Dialogue**: typewriter lines, E or click advances, choices render as
+   buttons, choosing "Not yet" leaves the quest un-accepted.
+3. **Gate rules**: entering the gate before accepting shows a hint line and
+   does NOT change scenes.
+4. **Wolves**: walk continuous patrol loops through the maze (never through
+   hedges), face their travel direction, die to one sword strike in reach
+   (2.6 m), each death poofs + counts down the HUD.
+5. **Sword**: click/F sweeps a visible arc (Trail3D); misses are allowed.
+6. **Return portal**: active any time; quest completes only when all wolves
+   are down (quest.cleared).
+7. **Restart**: play-again resets the quest and returns to a fresh village.
+8. **Wolves fight back**: within 6 m they abandon patrol and re-path to the
+   player THROUGH the maze (never through hedges); their fangs bite for 25
+   every ~1.1 s of contact; the HP bar tracks it.
+9. **Losing**: 0 HP → "YOU FELL" banner → automatic fresh-grove respawn
+   (full HP, 3 wolves, quest progress kept).
+10. **Sword**: the blade rides the right-hand bone; a strike plays the melee
+   clip and the trail follows the real swing.
+
+## Feel
+
+- Wind ambience always present, louder + higher while sprinting.
+- Dash trail only while sprinting.
+- Village = warm sunset; grove = cold dusk, denser fog, moonlight.
+
+## Verification (must stay green)
+
+- `bun run verify` — auditScene(×2)=0 warnings, full quest E2E headless,
+  record/replay bit-identical.
+- `bun run typecheck`, `bun run check` (incanto-check on src/).

package/templates-app/village-quest-3d/PROJECT/Status.md

@@ -0,0 +1,26 @@
+# Emberwood — Status
+
+## Done (2026-07-10, round 2)
+
+- Full quest arc playable + LOSABLE: wolves hunt the player through the maze
+  (findPath re-pathing), bites drain HP (repeatEvery fangs), 0 HP → YOU FELL →
+  fresh grove respawn.
+- Sword rides the hand bone (BoneAttachment3D) and strikes play the real
+  melee-attack clip — the Trail3D arc follows the actual arm swing.
+- Elder is a GLB villager (base-model, purple tint, idle clip).
+- Headless verify green: audits, quest E2E, hunt/bite/respawn, replay
+  bit-identical. Visual pass in a real browser (screenshots reviewed).
+
+## Round 3 (2026-07-11)
+
+- Grove is a real DUSK now: low warm sun, cool ambient, `environment.post`
+  vignette + desaturation grade, moonlight fill, gentle bloom. Village gets a
+  subtle warm grade.
+- Wolves take TWO strikes: the first flinches them (knockback along the
+  strike + red hurt-flash), the second fells them.
+- (previous round) camera sphere-probe landed engine-side; hedges raised
+  above the eye line.
+
+## Known limitations / ideas
+
+- A hurt/attack clip for the wolves once one lands in the animation catalog.

package/templates-app/village-quest-3d/PROJECT/Structure.md

@@ -0,0 +1,30 @@
+# Emberwood — Structure
+
+```
+index.html               canvas + loading bar
+src/main.ts              preload GLB/anim assets → createGame3D (village)
+src/village.scene.json   sunset village: Elder (Interactable), gate Area3D,
+                         player rig (controller `animations` map, Trail3D ×2),
+                         HUD (UiText/UiBanner/UiDialogue/UiButton)
+src/grove.scene.json     dusk grove: 3 wolves (PathFollow), return portal,
+                         empty `Maze` holder (hedges are built at runtime)
+src/behaviors.ts         GROVE_GRID + VillageDirector / GroveDirector / SwordStrike
+src/quest.ts             cross-scene quest flags (module singleton)
+verify.ts                audit + headless quest E2E + replay determinism
+```
+
+## Scene relationship
+
+`main.ts` boots the **village**. `goToScene(grove)` happens in
+VillageDirector.onGateEnter; `goToScene(village)` in GroveDirector.onPortalEnter
+and the play-again button. Both scenes redeclare the same input map and player
+rig — scenes are self-contained by design (a scene JSON is the whole truth).
+
+## The one-grid trick
+
+`GROVE_GRID` (rows of `#`/`.`) is the single source for:
+1. hedge collider boxes — `parseCells` + `mergeSolidRects` (from `incanto/2d`,
+   the pure helpers are dimension-agnostic) → few merged StaticBody3D boxes;
+2. wolf routes — `gridFromRows` + `findPath` (A*, no diagonals) → PathFollow
+   waypoint rings;
+3. spawn/patrol cells in `PATROLS`.

package/templates-app/village-quest-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>

package/templates-app/village-quest-3d/index.html

@@ -0,0 +1,68 @@
+<!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%234a6b3a%22/><text x=%2250%22 y=%2268%22 font-size=%2255%22 text-anchor=%22middle%22 font-family=%22Arial%22 font-weight=%22bold%22 fill=%22%23ffd166%22>eb</text></svg>" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Emberwood — Incanto quest</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+        overflow: hidden;
+        font-family: Arial, sans-serif;
+        background: #10130d;
+      }
+      canvas {
+        display: block;
+        width: 100vw;
+        height: 100vh;
+      }
+      .loading-container {
+        position: fixed;
+        inset: 0;
+        z-index: 50;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        background: black;
+        color: white;
+      }
+      .loading-title {
+        font-size: 1.5rem;
+        font-weight: bold;
+        margin-bottom: 1rem;
+      }
+      .progress-track {
+        width: 240px;
+        height: 8px;
+        border-radius: 4px;
+        background: #2a2f26;
+        overflow: hidden;
+      }
+      #progress {
+        width: 0%;
+        height: 100%;
+        background: #ffd166;
+        transition: width 0.15s;
+      }
+      #progress-text {
+        margin-top: 8px;
+        font-size: 0.85rem;
+        color: #aaa;
+      }
+    </style>
+  </head>
+  <body>
+    <canvas></canvas>
+    <div id="loading" class="loading-container">
+      <div class="loading-title">Emberwood</div>
+      <div class="progress-track"><div id="progress"></div></div>
+      <div id="progress-text">0%</div>
+    </div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates-app/village-quest-3d/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "village-quest-3d",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "check": "incanto-check src",
+    "verify": "bun verify.ts"
+  },
+  "dependencies": {
+    "@dimforge/rapier2d-compat": "0.19.3",
+    "@dimforge/rapier3d-compat": "0.19.3",
+    "@pixiv/three-vrm": "^3.5.3",
+    "incanto": "^0.13.0",
+    "three": "^0.184.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/three": "^0.184.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  }
+}