incanto 0.7.1 → 0.9.0

package/skills/incanto-building-2d-games.md

@@ -61,6 +61,37 @@ A solid-colored rectangle — no texture, no asset file. Props: `size [100,100]`
 `color '#ffffff'`, `opacity 1`, `anchor [0.5,0.5]`. The prototyping workhorse
 (paddles, walls, platforms, flashes); swap in a `Sprite2D` when art arrives.
 
+### `TileMap2D` (a whole tile level in ONE node)
+Grid render in a single draw call **plus** greedy-merged static colliders —
+stop hand-placing dozens of ColorRect walls:
+
+```jsonc
+{ "name": "Level", "type": "TileMap2D", "props": {
+    "texture": "$tiles",      // atlas: tileSize×tileSize squares, L→R, T→B
+    "tileSize": 32,
+    "cells": [
+      "..................",
+      "......GGG.........",
+      "000000000000000000"
+    ],
+    "legend": { "G": 12 },    // chars → atlas tile index (digits 0-9 are free)
+    "solid": [0, 12]          // these tile indices become static colliders
+} }
+```
+
+- `.` / space = empty; digits `0-9` = atlas tile index directly; any OTHER char
+  must be in `legend` — unknown chars **hard-fail at load** (fix the map, not
+  the runtime).
+- `solid` tiles are merged into a handful of `StaticBody2D` rect colliders
+  (greedy rectangles), so a 100×50 level costs a few bodies, not thousands.
+- Cell (0,0) hangs its TOP-LEFT on the node's origin; position the node to
+  place the level. `columns: 0` (default) derives atlas columns from the
+  texture width.
+- No texture yet? Colliders still work — pair with ColorRect2D placeholders or
+  just leave it invisible while you block out the level.
+- Change the map at runtime by REPLACING `cells` (mutations are not watched):
+  `map.cells = [...rows]` — geometry and colliders rebuild next frame.
+
 ### `Sprite2D`
 | Prop | Default | Notes |
 |---|---|---|

package/skills/incanto-building-3d-games.md

@@ -358,6 +358,27 @@ paletteColors:[…saturated…], shimmer:8`), a lingering ember glitter
 spreadDeg:180`) with `renderOrder:100`, each parented to a stable
 node (NOT the collectible's container), self-removing on `finished`.
 
+## Trails (`Trail3D` — motion ribbons)
+
+A fading world-space ribbon behind whatever it's parented to — wingtip trails,
+sword arcs, tyre streaks, dash effects. Cheaper and crisper than particles for
+"where did it move" lines:
+
+```jsonc
+{ "name": "WingTrail", "type": "Trail3D",
+  "props": { "width": 0.4, "color": "#aaddff", "seconds": 0.8, "additive": true } }
+```
+
+Parent it to the MOVING node (it records that node's world position). The strip
+faces the camera and tapers + fades toward the tail over `seconds`.
+
+- `width` (m, default 0.3), `color`, `opacity` (0.8), `seconds` (0.6 lifetime).
+- `additive: true` for glowing energy trails (dark backdrops); default normal
+  blending reads better in daylight.
+- `emitting: false` stops laying NEW ribbon while the old tail fades out — flip
+  it from script for dash/boost effects (`trail.emitting = boosting`).
+- `minDistance` (0.05 m) filters jitter when the parent is near-stationary.
+
 ## Terrain
 
 `Terrain3D` is procedural heightfield terrain with biome texture splatting —

package/skills/incanto-editor.md

@@ -110,6 +110,19 @@ Save activates only when the working scene differs from the original
 (`Ctrl/Cmd+S`); undo is `Ctrl/Cmd+Z`. Saving writes pretty-printed JSON to
 `--output` (default: the input file).
 
+## Painting TileMap2D levels
+
+Select a `TileMap2D` node and the inspector grows a **🖌 paint tiles** tool:
+toggle it on and left-clicks (and drags) on the canvas paint cells with the
+active brush. The palette chips offer every char already used in `cells`, the
+`legend` chars, and an eraser (`␡` = `.`); the small text box takes any other
+single char (digits map straight to atlas tile indices, other chars need a
+`legend` entry). The grid grows right/down automatically when you paint past
+the edge — to grow left/up, move the node instead (cell (0,0) hangs on the
+node origin). Merged solid colliders re-derive live as you paint. Each painted
+cell is one undo step; toggle paint off (or select another node) to get normal
+click-select back.
+
 ## Generate environments
 
 The **✦ button** beside the add-node controls opens the Generate dialog — the

package/skills/incanto-gameplay-behaviors.md

@@ -745,6 +745,10 @@ Terminal states ignore further transitions; the restart action (or
 physics, input. Listen to the `flowChanged(state)` signal for custom UI.
 `restartScene(engine)` is exported standalone.
 
+Multi-scene games: `flow.goToScene(nextSceneJson, { fadeSeconds: 0.4 })`
+fades to black, swaps, fades back (headless = instant). Title → level →
+next level is three JSON files and this one call.
+
 ## Boot loading overlay
 
 ```ts
@@ -765,3 +769,27 @@ save.set('highScore', Math.max(score, save.get('highScore', 0)));
 
 JSON round-tripped; headless/private-mode falls back to in-memory (never
 throws). `clear()` wipes only your namespace.
+
+## Pathfinding (grid A* + PathFollow)
+
+```ts
+import { findPath, gridFromRows } from 'incanto';
+
+const grid = gridFromRows([   // or { width, height, solid(x,y) } over your map data
+  '..........',
+  '..######..',
+  '..........',
+]);
+const cells = findPath(grid, [0, 1], [9, 1]);          // null = unreachable
+(npc.behavior as PathFollow).setPath(
+  (cells ?? []).map(([cx, cy]) => [cx * TILE, cy * TILE]),
+);
+npc.on('arrived', () => attack());
+```
+
+`findPath` is pure and dimension-free (cells in, cells out; diagonals on by
+default, corner-cutting forbidden; `{ diagonal: false }` for 4-way).
+`PathFollow` (registered behavior) walks waypoints at constant `speed`
+(units/sec — px in 2D, meters in 3D), emits `waypointReached(i)` /
+`arrived`, and `loop: true` patrols. Corners never eat frame budget — the
+speed is exact across bends.

package/skills/incanto-hud.md

@@ -56,3 +56,27 @@ banner.show('YOU DIED', { color: '#ef4444', seconds: 0 }); // sticky until next
 
 Pair with the `Health` / `ScoreKeeper` gameplay behaviors: listen to their
 signals and write the widget props — that is the whole HUD wiring.
+
+## Interactive widgets: UiButton & UiDialogue
+
+```json
+{ "name": "Talk", "type": "UiDialogue" },
+{ "name": "Start", "type": "UiButton",
+  "props": { "anchor": "center", "text": "START" } }
+```
+
+```ts
+const talk = this.node.getNode('%Talk') as UiDialogue;
+talk.say('Elder', 'Welcome to Lumina Village...');
+talk.say('Elder', 'Will you help us?', ['Yes', 'No']);
+talk.on('choiceMade', (i) => { if (i === 0) startQuest(); });
+talk.on('dialogueFinished', () => player.frozen = false);
+// while talk.active, skip player input — the box eats clicks to advance
+
+(this.node.getNode('%Start') as UiButton).on('pressed', () => flow.restart());
+```
+
+Typewriter reveal at `charsPerSecond` (0 = instant); clicking the box
+reveals the line then advances; choice lines render buttons and wait for
+`choose(i)`. Buttons opt into pointer events — the rest of the HUD stays
+click-through.

package/skills/incanto-multiplayer.md

@@ -140,6 +140,33 @@ const manager = await NetworkManager.create(engine, { transport: local.createCli
 engine.updated.connect((dt) => void local.tick(Math.min(dt, 0.05) * 1000));
 ```
 
+### Split-screen preview in one call (`createSplitScreen`)
+
+Testing multiplayer alone means playing BOTH sides. `createSplitScreen` wires
+the whole N-panel harness — one LocalGameServer, one engine + NetworkManager
+per player — so you only supply the per-panel renderer/input:
+
+```ts
+import { createSplitScreen, registerNodesNet } from 'incanto/net';
+
+const canvases = [document.getElementById('p1'), document.getElementById('p2')];
+const { players, server, dispose } = await createSplitScreen({
+  scene: gameJson,                       // shared scene (each panel gets its own copy)
+  server: Server,                        // your v2 Server class (optional)
+  scenes: { 'remote-player': remoteJson }, // NetworkSpawner scenes, every panel
+  accounts: ['p1', 'p2'],                // one panel per account (default)
+  setup: ({ engine }, i) => {            // finish wiring each panel
+    new Renderer2D({ canvas: canvases[i], engine });
+    engine.input.attachKeyboard(i === 0 ? window : canvases[i]); // split inputs!
+    engine.start();
+  },
+});
+```
+
+The first panel's clock pumps `server.tick` (so `$roomTick` runs) — don't add
+your own. `dispose()` tears every panel down. Going live is unchanged: ONE
+client per browser with `createAgent8Server()` as the transport.
+
 It runs the SAME class body the cloud runs: the v2 globals (`$sender`/`$global`/
 `$room`/`$lock`) are injected per call, a FRESH `Server` instance runs per request
 (so `this.*` never persists), and calls are serialized (no global leaks across

package/skills/incanto-node-reference.md

@@ -241,6 +241,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `sprintAction` | `"sprint"` | string |
 | `skinPath` | `"../Skin"` | string |
 | `skinYawOffset` | `0` | number |
+| `animations` | `{}` | object |
 
 Signals: `movementStateChanged(state)`
 
@@ -711,6 +712,25 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `textureBase` | `"https://agent8-games.verse8.io/assets/3D/default/textures/terrain"` | string |
 | `basins` | `[]` | array |
 
+## `TileMap2D` — `incanto/2d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0]` | array |
+| `rotation` | `0` | number |
+| `static` | `false` | boolean |
+| `scale` | `[1,1]` | array |
+| `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `visible` | `true` | boolean |
+| `texture` | `""` | string |
+| `tileSize` | `32` | number |
+| `columns` | `0` | number |
+| `cells` | `[]` | array |
+| `legend` | `{}` | object |
+| `solid` | `[]` | array |
+| `opacity` | `1` | number |
+
 ## `Timer` — `incanto`
 
 | Prop | Default | Kind |
@@ -721,6 +741,25 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 
 Signals: `timeout`
 
+## `Trail3D` — `incanto/3d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `width` | `0.3` | number |
+| `color` | `"#ffffff"` | string |
+| `opacity` | `0.8` | number |
+| `seconds` | `0.6` | number |
+| `emitting` | `true` | boolean |
+| `additive` | `false` | boolean |
+| `minDistance` | `0.05` | number |
+
 ## `Tree3D` — `incanto/3d`
 
 | Prop | Default | Kind |
@@ -780,6 +819,31 @@ Signals: `bannerShown`
 | `background` | `"rgba(0,0,0,0.5)"` | string |
 | `label` | `""` | string |
 
+## `UiButton` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `text` | `"OK"` | string |
+| `size` | `16` | number |
+| `color` | `"#ffffff"` | string |
+| `background` | `"rgba(255,255,255,0.14)"` | string |
+| `disabled` | `false` | boolean |
+
+Signals: `pressed`
+
+## `UiDialogue` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"bottom"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `charsPerSecond` | `40` | number |
+| `width` | `520` | number |
+
+Signals: `lineShown` · `choiceMade` · `dialogueFinished`
+
 ## `UiText` — `incanto`
 
 | Prop | Default | Kind |
@@ -951,6 +1015,15 @@ Signals: `arrived`
 | `frequency` | `1` | number |
 | `mode` | `"position"` | one of: `position` `rotation` `scale` |
 
+### `PathFollow`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `speed` | `120` | number |
+| `loop` | `false` | boolean |
+
+Signals: `waypointReached` · `arrived`
+
 ### `Patrol`
 
 | Prop | Default | Kind |

package/skills/incanto-physics-and-input.md

@@ -133,6 +133,15 @@ Injected state combines with key state (vectors clamped to unit length).
 - Reference: [examples/2d-phaser-sprite-character-gravity](https://github.com/rareboe/Incanto/tree/main/examples/2d-phaser-sprite-character-gravity) — gravity, jump, attack lockout, custom
   `Player` node type. Verified in Chromium end-to-end.
 
+## Platformer staples (2D)
+
+- **One-way platforms**: `"collider": { "shape": "rect", "size": [300, 20],
+  "oneWay": true }` on a StaticBody2D — characters jump up THROUGH it and
+  land ON it (solid only when falling from above). The Mario ledge.
+- **Moving platforms carry riders automatically**: a CharacterBody2D
+  standing on ANY body follows that body's movement (elevators, patrol
+  platforms — just animate the platform's `position`; the character rides).
+
 ## Joints (Joint2D / Joint3D)
 
 Link two bodies: put the joint node as a CHILD of body A, point `target` at

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

@@ -198,3 +198,34 @@ depth-test off, so it shows through walls). Extent-less nodes get a small
 marker cube at their position. That is the fastest answer to "which thing
 on screen IS this node?" — and the reverse of it: walk the tree clicking
 rows until the orange box lands on the thing you're hunting.
+
+## Semantic warnings (audit)
+
+`incanto-check` now WARNS about scenes that load fine but play wrong: no
+`current` camera, physics bodies without colliders, animated nodes frozen
+inside a `static` subtree, HUD widgets outside a HudLayer. Programmatic:
+`auditScene(json)` from `incanto` or `incanto/test` returns the warnings.
+
+## Deterministic replay (record once, regression-test forever)
+
+The engine is fully deterministic under a seed + injected clock, so a
+recording of (tick timestamps + input events) replays BIT-identically:
+
+```ts
+import { Engine, loadScene, replay, startRecording } from 'incanto';
+
+// while playing (dev build):
+const rec = startRecording(engine);
+// ... play the level ...
+save.set('replays/level1', rec.stop());
+
+// in a headless test:
+const engine = new Engine({ seed: SAME_SEED });
+engine.setScene(loadScene(sceneJson));
+replay(engine, recording, { onTick(i) { /* mid-run asserts */ } });
+expect(player.position).toEqual(expected); // exact, not approximate
+```
+
+Rules that make it hold (the engine's own rules anyway): use `engine.rng`
+never Math.random, dt/`engine.time` never Date.now. Gamepads replay through
+the ACTIONS they were bound to, not raw pad state.