incanto 0.1.0

package/skills/incanto-audio.md

@@ -0,0 +1,309 @@
+---
+name: incanto-audio
+description: Sound in Incanto — zero-asset PROCEDURAL SFX presets (coin/jump/hurt/explosion/laser/win…, the art-free audio analog of particle presets), the AudioPlayer node (preset vs src file, autoplay + browser gesture-unlock, the finished signal, 3D spatial/positional audio), the music manager (crossfade/loop background music), global volume buses (master/sfx/music + mute), and the built-in audio catalog of real sound files. Use whenever a game needs sound, sfx, audio effects, music, spatial/positional audio, or volume control.
+---
+
+# Audio — sound, SFX, and music
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+Sound comes from the **`AudioPlayer`** node. It has two modes:
+
+1. **`preset`** — a built-in **procedural SFX** synthesized on the fly. **Zero
+   asset bytes, instant, deterministic.** This is the headline path: the audio
+   analog of the `Particles2D` presets / art-free prototyping. Reach for this
+   first — a working game can ship sound with no files at all.
+2. **`src`** — play an audio file (URL). Good for music and longer clips, and
+   for the curated built-in sounds (§4). Used when `preset` is `"custom"`.
+
+All volume routes through global **buses** (§3): `master × (sfx|music) × volume`.
+
+`AudioPlayer` is headless-safe — with no audio backend (node, the verify VM)
+every method is a silent no-op, so scenes load and simulate everywhere.
+
+---
+
+## 1. Procedural SFX presets — the zero-asset path (lead with this)
+
+Set `preset` to one of the names below and call `play()`. No files, no loading.
+
+```jsonc
+{ "type": "AudioPlayer", "name": "Coin", "props": { "preset": "coin" } }
+```
+
+```ts
+const coin = scene.tree.root.getNode('Coin'); // an AudioPlayer
+coin.play();   // synthesizes + plays instantly; rapid calls OVERLAP (no cutoff)
+```
+
+### The preset set
+
+| preset      | sound it makes                                  | typical use            |
+|-------------|-------------------------------------------------|------------------------|
+| `coin`      | bright ascending chime                          | collect a coin         |
+| `pickup`    | soft two-tone blip                              | generic item pickup    |
+| `jump`      | rising whoop                                     | jump                   |
+| `hurt`      | harsh downward buzz                              | take damage            |
+| `hit`       | short noisy thud                                 | impact / melee hit     |
+| `explosion` | big falling-pitch boom                           | explosion (+particles) |
+| `powerup`   | cheerful rising sweep                            | power-up / level up    |
+| `laser`     | zappy descending beam                            | laser / energy shot    |
+| `shoot`     | punchy square shot                               | gunfire / projectile   |
+| `blip`      | tiny neutral tick                                | UI feedback            |
+| `select`    | confident two-step                               | menu select / confirm  |
+| `step`      | soft muted noise tap                             | footstep               |
+| `win`       | happy fanfare rise                               | victory                |
+| `lose`      | sad descending tone                              | game over              |
+
+(Authoritative list: `incanto-node-reference.md` → `AudioPlayer.preset` options,
+or `import { SFX_PRESET_NAMES } from 'incanto'`.)
+
+### Variation: `pitch` + `seed`
+
+Repeated identical SFX feel robotic. Vary them for free:
+
+- **`pitch`** (default 1) — multiplies the frequency. `0.8` lower, `1.4` higher.
+- **`seed`** (default 0) — varies the noise in noisy presets (`explosion`,
+  `hit`, `step`). Same seed → byte-identical sound (deterministic, replay-safe).
+
+```jsonc
+{ "type": "AudioPlayer", "name": "Step",
+  "props": { "preset": "step", "pitch": 1.1, "seed": 3 } }
+```
+
+To re-roll variation at runtime, set `seed` before each `play()`:
+
+```ts
+step.seed = (step.seed + 1) | 0; step.play();
+```
+
+### Firing presets from gameplay
+
+Wire them through scene `connections` — e.g. play `coin` when a Collector picks
+something up, `hurt` when Health takes damage:
+
+```jsonc
+"connections": [
+  { "signal": "collected", "from": "Player/Collector", "to": "Coin",   "handler": "play" },
+  { "signal": "damaged",   "from": "Player/Health",    "to": "Hurt",   "handler": "play" }
+]
+```
+
+`play` is a method on `AudioPlayer`, so a connection can target it directly.
+
+> Procedural SFX use **WebAudio** (low-latency, overlap-friendly) — not the
+> HTMLAudio element. WebAudio is a browser API behind a headless guard, so it's
+> a no-op in the verify VM. Like all audio it needs a user gesture first; the
+> same unlock listener that retries `src` players also resumes the SFX context
+> (see §2).
+
+---
+
+## 2. The AudioPlayer node (preset vs src file)
+
+```jsonc
+{ "type": "AudioPlayer", "name": "Bgm", "props": {
+    "src": "incanto/assets/audio/...mp3",  // file URL (preset = "custom")
+    "preset": "custom",                      // or a preset name → ignores src
+    "volume": 1,                              // 0..1, before bus gain
+    "bus": "sfx",                            // "sfx" (default) or "music"
+    "loop": false,                            // loop the src clip (music)
+    "autoplay": false                         // play on first frame in the tree
+} }
+```
+
+Methods: **`play()`**, **`stop()`**. Signal: **`finished`** (fires when a
+non-looping `src` clip ends — connect it to clean up or chain sounds). Procedural
+presets are fire-and-forget one-shots: they do not emit `finished`.
+
+### Autoplay + the browser gesture-unlock
+
+Browsers block audio before the first user gesture. `autoplay: true` (or any
+early `play()`) that gets blocked is marked pending; **`createGame2D` /
+`createGame3D` automatically retry every pending player AND resume the WebAudio
+SFX context on the first pointerdown/keydown** — you don't wire anything. A
+blocked play is not an error; it just waits for the gesture.
+
+### Music: loop a `src` clip on the music bus
+
+```jsonc
+{ "type": "AudioPlayer", "name": "Music", "props": {
+    "src": "incanto/assets/audio/...mp3",
+    "loop": true, "autoplay": true, "bus": "music", "volume": 0.6 } }
+```
+
+> For crossfading between tracks (e.g. exploration → boss music), use the **music
+> manager** (§5) instead of an `AudioPlayer` — it owns a single track and ramps.
+
+---
+
+## 2b. Spatial (3D positional) audio
+
+Set **`spatial: true`** on an `AudioPlayer` in a **3D scene** and the sound pans
+(left/right) and attenuates by **distance** — the emitter is the node's world
+position, the **listener is the active `Camera3D`** (the one marked `current`).
+The 3D adapter feeds the emitter + listener pose to the panner every frame, so
+moving the emitter or the camera updates the sound live. Works for BOTH paths
+(procedural `preset` and a `src` file).
+
+```jsonc
+// Attach under a moving Node3D — it emits from THAT node's world position.
+{ "type": "Node3D", "name": "Enemy", "props": { "position": [8, 0, -3] },
+  "children": [
+    { "type": "AudioPlayer", "name": "Footsteps", "props": {
+        "preset": "step",
+        "spatial": true,        // ← turn on 3D positional audio
+        "refDistance": 2,       // full volume within 2 units
+        "maxDistance": 40,      // inaudible past 40 units
+        "rolloff": "inverse"    // "inverse" | "linear" | "exponential"
+    } }
+  ] }
+```
+
+| prop          | default     | meaning                                                |
+|---------------|-------------|--------------------------------------------------------|
+| `spatial`     | `false`     | off = ordinary non-positional sound (back-compat)      |
+| `refDistance` | `1`         | distance at which gain is full; closer never louder    |
+| `maxDistance` | `50`        | distance past which gain stops falling                 |
+| `rolloff`     | `"inverse"` | attenuation curve (WebAudio PannerNode distance model) |
+
+- **`inverse`** (default): `ref / (ref + d−ref)` — natural-sounding 1/d falloff.
+- **`linear`**: straight ramp to ~0 at `maxDistance`.
+- **`exponential`**: steeper near falloff.
+
+Under the hood spatial audio uses a WebAudio **`PannerNode` (HRTF)** with the
+listener driven by the camera's world position + orientation. The pure
+distance-gain + pan-sign math (`spatialGain`, `spatialPan`, exported) is what the
+non-WebAudio paths use, so headless gameplay is unaffected.
+
+> **2D scenes:** spatial is currently **ignored** (no listener is fed) — a 2D
+> sound plays non-positionally regardless of `spatial`. Pan a 2D sound yourself
+> from the camera-relative x-offset if you need it. Spatial is a 3D feature.
+
+> **Headless / verify VM:** spatial is a no-op like all audio — `play()` won't
+> throw and your gameplay logic is unaffected.
+
+---
+
+## 3. Volume buses (global volume + mute)
+
+Every sound's final loudness is `master × bus × volume`, where `bus` is the
+node's `sfx` or `music` gain. The buses live on the engine as `engine.audio`:
+
+```ts
+engine.audio.master = 0.8;   // dim everything (0..1)
+engine.audio.sfx    = 1;     // SFX bus gain
+engine.audio.music  = 0.4;   // quieter background music
+engine.audio.muted  = true;  // global mute toggle (true → all sound 0)
+```
+
+Values clamp to `[0,1]`; non-finite sets are ignored. `engine.audio.changed`
+fires on any change (drives a settings UI). Procedural SFX go to whichever `bus`
+the node declares (default `sfx`); music-ish loops typically set `bus: "music"`.
+Changes apply to currently-playing `src` clips on the next frame and to every new
+sound immediately.
+
+A settings slider just writes these numbers — no per-node bookkeeping.
+
+---
+
+## 4. Built-in audio catalog (real sound files)
+
+Alongside the procedural set, the package ships a small set of **real**,
+owner-licensed (MIT-ish) sound files — handy when you want recorded SFX. They're
+in the same catalog as the art (`kind: "audio"`):
+
+```bash
+bunx incanto-assets list --json   # filter kind === "audio"
+```
+
+Built-ins include `explosion`, `attacked` (hurt), `gold-loot` (coin), `slash`,
+`hit-metal-bang`, `heal`, `spells-cast`, `ice-spear`, `monster-died`, `smite`,
+`walk` (footstep), `ui-click`. Each entry's **`url`** is the drop-in contract:
+`incanto/assets/audio/<file>` — exactly like the packaged sprites. Put it in
+`AudioPlayer.src`:
+
+```jsonc
+{ "type": "AudioPlayer", "name": "Boom",
+  "props": { "src": "incanto/assets/audio/explosion.mp3", "bus": "sfx" } }
+```
+
+In a bundler game (vite, the usual target) you can `import url from
+'incanto/assets/audio/explosion.mp3'` and write that into `src`; or
+`bunx incanto-assets copy <name> --out public/assets` to copy the file. For more
+or different sound, any audio URL works (asset MCP servers, your own CDN) — never
+invent URLs; use the catalog or a real source. Large music tracks are NOT
+bundled (keep the package small) — reference them by URL.
+
+### Editor
+
+The scene composer (`bunx incanto-editor`) shows `preset`, `bus`, and `rolloff`
+as dropdowns, `spatial` as a checkbox, `refDistance`/`maxDistance` as numbers,
+and `AudioPlayer.src` as an **audio asset picker** (browse the built-in sounds
+by name, or paste a URL). Zero-asset SFX = pick a `preset` instead of a `src`.
+
+---
+
+## 5. Music manager (crossfade / loop, single background track)
+
+For **background music** you usually want ONE track at a time and the ability to
+**crossfade** to another (exploration → boss, level A → level B). That's
+`engine.music` — a single-track manager that streams a clip and ramps gains:
+
+```ts
+// Loop a track (full volume, music bus):
+engine.music.play('incanto/assets/audio/theme.mp3');
+
+// Options: { loop = true, fadeIn = 0 (seconds), bus = 'music' }
+engine.music.play('intro.mp3', { loop: false, fadeIn: 2 });
+
+// Equal-power crossfade to a new track over N seconds (old fades out as new
+// fades in — no mid-fade volume dip):
+engine.music.crossfadeTo('boss.mp3', 3);
+
+// Fade the current track out and stop (0 = instant):
+engine.music.stop(2);
+
+// Per-manager volume (on top of the bus gain):
+engine.music.setVolume(0.5);
+
+// What's playing (the logically-current track src, or null):
+engine.music.current;
+```
+
+It routes through the **music bus** by default, so `engine.audio.music` /
+`master` / `muted` dim it for free (a settings slider needs no extra wiring).
+Fades advance automatically each frame (the engine ticks the manager). Like all
+audio it needs a user gesture; `createGame2D`/`createGame3D` resume + (re)start a
+gesture-blocked track on the first pointer/key, same as SFX.
+
+**Why a manager and not an `AudioPlayer` node?** A node is a one-shot/loop with
+no concept of "the current music"; crossfading needs to hold two tracks and ramp
+both. The imperative manager (call it from a behavior on scene change) is the
+clean fit; the looping-`src` `AudioPlayer` (§2) stays the right tool for a *fixed*
+background loop authored in scene JSON. Wire `crossfadeTo` from gameplay:
+
+```ts
+// e.g. in a behavior when the boss spawns:
+this.tree.engine.music.crossfadeTo('incanto/assets/audio/boss.mp3', 3);
+```
+
+> Large music files are NOT bundled — reference them by URL (see §4). Headless:
+> the manager's state machine still runs (`current` updates) but plays nothing.
+
+---
+
+## Decision guide
+
+- **Need a quick game sound (coin/jump/hit/explosion/…)** → set `preset`. Done.
+- **Want a specific recorded sound** → built-in audio catalog `src`, or any URL.
+- **A fixed background loop authored in JSON** → `src` + `loop:true` +
+  `autoplay:true` + `bus:"music"` on an `AudioPlayer`.
+- **Switchable / crossfading music** → `engine.music.play(...)` /
+  `crossfadeTo(...)` / `stop(...)` (§5).
+- **3D sound that pans + fades with distance** → `spatial:true` on an
+  `AudioPlayer` in a 3D scene (§2b); listener = the active `Camera3D`.
+- **Global volume / mute / settings** → `engine.audio.master/sfx/music/muted`.
+- **Verifying headlessly** → audio is a no-op in the VM; assert `play()` doesn't
+  throw and check your gameplay/score logic instead (see incanto-verifying).

package/skills/incanto-behaviors-and-scripts.md

@@ -0,0 +1,169 @@
+---
+name: incanto-behaviors-and-scripts
+description: Attach vibe-coded TypeScript to JSON nodes via the Behavior system — registerBehavior, script props, JSON connections to behavior methods, Timer, CharacterController2D. Use when adding game logic.
+---
+
+# Behaviors & Scripts
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+> **For ready-made behaviors, see `incanto-gameplay-behaviors.md` first.** Health,
+> score, pickups, contact damage, lifetimes and interaction ship built-in and
+> auto-register in `createGame` — wire them from JSON with no code. Write a custom
+> behavior (this doc) only for game-specific logic the library doesn't cover.
+
+JSON owns STRUCTURE; TypeScript owns BEHAVIOR. A node carries at most ONE script:
+
+```json
+{ "name": "Level", "type": "Node2D",
+  "script": { "name": "CoinCounter", "props": { "target": 10 } } }
+```
+
+```ts
+import { Behavior, registerBehavior } from 'incanto';
+
+class CoinCounter extends Behavior {
+  static readonly props = { target: { default: 0 } }; // same schema model as nodes
+  target = 0;
+  collected = 0;
+
+  override onReady(): void {}                  // once per instance, after the node's own
+  override update(dt: number): void {}         // every frame
+  override fixedUpdate(dt: number): void {}    // every fixed step
+  onCoinCollected(other: unknown): void {      // JSON connections call this
+    this.collected += 1;
+  }
+}
+registerBehavior('CoinCounter', CoinCounter);  // EXPLICIT — before loadScene
+```
+
+## The three-artifact contract (keep them in sync!)
+
+1. scene JSON `"script": {"name": "CoinCounter"}`
+2. the TS class
+3. `registerBehavior('CoinCounter', CoinCounter)` in the game entry
+
+A missing registration is a hard `UNKNOWN_BEHAVIOR` at load listing registered names.
+Script `props` validate against `static props` (`UNKNOWN_PROP` / `PROP_TYPE_MISMATCH`).
+Hot reload: `registerBehavior(name, ctor, { replace: true })` swaps the implementation
+under an existing name (re-registering a different class without it → `DUPLICATE_BEHAVIOR`).
+
+## What a Behavior can reach
+
+- `this.node` — the host node (cast to its type when needed)
+- `this.getNode(path)` / `this.emit(...)` / `this.on(...)` — node delegates
+- `this.engine` / `this.input` — via the scene tree (TREE_VIOLATION if the scene isn't
+  set on an Engine)
+- Engine access in `onReady` (`this.engine` / `this.rng` / `this.log`) works under
+  `createGame2D/3D` — they pass `{ engine }` to `loadScene`, attaching it BEFORE
+  `onReady` fires. Under a manual boot it throws `TREE_VIOLATION` until
+  `engine.setScene(scene)`: prefer `createGame` (or `loadScene(json, { engine })`),
+  or defer engine-dependent work to the first `update`. Two onReady caveats even
+  with the engine attached: `engine.scene` is still null (setScene runs after),
+  and the scene's `input` actions are not declared yet — query input from
+  `update`/`fixedUpdate`, never `onReady`.
+- `this.rng` — seeded engine randomness: `next()` [0,1), `range(min,max)`,
+  `int(min,max)` (inclusive), `pick(arr)`. **Never `Math.random()` in game logic** —
+  with `new Engine({ seed: 42 })` a run replays identically (scripted verification).
+- `this.log` — the engine log channel (`debug/info/warn/error(...parts)`; debug overlay
+  and headless harnesses tail it via `entries()` / the live `added` signal)
+
+## Runtime API (the imperative half)
+
+What behavior code actually calls at runtime — all instance methods, no globals:
+
+| Call | Semantics |
+|---|---|
+| `parent.addChild(node)` | attach a DETACHED node (already-parented → `TREE_VIOLATION`); sibling name collisions auto-rename (`Enemy` → `Enemy2`) |
+| `duplicateNode(node)` | deep-clone via serialize→rebuild — returns a **detached** node; attach it explicitly with `addChild` |
+| `node.queueFree()` | deferred destruction — flushed at the END of the current update pass (queued during a flush = freed next pass) |
+| `node.free()` | immediate detach + teardown (children first, signals disconnected) |
+| `root.getNodesByName('Enemy')` | EVERY node with that name in the subtree, document order |
+| `node.getNodeOrNull(path)` | like `getNode` but `null` instead of `NODE_NOT_FOUND` |
+| `node.getNode('%Player')` | unique-name lookup across the whole tree (≥2 matches → `DUPLICATE_UNIQUE_NAME`) |
+| `this.node.tree?.getNodesInGroup('enemies')` | group query (also `tree.callGroup(group, method, ...args)`) |
+| `engine.stop()` / `engine.start()` | pause / resume the loop — stop resets the clock and accumulator, so no banked sim time leaks into the resume |
+| `engine.step()` | advance exactly ONE fixed step + one update (both dt = the fixed step) — the unit of time for headless tests |
+| `engine.tick(timestampMs)` | manual frame advance — takes an **absolute** ms timestamp (rAF-style), NOT a dt; the first call after (re)start only primes the clock |
+| `engine.setScene(scene)` | swap scenes: the previous root is freed, the input map is cleared and redeclared from the new scene's `input{}`, then `sceneChanged` fires |
+| `engine.stats()` | live perf counters `{ fps, frameMs, nodes, running }` — fps/frameMs average the last ~60 REAL `tick` frames (headless `step()` runs report 0), nodes is the current tree size. GPU counters (triangles/draw calls) live on `renderer.stats()` / the merged `game.stats()` |
+
+The recurring traps: `duplicateNode` does NOT insert the clone anywhere — a
+"spawner that does nothing" usually forgot `addChild`. `engine.tick(16)` does
+not mean "advance 16ms": tick wants wall-clock timestamps, so scripted loops
+should call `engine.step()` instead. And `queueFree` inside `update` is always
+safe — the node keeps existing until the pass ends.
+
+## Custom signals (declare before emit)
+
+Signals are part of a node's contract: emitting or subscribing an UNDECLARED signal is a
+hard `UNKNOWN_SIGNAL` listing the declared ones. A behavior declares its custom signals
+with `static signals` (merged up the class chain) — auto-declared onto its node at load:
+
+```ts
+class GameRules extends Behavior {
+  static signals = ['gameOver'];               // REQUIRED before this.emit('gameOver')
+  onPlayerDied(): void { this.emit('gameOver'); }
+}
+```
+
+Built-in node signals (`timeout`, `triggerEnter`, `animationFinished`, …) are already
+declared by their classes. Escape hatch for runtime one-offs: `node.declareSignal(name)`
+(instance-only — ad-hoc declarations do NOT survive `duplicateNode`/serialize; prefer
+`static signals`); `node.declaredSignalNames()` lists everything a node may emit.
+
+## Connections → behavior methods
+
+```json
+"connections": [
+  { "signal": "triggerEnter", "from": "Coins/CoinA", "to": ".", "handler": "onCoinCollected",
+    "once": true, "filter": { "group": "player" } }
+]
+```
+- `handler` must exist on the target NODE or its BEHAVIOR — hard `UNKNOWN_HANDLER`
+  otherwise (validated at load; node methods take precedence on invocation).
+- Handlers receive the EMITTED args only (e.g. the other body for `triggerEnter`) — not
+  the emitting node. For per-emitter logic, attach a small behavior to the emitter itself
+  (see the `Pickup` pattern: a coin's own `triggerEnter` → its own `onTaken` → `queueFree`).
+
+## Timer (core node — never setTimeout in game logic)
+
+```json
+{ "name": "Spawner", "type": "Timer", "props": { "waitTime": 2, "autostart": true } }
+```
+Emits `timeout` every `waitTime` s (`oneShot` for once). API: `start(time?)`, `stop()`, `running`.
+
+## CharacterController2D (JSON-only playable characters)
+
+Child of a `CharacterBody2D` (hard error otherwise):
+```json
+{ "name": "Player", "type": "CharacterBody2D",
+  "props": { "collider": { "shape": "capsule", "radius": 10, "height": 20 } },
+  "children": [
+    { "name": "Controller", "type": "CharacterController2D",
+      "props": { "mode": "platformer", "maxSpeed": 260, "jumpHeight": 146 } }
+  ] }
+```
+- `platformer`: x movement + gravity (scene `physics.gravity[1]`) + jump (`jumpHeight` px)
+- `topDown`: full-axis movement, no gravity
+- Defaults: `mode 'platformer'`, `maxSpeed 220`, `jumpHeight 64`, `moveAction 'move'`,
+  `jumpAction 'jump'`. Timer defaults: `waitTime 1`, `oneShot false`, `autostart false`.
+- ⚠️ Connection handler names must not collide with Node API methods (`emit`, `update`,
+  `on`, `queueFree`, …) — the NODE method wins silently. Prefix handlers with `on`.
+
+Reference: [examples/2d-phaser-sprite-character-gravity](https://github.com/rareboe/Incanto/tree/main/examples/2d-phaser-sprite-character-gravity) — engine nodes + one small PlayerControl behavior
+(`CoinCounter`, `Pickup`) wired entirely through JSON connections. Verified in Chromium.
+
+## Spawning nodes at runtime
+
+Nodes you create in code and intend to serialize need uids like everything
+else — mint them with the engine's generator, never by hand:
+
+```ts
+import { newUid } from 'incanto';
+import { Sprite2D } from 'incanto/2d'; // node classes live in their dimension entry
+
+const coin = new Sprite2D('Coin');
+coin.uid = newUid(); // n_xxxxxxxxxxxxxxxx (crypto, 16 base36 chars)
+```