npm - incanto - Versions diffs - 0.61.0 → 0.63.0 - Mend

incanto 0.61.0 → 0.63.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (54) hide show

package/bin/incanto-verify.mjs +134 -55
package/dist/2d.d.ts +42 -0
package/dist/2d.js +3 -3
package/dist/3d.d.ts +22 -0
package/dist/3d.js +5 -5
package/dist/{create-game-DH7JI5xx.js → create-game-lLeITaZ5.js} +8 -8
package/dist/{create-game-IX5lEH0P.js → create-game-viBqXUoZ.js} +6 -6
package/dist/{duplicate-CGqAmK2h.js → duplicate-BOOKmkQ7.js} +1 -1
package/dist/editor.js +39 -18
package/dist/{environment-presets-CNxCuhZF.js → environment-presets-QR7_75KJ.js} +5 -3
package/dist/{gameplay-Dtzd2itW.js → gameplay-CuqoHHUB.js} +153 -16
package/dist/gameplay.js +1 -1
package/dist/index.d.ts +92 -1
package/dist/index.js +6 -6
package/dist/{loader-D7jTvDQv.js → loader-zDynoew_.js} +160 -2
package/dist/net.js +1 -1
package/dist/{physics-2d-CBnor8Zf.js → physics-2d-CllJXlic.js} +11 -3
package/dist/{physics-3d-BTUfUSWO.js → physics-3d-BL_pFJ19.js} +123 -17
package/dist/react.js +1 -1
package/dist/{register-DL3izw8j.js → register-1cKM8DEj.js} +60 -9
package/dist/{register-xuSRyD6b.js → register-Btm7_Emq.js} +158 -2
package/dist/{replay-D7-yle3s.js → replay-Bhdntkvq.js} +15 -2
package/dist/{split-screen-5Ban4q4n.js → split-screen-Dx0LvzqS.js} +2 -2
package/dist/{src-DozXvyZS.js → src-BlV9Sv4m.js} +1 -1
package/dist/{teardown-B6rwJOyS.js → teardown-BwhkcNt8.js} +1 -1
package/dist/{test-Dch_7VQD.js → test-Ct1_zf5S.js} +64 -20
package/dist/test.d.ts +41 -0
package/dist/test.js +2 -2
package/dist/vite.js +2 -2
package/editor/assets/{agent8-CF1JL2tR.js → agent8-CLZXBRoM.js} +1 -1
package/editor/assets/{debug-3QzYhOPA.js → debug-eaSKFAKW.js} +1 -1
package/editor/assets/{index-CAD2c5ug.js → index-D66AuRwG.js} +91 -91
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +91 -0
package/skills/README.md +4 -0
package/skills/incanto-behaviors-and-scripts.md +37 -0
package/skills/incanto-building-2d-games.md +20 -1
package/skills/incanto-building-3d-games.md +1 -1
package/skills/incanto-game-feel.md +3 -2
package/skills/incanto-gameplay-behaviors.md +45 -6
package/skills/incanto-node-reference.md +12 -0
package/skills/incanto-physics-and-input.md +53 -2
package/skills/incanto-scene-json-authoring.md +15 -1
package/skills/incanto-verifying-your-game.md +31 -1
package/skills/incanto-your-first-game.md +237 -0
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/game.scene.json +4 -2
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/game.scene.json +3 -2
package/templates-app/tps-3d/verify.ts +38 -0
package/templates-app/village-quest-3d/package.json +1 -1

package/editor/index.html CHANGED Viewed

@@ -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-D66AuRwG.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json CHANGED Viewed

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

package/schemas/scene.schema.json CHANGED Viewed

@@ -295,6 +295,9 @@
         {
           "$ref": "#/$defs/Particles3D"
         },
+        {
+          "$ref": "#/$defs/Respawn"
+        },
         {
           "$ref": "#/$defs/RigidBody2D"
         },
@@ -2040,6 +2043,10 @@
             "slopeLimitDeg": {
               "type": "number",
               "default": 45
+            },
+            "stepHeight": {
+              "type": "number",
+              "default": 0.35
             }
           },
           "additionalProperties": false
@@ -5327,6 +5334,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/README.md CHANGED Viewed

@@ -1,6 +1,10 @@
 # incanto skills (shipped)
 Full agent skills for building games with this **installed version** of Incanto.
+**New here? `incanto-your-first-game.md` is the walkthrough** — scaffold to a game
+with a real win and lose, the shape of the loop, and the traps that cost a first
+author an hour. Then come back to this list.
 An AI agent should start with `incanto-scene-json-authoring.md`, then the domain skill
 for the task at hand, and **finish every task with `incanto-verifying-your-game.md`**
 — you cannot see the game, and that skill is how you find out whether it works.

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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-game-feel.md CHANGED Viewed

@@ -20,7 +20,8 @@ feel of /Game/Player
   turnaround       367 ms
   input → motion   1 frame(s)
-  jump apex        0.262 u
+  jump apex        0.262 u   (tapped)
+  held apex        0.981 u   ← size your level against THIS
   time to apex     133 ms
   airtime          267 ms
   coyote window    100 ms
@@ -47,7 +48,7 @@ reports **0 ms**. That was a real bug in this engine's own 3D controller until
 | `to a stop` | how much you slide. A platformer that overshoots ledges has a long one. |
 | `turnaround` | the cost of changing your mind. The number players feel most and name least. |
 | `input → motion` | 1 frame is immediate. More than 2 and something is buffering. |
-| `jump apex` / `airtime` | compare against the gaps and platform heights in your level. |
+| `jump apex` / `airtime` | compare against the gaps and platform heights in your level. **Use the HELD apex** — the plain one is a one-frame TAP, and with `jumpCutMultiplier` (the variable-height jump the 3D character skill recommends at `0.45`) that is a fraction of the real jump: measured 0.478 u tapped against 1.831 u held on the same scene. The held line only appears when the two differ. |
 | `coyote window` | **0 reads to players as "the controls are broken"**, not as a missing feature. |
 | `jump buffer` | 0 throws away a press made a few frames before landing. |

package/skills/incanto-gameplay-behaviors.md CHANGED Viewed

@@ -222,18 +222,41 @@ Signals: `totalChanged(total)` — Methods: `collect(value)` — state: `total`
 Deals damage to whatever it touches — projectiles, spikes, lava, enemy hitboxes.
 **Goes on an Area.** On `triggerEnter`, finds the contacted entity's `Health` and
 calls `damage(amount)`, then emits `dealtDamage(amount, healthOwnerNode)`.
-`oncePerTarget` (default) prevents re-hitting a resting body every frame;
-`destroySelf` frees the hazard after a hit (single-use projectiles).
 | Prop | Default | Meaning |
 |---|---|---|
 | `amount` | `10` | HP removed per contact |
 | `targetGroup` | `""` | only damage targets whose Health-owner is in this group (`""` = any) |
-| `oncePerTarget` | `true` | damage each target at most once |
+| `oncePerTarget` | `true` | damage each target at most **once, ever** |
+| `repeatEvery` | `0` | seconds between re-hits while still overlapping (`0` = entry only) |
 | `destroySelf` | `false` | `queueFree()` after the first hit |
 Signals: `dealtDamage(amount, target)`
+### `repeatEvery` is the "and it keeps hurting" knob
+**Contact events fire on ENTRY and EXIT, not per frame.** So `oncePerTarget:
+false` does not mean "hurt every frame" — it means "hurt again on RE-entry". An
+enemy that closes on you and stops moving has entered once, and deals one hit
+and then nothing. Measured, 6 seconds of unbroken overlap at `amount: 10`:
+```
+oncePerTarget=false  repeatEvery=0     → hp 90   ← one hit, then nothing
+oncePerTarget=false  repeatEvery=0.5   → hp 0
+oncePerTarget=true   repeatEvery=0.5   → hp 0
+oncePerTarget=true   repeatEvery=0     → hp 90
+```
+`repeatEvery` is the only prop that makes a resting overlap keep hurting, and it
+overrides `oncePerTarget` — lava pools, poison clouds, an enemy standing on you.
+Set it on **every enemy contact hitbox**; without it a game plays as though the
+enemies are harmless the moment one of them corners you, and every check comes
+back green.
+Pair it with `Health.invulnerableFor`, which is the real "don't drain me every
+frame" guard: with `invulnerableFor: 0.6`, a `repeatEvery` under 0.6 s just
+lands on i-frames, so 0.5–1 s is the useful range.
 **`targetGroup` — stop enemies killing each other.** With no collision layers in
 v0 (everything overlaps everything), an enemy's contact hitbox would damage any
 `Health` it touches, including other enemies clustered at the spawn point. Gate
@@ -513,6 +536,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 +613,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 +662,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` |
@@ -679,7 +716,8 @@ interaction is a `connection`.
         "script": { "name": "Pickup", "props": { "value": 1 } } },
       { "name": "Spike", "type": "Area2D", "props": { "position": [120, 80],
         "collider": { "shape": "rect", "size": [24, 24] } },
-        "script": { "name": "DamageOnContact", "props": { "amount": 40, "oncePerTarget": false } } }
+        "script": { "name": "DamageOnContact",
+          "props": { "amount": 40, "oncePerTarget": false, "repeatEvery": 0.5 } } }
     ]
   },
   "connections": [
@@ -764,7 +802,8 @@ glue an early sim had to hand-write):
               { "name": "Hit", "type": "Area2D",
                 "props": { "collider": { "shape": "circle", "radius": 12 } },
                 "script": { "name": "DamageOnContact",
-                  "props": { "amount": 10, "targetGroup": "player", "oncePerTarget": false } } }
+                  "props": { "amount": 10, "targetGroup": "player",
+                    "oncePerTarget": false, "repeatEvery": 0.5 } } }
             ] }
         ] }
     ]

package/skills/incanto-node-reference.md CHANGED Viewed

@@ -239,6 +239,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `velocity` | `[0,0,0]` | array |
 | `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
+| `stepHeight` | `0.35` | number |
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -706,6 +707,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 CHANGED Viewed

@@ -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.
@@ -336,6 +357,36 @@ the tree says, without your scene falling over while you look at it. Use it for
 any "show me the collision geometry" tool. Do NOT use it to freeze a running
 game — that is `engine.timeScale = 0`, which keeps the world coherent.
+## A walking body climbs a step (`stepHeight`, 3D)
+`CharacterBody3D.stepHeight` (default `0.35` m, `0` = off) is how high a ledge
+the body walks UP without jumping. It is Rapier's autostep, and **Rapier does not
+autostep unless it is asked** — before 0.63 nothing asked, so any walking body
+was stopped dead by a curb.
+You will not see this on the player: `CharacterController3D` rides a hover spring
+rather than the character controller, so it floats over small ledges already.
+It is the ENEMIES that walk, and a chaser walks a straight line — it cannot go
+around. Measured on the shipped `tps-3d` template, whose arena has a 0.6 m ramp
+between the spawn and the player, standing still for 45 seconds:
+```
+before   hits=0  hp=100  closest an enemy ever got = 33.91m
+after    hits=9  hp=..   closest = 1.80m   (exactly Chase.stopRange)
+```
+They chased at full speed the whole time and piled up against the near face of a
+knee-high box. Raise `stepHeight` for a world with real stairs; set it to `0` for
+something that genuinely should be blocked by a curb.
+**It loses to a large downward velocity.** Autostep happens inside the movement
+solve, so a body driven with a big constant gravity term every frame never
+climbs. Same 0.3 m ledge, same `stepHeight: 0.35`, only the `velocity[1]`
+differs: `0` → cleared, `−0.1` → cleared, `−2` → stopped at the face. If you are
+integrating your own gravity, apply it as a falling SPEED that resets on the
+ground, not as a constant push. (`moveBody`, which `Chase` and `Patrol` use,
+derives velocity from a position delta and carries no such term.)
 ## Moving platforms carry their riders (2D **and** 3D)
 A `CharacterBody2D`/`CharacterBody3D` standing on a body that moves is dragged

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

@@ -299,7 +299,21 @@ 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`. On **both**, it is
+  validated hard at load. Otherwise → `UNKNOWN_HANDLER`.
+- **The ARGUMENTS are checked when the wire fires**, not at load — nothing declares
+  how many a signal carries, so the pair can only be compared at the moment both
+  are known. A handler given fewer than it needs is reported once, by name:
+  ```
+  [incanto] 'died' from 'Enemy' carries 0 argument(s) and 'Keeper.addScore' needs 1.
+            The missing one(s) arrive as undefined — a number handler gets NaN and
+            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
   `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

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

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