incanto 0.1.0

package/skills/incanto-verifying-your-game.md

@@ -0,0 +1,191 @@
+---
+name: incanto-verifying-your-game
+description: Verify an Incanto game WITHOUT a browser — headless scene validation (incanto-check), scripted gameplay runs with assertions (runScript), scene-state captures as text screenshots, and engine logs. Use after every scene/behavior edit, and whenever you need to prove a gameplay change actually works.
+---
+
+# Verifying your game (browserless)
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+You usually cannot SEE the game (no browser in most agent environments). The
+scene state itself is your screenshot. The loop is: **edit → check → scripted
+run → read the capture → fix**. Never hand a game back without steps 2–3.
+
+## 1. After EVERY scene edit: `incanto-check`
+
+```bash
+bunx incanto-check               # validates every *.scene.json under cwd
+bunx incanto-check --json        # machine-readable (code + details.path/prop)
+```
+
+Runs every hard load-time check (unknown types/props, bad colliders, dangling
+connections, undeclared signals, duplicate uids…) and names the offending node
+path. Unregistered behaviors are stubbed — no TypeScript needed.
+(`--strict-behaviors` fails on behavior names the ENGINE doesn't know;
+incanto-check can't load your TS, so with custom behaviors skip the flag and
+get code-aware validation from `incanto-play --behaviors` / `runScript`
+instead.) Wire incanto-check as a `"check"` script in package.json and run
+it before declaring anything done.
+
+## 2. Play it from bash (incanto-play)
+
+The interactive headless loop — inputs in, the screen out AS SCENE JSON:
+
+```bash
+bunx incanto-play src/game.scene.json --behaviors src/behaviors.ts <<'EOF'
+vector move 1 0
+step 1000
+press jump
+step 500
+capture
+logs
+quit
+EOF
+```
+
+Every response is one JSON line. `capture` returns the CURRENT state in the
+exact *.scene.json format (positions, text, everything non-default) — read
+it like a screenshot; `capture snap.json` writes it to disk for diffing.
+Other commands: `release <action>`, `key KeyW down|up`, `mouse 0 down|up`,
+`pointer <dx> <dy>`, `wheel <dy>`, `describe` (one line per node), `logs`
+(your `this.log` output), `--commands file` to replay a script. Without
+`--behaviors` scripts are stubbed (structure-only play); `--behaviors`
+accepts your .ts directly. `--seed` makes runs reproducible. `--behaviors` registers every EXPORTED
+`Behavior` subclass under its export name.
+
+Script steps' `do:`/`assert:` callbacks receive the full RunContext —
+`{ engine, scene, timeMs, getNode, capture }` — so closed-loop autopilots
+work inside runScript: `do: (ctx) => ctx.engine.input.setActionVector('move',
+chase(ctx), 0)`.
+
+**Reaching nodes & state from a step (the gotchas a sim hit):**
+- `ctx.getNode(path)` and `ctx.scene.root.getNode(path)` resolve from the ROOT.
+  When the root node IS named `Game`, the root is `ctx.scene.root` (or
+  `ctx.getNode('.')`) — `ctx.getNode('Game')` looks for a CHILD named `Game` and
+  throws. Reach a child as `ctx.getNode('Player')`, a grandchild as
+  `ctx.getNode('Player/Weapon')`.
+- **Behavior state lives on `node.behavior`.** Read a Health's HP via
+  `ctx.getNode('Player').behavior.current`; a ScoreKeeper's score via
+  `ctx.scene.root.behavior.score`. The behavior's own methods (`addScore`,
+  `damage`) are on `node.behavior` too.
+- **Signals are events to CONNECT, not fields to read.** `allCleared`, `won`,
+  `died` are emitted — listen with `ctx.scene.root.on('won', …)` inside a `do:`
+  step (or assert the resulting STATE, e.g. `behavior.score`). There is no
+  `behavior.allCleared` boolean.
+
+Rapier may print a deprecated-parameters warning on stderr when physics
+initializes headlessly — library-internal noise, safe to ignore.
+
+Headless gotchas: `engine.start()` needs requestAnimationFrame (a browser) —
+headless code always advances time with `engine.step()` (one fixed tick;
+default 60/s, so 60 steps ≈ 1s). A `vector2` input action must declare ALL
+FOUR direction arrays — use `[]` for directions you don't bind.
+
+## 3. Prove gameplay with a scripted run (runScript)
+
+`incanto/test` plays the game headlessly at a fixed timestep, driving input by
+ACTION intent (the same actions your scene's `input{}` declares):
+
+```ts
+import { runScript } from 'incanto/test';
+import { PlayerControl } from './src/behaviors';
+import sceneJson from './src/game.scene.json';
+
+const result = await runScript(sceneJson, {
+  behaviors: { PlayerControl },        // real classes — props validate too
+  durationMs: 3000,
+  seed: 42,                            // same seed → identical run
+  steps: [
+    { atMs: 0,    vector: ['move', 1, 0] },          // hold right
+    { atMs: 1000, press: 'jump' },
+    { atMs: 1100, release: 'jump' },
+    { atMs: 1500, label: 'jump apex reached',
+      assert: (ctx) => (ctx.getNode('Player') as never as { position: number[] }).position[1]! < 300 },
+  ],
+  snapshotEveryMs: 500,
+});
+console.log(result.describe());        // run report + final scene, one line per node
+if (!result.ok) process.exit(1);       // failures carry atMs + label + message
+```
+
+Run it with `bunx tsx verify.ts` (or inside a vitest test). Physics enables
+automatically from the scene's `dimension`. `result.snapshots` holds periodic
+captures; `result.logs` holds everything behaviors logged via `this.log`.
+Steps that never execute (atMs beyond the run) are reported as failures —
+an assert cannot "pass" by not running.
+
+Note: `validateScene`/`runScript` register node types and your `behaviors`
+into the process-global registries (hot-replacing same names). In a test
+suite, isolate with `clearRegistry()`/`clearBehaviors()` between files if
+you register conflicting classes.
+
+## 4. Read the scene like a screenshot
+
+```ts
+import { captureScene, describeCapture } from 'incanto/test';
+// `scene` is a loaded Scene (e.g. `ctx.scene` in a step, or `result.finalCapture`
+// for the end state — runScript also returns `result.snapshots`).
+console.log(describeCapture(captureScene(scene)));
+// scene MyGame (2d)
+// /Root Node2D
+// /Root/Player CharacterBody2D script=PlayerControl position=[312,180] velocity=[180,0]
+// /Root/UI/Score Label text="Score: 3"
+```
+
+One grep-able line per node, showing only NON-default props — position, text,
+visibility, velocity. Assert against these instead of pixels.
+
+## 5. Validate programmatically
+
+```ts
+import { validateScene } from 'incanto/test';
+const res = validateScene(sceneJson);          // { ok } | { ok: false, error }
+if (!res.ok) console.error(res.error.code, res.error.details); // details.path/prop/signal/validOptions
+```
+
+## 6. Catch broken edits at save time (vite)
+
+```ts
+// vite.config.ts
+import { incantoScenes } from 'incanto/vite';
+export default { plugins: [incantoScenes()] };
+```
+
+Invalid `*.scene.json` saves keep the last good scene running and surface the
+IncantoError in the terminal AND as a browser overlay.
+
+## 7. See inside the RUNNING game (debug overlay)
+
+```ts
+// Default is OFF. Gate it to your dev server with an env var — never ship it on.
+createGame2D({ ..., debug: import.meta.env.VITE_INCANTO_DEBUG === '1' });
+```
+```bash
+VITE_INCANTO_DEBUG=1 bun run dev   # overlay on; plain `bun run dev` / prod build = off
+```
+
+A ☰ debug menu (top-left) toggles three draggable/resizable panels over the
+live game: **Explorer** (the scene tree — click any node), **Inspector** (the
+selected node's current state; numbers/strings/booleans/vectors editable
+in-place), **Logs** (an `engine.log` tail with level filters and an optional
+browser-console capture toggle) — plus **Stats**, an always-on-top chip pinned
+top-right (`60 fps · 12.1 ms` / `nodes 34 · tris 18.2k · calls 21`, refreshed
+~2×/s; the same numbers any code can read via `game.stats()`). Manual boots:
+`(await import('incanto/debug')).attachDebugOverlay(engine)`.
+
+**Security — `debug` defaults to `false` and there is NO URL/query toggle**, so
+a DEPLOYED build can never be switched on by an end user (no more `?incanto_debug=1`).
+Enable it only from your own dev environment via the env-var gate above. The
+overlay is a lazily-imported chunk — it stays out of the main bundle (no size
+cost), but it still ships in the build, so that runtime `debug` flag is the only
+thing gating it: keep it `false` (or dev-gated) in anything you publish.
+
+## 8. Debugging signals
+
+- `this.log.info(...)` in behaviors — shows up in `runScript().logs` (and the
+  browser console never has to be scraped).
+- Determinism: draw randomness from `this.rng`, never `Math.random()`, and any
+  seeded run reproduces exactly.
+- A run that "does nothing": remember the first engine tick only primes the
+  clock — `runScript` already handles this for you.

package/skills/incanto-web-integration.md

@@ -0,0 +1,96 @@
+---
+name: incanto-web-integration
+description: Embed an Incanto game in a React/Next/any web app — the IncantoCanvas component, useGame/useNodeProp/useSignal hooks, DOM HUD overlays vs UILayer, SSR safety, responsive sizing. Use when putting a game inside an existing website, building a React HUD, or wiring game state to web UI.
+---
+
+# Web integration (React and beyond)
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+Incanto's core is framework-free and every entry imports cleanly in Node (SSR
+safe). `incanto/react` is the official last mile — React is an OPTIONAL peer:
+`bun add react` only if you use it.
+
+## React: the component
+
+```tsx
+import { IncantoCanvas, useNodeProp, useSignal } from 'incanto/react';
+import { PlayerControl } from './behaviors';
+import sceneJson from './game.scene.json';
+
+function Hud() {
+  const score = useNodeProp<string>('UI/Score', 'text'); // re-renders only on change
+  useSignal('Coin', 'triggerEnter', () => confetti());   // auto-disconnects
+  return <div style={{ pointerEvents: 'auto' }}>{score}</div>;
+}
+
+export function GamePage() {
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <IncantoCanvas scene={sceneJson} behaviors={{ PlayerControl }}>
+        <Hud /> {/* children = DOM overlay over the canvas, game context inside */}
+      </IncantoCanvas>
+    </div>
+  );
+}
+```
+
+- The component boots `createGame2D/3D` in an effect (lazy-imported by the
+  scene's `dimension` — a 2D game never bundles the 3D stack), and `dispose()`s
+  everything on unmount. **StrictMode-safe**: double-invoked boots are disposed.
+- All createGame options pass through: `physics`, `touch`, `debug`, `seed`,
+  `pixelRatio`, `pointer` (3D), `keyboard: 'window' | 'canvas' | false`,
+  `fallback` (loading UI), `onReady(game)`.
+- Pass a STABLE `scene` reference — a new object identity re-boots the game.
+- Hooks need the `<IncantoCanvas>` context: put HUD components in `children`.
+  The overlay wrapper is `pointer-events: none`; re-enable per element.
+
+## DOM HUD vs UILayer — pick one per piece of UI
+
+| | DOM overlay (React/HTML) | `UILayer` nodes (in-canvas) |
+|---|---|---|
+| Styling | full CSS, fonts, a11y | engine Label/ColorRect only |
+| State | `useNodeProp`/`useSignal` | behaviors mutate props |
+| Serialized in scene JSON | no | yes (agents can edit it) |
+| Works in headless capture | no | yes (`describeCapture` sees it) |
+
+Rule of thumb: score/menus/dialogs that look like WEB UI → DOM overlay;
+anything the game itself must own (and runScript must verify) → UILayer.
+
+Pin a DOM element to a world position: `game.renderer.screenFromWorld(wx, wy)`
+each frame (subscribe `engine.updated`), then `transform: translate(x, y)`.
+
+Perf note: `useNodeProp` deep-compares per frame — subscribe to LEAF values
+(`'UI/Score', 'text'`), not big objects like a whole `animations` map.
+
+Perf HUDs: `game.stats()` returns `{ fps, frameMs, nodes, running, triangles,
+drawCalls, geometries, textures }` at any time — poll it on a `setInterval`
+(2×/s is plenty) into React state; never subscribe it per frame.
+
+## Next.js / SSR
+
+Every incanto entry imports in Node — no `dynamic()` tricks needed. The game
+itself boots inside `useEffect`, so server rendering emits the container +
+fallback only. In the App Router mark the page `'use client'`.
+
+## No React? Vanilla embed
+
+```ts
+const game = await createGame2D({ canvas, scene: sceneJson, behaviors: { … } });
+// later, on teardown (SPA route change):
+game.dispose(); // one call: renderer, physics, loop, scene, listeners
+```
+
+The canvas follows its CSS size every frame — size the CONTAINER with normal
+CSS/flex/grid and give the canvas `width:100%; height:100%; display:block`.
+Use the scene `viewport` header (see incanto-building-2d-games) so world
+coordinates stay in design pixels no matter the container.
+
+## Bridging game ↔ web state
+
+- Web → game: call behavior methods (`game.engine.scene.root.getNode('Player')
+  .behavior`), or `engine.input.pressAction('jump')` (same pipeline as keys).
+- Game → web: `useNodeProp` (polling, change-detected) or `useSignal`
+  (event-driven). For non-React, `engine.updated.connect(read)` +
+  `node.on('signal', cb)` are the same primitives.

package/templates/agent8-server.js

@@ -0,0 +1,84 @@
+/**
+ * LEGACY agent8 netcode kernel (root `server.js`, gameserver-sdk v1).
+ *
+ * PREFER THE STRUCTURED v2 TEMPLATE: `agent8-server.ts` (sibling file) is the
+ * current standard — run `npx -y @agent8/gameserver-node init` and drop that body
+ * into `server/src/server.ts`. Use THIS file only for an existing project that
+ * already ships a root `server.js`. See the service's `gameserver-sdk-v2` skill
+ * for the migration guide.
+ *
+ * Implements EXACTLY the room protocol incanto's NetworkManager (and the
+ * in-memory LoopbackHub) speak, so a game proven on Loopback runs live by
+ * swapping the transport.
+ *
+ * Platform facts baked into this design (do not fight them):
+ * - A NEW Server instance runs per request in isolated-vm: `this.*` never persists.
+ *   Use $global/$room for state — NEVER setTimeout/setInterval (no $roomTick in legacy).
+ * - $room.updateMyState / $room.updateRoomState are SHALLOW merges — keep state maps flat.
+ * - Room data is ephemeral; persist long-term data to $global before rooms empty.
+ * - Trust $sender.account, never trust args. Guard economy/score writes with $lock.
+ *
+ * LEGACY server.js MUST NOT use `export` — just define the class (the platform
+ * picks up a root `server.js` over `server/dist/server.js`).
+ */
+class Server {
+  // ---- rooms -----------------------------------------------------------------
+
+  async joinRoom(roomId) {
+    return await $global.joinRoom(roomId); // undefined → server-assigned room
+  }
+
+  async leaveRoom(_roomId) {
+    return await $global.leaveRoom(); // acts on $sender's current room
+  }
+
+  // ---- per-player state (owner-authoritative: movement, cosmetics) ------------
+
+  async setMyState(_roomId, patch) {
+    await $room.updateMyState(patch); // shallow merge
+    return true;
+  }
+
+  // ---- shared room state (match phase, timers) --------------------------------
+
+  async patchRoomState(_roomId, patch) {
+    await $room.updateRoomState(patch); // shallow merge
+    return true;
+  }
+
+  // ---- room collections (spawned entities: bullets, pickups) -------------------
+
+  async addEntity(_roomId, collectionId, entity) {
+    const doc = await $room.addCollectionItem(collectionId, entity);
+    return doc.__id;
+  }
+
+  async updateEntity(_roomId, collectionId, id, patch) {
+    await $room.updateCollectionItem(collectionId, { __id: id, ...patch });
+    return true;
+  }
+
+  async removeEntity(_roomId, collectionId, id) {
+    await $room.deleteCollectionItem(collectionId, id);
+    return true;
+  }
+
+  // ---- transient events (explosions, chat) -------------------------------------
+
+  async sendEvent(_roomId, type, payload) {
+    $room.broadcastToRoom(type, payload);
+    return true;
+  }
+
+  // ---- EXTEND BELOW: server-authoritative game rules ----------------------------
+  // Example — guarded score (never let clients write scores directly):
+  //
+  // async awardPoint(_roomId) {
+  //   const account = $sender.account;
+  //   await $lock(`score:${account}`, async () => {
+  //     const state = (await $room.getUserState(account)) ?? {};
+  //     await $room.updateUserState(account, { score: (state.score ?? 0) + 1 });
+  //   });
+  //   return true;
+  // }
+}

package/templates/agent8-server.ts

@@ -0,0 +1,138 @@
+/**
+ * Incanto netcode kernel for the agent8 GameServer SDK v2 (STRUCTURED project).
+ *
+ * HOW TO USE — DO NOT hand-create the server project. Run the init command first
+ * (it generates server/package.json, server/tsconfig.json, server/src/server.ts,
+ * server/test/), THEN drop this class body into server/src/server.ts:
+ *
+ *     npx -y @agent8/gameserver-node init    # only if server/ does not exist yet
+ *     # then replace server/src/server.ts with the body below
+ *     npx -y @agent8/gameserver-node test    # write + run server tests
+ *     npx -y @agent8/gameserver-node build   # generates server/dist/server.js
+ *     # then DEPLOY = push to the repository (platform auto-builds + deploys).
+ *
+ * Server-code specifics (the $global/$room/$sender/$asset/$lock contexts, the
+ * isolated-vm limits, build/deploy) AND the live client's connection + auth/identity
+ * (useGameServer / server.connect / $sender.isGuest etc.) are owned by the service's
+ * `gameserver-sdk-v2` skill — this file is ONLY the incanto-flavored room protocol body.
+ *
+ * This class implements EXACTLY the room protocol incanto's NetworkManager (and
+ * the in-memory LoopbackHub) speak, so a game proven on Loopback runs live by
+ * swapping the transport — nothing else changes.
+ *
+ * Platform facts baked into this design (do not fight them):
+ * - A NEW Server instance runs per request in isolated-vm: `this.*` never persists.
+ *   Use $global/$room for state, $roomTick for periodic logic — NEVER setTimeout/setInterval.
+ * - $room.updateMyState / $room.updateRoomState are SHALLOW merges — keep state maps flat.
+ * - Room data is ephemeral (cleared when the last user leaves); persist long-term
+ *   data to $global before rooms empty.
+ * - Trust $sender.account; never trust args. Guard economy/score writes with $lock.
+ *
+ * STRUCTURED v2 requires the `export` keyword (legacy root server.js must NOT export).
+ */
+
+// These globals are injected by the agent8 isolated-vm runtime (see gameserver-sdk-v2).
+declare const $sender: { account: string; roomId: string };
+declare const $global: {
+  joinRoom(roomId?: string): Promise<string>;
+  leaveRoom(): Promise<string>;
+};
+declare const $room: {
+  updateMyState(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  updateRoomState(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getUserState(account: string): Promise<Record<string, unknown>>;
+  updateUserState(account: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  addCollectionItem(collectionId: string, item: Record<string, unknown>): Promise<{ __id: string }>;
+  updateCollectionItem(
+    collectionId: string,
+    item: Record<string, unknown>,
+  ): Promise<{ __id: string }>;
+  deleteCollectionItem(collectionId: string, itemId: string): Promise<{ __id: string }>;
+  broadcastToRoom(type: string, message: unknown): void;
+  countUsers(): Promise<number>;
+};
+declare function $lock<T>(key: string, fn: () => T | Promise<T>): Promise<T>;
+
+export class Server {
+  // ---- rooms -----------------------------------------------------------------
+
+  /** undefined roomId → server-assigned random room; explicit id → shared room. */
+  async joinRoom(roomId?: string): Promise<string> {
+    return $global.joinRoom(roomId);
+  }
+
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: roomId kept for protocol symmetry with LoopbackHub.
+  async leaveRoom(roomId?: string): Promise<string> {
+    return $global.leaveRoom(); // acts on $sender's current room
+  }
+
+  // ---- per-player state (owner-authoritative: movement, cosmetics) ------------
+  // NetworkManager throttles owner sync into one setMyState({sync:{…}}) per window.
+
+  async setMyState(_roomId: string, patch: Record<string, unknown>): Promise<boolean> {
+    await $room.updateMyState(patch); // shallow merge; surfaces via subscribeRoomAllUserStates
+    return true;
+  }
+
+  // ---- shared room state (match phase, timers) --------------------------------
+
+  async patchRoomState(_roomId: string, patch: Record<string, unknown>): Promise<boolean> {
+    await $room.updateRoomState(patch); // shallow merge
+    return true;
+  }
+
+  // ---- room collections (spawned entities: bullets, pickups) -------------------
+
+  async addEntity(
+    _roomId: string,
+    collectionId: string,
+    entity: Record<string, unknown>,
+  ): Promise<string> {
+    const doc = await $room.addCollectionItem(collectionId, entity);
+    return doc.__id;
+  }
+
+  async updateEntity(
+    _roomId: string,
+    collectionId: string,
+    id: string,
+    patch: Record<string, unknown>,
+  ): Promise<boolean> {
+    await $room.updateCollectionItem(collectionId, { __id: id, ...patch });
+    return true;
+  }
+
+  async removeEntity(_roomId: string, collectionId: string, id: string): Promise<boolean> {
+    await $room.deleteCollectionItem(collectionId, id);
+    return true;
+  }
+
+  // ---- transient events (explosions, chat) -------------------------------------
+
+  async sendEvent(_roomId: string, type: string, payload: unknown): Promise<boolean> {
+    $room.broadcastToRoom(type, payload);
+    return true;
+  }
+
+  // ---- server-driven periodic logic (OPTIONAL) ---------------------------------
+  // Runs every 100–1000ms while the room has users — the ONLY way to do timed
+  // server logic (no setTimeout/setInterval). Drive match clocks, AI waves, etc.
+  // Delete if your game is purely client-driven.
+  //
+  // $roomTick(deltaMS: number, roomId: string): void {
+  //   // e.g. advance a shared match timer in room state
+  // }
+
+  // ---- EXTEND BELOW: server-authoritative game rules ----------------------------
+  // Example — guarded score (never let clients write scores directly). $lock makes
+  // the read-modify-write atomic against concurrent requests:
+  //
+  // async awardPoint(_roomId: string): Promise<boolean> {
+  //   const account = $sender.account;
+  //   await $lock(`score:${account}`, async () => {
+  //     const state = (await $room.getUserState(account)) ?? {};
+  //     await $room.updateUserState(account, { score: ((state.score as number) ?? 0) + 1 });
+  //   });
+  //   return true;
+  // }
+}