incanto 0.69.0 → 0.70.0

package/skills/incanto-localization.md

@@ -64,7 +64,7 @@ A text prop becomes translatable by naming a key with `@t:` — the same shape a
 the `"$assetKey"` references you already write:
 
 ```json
-{ "name": "Start", "type": "UiButton", "props": { "text": "@t:menu.start" } }
+{ "name": "Start", "type": "UiButton", "props": { "text": "@t:menu.start" } },
 { "name": "Wave",  "type": "UiText",   "props": { "format": "@t:hud.wave" } }
 ```
 
@@ -101,10 +101,18 @@ param is left alone rather than blanked.
 
 ### Authoring the table
 
-The scene header's **advanced** section has a `strings` field — the same
-raw-JSON editor `input` and `multiplayer` use. Until 0.61 it was the one of
-those three the panel did not show, so a localized game could be read by the
-editor and never authored in it.
+The scene header has a **strings** table: one row per key, one column per
+language, `+ key` and `+ language`. Two things it shows that the JSON cannot:
+
+- an **untranslated cell** shows the English it will silently fall back to,
+  greyed — that fallback is the design, not an error, and this is where you see
+  it happening;
+- a key the **base locale is missing** is marked red, because that is the one
+  case that really breaks: nothing to fall back to, so the raw key paints.
+
+Deleting a key a prop still says asks first, and tells you how many props will
+start painting the key. The raw-JSON `strings` field is still in **advanced**
+for pasting a whole table in at once.
 
 ## Checking a translation without a browser
 

package/skills/incanto-multiplayer.md

@@ -34,6 +34,16 @@ Authority rules:
 - movement/cosmetics → **owner-authoritative** (the replication below)
 - score/economy/inventory → **server-function-authoritative** (extend `server.js`;
   `$sender.account` is trustworthy, args are NOT; guard with `$lock`)
+
+  > **`$lock` is NOT reentrant.** Taking one key inside another's callback —
+  > `$lock('clock')` inside `$lock('match')`, one string apart in a
+  > read-modify-write — DEADLOCKS. The preview server runs every client's calls
+  > one at a time, so one stuck call wedges the whole match: every
+  > `setMyState` stops, new players can never join, and `local.tick()` never
+  > resolves. It says so now (`a call has been running for over 5s and every
+  > other client is blocked behind it`) instead of hanging in silence, and
+  > `incanto-multiplay` prints its verdict instead of exiting 13 with nothing.
+  > Take one lock, do the whole read-modify-write inside it, and release.
 - physics/AI run client-side; one-simulator needs (NPC waves) use the host-client pattern
 
 ## Scene JSON
@@ -61,7 +71,9 @@ working game's. All three are hard `BAD_FORMAT` errors now, and
              — write ["position"] (on 'Player')
 ```
 
-Valid keys: `mode` (`owner` | `observer`), `sync` (array of prop names),
+Valid keys: `mode` (`owner` — the only one the engine reads; `observer` was a
+sketch that shipped in the validator's list and was never implemented, so it is
+now refused by name), `sync` (array of prop names),
 `throttleMs` (number). An `owner` with an empty `sync` is an error too — it is
 a half-finished edit that behaves exactly like a broken one.
 
@@ -76,7 +88,11 @@ a half-finished edit that behaves exactly like a broken one.
   keyframe (`keyframeMs`, default 2 s) comes round, which is also what heals a
   send that never reached the wire. Spawned entities (bullets,
   pickups) go through **collections**, never extra owner nodes.
-- **`NetworkSpawner`** (register with `registerNodesNet()`): `source: "users"` spawns one
+- **`NetworkSpawner`** (register with `registerNodesNet()`): **`scene` is REQUIRED** —
+  the key you registered the remote's scene under. Without one the spawner used to
+  return from every frame and no remote ever appeared, on a scene that loaded,
+  audited and played clean. A spawner in a game with no multiplayer at all says so
+  after two seconds, by name. `source: "users"` spawns one
   instance of the registered scene per OTHER account (self skipped); the flat `sync` patch
   applies onto the spawned scene's root; `position` lerps when `interpolate: true`
   (remote entities render slightly in the past — that's correct). Emits
@@ -98,7 +114,10 @@ import { NetworkManager, registerNodesNet, LoopbackHub } from 'incanto/net';
 // node (`Unknown node type 'Node2D'`).
 registerNodes2D();
 registerNodesNet();
-const scene = loadScene(json);
+// `{ engine }` on a MANUAL boot, always: `onReady` runs during the load, and a
+// behaviour that reads `this.engine`/`this.rng` there (Wander draws its first
+// heading in it) throws TREE_VIOLATION without it.
+const scene = loadScene(json, { engine });
 engine.setScene(scene);
 
 // DEV / offline / split-screen: zero infrastructure, built-in protocol only
@@ -142,6 +161,31 @@ delta-merged ARRAY `[{...state, account, __updated}]` → an account-keyed Recor
 `subscribeRoomCollection` arrives as `{items:[{__id,…}], changes}` → a `__id`-keyed
 Record. It also re-issues every subscription after a reconnect.
 
+**When the socket drops it keeps trying** — 0.5s, 1, 2, 4, then 8 up to eight
+attempts — and SAYS so on the first failure and again if it gives up:
+
+```
+[incanto] the multiplayer connection dropped and the server would not take it
+back (ECONNREFUSED). Retrying — other players cannot see this one until it
+comes back.
+```
+
+There used to be one attempt and no catch, so a server that was still
+restarting rejected it, the rejection escaped an unawaited `void reconnect()`,
+the re-issue loop never ran and nothing scheduled a second try: **the session
+never came back, and nothing said a word.** A `connect()` that resolved `false`
+was taken for success and re-issued every subscription onto a dead socket.
+
+**A replication send that fails now reaches `stats().errors`.** It was
+`void this.setMyState(…)`, so the rejection went to the host's
+unhandled-rejection channel — not `engine.log`, not the error count. A client
+whose socket died kept playing perfectly on its own screen while everyone else
+watched it frozen, and the run reported `errors: 0`.
+
+**A transport that REFUSES the connection now throws** `NETWORK_UNAVAILABLE`
+out of `NetworkManager.create`, instead of returning a fully-formed manager
+with `connected === false` that had joined nothing.
+
 ## Writing a custom transport (any backend)
 
 Implement `NetworkTransport` (exported from `incanto/net`): `connect`/`disconnect`,
@@ -354,6 +398,22 @@ Kernel constraints (agent8 platform facts — don't fight them):
 - room data is ephemeral — persist to `$global` before rooms empty
 - never expose unthrottled per-frame remoteFunction (rapid calls are rejected); guard score/economy with `$lock`
 
+## Changing scene in a multiplayer game
+
+A manager is bound to the ROOM the scene it was created for declares.
+
+- **Same room, new scene** (level 2 of one match, a map vote): nothing to do.
+  The manager rebinds to the incoming tree and keeps broadcasting; the new
+  owner node re-sends its full state.
+- **Different room** (lobby → match, leaving for another arena): create a NEW
+  manager for the new room. Broadcasting stops on purpose — leaking one room's
+  state into another is exactly what the binding prevents — and the engine logs
+  an error saying which room it is bound to and which the scene asked for.
+
+Dispose the old handle whenever you like, before or after creating the new one:
+disposing a handle that a later `create()` already superseded leaves the live
+manager alone.
+
 ## State rules
 
 - JSON-safe by construction: vectors as arrays, no `undefined`/`NaN`/typed arrays
@@ -392,3 +452,23 @@ changed nothing — a ✓ that could not have been a ✗.
 
 If your server cannot be loaded the run REFUSES rather than quietly measuring a
 game without its own rules.
+
+**Pass `--behaviors src/behaviors.ts` too.** A sync key is very often written by
+game TypeScript (`player.firing = input.isPressed('fire')`), and without the
+behaviors the harness cannot tell a DEAD sync key from one whose writer was
+never loaded — so it says nothing about them at all. With the behaviors there,
+a key the owner cannot read is reported as what it is:
+
+```
+✗ p1 declares `firing` in its `network.sync` and cannot READ it — it is never
+  sent, so no client will ever see it change.
+```
+
+That is the most complete failure of replication there is, and the rung used to
+grade it PASS: an unreadable key was dropped from the comparison, so
+every client agreed perfectly about a value nobody ever sent.
+
+**`collection:` spawners are compared too.** The account-keyed half of the check
+cannot see them — a bullet has no account — so a spawner that took a hundred
+entities off the wire and materialised none of them used to be entirely silent.
+Now it says which spawner, and how many entities it dropped.