incanto 0.49.0 → 0.51.0

package/editor/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-5dEIhvsf.js"></script>
+    <script type="module" crossorigin src="./assets/index-CUc1U7wm.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

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

@@ -213,8 +213,13 @@ listing the valid set. With a viewport design, UI coordinates are design px.
   ```
   `setScene` frees the old root, clears + redeclares the input map from the new
   scene's `input{}`, and emits `sceneChanged` — `createGame2D`'s touch overlay
-  rebuilds itself on that signal, and the renderer loads the new scene's assets
+  rebuilds itself on that signal, the PHYSICS world registers the new scene's
+  bodies before its first frame, and the renderer loads the new scene's assets
   on demand. Register any extra behaviors/node types BEFORE the `loadScene` call.
+
+  The input map is CLEARED by the swap, which matters for a headless drive: an
+  injected `setActionVector` does not carry into the next level — set it again
+  after the transition, the same way a player's held key is re-read.
 - **Game over / restart**: swap to a fresh load of the SAME JSON —
   `engine.setScene(loadScene(levelJson))`. `loadScene` treats the JSON as
   read-only (everything it keeps is cloned), so reloading the same imported

package/skills/incanto-gameplay-behaviors.md

@@ -356,6 +356,17 @@ whole entity toward the target. (Distance is measured from the moved parent.)
   "script": { "name": "Chase", "props": { "target": "/root/Player", "speed": 120, "stopRange": 20 } } }
 ```
 
+**A character body chases through the level, not through walls.** When the node
+being moved is a `CharacterBody2D`/`3D`, `Chase` (and `Patrol`) move it with
+`moveAndSlide()`, so it collides and slides like any character. A plain
+`Node2D`/`Node3D` — the example above — has no collider and keeps the direct
+write, which is also what you want for a ghost or a flying marker.
+
+This is straight-line homing, not pathfinding: a body can now be STOPPED by
+geometry it used to walk through. When enemies must find their way around a
+level, that is what `buildTerrainNav` + `findPath` + `PathFollow` are for (see
+`incanto-building-3d-games.md`).
+
 ## Wander
 
 Seeded random roaming inside a circle around the spawn point — idle critters,

package/skills/incanto-node-reference.md

@@ -1422,6 +1422,19 @@ Signals: `collected(value, other)`
 | `direction` | `null` | null |
 | `gravity` | `0` | number |
 
+### `SavePoint`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `game` | `"game"` | string |
+| `slot` | `"1"` | string |
+| `label` | `""` | string |
+| `scene` | `""` | string |
+| `restoreOnReady` | `false` | boolean |
+| `probeOnReady` | `false` | boolean |
+
+Signals: `saved` · `restored` · `noSave` · `hasSave`
+
 ### `ScoreKeeper`
 
 | Prop | Default | Kind |

package/skills/incanto-playtesting.md

@@ -98,12 +98,23 @@ far more useful.
 ## Replays
 
 A run that did not win is written out. Because the engine is deterministic
-(seeded RNG, injected clock), a replay reproduces that run **bit-identically**:
+(seeded RNG, injected clock), a replay reproduces that run **bit-identically** —
+feed the file straight back in, with the seed the run used:
 
 ```bash
-bunx incanto-play src/game.scene.json --seed 7   # then replay the recording
+bunx incanto-play src/game.scene.json --seed 1 --commands .incanto/playtest/fell-seed1.json
+#  {"ok":true,"cmd":"replay","frames":804,"events":963}
+#  … then the scene as it ended: /Game/Player position=[28.9, -49.46, …]
 ```
 
+`--commands` takes either a text command script or a replay file and tells them
+apart by content. The seed matters: the world's own randomness (spawners,
+wandering AI) comes from it, and only the PLAYER's input is in the recording.
+
+Then read where it ended. The player above left a walled 40×40 arena at
+`x = 28.9` before falling — a thing you cannot learn from "fell in 1/4" and can
+read straight off the replay.
+
 One file per *kind* of failure — twenty identical "stuck" replays teach nothing
 the first one does not.
 

package/skills/incanto-save-slots.md

@@ -47,6 +47,17 @@ restored.** You resume at the scene's start with stats, inventory, unlocks and
 quest flags intact — a checkpoint save. If your game needs a position, save it:
 `serialize()` returns anything.
 
+**What the run CONSUMED is remembered.** Reloading from the file brings back
+every gem you already picked up, which would let a collect-five-to-win run
+resume at four with five gems on the map. So the save also carries the authored
+uids that are no longer in the tree, under `#freed`, and the restore frees them
+again — collectibles, opened chests, destroyed crates, a named boss. Spawned
+clones never have uids (`duplicateNode` drops them on purpose), so the ledger is
+exactly the authored world.
+
+Those nodes go on the **next frame** (`queueFree`, not an immediate detach), so
+read `report.freed` rather than counting children the instant restore returns.
+
 ## Making a behavior saveable
 
 Two optional hooks, exactly like the other five:
@@ -82,8 +93,17 @@ lives, won/lost), `Collector` (total).
 
 The uid is the join key, because it is the one identifier that survives a rename
 or a reparent. The editor assigns one to every node it touches. A hand-written
-scene may not have them — `engine.captureState()` logs any node that has state to
-save and no uid to key it under.
+scene may not have them, and then the save is silently empty — so
+**`incanto-check` warns about it**, naming each node, long before you write a
+save:
+
+```
+warn: these carry state a save keeps and have no uid to key it under, so the
+      save comes back EMPTY and the load reports no problem: Game (ScoreKeeper),
+      Game/Player (Health). Give each one a "uid" from newUid().
+```
+
+At runtime `engine.captureState()` logs the same thing per node.
 
 Never hand-craft a uid. Use `newUid()`.
 
@@ -120,7 +140,68 @@ It never throws. A save naming a uid this build deleted reports it in
 `report.missing` and restores everything else; refusing to load would mean a
 patch that moves one node deletes everyone's progress.
 
-## A load menu
+## Many levels: the router is three lines, and they are yours
+
+The engine does not route scenes — deliberately, because only your game knows
+what a key means. What it does is record the key, so the routing is a lookup:
+
+```ts
+import { createGame2D, loadScene } from 'incanto';
+import level1 from './level1.scene.json';
+import level2 from './level2.scene.json';
+
+const SCENES: Record<string, unknown> = { level1, level2 };   // key → scene JSON
+
+// New game
+const game = await createGame2D({ canvas, scene: SCENES.level1 });
+
+// Next level — the SavePoint in the new scene writes `level2` from here on
+(game.scene.root.getNode('Flow').behavior as GameFlow).goToScene(SCENES.level2);
+
+// Continue
+const slot = new SaveSlots('chapters').read('1');
+const scene = SCENES[slot?.scene ?? 'level1'];
+const game = await createGame2D({ canvas, scene });
+// then `restoreOnReady: true` on that scene's SavePoint, or call restore()
+```
+
+A `SavePoint` records `scene` as the scene's own `name` unless you set the prop,
+so `level2.scene.json` named `level2` needs no wiring at all. Set `scene`
+explicitly when one file is entered more than one way (`"chapter-2-rescue"`).
+
+**The swap clears the input map** (the new scene declares its own `input{}`), and
+physics registers the new bodies before that scene's first frame — so a
+character walks in level two exactly as it did in level one.
+
+## A title screen, in JSON
+
+A `SavePoint` can ASK without loading. `probeOnReady` fires on the first frame
+and emits `hasSave(label, playtime, scene)` or `noSave`, so the menu wires
+itself:
+
+```json
+{ "name": "Save", "type": "Node", "uid": "n_…",
+  "script": { "name": "SavePoint",
+              "props": { "game": "chapters", "slot": "1", "probeOnReady": true } } }
+```
+```json
+{ "signal": "noSave",  "from": "Save", "to": "HUD/Menu/Continue", "handler": "hide" },
+{ "signal": "noSave",  "from": "Save", "to": "HUD/Menu/SlotInfo", "handler": "hide" },
+{ "signal": "hasSave", "from": "Save", "to": "HUD/Menu/SlotInfo", "handler": "setText" }
+```
+
+With `"format": "Continue: {}"` on that `UiText`, a fresh install shows a menu
+with no Continue button and a save shows `Continue: Chapter 2`. Every HUD widget
+takes `show`/`hide` from a wire (`visible` is a prop, and a connection needs a
+method — the same wall `setText` broke through).
+
+The label leads because that is what a menu shows; an unlabelled slot falls back
+to its scene key, so the line is never blank.
+
+**The button's press is still yours**, and rightly: `pressed → your router`. See
+the three lines above.
+
+## Several slots
 
 ```ts
 for (const slot of slots.all()) {         // newest first
@@ -130,23 +211,64 @@ slots.remove('2');
 slots.clear();                            // "delete all data"
 ```
 
+One `SavePoint` per slot is the declarative version: three nodes with
+`slot: "1" | "2" | "3"`, each probing into its own row of the menu.
+
 ## Checking your coverage
 
 ```ts
-import { behaviorsWithoutSave } from 'incanto';
-console.log(behaviorsWithoutSave(game.engine.scene.root));
+import { behaviorsWithoutSave, savesWithoutUid } from 'incanto';
+console.log(behaviorsWithoutSave(game.engine.scene.root)); // forgot serialize?
+console.log(savesWithoutUid(game.engine.scene.root)); // forgot the uid?
 ```
 
-Names every behavior in the tree that has props and no `serialize`. Not all of
-them are wrong — a behavior that derives everything from time has nothing to
+`behaviorsWithoutSave` names every behavior with props and no `serialize`. Not
+all of them are wrong — one that derives everything from time has nothing to
 save — but it is the list to read before shipping.
 
-## Autosave
+`savesWithoutUid` is the other half, and none of it is debatable: a behavior
+that DOES serialize, on a node with no uid, is state that goes nowhere.
+`incanto-check` catches the built-ins it can recognise from the JSON
+(`Health`, `ScoreKeeper`, `Collector`); a scene file cannot be asked whether
+YOUR behavior serializes, so this walks the live tree and names those too.
 
-There is no autosave node, on purpose: *when* to save is a design decision
-(checkpoint, level end, every 60s, on quit) and only your game knows. Wire it to
-whatever signal marks the moment:
+## Saving from the scene — `SavePoint`
 
+*When* to save is a design decision (checkpoint, level end, on quit) and only
+your game knows — so the scene still chooses, by picking which signal to wire.
+What it does not need any more is a method of your own to wire it to:
+
+```json
+{ "name": "Save", "type": "Node", "uid": "n_…",
+  "script": { "name": "SavePoint",
+              "props": { "game": "vault", "slot": "1", "label": "Chapter 2" } } }
+```
 ```json
-{ "from": "Level/Exit", "signal": "triggerEnter", "to": "Game", "handler": "onCheckpoint" }
+{ "signal": "triggerEnter", "from": "Level/Exit", "to": "Save", "handler": "save" },
+{ "signal": "collected",    "from": "Gems/Gem1",  "to": "Save", "handler": "save" },
+{ "signal": "won",          "from": ".",          "to": "Save", "handler": "save" }
 ```
+
+| prop | default | meaning |
+| --- | --- | --- |
+| `game` | `"game"` | slot namespace — keeps two games on one origin apart |
+| `slot` | `"1"` | which slot this node reads and writes |
+| `label` | `""` | shown in a load menu |
+| `scene` | `""` | the key a loader routes back to (empty = this scene's `name`) |
+| `restoreOnReady` | `false` | read the slot on the first frame — a "Continue" boot |
+
+Methods: `save()` · `restore()` · `clear()` — and `playtime` / `slotScene()` to
+read. Signals: `saved(slot)` · `restored(count)` · **`noSave`**, which is what
+greys out a Continue button.
+
+`restoreOnReady` lands on the **first frame**, not in `onReady`: `onReady` runs
+children-first, so restoring there would hand the score keeper its state back
+and then watch the root's own `onReady` set it to zero.
+
+**A checkpoint wired to `collected` counts that pickup.** `Pickup` queues its
+free before it announces, so a save taken from the handler records the world
+without it — otherwise the gem came back on the next run with the score that
+counted it already banked.
+
+Still your code when the moment is not a signal — every 60 s, on `visibilitychange`,
+on a quit button: call `engine.captureState()` and `slots.write()` yourself.

package/templates-app/beacon-isle-3d/package.json

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.49.0",
+    "incanto": "^0.51.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.49.0",
+    "incanto": "^0.51.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.49.0",
+    "incanto": "^0.51.0",
     "three": "^0.184.0"
   },
   "devDependencies": {