incanto 0.58.0 → 0.59.0

package/skills/incanto-localization.md

@@ -65,12 +65,29 @@ the `"$assetKey"` references you already write:
 
 ```json
 { "name": "Start", "type": "UiButton", "props": { "text": "@t:menu.start" } }
-{ "name": "Wave",  "type": "UiText",   "props": { "text": "@t:hud.wave" } }
+{ "name": "Wave",  "type": "UiText",   "props": { "format": "@t:hud.wave" } }
 ```
 
-Works on every text-bearing widget: `UiText.text`, `UiButton.text`,
-`UiBar.label`, `UiSelect.label`, `UiBanner.show()`, and `UiDialogue` lines,
-speakers and choices.
+Works on every text-bearing widget: `UiText.text` and `.format`,
+`UiButton.text`, `UiBar.label`, `UiSelect.label` **and `.options`**,
+`UiBanner.show()`, `UiDialogue` lines/speakers/choices — and `Label3D` / 2D
+`Label`, the text that lives in the world.
+
+**A key with a `{}` slot needs `format`, not `text`.** A prop resolves the key
+and paints the result verbatim: `"hud.wave": "Wave {n}"` in `text` puts the
+characters `Wave {n}` on screen. `format` is the template `setText` fills:
+
+```json
+{ "name": "Wave", "type": "UiText", "props": { "format": "@t:hud.wave" } }
+```
+```ts
+wave.setText(String(n));   // "Wave 3" — and it re-reads on a language switch
+```
+```json
+"strings": { "en": { "hud.wave": "Wave {}" }, "ko": { "hud.wave": "{} 웨이브" } }
+```
+
+The slot moves with the language, which is the whole reason it is a slot.
 
 From a behavior, `engine.t(key, params)`:
 
@@ -78,8 +95,9 @@ From a behavior, `engine.t(key, params)`:
 banner.show(this.engine.t('hud.wave', { n: this.wave }));
 ```
 
-`{n}` slots are filled from `params`; a slot with no matching param is left
-alone rather than blanked.
+`{n}` slots are filled from `params` — this is the ONLY path that fills a NAMED
+slot; a scene-JSON prop has no params to fill it from. A slot with no matching
+param is left alone rather than blanked.
 
 ## The language picker
 
@@ -96,10 +114,24 @@ because a player who cannot read the language on screen still has to find theirs
 Picking one switches the game **live** and persists the choice through
 `engine.settings`, so the next visit opens in it.
 
+### Text that lives in the world
+
+`Label3D` and the 2D `Label` resolve `@t:` too, and re-bake their texture when
+the language changes — a sign over a shop door, a nameplate, a damage number.
+The prop keeps the marker; only the painted words change.
+
+```json
+{ "name": "Sign", "type": "Label3D",
+  "props": { "text": "@t:sign.welcome", "height": 0.4 } }
+```
+
 ## What NOT to localize
 
-- **Values, not labels.** `UiSelect.options` are values the game compares
-  against (`"low,medium,high"`); translating them breaks the comparison.
+- **Option VALUES stay identifiers — but you can still translate what is shown.**
+  `UiSelect.options` are what the game compares against, and `@t:` in an option
+  changes only the words on screen: the value `changed` emits is exactly what
+  you wrote. So `"options": "@t:diff.easy,@t:diff.hard"` displays 쉬움/어려움
+  and still hands your handler `@t:diff.easy`.
 - **Node names, group names, asset keys, signal names, action names.** These are
   identifiers.
 - **Anything a behavior parses.** If code does `if (value === 'start')`, that

package/skills/incanto-multiplayer.md

@@ -49,9 +49,32 @@ Authority rules:
 ] }
 ```
 
+**The `network` block is validated at LOAD.** It used to be the one node-level
+block the loader cloned without looking at, and its typos are invisible at
+runtime — a string `sync`, a capitalised `mode`, the plural `syncs` each mean
+"nothing replicates and nothing says so", and produce a report identical to a
+working game's. All three are hard `BAD_FORMAT` errors now, and
+`bunx incanto check` catches them before you ever open a browser:
+
+```
+[BAD_FORMAT] "network.sync" must be an ARRAY of prop names, not "position"
+             — write ["position"] (on 'Player')
+```
+
+Valid keys: `mode` (`owner` | `observer`), `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.
+
 - **ONE owner node per player.** Its `sync` keys are relative to ITSELF
-  (`position` = own prop, `Skin.animation` = child path + prop). Changed values coalesce
-  into one throttled `setMyState({sync: {...}})` per window. Spawned entities (bullets,
+  (`position` = own prop, `Skin.animation` = child path + prop). A change to ANY
+  of them sends ALL of them, once per throttle window — the payload is the whole
+  set, deliberately: backends shallow-merge one level down, so a partial patch
+  would REPLACE the stored `sync` object and erase every key that had stopped
+  changing (a team colour, a skin, a name). Players already in the room would
+  never notice — they applied it once and kept it — while the next joiner
+  rendered the default forever. An idle owner still sends nothing until the
+  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
   instance of the registered scene per OTHER account (self skipped); the flat `sync` patch
@@ -193,8 +216,38 @@ It runs the SAME class body the cloud runs: the v2 globals (`$sender`/`$global`/
 **Verifying a whole match**: `playMultiplayer` from `incanto/test` runs N clients
 against one in-memory server for a fixed number of simulated seconds and reports
 what they ended up sharing — rooms, who saw whom, what each `NetworkSpawner`
-materialised, per-client frame errors, the final room state. See
-`incanto-verifying-your-game.md`.
+materialised, per-client frame errors, the final room state, and **whether the
+clients hold the same VALUES**.
+
+That last part is the one that matters and the one that used to be missing.
+"Saw p2" only ever meant "p2 is in the room" — the kernel puts an empty entry
+there at join — so a game whose replication was completely dead reported exactly
+what a working one did. After the match quiesces, every key in every owner's
+`network.sync` is read on the sender and on each other client's spawned copy and
+compared:
+
+| | |
+|---|---|
+| `missing` | that client never materialised the account at all |
+| `absent` | the key path does not resolve on the spawned scene — a renamed child |
+| `shape` | different array lengths; a componentwise lerp calls that "already correct" |
+| `mismatch` | the values differ beyond the interpolation tolerance |
+| `erased` | the live clients agree, and a LATE JOINER never got it |
+
+`erased` is why the harness brings one more client in after everything settles.
+Players already in the room applied a value once and kept it on their node, so
+they agree with each other while the authoritative snapshot is already wrong —
+a two-browser test cannot see it, and the next person to join sees the default
+forever. Set `lateJoin: false` to skip that half; `seed` makes the whole match
+reproducible.
+
+**What it does not prove.** One in-memory server means no latency, no loss, no
+reordering: this measures the apply path and the protocol shape, never the live
+wire. A reconnect that never re-joins, a throttle that discards a payload, a
+batch dropped on a closed socket — none of those are in reach, and the report
+says so on its own summary line.
+
+See `incanto-verifying-your-game.md`.
 
 **Driving one by hand**: server calls are QUEUED and only run when the event loop
 turns, so a synchronous frame loop enqueues a thousand ticks that never execute —

package/skills/incanto-node-reference.md

@@ -81,6 +81,7 @@ Signals: `animationFinished(name)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -97,6 +98,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -213,6 +215,7 @@ Signals: `finished`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `velocity` | `[0,0]` | array |
 | `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
@@ -232,6 +235,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `velocity` | `[0,0,0]` | array |
 | `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
@@ -713,6 +717,7 @@ Signals: `finished`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `mass` | `1` | number |
 | `gravityScale` | `1` | number |
 | `fixedRotation` | `false` | boolean |
@@ -735,6 +740,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 | `mass` | `1` | number |
 | `gravityScale` | `1` | number |
 | `fixedRotation` | `false` | boolean |
@@ -828,6 +834,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -844,6 +851,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
+| `enabled` | `true` | boolean |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
 
@@ -1377,6 +1385,16 @@ Signals: `dealtDamage(amount, target)`
 
 Signals: `dayPhaseChanged`
 
+### `FloatAway`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `rise` | `1` | number |
+| `seconds` | `0.7` | number |
+| `hold` | `0.3` | number |
+| `drift` | `0` | number |
+| `freeOnEnd` | `true` | boolean |
+
 ### `FollowCamera`
 
 | Prop | Default | Kind |

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

@@ -79,6 +79,32 @@ mesh or one model and warns when the body carries more.
   (capsule recommended), `velocity`, `stickToGround true`, `slopeLimitDeg 45`.
   API: `moveAndSlide()` (call from `fixedUpdate`), `isOnFloor()`.
 
+### `enabled` — a collider that is off for now
+
+Every physics body takes **`enabled`** (default `true`). Off means no contacts
+and no `triggerEnter`/`triggerExit`; the body stays, so nothing is rebuilt and
+re-arming is one write.
+
+```jsonc
+// a melee hitbox: real collider, authored OFF
+{ "name": "Sword", "type": "Area2D",
+  "props": { "collider": { "shape": "circle", "radius": 30 }, "enabled": false } }
+```
+```ts
+sword.enabled = true;    // the active window of the swing
+sword.enabled = false;   // …and done
+```
+
+**Do not arm a hitbox by swapping `collider` in and out.** Replacing the
+collider prop tears the rigid body down and builds a new one — twice per swing —
+and a scene authored `"collider": {}` warns `has no collider — physics skips it`
+on every boot, which is true and unactionable and teaches its reader to ignore
+warnings.
+
+Good for anything that is sometimes solid: a door that opens, a platform that
+phases, a shield that is only up while blocking, a trigger that fires once and
+retires.
+
 Physics simulates WORLD positions: bodies under offset parents work (offsets compose),
 but ancestor ROTATION/SCALE are not supported for physics bodies — keep body ancestors
 untransformed or translation-only.

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

@@ -34,12 +34,34 @@ $ bunx incanto verify                       # finds your scene AND your behaviou
 ✓ loads — the scene is legal and its assets resolve
 ? plays — 8 runs played without reaching a win (4 lost, 4 ran out the clock)
 ✓ feels — 5 of 7 fired — silent: /Game/Boss/Roar, /Game/Boss/Boom
+· agrees — not run — this scene has no `multiplayer` header
 ? draws — the dev server is running on :5173, but no page answered
 
 passes what was measured — plays, draws not measured.
 next: nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`
 ```
 
+### `agrees` — do two clients hold the same values?
+
+Skipped outright unless the scene has a `multiplayer` header. When it does,
+`incanto multiplay` runs a real match headlessly, lets it QUIESCE, then reads
+every key in the owner's `network.sync` on the sender and on each other
+client's spawned copy and compares them — plus one client that joins AFTER
+everything settles, which is the only observer that reads the authoritative
+snapshot fresh.
+
+```
+✓ agrees — 8 replicated value(s) match across clients and a late joiner
+           — over one in-memory server, not a live wire
+✗ agrees — p2 has no `Skin.rotation` for p1 — the key path does not resolve on
+           the spawned scene (a renamed child?), or it was never sent.
+```
+
+That trailing clause is not modesty, it is the measurement's boundary: one
+in-memory server has no latency, no loss and no reordering, so this proves the
+apply path and says nothing about a reconnect that never re-joins or a batch
+dropped on a closed socket.
+
 Runs the rungs below in order and says the ONE thing to do next. Three rules it
 encodes so you do not have to remember them:
 

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.58.0",
+    "incanto": "^0.59.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/platformer-2d/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.58.0",
+    "incanto": "^0.59.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/star-survivor/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.58.0",
+    "incanto": "^0.59.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.58.0",
+    "incanto": "^0.59.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.58.0",
+    "incanto": "^0.59.0",
     "three": "^0.184.0"
   },
   "devDependencies": {