incanto 0.69.0 → 0.71.0

package/skills/incanto-save-slots.md

@@ -42,10 +42,17 @@ Reloading from source sidesteps all three. The structure comes from the file
 (authoritative, already validated); the save carries only what the file cannot
 know.
 
-**The cost, stated plainly: spawned enemies and mid-level positions are not
-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.
+**The cost, stated plainly: spawned enemies, mid-level positions and anything
+else that lives in the TREE are not 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.
+
+"Inventory" there means a behavior's DATA — a list of item ids, a wallet, a
+quest flag. An inventory made of WIDGETS MOVED BETWEEN SLOTS
+(`incanto-hud.md`'s drag recipe) is structure, so it reloads exactly as the
+file has it: measured on a bench with one item dragged across, the save
+mentions no slot and the reload puts the item back on its shelf. That skill
+prints the `serialize` that keeps the slot map as data.
 
 **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
@@ -83,11 +90,59 @@ class QuestLog extends Behavior {
 `maxHealth` no — that comes back from the scene JSON, and duplicating it makes
 old saves fight your balance patches.
 
+**Randomness is carried for you.** `captureState()` records where
+`engine.rng` has got to and `restoreState()` puts it back, because without that
+a load replays the seeded sequence from the top — the first "random" event after
+a save is the one the RUN opened with, and every loot roll, wander and spawn
+wobble repeats the opening of the game. Nothing to do; `engine.rng.position` is
+readable if you want it for something else.
+
 `deserialize` is defensive on purpose: that data may come from a build of your
 game that shipped six weeks ago. Check what you read.
 
-Built-ins that already save: `Health` (current, dead), `ScoreKeeper` (score,
-lives, won/lost), `Collector` (total).
+Built-ins that already save: `Collector` (total), `Currency` (amount),
+`DayNight` (hour, paused), `Health` (current, dead), `SavePoint` (playtime),
+`ScoreKeeper` (score, lives, won/lost), `WaveSpawner` (which wave).
+
+`WaveSpawner` RESTARTS the wave you were on rather than resuming mid-spawn —
+spawned entities are never restored, so resuming "four enemies into wave 3"
+would resume a wave whose enemies do not exist. `waveStarted` fires again, so a
+HUD wired to it catches up on its own.
+
+Every one of them needs a `uid` on its node, and `incanto-check` says so if it
+has none — that check reads the same list.
+
+## Tell the screen: `announce()`
+
+`deserialize` writes fields. Your HUD is wired to **signals** — that is what
+`incanto-hud.md` teaches and the only thing the editor can wire — so a restore
+that only writes fields leaves the screen showing a fresh start:
+
+```
+HUD    score="0"    hp=100/100  gems="0"
+TRUTH  score=1400   hp=38       gems=7
+```
+
+with no error anywhere and a restore report of `{missing: [], restored: 3}`.
+
+So there is a third hook, called once after the whole restore pass:
+
+```ts
+override announce() {
+  this.emit('questChanged', this.stage);   // what the screen SHOWS
+}
+```
+
+**Emit only what displays.** Not `died`, not `won`, not `levelUp` — a save is
+being read, nothing just happened, and re-firing an outcome signal on load is
+how a Continue lands straight on the game-over screen it was loaded to escape.
+It runs after every `deserialize` in the pass, so a handler that reads a sibling
+sees restored values there too.
+
+`Health`, `ScoreKeeper`, `Collector` and `Currency` implement it. `ScoreKeeper`
+gained **`livesChanged`** for this: `lifeLost` is the EVENT (flash, sound,
+respawn) and fires only on a real loss, while `livesChanged` is the COUNT and
+fires on both. Wire a lives counter to `livesChanged`.
 
 ## Every node you save — and every node that VANISHES — needs a uid
 
@@ -109,6 +164,20 @@ it just wrote is already wrong. It does not guess a replacement: a uid survives
 a rename and a reparent, and a saved PATH would point at whatever node moved
 into that slot after your next edit.
 
+**Put the uid on the node that OWNS the state, not on its art.** A collectible
+is normally one node with the script and a plain child for the sprite:
+
+```jsonc
+{ "name": "Sword", "type": "Area2D", "uid": "n_sr9scvhygy01mgxr",
+  "script": { "name": "ItemPickup" },
+  "children": [ { "name": "Icon", "type": "Sprite2D" } ] }   // no uid needed
+```
+
+Freeing the sword takes the icon with it, so the parent's uid in `#freed`
+records both — the audit says nothing about the child, and adding a uid to it
+changes nothing. What the audit still catches is the child that goes while its
+parent LIVES: that one really does come back.
+
 
 
 The uid is the join key, because it is the one identifier that survives a rename
@@ -156,6 +225,35 @@ if (slot) {
 `onReady` is where a behavior sets its starting values, so restoring first would
 be overwritten.
 
+**Not from `onReady` itself, either**, which is the tempting place to put
+"continue my run" and the one that cannot work: the ready pass runs while the
+scene is still loading, and `engine.scene` — which both halves of this API read
+— is not assigned until `setScene`. Both say so now rather than answering
+quietly:
+
+```
+[incanto] restoreState() ran before the engine had a scene, and restored NOTHING.
+```
+
+Before that it reported every uid in the save as `missing`, which is the
+signature of a save format change, so the hunt started in the wrong place
+entirely.
+
+**To keep the continue INSIDE the game** (where a harness can reach it —
+`runScript` boots the scene, never your `main.ts`), do it on the first frame:
+
+```ts
+class Game extends Behavior {
+  private continued = false;
+  override update(): void {
+    if (this.continued) return;
+    this.continued = true;
+    const slot = this.slots.read('1');
+    if (slot) this.engine.restoreState(slot.state);
+  }
+}
+```
+
 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.
@@ -194,6 +292,49 @@ explicitly when one file is entered more than one way (`"chapter-2-rescue"`).
 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.
 
+## State that outlives a SCENE, not just a session
+
+A save and a scene swap are different mechanisms and the word "persist" covers
+both, so this is the one thing a two-scene quest game has to be told: **the
+three hooks above carry state across a SAVE and nothing across a SWAP.**
+
+`goToScene` replaces the tree. The new scene's behaviors are new objects with
+`onReady` starting values — a quest flag set in the village is gone when the
+cellar loads, and nothing reports it, because nothing went wrong.
+
+A quest that has to survive both is three parts, and each one alone fails
+differently. Measured on a two-scene game built for this:
+
+| | swap | save |
+| --- | --- | --- |
+| a module object in YOUR code | ✅ crosses | ❌ `captureState()` cannot see it — `restored: 0`, and the report is clean |
+| `serialize`/`deserialize` alone | ❌ the new scene's behavior starts fresh | ✅ `restored: 1` |
+| …plus `announce()` | — | the HUD, which otherwise reads the old value over restored state |
+
+So: keep the truth in a module object, and give ONE behavior that exists in
+every scene the job of writing it in and out.
+
+```ts
+/** Not engine state — YOUR game's, and a module is where a swap cannot reach. */
+export const quest = { accepted: false, carrying: false, done: false };
+
+export class Hold extends Behavior {
+  static signals = ['questChanged'];
+  override serialize() { return { ...quest }; }
+  override deserialize(d: JsonValue) { Object.assign(quest, d as object); }
+  override announce() { this.emit('questChanged', quest.stage); }  // the screen
+}
+```
+
+**Give that node the same `uid` in every scene it appears in.** The save is keyed
+by uid, so `village.scene.json` and `cellar.scene.json` sharing one uid on their
+root is what lets a save taken in either one restore into either one. Generate it
+once with `newUid()` and paste it into both files — this is the single case where
+one uid legitimately appears in two scenes, because it is one thing.
+
+`behaviorsWithoutSave()` finds the behavior you forgot: on the game above it
+named `/Village (Hold)` first, out of 46% of the scripted nodes it lists.
+
 ## A title screen, in JSON
 
 A `SavePoint` can ASK without loading. `probeOnReady` fires on the first frame
@@ -220,7 +361,19 @@ 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.
+the three lines above. `examples/lanternhold-2d` ships this exact menu — a fresh
+install with no Continue, and a returning player whose slot line reads what the
+game SAVED (`last saved: Village` — the SavePoint's own label, not something the
+title screen guessed).
+
+Two things that cost a run each to learn there:
+
+- **A hand-written slot with `state: {}` restores nothing.** The engine says so
+  — `restored 0 of 2 saveable behaviour(s)` — but a menu built on one looks
+  perfectly green. Write the slot the way the game writes it.
+- **Hold the engine before you route.** `goToScene` frees the tree the button
+  lives in, so `this.engine` on the next line throws. See "Game flow" in
+  `incanto-gameplay-behaviors.md`.
 
 ## Several slots
 
@@ -235,6 +388,63 @@ 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.
 
+### Restore into a scene that has been PLAYED
+
+A save is restored INTO a freshly loaded scene. The structure comes from the
+file; `#freed` then takes away the nodes that run had consumed — and nothing
+puts any back. So a pause-menu Load, a slot menu, or death wired straight to
+`SavePoint.restore()` leaves THIS run's collectibles deleted:
+
+```
+CONTROL restart the scene from source, then restore → gems [Gem2,Gem3], won
+death wired straight to restore (no reload)         → gems [Gem3],       lost
+```
+
+…and the next autosave writes that hybrid back to the slot, so the unwinnable
+run survives a page reload. Reload first — `GameFlow.restart` with
+`restoreOnReady`, or `restartScene(engine)` and then restore. After a restart
+the SavePoint node is a NEW one, so a held behavior reference is stale.
+
+`report.stale` names the authored nodes this tree consumed that the save does
+not account for, and the engine warns when it is non-empty. It is a warning
+rather than an error because a node that freed ITSELF on a timer lands in the
+same set, and only your game knows which of its nodes are transient.
+
+### A save hook that throws
+
+`serialize()`, `deserialize()` and `announce()` are your code, and your code
+throws. All three are caught now, and each says something different:
+
+- a **`serialize()`** that throws leaves a HOLE in the save — that behavior's
+  whole run is missing — so `SavePoint.save()` **refuses to write** and emits
+  `saveFailed` instead of `saved`. Overwriting the previous slot with a holed
+  save destroys the progress the player actually had. `engine.lastCaptureFailures`
+  names them if you call `captureState()` yourself.
+- a **`deserialize()`** that throws is in `report.skipped` as before, and now
+  also in **`report.refused`** with the reason — a save this build cannot read
+  and a node with no `deserialize` at all are different problems.
+- an **`announce()`** that throws means the state IS restored and the SCREEN was
+  not told: **`report.unannounced`**. It reported `restored: 2, expected: 2`
+  over a HUD showing zeros, and it does not take an override to reach — a
+  `getNode('HUD/ScoreLabel')` on a renamed node lands there.
+
+### A save that cannot be read
+
+A truncated write (a power cut, a tab closed mid-save) or a slot from a build
+that predates this one is not offered by `all()` — but it is not *gone* either,
+and a load menu that quietly shows one fewer row than the player remembers is
+the worst thing a save system can do:
+
+```ts
+for (const { id, why } of slots.problems()) {
+  render(`slot ${id}: ${why === 'corrupt' ? 'damaged' : 'from an older version'}`);
+}
+```
+
+The slot INDEX is rebuilt from storage when it cannot be read, so one corrupt
+byte in a derived list no longer hides every save on the machine — nor lets the
+next `write()` orphan them. It says so on the console when it does.
+
 ## Checking your coverage
 
 ```ts

package/skills/incanto-scene-json-authoring.md

@@ -33,14 +33,22 @@ wiring, and composition are all in the file. TS is for *behavior only* (attached
 ```
 
 - `format` MUST be `1`. `type` MUST be `"scene"`. `name` non-empty.
-- `dimension` is optional: `"2d"` or `"3d"` only.
+- `dimension` is optional: `"2d"` or `"3d"` only. Left out, it is INFERRED from
+  the node types in the tree (anything ending `3D` makes the scene 3D) — write
+  it anyway, because it is what the environment validator, the audit's
+  no-camera/no-light warnings and `physics: "auto"` all read.
 - `fragment` (optional, default `false`) says this file is a PIECE of another
   scene — a spawner's prefab, a sub-scene something instances — and is never
   rendered on its own. It changes nothing at runtime; it tells the checker to
-  stop asking a prefab where its camera and its sun are. Set it on any scene
-  you load from TypeScript and hand to a spawner. (A scene another scene
-  embeds with `instance` needs no key — `incanto-check` walks the project and
-  can see that for itself.)
+  stop asking a prefab where its camera and its sun are, and to stop answering
+  the two questions only the HOST can answer: a node path that leaves the file
+  (`/root/Bolts` is the fragment's own root only while the fragment is alone)
+  and a `DamageOnContact.targetGroup` whose victims live in the host scene.
+  Those two are still NAMED, with a reworded verdict — a typo is most likely in
+  exactly this file, written away from the scene that gives it meaning. Set it
+  on any scene you load from TypeScript and hand to a spawner. (A scene another
+  scene embeds with `instance` needs no key — `incanto-check` walks the project
+  and can see that for itself.)
 - `viewport` (optional) makes scene JSON own responsive layout: author the world
   in fixed `design` pixels (`[width, height]`, positive numbers) and the renderer
   maps them onto any canvas size. `fit`: `"expand"` (design rect always fully
@@ -96,12 +104,24 @@ Rules the engine enforces with **hard errors** (it never warns silently):
 3. Prop keys and value kinds are validated against the type's schema:
    unknown key → `UNKNOWN_PROP` (message lists valid keys); wrong JSON kind
    (e.g. string where the default is boolean) → `PROP_TYPE_MISMATCH`.
+   A few props accept TWO kinds — `Flowers3D.density` takes a preset name or
+   plants per m², `Water3D.underwater` takes `true`/`false` or a settings
+   object — and `incanto-node-reference.md` names both in its Kind column
+   (`one of: lush sparse none, or number`). The error names them too, so a
+   value the loader refuses tells you every shape it would have taken.
 4. Sibling names must be unique. Colliding names are auto-renamed by incrementing a
    trailing number (`Enemy` → `Enemy2` → `Enemy3`) — **write unique names yourself** so your
    connection paths stay valid (connections resolve after renaming).
 5. Node names must not contain `/` or `%` and must be non-empty.
 6. `groups` are string tags for queries (`getNodesInGroup`, connection filters).
    `tags` is free-form JSON for game-logic identity (`{"kind": "ITEM", "value": 10}`).
+   **`groups` is a LIST and `tags` is an OBJECT**, and the loader now says so:
+   `"groups": "player"` used to load clean and spread the string one CHARACTER
+   at a time (`["p","l","a","y","e","r"]`), so `player` was in no group and
+   every query and `filter: {group: "player"}` silently matched nothing. Every
+   node key is checked for its KIND now — `props`/`overrides` an object,
+   `children` a list, `uid` a non-empty string from `newUid()` — as are the
+   header's `constants`, `multiplayer` (objects) and `connections` (a list).
 7. `script` resolves to a registered Behavior at load (`incanto-behaviors-and-scripts.md`);
    `network` drives multiplayer replication (`incanto-multiplayer.md`). Both round-trip
    losslessly through export.
@@ -321,10 +341,21 @@ that do exist at the failing spot).
             never recovers.
   ```
 
-  `died → ScoreKeeper.addScore` is the natural way to score a kill and it sets the
-  score to `NaN` on the first one, with the win condition then permanently out of
-  reach. A handler that DEFAULTS what it is not given is correct and stays silent:
-  `won → GameFlow.win` works, because `win(text = 'YOU WIN')` needs nothing. On **both**, it is
+  `died → ScoreKeeper.addScore` is the natural way to score a kill and it used to
+  set the score to `NaN` on the first one, with the win condition then
+  permanently out of reach. The numeric handlers REFUSE a non-number now, so the
+  same wire fails loudly instead — and so does the one the arity check cannot
+  see: `clicked → addScore` hands the NODE, which is one argument into one
+  parameter, and `score + node` is a STRING that grows forever. A handler that DEFAULTS what it is not given is correct and stays silent:
+  `won → GameFlow.win` works, because `win(text = 'YOU WIN')` needs nothing.
+
+  Writing your OWN handler, the same rule applies to you: an optional parameter
+  is a **default**, not a `?`. `hurt(amount: number, from?: Node)` counts as
+  needing 2, because `?` is a TypeScript annotation that does not survive to
+  runtime — write `from: Node | undefined = undefined` and the wire is judged on
+  what it actually needs. Every engine method a wire can name has been corrected
+  to this; before that, four of five documented HUD wires were reported as
+  broken while working perfectly. On **both**, it is
   `AMBIGUOUS_HANDLER`: the node's method wins, so the script's would never run
   and nothing would say so. A core node answers to 62 public methods before any
   adapter adds more (`stop` `play` `show` `clear` `say` `start` `free` …), which
@@ -333,7 +364,11 @@ that do exist at the failing spot).
 - Unresolvable `from`/`to` → `DANGLING_CONNECTION` at load. Renaming a node breaks its
   connections **loudly** — update paths in the same edit.
 - `filter` gates firing on the first emitted argument: it must be a node in `filter.group`
-  and/or match every `filter.tag` entry. With `once: true`, the connection is consumed only
+  and/or match every `filter.tag` entry. **A filter's keys are `group` and `tag`, and a
+  connection's are `[signal, from, to, handler, once, filter]`** — anything else is a load
+  error, because a filter the matcher cannot read (`{"gruop": "player"}`, or the bare
+  string `"player"`) passes EVERYTHING, which is the opposite of what a filter is for, and
+  `"once": "no"` is truthy so it fires exactly once. With `once: true`, the connection is consumed only
   when the filter matches.
 
 ## Sub-scene composition
@@ -345,7 +380,20 @@ that do exist at the failing spot).
 - `instance` embeds another scene's tree; `overrides` deep-merge onto the sub-scene root's
   props. At the instancing site, `groups` and `children` COMPOSE (union/append), while
   `tags`/`script`/`network` REPLACE the sub-scene root's values when declared (omitted = kept).
-- The sub-scene's own `connections` are wired inside its subtree automatically.
+- The sub-scene's own `connections` are wired inside its subtree automatically,
+  and so are its `assets`, `input`, `strings`, `constants` and `orderGroups` —
+  **a prefab brings everything it declares**. (Its `orderGroups` used to come
+  through as NAMES only, so `"orderGroup": "loot"` validated and the band's
+  number was dropped: the sprite sorted in the default band and the scene loaded
+  clean.) A `coin.scene.json` with its own
+  spritesheet, or a `player.scene.json` with its own `move`/`jump` bindings, is
+  a complete, reusable thing.
+- The HOST wins any asset key, action name or string it declares itself, so a
+  level can re-point a prefab's art or rebind its controls without editing the
+  prefab. Two INSTANCED scenes declaring one asset key with different urls — or
+  one action name with different keys — is a hard error naming both:
+  first-writer-wins would hand the second prefab the first one's art in silence.
+  The same key with the same value is just two prefabs agreeing.
 - There is **no** scene inheritance — composition only.
 - Current limitation: exporting expands instances into full trees (the `instance` reference is
   not preserved on export yet).
@@ -373,6 +421,12 @@ that do exist at the failing spot).
 | `DUPLICATE_BEHAVIOR` | two classes registered under one behavior name | rename one, or `{ replace: true }` for hot reload |
 | `TREE_VIOLATION` | invalid name, re-parenting without detach, cycles, double root | follow the rule in the message |
 
+Every one of these lists what WOULD have worked, and names the nearest
+candidate when there is one — `Unknown node type 'Label2D'. Did you mean
+"Label"?`, `Unknown prop 'size' on 'Label'. Did you mean "fontSize"?`. A name
+that resembles nothing gets the list alone, because a suggestion that is not the
+answer is worse than none.
+
 Scene-load and registry errors carry structured `details` (`path`, `uid`, `nodeType`,
 `prop`, `signal`, `validOptions`) mirroring the prose — prefer those over regexing the
 message (a few runtime errors still carry prose only). Scene-load
@@ -384,7 +438,10 @@ errors append the offending node's path: `… (at '/Level/Enemies/Slime3')`.
 import { loadScene, registerCoreNodes, duplicateNode } from 'incanto';
 
 registerCoreNodes();                            // explicit — never an import side effect
-const scene = loadScene(json, { resolveScene }); // throws IncantoError on any problem
+// `{ engine }` on a manual boot: `onReady` runs during the LOAD, so a behaviour
+// that reads `this.engine` or `this.rng` there throws without it. `createGame2D`
+// /`3D` and `runScript` pass it for you.
+const scene = loadScene(json, { engine, resolveScene }); // throws IncantoError on any problem
 scene.root.getNode('Player').emit('hit', 10);
 const copy = duplicateNode(scene.root.getNode('Coin'));
 const exported = scene.toJSON();                 // lossless (delta-only props)