incanto 0.60.0 → 0.62.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-BjC88k97.js"></script>
+    <script type="module" crossorigin src="./assets/index-D422P4kW.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

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

package/schemas/scene.schema.json

@@ -295,6 +295,9 @@
         {
           "$ref": "#/$defs/Particles3D"
         },
+        {
+          "$ref": "#/$defs/Respawn"
+        },
         {
           "$ref": "#/$defs/RigidBody2D"
         },
@@ -3696,6 +3699,10 @@
             "align": {
               "type": "string",
               "default": "left"
+            },
+            "opacity": {
+              "type": "number",
+              "default": 1
             }
           },
           "additionalProperties": false
@@ -5323,6 +5330,90 @@
       },
       "required": ["name", "type"]
     },
+    "Respawn": {
+      "type": "object",
+      "x-signals": ["respawned"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "Respawn"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "target": {
+              "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
+              "default": ".."
+            },
+            "below": {
+              "default": null
+            },
+            "to": {
+              "type": "array",
+              "default": []
+            },
+            "resetVelocity": {
+              "type": "boolean",
+              "default": true
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "enum": ["owner", "observer"]
+            },
+            "sync": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "throttleMs": {
+              "type": "number"
+            }
+          },
+          "additionalProperties": false
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "RigidBody2D": {
       "type": "object",
       "x-signals": ["triggerEnter", "triggerExit"],

package/skills/incanto-3d-models.md

@@ -94,7 +94,7 @@ meta (name/authors) + humanoid bone count. Decision rules:
 
 `ModelInstance3D` props: `model` (`$key` or a direct URL), `targetHeight` (>0 uniformly
 scales the model to stand that many units tall — composes with the node `scale`, reactive
-at runtime; see "Sizing" below), `animation` (see below), `tint` (hex; `""`=off — multiplies into
+at runtime; see "Sizing" below), `animation` (see below), `tint` (any CSS colour — `"#5f8f4a"`, `"chartreuse"`; `""`=off — multiplies into
 every material to RESKIN one shared GLB into many variants, e.g. base human → green
 zombie; clones materials per instance so other instances are untouched),
 `metalness`/`roughness` (0..1 overrides applied to EVERY material; `-1`=keep authored —

package/skills/incanto-assets.md

@@ -86,7 +86,16 @@ Every catalog entry has a `url` that is directly usable; there are two classes:
   `copy` does this for you and prints the ready-to-paste JSON — for animated
   sheets it includes the full `animations` map (idle/move/attack…) derived from
   the sheet metadata. `Sprite2D.texture` / `AnimatedSprite2D.sheet` take a
-  `"$assetKey"` ref (the engine hard-fails on a raw URL).
+  `"$assetKey"` ref, and the engine hard-fails at LOAD on anything else — a raw
+  URL, a bare catalog id, or a `$key` the scene does not declare:
+
+  ```
+  [UNKNOWN_ASSET] 'Coin.texture' names asset '$coinn', which the scene does not
+                  declare. Declared: [coin, gem]. (at '/Room/Coin')
+  ```
+
+  (It genuinely did not, until 0.61: the check lived in the renderer, so only a
+  browser ever reached it and a typo'd ref simply drew nothing.)
 
 The scene **composer (incanto-editor)** wires all of this for you: the inspector
 shows an asset PICKER on every texture/sheet/map prop — browse the built-ins by

package/skills/incanto-audio.md

@@ -138,9 +138,13 @@ motor.stop(1.2);       // …or a slow custom fade
 } }
 ```
 
-Methods: **`play()`**, **`stop()`**. Signal: **`finished`** (fires when a
-non-looping `src` clip ends — connect it to clean up or chain sounds). Procedural
-presets are fire-and-forget one-shots: they do not emit `finished`.
+Methods: **`play()`**, **`stop()`**. Signal: **`finished`** — connect it to clean
+up or chain sounds. It fires when a non-looping `src` clip ends AND when a
+procedural preset does: a preset's length is `attack + sustain + decay`, known
+exactly, so `player.playing` is true for that long and `finished` arrives at the
+end. It is measured on the unscaled clock, because a paused game still hears the
+tail of the hit that paused it, and it fires headlessly too — the length is
+arithmetic, not a device. `stop()` is not a finish and does not emit.
 
 ### Autoplay + the browser gesture-unlock
 
@@ -175,14 +179,14 @@ and models that 404'd:
 
 ---
 
-## 2b. Spatial (3D positional) audio
+## 2b. Spatial (positional) audio
 
-Set **`spatial: true`** on an `AudioPlayer` in a **3D scene** and the sound pans
-(left/right) and attenuates by **distance** — the emitter is the node's world
-position, the **listener is the active `Camera3D`** (the one marked `current`).
-The 3D adapter feeds the emitter + listener pose to the panner every frame, so
-moving the emitter or the camera updates the sound live. Works for BOTH paths
-(procedural `preset` and a `src` file).
+Set **`spatial: true`** on an `AudioPlayer` and the sound pans (left/right) and
+attenuates by **distance** — the emitter is the node's world position, the
+**listener is the active camera** (`Camera3D` or `Camera2D`, the one marked
+`current`). The adapter feeds the emitter + listener pose to the panner every
+frame, so moving the emitter or the camera updates the sound live. Works in both
+dimensions and for BOTH paths (procedural `preset` and a `src` file).
 
 ```jsonc
 // Attach under a moving Node3D — it emits from THAT node's world position.
@@ -214,9 +218,13 @@ listener driven by the camera's world position + orientation. The pure
 distance-gain + pan-sign math (`spatialGain`, `spatialPan`, exported) is what the
 non-WebAudio paths use, so headless gameplay is unaffected.
 
-> **2D scenes:** spatial is currently **ignored** (no listener is fed) — a 2D
-> sound plays non-positionally regardless of `spatial`. Pan a 2D sound yourself
-> from the camera-relative x-offset if you need it. Spatial is a 3D feature.
+> **2D scenes** work the same way: the listener is the active `Camera2D` (its
+> world position is the view centre, and its own rotation turns the stereo image
+> with it). The one difference is the UNIT — a 2D scene measures in PIXELS,
+> and `refDistance: 1` / `maxDistance: 50` are metre-shaped defaults that put a
+> sound at its quietest about one sprite away. Set them to your level's scale
+> (`refDistance: 100`, `maxDistance: 900` is a reasonable start); `incanto check`
+> warns when it sees `spatial: true` in a 2D scene with the defaults left alone.
 
 > **Headless / verify VM:** spatial is a no-op like all audio — `play()` won't
 > throw and your gameplay logic is unaffected.

package/skills/incanto-behaviors-and-scripts.md

@@ -102,7 +102,7 @@ What behavior code actually calls at runtime — all instance methods, no global
 | `engine.stop()` / `engine.start()` | pause / resume the loop — stop resets the clock and accumulator, so no banked sim time leaks into the resume |
 | `engine.step()` | advance exactly ONE fixed step + one update (both dt = the fixed step) — the unit of time for headless tests |
 | `engine.tick(timestampMs)` | manual frame advance — takes an **absolute** ms timestamp (rAF-style), NOT a dt; the first call after (re)start only primes the clock |
-| `engine.setScene(scene)` | swap scenes: the previous root is freed, the input map is cleared and redeclared from the new scene's `input{}`, then `sceneChanged` fires |
+| `engine.setScene(scene)` | swap scenes: the previous root is freed, the input map is cleared and redeclared from the new scene's `input{}`, the clock resets (`time`, `unscaledTime`, and **`timeScale` back to 1** — a level restarted out of a frozen game-over must not boot frozen), then `sceneChanged` fires |
 | `engine.stats()` | live perf counters `{ fps, frameMs, nodes, running }` — fps/frameMs average the last ~60 REAL `tick` frames (headless `step()` runs report 0), nodes is the current tree size. GPU counters (triangles/draw calls) live on `renderer.stats()` / the merged `game.stats()` |
 
 The recurring traps: `duplicateNode` does NOT insert the clone anywhere — a
@@ -138,11 +138,50 @@ declared by their classes. Escape hatch for runtime one-offs: `node.declareSigna
 ]
 ```
 - `handler` must exist on the target NODE or its BEHAVIOR — hard `UNKNOWN_HANDLER`
-  otherwise (validated at load; node methods take precedence on invocation).
+  otherwise, and hard `AMBIGUOUS_HANDLER` when BOTH have it (node methods take
+  precedence on invocation, so the script's would never run). Prefix handlers
+  with `on` and the question never comes up.
 - Handlers receive the EMITTED args only (e.g. the other body for `triggerEnter`) — not
   the emitting node. For per-emitter logic, attach a small behavior to the emitter itself
   (see the `Pickup` pattern: a coin's own `triggerEnter` → its own `onTaken` → `queueFree`).
 
+## Respawn (core node — catch a player who leaves the world)
+
+Hang it off the thing it guards. That is the whole feature:
+
+```json
+{ "name": "Player", "type": "RigidBody3D", "props": { "…": "…" },
+  "children": [
+    { "name": "Controller", "type": "CharacterController3D" },
+    { "name": "Catch", "type": "Respawn" }
+  ] }
+```
+
+With no props it guards its parent, catches it 50 m under the spawn (1000 px in
+2D — the same line `incanto-playtest` calls `fell`), puts it back where it
+started and zeroes the velocity the fall built up. Works in both dimensions.
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `target` | `".."` | who is being caught — the parent, normally |
+| `below` | `null` | the line, in the scene's own down. `null` = auto (see above) |
+| `to` | `[]` | where to put it back. Empty = wherever it started |
+| `resetVelocity` | `true` | drop the speed the fall built up — off and it falls straight back through |
+
+Signal `respawned(target, y)`, and a `falls` counter. It deliberately does NOT
+decide what falling COSTS: wire `respawned` to a `ScoreKeeper.loseLife` or a
+`Health.damage` if it should hurt, and leave it alone if it should not.
+
+**A node, not a behavior**, because a node holds one behavior and the player's
+is already spoken for.
+
+Nothing in the engine did this before 0.62, and five shipped examples proved
+what that cost: with the `plays` rung finally counting defects,
+`basic-3d-sideview` failed 8 seeded runs of 8, `water-lake-3d` 7,
+`water-ocean-3d` 5, `water-pool-3d` 4, `water-river-3d` 1 — every one of them
+the player walking off the terrain and falling forever. One `Respawn` node each,
+no TypeScript, and all five are clean.
+
 ## Timer (core node — never setTimeout in game logic)
 
 ```json
@@ -166,7 +205,9 @@ Child of a `CharacterBody2D` (hard error otherwise):
 - Defaults: `mode 'platformer'`, `maxSpeed 220`, `jumpHeight 64`, `moveAction 'move'`,
   `jumpAction 'jump'`. Timer defaults: `waitTime 1`, `oneShot false`, `autostart false`.
 - ⚠️ Connection handler names must not collide with Node API methods (`emit`, `update`,
-  `on`, `queueFree`, …) — the NODE method wins silently. Prefix handlers with `on`.
+  `on`, `queueFree`, …) — the NODE method wins. That is `AMBIGUOUS_HANDLER` at load
+  now, not a silent wrong call; `incanto check` warns on the same pair from the
+  file alone. Prefix handlers with `on`.
 
 Reference: [examples/2d-phaser-sprite-character-gravity](https://github.com/rareboe/Incanto/tree/main/examples/2d-phaser-sprite-character-gravity) — engine nodes + one small PlayerControl behavior
 (`CoinCounter`, `Pickup`) wired entirely through JSON connections. Verified in Chromium.

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

@@ -170,10 +170,21 @@ ALWAYS confirm in the browser (`bun run dev`) that the feet touch the surface.
 | `zoom` | `1` | 2 = world pixels doubled |
 | `limits` | `[]` | `[minX,minY,maxX,maxY]` — view rect clamped inside |
 | `current` | `false` | mark exactly one |
-Camera `position` is the view CENTER. With no camera, the view shows (0,0)–(w,h).
+Camera `position` is the view CENTER, and it composes with its ancestors like any
+other node — so parenting the camera to the player (the Godot/Phaser idiom) works,
+and so does putting it inside the container that holds the level. `follow` and the
+`FollowCamera` behavior compare WORLD positions at both ends, so the target can live
+under a different parent than the camera. With no camera, the view shows (0,0)–(w,h).
+
+(Before 0.62 the view centre was the camera's LOCAL prop. A camera under a player at
+`[1400, 900]` framed the world origin — and `framing`, which composes full world
+matrices, reported `centred [1400, 900] … 1 in view`, certifying a frame the renderer
+never drew.)
 
 ### `Label`
-`text`, `fontSize 16`, `color '#ffffff'`, `font 'monospace'`, `align 'left'|'center'|'right'`.
+`text`, `fontSize 16`, `color '#ffffff'`, `font 'monospace'`, `align 'left'|'center'|'right'`,
+`opacity 1` (0..1, like `Sprite2D`/`ColorRect2D` — a `Label` can fade now, which is
+what makes `FloatAway` work on one).
 CanvasTexture-rendered; mutate `label.text` freely (re-rasterizes only on change).
 
 ### `UILayer`
@@ -250,14 +261,21 @@ listing the valid set. With a viewport design, UI coordinates are design px.
   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.
+
+  So is the CLOCK: `time`, `unscaledTime` and `timeScale` all start over. That
+  last one is why the game-over recipe below is safe — a swap out of a frozen
+  screen boots the next level running, not frozen.
 - **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
   object yields a clean run; only clone (`structuredClone(levelJson)`) first if
   your own code mutated that object. (`createGame`'s `scene` option already
   structuredClones internally.)
-- **Pause / resume**: `engine.stop()` halts the loop (clock and accumulator
-  reset — no banked time on resume); `engine.start()` resumes.
+- **Pause / resume**: `engine.timeScale = 0` is the pause you want — the loop
+  keeps running, so menus, banners and the key that closes them stay live (this
+  is what `GameFlow.pause()` does). `engine.stop()` halts the loop entirely
+  (clock and accumulator reset — no banked time on resume); `engine.start()`
+  resumes. Either way a `setScene` puts `timeScale` back to 1.
 - **Save / load** (a behavior, localStorage):
   ```ts
   localStorage.setItem('save', JSON.stringify({ score: this.score }));
@@ -348,6 +366,16 @@ Mark unchanging subtrees (tile decor, backgrounds) `static: true` — the
 renderer syncs them once and skips them every frame. Flip to `false` to
 resume live syncing.
 
+The freeze waits for the node to have something worth freezing: a `Sprite2D` or
+`TileMap2D` whose texture has not decoded yet keeps syncing until it has, and a
+texture that never arrives never freezes at all (`assetErrors()` is what reports
+that one). Before 0.62 the latch fired on frame one regardless — and a
+`TextureLoader` fills `.image` asynchronously while the renderer loads and syncs
+in the same frame, so the state frozen was `visible: false`, permanently. A
+static backdrop was invisible for the life of the game with nothing reporting
+it: the texture loaded fine, `stats().errors` was 0, and `framing` reads props
+rather than pixels and still called the node on-screen.
+
 ## Before you hand it back
 
 You cannot see this game. `incanto-verifying-your-game.md` is how you find out

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

@@ -69,7 +69,7 @@ All 3D nodes extend `Node3D` and therefore have the transform props:
 |---|---|---|
 | `position` | `[0,0,0]` | meters; +Y up |
 | `rotation` | `[0,0,0]` | **degrees**, Euler XYZ |
-| `scale` | `[1,1,1]` | |
+| `scale` | `[1,1,1]` | resizes the DRAWN mesh. `Terrain3D`/`Water3D`/`River3D` reject a non-unit scale at load — they keep a CPU twin (`heightAt`, the heightfield collider, the water surface query) built from `size`, so scaling would move the picture and not the ground. Resize those with `size` |
 | `visible` | `true` | hides the whole subtree's rendering |
 
 ### `MeshInstance3D`

package/skills/incanto-editor.md

@@ -104,7 +104,7 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   changed. A prop is rewritten only if its type declares `nodePath: true`, so a
   text prop that merely reads "Player" is never touched. `+` adds a child of any registered
   type, `✕` deletes the selection. Selecting the ⚙ scene row edits the header
-  (dimension, gravity with real inputs, environment/input/assets/multiplayer).
+  (dimension, gravity with real inputs, environment/input/assets/multiplayer/strings).
 - **CONNECTIONS on the selected node** — the inspector's last section shows what
   the node **emits** and what it **receives**, each row being signal → target →
   handler with a ✕ to remove and `+ connect` to add. Signals come from the node

package/skills/incanto-gameplay-behaviors.md

@@ -315,6 +315,15 @@ toward `target.position + offset`. Works in 2D and 3D.
   "script": { "name": "FollowCamera", "props": { "target": "/root/Player", "smoothing": 0.9 } } }
 ```
 
+**Not together with `CharacterController3D`.** That controller drives the
+scene's current `Camera3D` itself, in every one of its views — so a
+`FollowCamera` on the same camera is a second writer, and the two fight for the
+position every frame. Measured on a scene with both, target at (10, 0, 0): the
+camera settled at (6.59, 0.22, 1.36), which is neither answer, with no error
+anywhere. Use the controller's own `view` / `camDistance` for a third-person
+camera, and keep `FollowCamera` for the cameras nothing else drives.
+`incanto check` reports the pair.
+
 ## Patrol
 
 Walk a node along fixed waypoints at constant `speed` — guards, moving platforms.
@@ -504,6 +513,11 @@ pickups, spinning/pulsing coins. Drives one `axis` of `position`, `rotation`
   "script": { "name": "Oscillate", "props": { "axis": "z", "amplitude": 180, "frequency": 0.5, "mode": "rotation" } } }
 ```
 
+On a physics BODY, `mode: "rotation"` turns the collider too — a spinning blade
+cuts, a swinging gate blocks. (Before 0.62 it turned only the mesh: a body's
+angle was applied once at creation and never followed again, so every spinner
+built this way was decoration.)
+
 ## Buoyancy
 
 Float on water. Hangs on a `RigidBody3D` and asks the water how high it is at
@@ -576,7 +590,7 @@ later clones get `EnemyTemplate2`, `EnemyTemplate3`, …)
 | `prefab` | `""` | node path of the template to clone (required) |
 | `interval` | `1` | seconds between spawns |
 | `max` | `0` | max LIVE instances (0 = unlimited) |
-| `at` | `[]` | offset added to the spawner position ([x,y(,z)]) |
+| `at` | `[]` | where the clone appears, as an offset from the spawner ([x,y(,z)]) |
 | `autoStart` | `true` | begin ticking at ready |
 | `total` | `0` | total LIFETIME spawns (0 = infinite) |
 
@@ -625,6 +639,15 @@ MOVEMENT by design: **compose** it with `DamageOnContact` (deal damage), `Lifeti
 `direction` is a vector OR `'forward'` (from the node `rotation`); it's a
 union-typed prop so its default is `null` (= `'forward'`).
 
+In 3D, `'forward'` is the engine's ONE facing convention — **+Z**, the same
+`atan2(dx, dz)` basis `CharacterController3D` uses and `incanto-3d-character.md`
+spells out under "the +Z-FORWARD rule". So aim the bullet (or its shooter) with
+that formula and it flies at what you aimed at; do not add 180°. (Before 0.62
+this returned three.js's −Z instead, so every `'forward'` shot left the muzzle
+pointing at the shooter's back — at the right speed, with no error, which reads
+as a gun that simply never hits anything.) In 2D `rotation` is a scalar and
+`'forward'` is +x turned clockwise by it, unchanged.
+
 | Prop | Default | Meaning |
 |---|---|---|
 | `speed` | `300` | units per second along `direction` |
@@ -822,7 +845,9 @@ import { CameraShake, Cooldown, hitStop, screenFlash } from 'incanto/gameplay';
 - **hitStop(engine, seconds?)** — freezes `engine.timeScale` for REAL
   seconds then restores; stacked calls extend. Sells melee impacts. It measures
   those seconds on `engine.unscaledTime`, so it thaws in a headless session
-  exactly as it does in a browser.
+  exactly as it does in a browser, and a `setScene` under a live freeze drops it
+  (the swap resets that clock, and the killing blow — hit-stop, then restart —
+  is exactly when the two meet).
 - **engine.timeScale** — 1 realtime, 0.5 slow motion, 0 pause: scales
   variable AND fixed updates together (physics, timers, behaviors) — and it
   means the same thing headless, so a pause menu and a slow-motion finish can be
@@ -848,6 +873,13 @@ puff, a 2D `Label`. It reads the start position ONCE, so the ease does not
 compound, and it frees the node a frame after it is invisible rather than on the
 frame it gets there (which reads as a flicker).
 
+**`opacity` is not optional.** A node without one still rises and still frees
+itself, and skips the fade entirely — the number pops out at full brightness,
+which is the thing this behavior exists to prevent. It says so at ready, naming
+the node, rather than leaving you to spot a missing fade by eye. (The 2D `Label`
+in the list above is the reason: it had no `opacity` prop until 0.57, so the one
+2D node the doc named was the one it could not fade.)
+
 ## Did the effect fire?
 
 Sound has `engine.audio`; vision has **`engine.effects`**, and the question is
@@ -933,6 +965,11 @@ 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.
 
+**Any scene swap thaws.** The freeze lives on the engine, not on the flow, so
+leaving a game-over screen by your own route — `engine.setScene(loadScene(next))`
+from a menu button — puts `timeScale` back to 1 as surely as `flow.restart()`
+does. You cannot restart into a frozen level.
+
 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.

package/skills/incanto-hud.md

@@ -225,9 +225,11 @@ slot, the slot takes it. **Who owns the item is your game's business** — these
 report the GESTURE, not a model, so an inventory that stacks, swaps or refuses is
 your `connections` and a behavior, not a prop nobody could have guessed.
 
-A drop on a CHILD of a slot counts as a drop on the slot (the cursor lands on the
-icon inside it, which is the normal case), a drop on nothing cancels, and a
-widget never drops onto itself.
+A drop on a CHILD of a slot counts as a drop on the slot — the cursor lands on
+the icon inside it, which is the normal case, and the icon is itself a widget.
+A drop on nothing cancels, and so does putting a thing back into the slot it
+came from: that is not a move, and firing `dropped` for it would make every
+mis-grab look like a transfer.
 
 
 

package/skills/incanto-localization.md

@@ -99,6 +99,13 @@ banner.show(this.engine.t('hud.wave', { n: this.wave }));
 slot; a scene-JSON prop has no params to fill it from. A slot with no matching
 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.
+
 ## Checking a translation without a browser
 
 No headless check could see a translated string: a capture printed

package/skills/incanto-node-reference.md

@@ -482,6 +482,7 @@ Signals: `movementStateChanged(state)`
 | `color` | `"#ffffff"` | string |
 | `font` | `"monospace"` | string |
 | `align` | `"left"` | string |
+| `opacity` | `1` | number |
 
 ## `Label3D` — `incanto`
 
@@ -705,6 +706,17 @@ Signals: `finished`
 
 Signals: `finished`
 
+## `Respawn` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `target` | `".."` | node path |
+| `below` | `null` | null |
+| `to` | `[]` | array |
+| `resetVelocity` | `true` | boolean |
+
+Signals: `respawned`
+
 ## `RigidBody2D` — `incanto/2d`
 
 | Prop | Default | Kind |

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

@@ -50,6 +50,16 @@ the corners. Give the body its mesh as a CHILD and let the shape follow:
     "props": { "mesh": "box", "size": [14, 0.22, 2.2] } } ] }
 ```
 
+The child's OWN `position`, `rotation` and `scale` are part of the shape: raise the plank on
+the child instead of the body and the collider goes up with it; scale the crate 4× and it is
+solid at 4×. (It was not before 0.62 — the child transform was dropped and the collider sat
+at the body's origin at the authored size, so you walked through the deck you could see and
+landed on an invisible slab at ground level. Measured: a plank drawn with its top at y=3.2
+had its surface at y=0.2.) `collider.offset` stacks on top of that.
+
+A ball, a capsule and a cylinder have ONE radius between them, so a child scaled unevenly in
+x and z has no exact shape — the widest of the two is used and the engine says so by name.
+
 Bodies ignore an ANCESTOR's rotation, so a yawed structure puts each body at top level with
 its own `rotation` — the child mesh then turns with it, visual and collider together.
 
@@ -143,7 +153,13 @@ engine.input.isPressed('jump');      // held
 engine.input.justPressed('jump');    // one-frame edge (settled per tick)
 engine.input.getVector('move');      // normalized {x, y}, y-down (up = -y)
 ```
-Keys are `KeyboardEvent.code` strings (`KeyW`, `Space`, `ArrowLeft`). Unknown actions and
+Keys are `KeyboardEvent.code` strings (`KeyW`, `Space`, `ArrowLeft`) — plus `Mouse0..4`
+and `Pad0..16`, which live in the same space. **A value outside that set is a load
+error** naming the one you probably meant (`'W' → "KeyW"`, `'space' → "Space"`,
+`'Shift' → "ShiftLeft" or "ShiftRight"`): the map is looked up by exact string, so a
+misspelled code binds to nothing and the player silently does not have that control.
+An EMPTY key list is still fine — `{"keys": [], "touch": "button"}` is a touch-only
+control. Unknown actions and
 wrong-kind queries (getVector on a button) are hard errors listing valid names.
 Action declarations RESET on every `setScene` (no keybind bleed between scenes).
 
@@ -239,7 +255,12 @@ Injected state combines with key state (vectors clamped to unit length).
 - Pickups: `Area2D` in a group + `triggerEnter` → check `other.isInGroup('player')` →
   `queueFree()` — wire it via JSON `connections` to a behavior method (the `Pickup`
   pattern in `incanto-behaviors-and-scripts.md`), or imperatively with `node.on(...)`.
-- Teleport: just write `node.position` — the body follows. Launch: write `linearVelocity`.
+- Teleport: just write `node.position` — the body follows. **`node.rotation` follows
+  too**: turn a static or kinematic body at runtime and its COLLIDER turns with it, so
+  a spinning blade cuts and a swinging gate blocks. (It did not before 0.62 — the
+  angle was applied once at creation, the mesh turned and the collider stayed put.)
+  A free dynamic body's rotation belongs to the solver and is left alone.
+  Launch: write `linearVelocity`.
 - 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.
 

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

@@ -299,7 +299,11 @@ that do exist at the failing spot).
 - `signal` must be DECLARED on the from node (the class's or its behavior's
   `static signals`) — validated at load → `UNKNOWN_SIGNAL` otherwise.
 - `handler` must be a method on the target node OR its behavior (script) — both are
-  validated hard at load. Otherwise → `UNKNOWN_HANDLER`. Script names themselves must be
+  validated hard at load. Otherwise → `UNKNOWN_HANDLER`. 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
+  is why the collision is easy to write — rename the script's method. Script names themselves must be
   registered (`registerBehavior`) before `loadScene` → `UNKNOWN_BEHAVIOR` otherwise.
 - Unresolvable `from`/`to` → `DANGLING_CONNECTION` at load. Renaming a node breaks its
   connections **loudly** — update paths in the same edit.
@@ -336,6 +340,7 @@ that do exist at the failing spot).
 | `DUPLICATE_UNIQUE_NAME` | `%Name` matches ≥2 nodes | rename one, or use an explicit path |
 | `DANGLING_CONNECTION` | connection `from`/`to` unresolvable | fix the path after renames |
 | `UNKNOWN_HANDLER` | handler missing on the node AND its behavior | fix the method name |
+| `AMBIGUOUS_HANDLER` | handler is a method on the node AND on its behavior — the node's wins silently | rename the behavior's method |
 | `UNKNOWN_SIGNAL` | connection (or emit/on) names a signal the from node never declares | use a declared signal, or declare it (`static signals` / `declareSignal`) |
 | `UNKNOWN_BEHAVIOR` | `script.name` not registered | `registerBehavior(name, Class)` before `loadScene` |
 | `UNRESOLVED_INSTANCE` | no resolver, unknown path, or instance cycle | provide/fix `resolveScene`, break the cycle |

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

@@ -32,6 +32,7 @@ failures — but `framing` and `assetErrors()` you have to ASK for.
 $ bunx incanto verify                       # finds your scene AND your behaviours
 · behaviours: src/behaviors.ts (found, not named)
 ✓ loads — the scene is legal and its assets resolve
+    ! /Game/Chest: script Chest — target '%Ke' matches nothing
 ? 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
@@ -67,11 +68,40 @@ encodes so you do not have to remember them:
 
 - a **failed** rung makes the ones above it meaningless, so only the first is
   worth reading — the rest are marked `·` skipped;
+- a rung that PASSED can still have something to say. Anything its own tool
+  warned about is printed under it with a `!` — `loads` runs `incanto-check`,
+  and the ladder used to read only whether it passed and drop the warnings, so a
+  scene the check describes as "It will render black" came back as
+  `✓ loads — the scene is legal and its assets resolve`;
 - an **unmeasured** rung (`?`) is not a failure. "No dev server" means the
   question was never asked; treating that as a broken game sends you editing a
   scene that is fine;
 - a scene that declares **no win** is not a scene that cannot be won. A
-  walkabout has no end, and that is reported as unmeasured, not failed.
+  walkabout has no end, and that is reported as unmeasured, not failed;
+- but a **defect** fails the rung whatever the scene declares. `error` (a
+  behaviour threw) and `fell` (the player left the world) are counted BEFORE
+  anything else is decided:
+
+  ```
+  ✗ plays — 8 of 8 runs ended in a defect (8 fell out of the world)
+  next: the player left the world with nothing catching them — give the level a
+        floor, walls, or a respawn
+  ```
+
+  The routed answer to that last one is a `Respawn` node under the player
+  (`incanto-behaviors-and-scripts.md`) — one line of JSON, no per-frame `y`
+  check in your own code.
+
+  This used to be the sentence `8 runs played without error` — printed for a
+  scene with no declared win no matter what happened in it, including 8/8
+  `fell`, and exit 0. The child `incanto-playtest` had just printed
+  `✗ fell in 8/8`; the parent said the opposite of it.
+
+`stuck` — the player went nowhere — is the third defect and the one that needs
+a fair chance before it counts. It is only a failure when there WAS someone to
+move and your behaviours were loaded. A scene with no character controller, no
+`player` group and no node named `Player` reports `nothing here is drivable`,
+and a run without `--behaviors` reports that instead: neither is a broken game.
 
 `feels` is the sound-and-effects rung: it lists what the scene DECLARES against
 what actually fired during the playtest. A game whose feedback is wired but