incanto 0.61.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-CAD2c5ug.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.61.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"
         },
@@ -5327,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-behaviors-and-scripts.md

@@ -145,6 +145,43 @@ declared by their classes. Escape hatch for runtime one-offs: `node.declareSigna
   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

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

@@ -170,7 +170,16 @@ 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'`,
@@ -357,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-gameplay-behaviors.md

@@ -513,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
@@ -585,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) |
 
@@ -634,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` |

package/skills/incanto-node-reference.md

@@ -706,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-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

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