npm - incanto - Versions diffs - 0.47.0 → 0.49.0 - Mend

incanto 0.47.0 → 0.49.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 (55) hide show

package/bin/incanto-frame.mjs +58 -1
package/bin/incanto-logs.mjs +127 -0
package/bin/incanto-model.mjs +13 -1
package/bin/incanto-playtest.mjs +7 -0
package/bin/incanto-verify.mjs +41 -2
package/dist/2d.d.ts +21 -12
package/dist/2d.js +57 -3
package/dist/3d.d.ts +38 -1
package/dist/3d.js +114 -4
package/dist/{create-game-CniOiWzN.js → create-game-BgV6UbVA.js} +5 -5
package/dist/{create-game-D16MVIPO.js → create-game-DFBjMetZ.js} +83 -6
package/dist/{duplicate-CRtihGmC.js → duplicate-CI9WF_bg.js} +1 -1
package/dist/{environment-presets-D1b0ydTS.js → environment-presets-CZOH5TY5.js} +15 -20
package/dist/{gameplay-BQOeAid6.js → gameplay-02Btmmjn.js} +80 -9
package/dist/gameplay.d.ts +17 -0
package/dist/gameplay.js +1 -1
package/dist/index.d.ts +139 -1
package/dist/index.js +8 -7
package/dist/{loader-r49nDwB4.js → loader-DwazzlQb.js} +36 -6
package/dist/log-report-lxrQY9cH.js +0 -0
package/dist/net.js +3 -3
package/dist/{physics-2d-BmgXBNDB.js → physics-2d-vyCBfACH.js} +3 -3
package/dist/{physics-3d-CSoGjM8P.js → physics-3d-DpRqw8Mz.js} +4 -4
package/dist/react.js +1 -1
package/dist/{register-R2JTnIMw.js → register-BNPZYJmd.js} +23 -22
package/dist/{register-D651it1J.js → register-CB11yp21.js} +2 -2
package/dist/{register-BSXV8T9F.js → register-uvaZj1KX.js} +62 -2
package/dist/{replay-DilbZgQI.js → replay-C0XJIsO7.js} +1 -1
package/dist/sprite-animation-CMr6f1K2.d.ts +44 -0
package/dist/{particle-sim-Bw7hB93B.js → sprite-animation-D_p28jwU.js} +63 -1
package/dist/{src-Ca3oV1fe.js → src-DF4gCsqO.js} +1 -1
package/dist/{test-E4-otKqK.js → test-DRna_BQU.js} +210 -30
package/dist/test.d.ts +38 -6
package/dist/test.js +2 -2
package/dist/vite.js +41 -4
package/editor/assets/{agent8-_007gPF8.js → agent8-DCW4TgDt.js} +1 -1
package/editor/assets/{debug-0DI_MJaq.js → debug-RC6qts6S.js} +1 -1
package/editor/assets/{index-B-6eYZEi.js → index-5dEIhvsf.js} +92 -92
package/editor/index.html +1 -1
package/package.json +3 -2
package/schemas/scene.schema.json +10 -3
package/skills/incanto-3d-character.md +13 -2
package/skills/incanto-3d-models.md +40 -0
package/skills/incanto-assets.md +15 -0
package/skills/incanto-building-2d-games.md +57 -5
package/skills/incanto-building-3d-games.md +7 -0
package/skills/incanto-gameplay-behaviors.md +18 -1
package/skills/incanto-hud.md +39 -0
package/skills/incanto-node-reference.md +5 -3
package/skills/incanto-physics-and-input.md +1 -1
package/skills/incanto-playtesting.md +9 -2
package/skills/incanto-verifying-your-game.md +67 -0
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/tps-3d/package.json +1 -1
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-B-6eYZEi.js"></script>
+    <script type="module" crossorigin src="./assets/index-5dEIhvsf.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.47.0",
+  "version": "0.49.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -99,6 +99,7 @@
     "incanto-feel": "bin/incanto-feel.mjs",
     "incanto-new": "bin/incanto-new.mjs",
     "incanto-frame": "bin/incanto-frame.mjs",
-    "incanto-verify": "./bin/incanto-verify.mjs"
+    "incanto-verify": "./bin/incanto-verify.mjs",
+    "incanto-logs": "./bin/incanto-logs.mjs"
   }
 }

package/schemas/scene.schema.json CHANGED Viewed

@@ -1696,7 +1696,7 @@
               "maxItems": 2,
               "default": [0, 0]
             },
-            "snapToGround": {
+            "stickToGround": {
               "type": "boolean",
               "default": true
             },
@@ -1801,8 +1801,7 @@
               "default": "default"
             },
             "snapToGround": {
-              "type": "boolean",
-              "default": true
+              "default": null
             },
             "collider": {
               "type": "object",
@@ -1817,6 +1816,10 @@
               "maxItems": 3,
               "default": [0, 0, 0]
             },
+            "stickToGround": {
+              "type": "boolean",
+              "default": true
+            },
             "slopeLimitDeg": {
               "type": "number",
               "default": 45
@@ -7443,6 +7446,10 @@
               "type": "string",
               "default": ""
             },
+            "format": {
+              "type": "string",
+              "default": ""
+            },
             "size": {
               "type": "number",
               "default": 16

package/skills/incanto-3d-character.md CHANGED Viewed

@@ -171,6 +171,15 @@ Map movement states straight in JSON — no behavior needed:
 The controller writes `skin.animation` on every state change (crossfaded by
 the model). The `movementStateChanged` signal still fires for extras.
+**Where those clips come from.** Locomotion clips live at
+`https://agent8-games.verse8.io/assets/3d/animations/mixamorig/<name>.glb`
+(`idle-00`, `walk`, `run-medium`, `run-fast`, `jump`) and play on any mixamorig
+model as they are — retargeted through the humanoid map for a VRM. You do not
+have to assemble any of this by hand: run the character URL your asset MCP gave
+you through `bunx incanto-model <url>` and it prints the whole thing — assets,
+input actions, body, controller and skin — ready to paste. See
+`incanto-3d-models.md`.
 The controller also yaw-rotates the sibling at `skinPath` ('../Skin') toward
 the move direction at `turnSpeed` rad/s (100 = instant snap) — the body
 itself never rotates. The skin MOUNTS at 180° (facing away from the default
@@ -222,8 +231,10 @@ NPCs feel alive when they track you. One node, zero code:
 ## Facing a direction in 3D — the +Z-FORWARD rule (read before turning ANY skin)
-This trips people up REPEATEDLY, so here is the one rule. agent8's `base-model` (and
-any model you give `skinYawOffset: 0`) is **+Z-FORWARD**: its face looks down +Z at
+This trips people up REPEATEDLY, so here is the one rule. agent8's `base-model`
+(`https://agent8-games.verse8.io/assets/3d/characters/realistic%20style/base-model.glb`
+— note the escaped space; it is the reference rig these docs measure against) and
+any model you give `skinYawOffset: 0` are **+Z-FORWARD**: its face looks down +Z at
 rotation 0. To turn it to face a world heading `(dx, dz)`:
 ```ts

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

@@ -8,6 +8,46 @@ description: Loading GLB/glTF and VRM models in Incanto — the ModelInstance3D
 > Shipped inside the `incanto` npm package — this document always matches the
 > installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+## Where models come from
+**Search, don't invent.** Model URLs come from your asset MCP (vector search
+over the agent8 library) or from the editor's 📚 button
+(`bunx incanto-editor --token <v8 token>`) — never from a guessed path. There is
+no 3D model in the package's own catalog: `incanto-assets` ships 2D sprites,
+tiles, items, foliage/terrain textures and audio, and characters are the one
+thing you are expected to go and get.
+Then run the URL through the inspector, which is where a found file becomes a
+scene:
+```bash
+bunx incanto-model "https://…/base-model.glb"
+#   mixamorig rig — the 3d/animations clips play on this as they are
+#   stands 1.5 units tall
+#
+#   paste a playable character into your scene:
+#   { "assets": {…model + idle/walk/run/fastRun/airborne clips…},
+#     "input":  {…move / jump / sprint…},
+#     "node":   { "type": "RigidBody3D", … Controller + Skin … } }
+```
+For a **mixamorig or VRM humanoid** that is the whole character — body,
+controller, skin fitted to the capsule and dropped to its feet, the locomotion
+clips declared, and the input actions without which nothing reads the keyboard.
+Paste it and the character walks. For a prop, you get the model node.
+### The locomotion clips
+`https://agent8-games.verse8.io/assets/3d/animations/mixamorig/<name>.glb` —
+`idle-00` · `walk` · `run-medium` · `run-fast` · `jump`, plus
+`melee-attack`, `punch-00/01`, `kick-00/01/02`, `cast`, `swim`,
+`hit-to-body`, `death-backward`, `dance-wave`, and the `rifle-`/`pistol-`
+sets.
+These are not art you go searching for — they are the rig's vocabulary. They
+play on a mixamorig model as they are, and retarget through the humanoid map
+onto a VRM, so they fit whatever character your asset search returned.
 ## ALWAYS inspect before you place
 A file name tells you nothing about a model's size or contents. The package ships an

package/skills/incanto-assets.md CHANGED Viewed

@@ -11,6 +11,13 @@ description: Where game art comes from in Incanto — the FULL built-in catalog
 Resolve art in this order: ① built-ins (zero setup) → ② asset MCP servers /
 known URLs → ③ art-free primitives. Never invent asset URLs.
+**3D characters and props are step ②, always** — the built-in catalog is 2D
+sprites, tiles, items, foliage/terrain textures and audio, with no models in it.
+Search with your asset MCP (or the editor's 📚 library), then run the URL
+through `bunx incanto-model <url>`: for a rigged humanoid it prints a whole
+playable character — model, locomotion clips, body, controller, skin and input
+— ready to paste. See `incanto-3d-models.md`.
 ## 1. Built-in assets (in the package)
 ```bash
@@ -102,6 +109,14 @@ const { asset, props } = spriteFromLibraryMeta(animJson, {
 // asset → scene assets.hero; props → an AnimatedSprite2D's props. Done.
 ```
+The `animations` map it returns (and the one `incanto-assets copy` prints) also
+carries ALIASES for the movement states a character controller emits and the
+sheet does not name — `"run": "move"`, `"fall": "idle"` — because library sheets
+are `idle`/`move`/`attack` and no sheet ships a falling pose. That is what makes
+the printed JSON work when you paste it next to
+`movementStateChanged → play`; repoint any alias once you have the art. Sheets
+with no `idle` (a spinning coin) get none: they are not characters.
 For 3D files, ALWAYS inspect before placing: `bunx incanto-model file.glb`
 (bounds, animations, rig — see incanto-3d-models).

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

@@ -288,11 +288,32 @@ bunx incanto-check                       # will it load? is anything lit?
 printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
 ```
-`framing` tells you what the camera can actually SEE (on screen / off screen /
-behind it), what lights the scene, and which colliders intersect. Then read
-`stats().errors` (something threw and got skipped) and `assetErrors()` (a model
-404'd). All four are silent failures otherwise — the screen just looks wrong,
-or empty, and nothing throws.
+`framing` tells you what the camera can actually SEE, in 2D's own terms: the
+`viewport.design` window centred on the current `Camera2D` **and clamped by its
+`limits`**, which is the view the renderer really draws — a following camera
+sits at the player's y, and in a 544 px world that is hundreds of pixels past
+anything a 540 px window can show.
+```
+camera /Game/Camera centred [480, 274] showing 960×540px
+11 in view, 2 outside it
+  onScreen  /Game/Level (TileMap2D) [0, 0] screen [0.333, -0.007] 160px
+  onScreen  /Game/Gems/Gem1/Icon (Sprite2D) [512, 428] screen [0.067, 0.57] 157px
+  offscreen /Game/Goblins/Goblin2/Skin (AnimatedSprite2D) [1002, 512] … 574px
+  overlap   /Game/Gems/Gem4 ∩ /Game/Level
+```
+`screen` is −1…1 across the window, so `1.089` means "just past the right
+edge". A node counts as in view when its BOX is — a `ColorRect2D`'s `size`, a
+`TileMap2D`'s whole grid (which hangs from its TOP-LEFT, not its centre), or a
+collider. A bare `Sprite2D` declares no size, so read `offscreen` there as "its
+ORIGIN is outside the view". Nothing is ever "behind" a 2D camera and nothing is
+lit, so neither is reported; `overlap` is real interpenetration, not resting on
+a platform. HUD widgets are screen-space and are left out entirely.
+Then read `stats().errors` (something threw and got skipped) and `assetErrors()`
+(a texture 404'd). All of these are silent failures otherwise — the screen just
+looks wrong, or empty, and nothing throws.
 ## Platformer game feel (CharacterController2D)
@@ -324,6 +345,37 @@ behaves exactly as before.
 character from scene JSON instead of a behavior polling velocities. The 3D
 sibling has had this signal since it shipped.
+```json
+{ "signal": "movementStateChanged", "from": "Player/Ctl",
+  "to": "Player/Skin", "handler": "play" }
+```
+**The sheet will not have all six clips — alias the rest.** Library sheets
+(including every packaged character) carry `idle`/`move`/`attack`, and none of
+them ships a falling pose. An `animations` entry may be the NAME of another
+entry, which is what the states you have no artwork for should be:
+```json
+"animations": {
+  "idle":   { "frames": [0, 5],   "fps": 10, "loop": true },
+  "move":   { "frames": [6, 11],  "fps": 10, "loop": true },
+  "attack": { "frames": [12, 17], "fps": 10 },
+  "run": "move", "jump": "idle", "fall": "idle", "dash": "move"
+}
+```
+`incanto-assets copy` and `spriteFromLibraryMeta` already print these aliases,
+so pasting their output next to the wiring above works as-is; point any of them
+somewhere better when you have the art. Aliases may chain (`fall` → `jump` →
+`idle`), a circle is a hard error, and a name that resolves to nothing fails at
+READY — not on the frame the character first jumps. A misspelt clip is still a
+hard `UNKNOWN_ANIMATION`: an alias is a rename you wrote, not a silent fallback.
+**A cosmetic clip cannot stop the character.** If a `play` wire throws anyway,
+the engine turns THAT WIRE off and reports it — the controller keeps running.
+Read `stats().errors`, because the game will look fine and be missing an
+animation.
 Wall moves need to know there IS a wall: `CharacterBody2D` now answers
 `isOnWall()`, `wallSide()` (-1 left / +1 right) and `isOnCeiling()` as well as
 `isOnFloor()`. Before, the floor was the only surface a character could report,

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

@@ -401,6 +401,13 @@ the same bug.
   cloud). The grounding check below skips these, so mark them.
 - omitted — `y` is used exactly as authored.
+**On a `CharacterBody2D`/`3D` the ground-STICK is `stickToGround`** (default
+true — hold the capsule against the surface while it moves). It used to be
+called `snapToGround`, which shadowed the placement prop above: a character
+body was silently teleported onto the terrain at load, a lift value was
+rejected, and the only escape also turned the ground-stick off. A boolean
+`snapToGround` on a character body is now a hard error naming both props.
 Resolved at load, in the same frame the terrain is built, and it honours an
 ancestor's yaw, so props under a turned rig land where they look.

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

@@ -90,9 +90,19 @@ dies once.
 | `invulnerableFor` | `0` | seconds of immunity after a hit (i-frames; 0 = off) |
 | `freeOnDeath` | `false` | `queueFree()` this node when it dies (clone-safe) |
-Signals: `damaged(amount, current)` · `healed(amount, current)` · `died`
+Signals: `damaged(amount, current)` · `healed(amount, current)` ·
+`healthChanged(current, max)` · `died`
 Methods: `damage(n)` · `heal(n)` · `kill()` — state: `current`, `isDead`
+**`healthChanged` is the one to put on a health BAR.** `damaged`/`healed` lead
+with the DELTA, so wiring either to `UiBar.setValue` paints the damage as the
+health and looks like it works; `healthChanged` leads with the current value and
+carries the max, so `{ "signal": "healthChanged", "from": "Player", "to":
+"HUD/Hp", "handler": "setValue" }` is the whole health bar. It also fires for
+regeneration, which the other two never do — a regen bar wired to `healed` sits
+still while the character heals. Use `damaged`/`healed` for reacting to the HIT
+(sfx, flash, knockback), where the amount is the point.
 ```json
 { "name": "Player", "type": "CharacterBody2D", "groups": ["player"],
   "props": { "collider": { "shape": "capsule", "radius": 12, "height": 32 } },
@@ -162,6 +172,13 @@ arg 0) or `→ Collector.collect`.
 Signals: `collected(value, other)`
+The collector is resolved from the contacted node, its descendants, then its
+ancestor chain — the same search `DamageOnContact` uses for `Health`. So a
+player with a wider `Grab` sensor child still collects, and `other` is the
+ENTITY that owns the group, not whichever part of it touched first. (It stops
+at the entity: past a shared parent a crate standing next to the player would
+otherwise collect the coin.)
 ```json
 { "name": "Coin", "type": "Area2D",
   "props": { "collider": { "shape": "circle", "radius": 8 } },

package/skills/incanto-hud.md CHANGED Viewed

@@ -27,6 +27,45 @@ headless tests (core nodes, no three.js). Widgets pick one of 9 anchors:
 `topLeft top topRight left center right bottomLeft bottom bottomRight`.
 Widgets stacked on the same anchor form a column.
+## Driving widgets from the scene JSON (no TypeScript)
+The widgets take the gameplay signals directly, so a score line and a health bar
+are `connections[]` entries — not a behavior whose whole job is one assignment:
+```json
+"connections": [
+  { "signal": "scoreChanged",  "from": ".",      "to": "HUD/Score", "handler": "setText" },
+  { "signal": "healthChanged", "from": "Player", "to": "HUD/Hp",    "handler": "setValue" },
+  { "signal": "lifeLost",      "from": ".",      "to": "HUD/Lives", "handler": "setText" }
+]
+```
+```json
+{ "name": "Score", "type": "UiText",
+  "props": { "anchor": "topRight", "text": "Gems 0 / 8", "format": "Gems {} / 8" } }
+```
+- **`UiText.setText(value)`** — writes the whole line, or fills the `{}` slot in
+  `format` when you set one. `format` is resolved at PAINT like `text`, so
+  `"@t:hud.gems"` works and switching locale re-reads it. Until the first value
+  arrives it shows `text`, which is why you write both (`"Gems 0 / 8"` is the
+  opening line, `"Gems {} / 8"` is the template).
+- **`UiBar.setValue(current, max?)`** — takes the max as a second argument
+  because that is the shape `healthChanged` already has, so a raised ceiling
+  needs no second wire. `UiBar.setMax(max)` moves it alone.
+- **`UiBanner.show(text)`** — already a method, already wireable.
+**Wire `healthChanged`, not `damaged`.** `damaged(amount, current)` and
+`healed(amount, current)` lead with the DELTA — wire either to `setValue` and
+the bar paints the damage as the health and looks like it works. `setValue`
+refuses a non-number and names the right signal in the message, but a plausible
+wrong NUMBER is the trap worth knowing. `healthChanged(current, max)` also fires
+for regeneration, which the other two never do.
+Which signal carries what, at a glance: `ScoreKeeper.scoreChanged(score)` ·
+`ScoreKeeper.lifeLost(lives)` · `Collector.totalChanged(total)` ·
+`Health.healthChanged(current, max)` — all value-first, all wireable as-is.
 ## Driving widgets from behaviors
 Plain node access — same as everything else:

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

@@ -214,7 +214,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
 | `velocity` | `[0,0]` | array |
-| `snapToGround` | `true` | boolean |
+| `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -230,9 +230,10 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
-| `snapToGround` | `true` | boolean |
+| `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
 | `velocity` | `[0,0,0]` | array |
+| `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -1133,6 +1134,7 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `change
 | `draggable` | `false` | boolean |
 | `dropTarget` | `false` | boolean |
 | `text` | `""` | string |
+| `format` | `""` | string |
 | `size` | `16` | number |
 | `color` | `"#ffffff"` | string |
 | `shadow` | `true` | boolean |
@@ -1340,7 +1342,7 @@ Signals: `flowChanged`
 | `invulnerableFor` | `0` | number |
 | `freeOnDeath` | `false` | boolean |
-Signals: `damaged(amount, current)` · `healed(amount, current)` · `died`
+Signals: `damaged(amount, current)` · `healed(amount, current)` · `died` · `healthChanged`
 ### `Interactable`

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

@@ -76,7 +76,7 @@ mesh or one model and warns when the body carries more.
   Areas overlapping OTHER Areas fire too (e.g. a weapon-hitbox Area over an
   enemy-hitbox Area) — neither side needs to be a Body.
 - **`CharacterBody2D/3D`** — kinematic character (Rapier KCC). Props: `collider`
-  (capsule recommended), `velocity`, `snapToGround true`, `slopeLimitDeg 45`.
+  (capsule recommended), `velocity`, `stickToGround true`, `slopeLimitDeg 45`.
   API: `moveAndSlide()` (call from `fixedUpdate`), `isOnFloor()`.
 Physics simulates WORLD positions: bodies under offset parents work (offsets compose),

package/skills/incanto-playtesting.md CHANGED Viewed

@@ -48,16 +48,23 @@ two.
 |---|---|
 | `reached "won"` | `GameFlow` state `'won'`, or a `won` signal (e.g. `ScoreKeeper`) |
 | `lost` | `GameFlow` `'gameover'`, a `lost` signal, or the player's `Health.died` |
-| `fell` | the player's world Y dropped below `--fall-below` (default: 50 under the spawn) |
+| `fell` | the player left the world past `--fall-below` (default: 50 m under the spawn in 3D, 1000 px under it in 2D) |
 | `error` | `stats().errors` went above zero — a behavior threw |
 | `stuck` | none of the above before the clock ran out |
-| `never reached` | destinations the bot never came within 2 units of |
+| `never reached` | destinations the bot never came within `--reach-radius` of (default 2 m in 3D, 32 px in 2D) |
 | `never fired` | signals a `connections[]` entry listens to that never happened |
 | `danger` | how many times the player's `Health` emitted `damaged` |
 **Nothing here is a guess about your design.** The scene already declares what
 winning is; this only listens.
+**2D and 3D are read in their own units.** A 2D scene is pixels with **+y
+DOWN**, so "left the world" means y grew past the line and a jump is not a fall;
+a 3D scene is metres with +y up. Both defaults scale to the character —
+32 px next to a ~34 px sprite is the same reach as 2 m next to a 1.8 m rig.
+Set `--fall-below` / `--reach-radius` yourself only when your level says
+otherwise (a very tall 2D shaft, a tiny 3D prop).
 ## Destinations are what YOU marked
 A node counts as somewhere to go when it **runs a behavior**, **carries a

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

@@ -252,6 +252,13 @@ Also `incanto-play`'s `framing` command, and `describeFraming(scene)` /
 as on screen when its `size` box (or collider) is, not only its origin — so a
 200 m island whose origin sits off to the left is correctly `onScreen`.
+**A 2D scene gets a 2D report**, in pixels: the `viewport.design` window centred
+on the current `Camera2D` and CLAMPED by its `limits`, which is the view the
+renderer actually draws. Nothing is ever `behind` a 2D camera and nothing is
+lit, so those two lines are absent rather than answered — read
+`report.dimension` if you consume the structured form. A 2D scene with no
+camera is not a failure: the documented view is `(0,0)`–`(design)`.
 **For actual pixels**, turn on `preserveDrawingBuffer` — WebGL clears the buffer
 the instant a frame composites, so `canvas.toDataURL()` and every screenshot
 built on it come back BLANK without it:
@@ -278,6 +285,13 @@ stopped. It no longer can.
   behavior attached to a `CharacterController3D` stops that behavior — the
   character still walks and the camera still turns. Only a throw from the node's
   own update quarantines the node.
+- **A `connections[]` handler that throws takes down THAT WIRE, and nothing
+  else.** The handler runs inside the emit, so its exception used to surface in
+  whichever node emitted the signal — a `movementStateChanged → play` wire
+  naming a clip the sheet does not have switched off the character controller,
+  and the player stopped walking because an animation was missing. The wire is
+  reported once (naming the handler, not the emitter), disconnected, and counted
+  in `stats().errors`; every other wire on that signal keeps firing.
 - `engine.stats().errors` counts everything swallowed to stay alive. **A game
   that looks fine with `errors: 3` is a broken game** — read `engine.log`.
 - `engine.erroredNodes()` lists them; `engine.resumeErroredNodes()` puts them
@@ -348,6 +362,32 @@ ceiling — drive `engine.timeScale`, with `0.25× 0.5× 1× 2×` presets:
 number is refused and negatives clamp to 0: the scale multiplies every dt in
 the engine, so one NaN would take physics, timers and animation with it.
+### `bunx incanto-logs` — what the game is SAYING
+`incanto-frame` gets the pixels out of the browser; this gets the words. The
+engine writes diagnostics for exactly this — and until they had a channel out,
+they reached a human only, in the debug overlay's logs panel.
+```
+$ bunx incanto-logs
+asset $characters/base never loaded: … responded with 404
+[error] incanto: failed to load model '…/NO-SUCH-MODEL.glb'
+82 nodes · frame rate not measurable — the page is hidden (a window covered by
+another counts), and the browser throttles it. Bring it to the front
+```
+That game's grass, water and trees all rendered — `incanto-frame` called it
+healthy (`subject fills 84.2%`) because they ARE there. Only the player was
+missing. **Pixels and words answer different questions; a game can pass one and
+fail the other**, which is why both are rungs.
+It needs no render, so it answers from a page the browser has stopped drawing.
+Exit 1 when something is wrong: an error logged, an error swallowed to keep the
+game alive, or an asset that never loaded.
+A repeated warning is folded into one line with a count (`×600`) — a game
+shouting the same thing every frame has one problem, not six hundred.
 ### `bunx incanto-frame` — what is actually on screen
 The rung above framing. `framing` PREDICTS what the camera should see from the
@@ -386,6 +426,33 @@ browser, not in the dev server.** You do not have to tell it where anything is
 it reads the ports that are actually listening, asks each one whether it is an
 incanto dev server, and asks that page for a frame over vite's own HMR channel.
+#### Drive it somewhere first
+Every interesting state in a game is downstream of input, and the boot screen is
+the only frame anything could capture before this:
+```
+$ bunx incanto-frame --do "vector move 0 1; step 3000; vector move 0 0" --out bridge.png
+frame 1280×720 · luminance 0.68
+subject fills 21.4% of frame
+drove 180 frames before capturing
+wrote bridge.png — open it, or read it
+```
+The same words `incanto-play` takes — `press`/`release ACTION`, `vector ACTION X Y`,
+`key CODE down|up`, `pointer DX DY`, `step MS`, separated by semicolons or
+newlines. `--do-file` reads a longer plan from a file. One vocabulary for the
+headless gamepad and the live one.
+`step` waits on the REAL clock: this is the running game, with its own loop, its
+own physics and its own animation, and stepping it by hand would fight all three.
+**`drove N frames` is the number to check.** A browser stops animating a tab it
+considers hidden — including a window merely covered by another — and the inputs
+then land on a game that never advances: the capture comes back UNCHANGED and
+looks perfectly healthy. `drove 0 frames` is refused with an error rather than
+handed over as a picture.
 #### Look at it
 ```

package/templates-app/beacon-isle-3d/package.json CHANGED Viewed

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.47.0",
+    "incanto": "^0.49.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/package.json CHANGED Viewed

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.47.0",
+    "incanto": "^0.49.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/package.json CHANGED Viewed

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.47.0",
+    "incanto": "^0.49.0",
     "three": "^0.184.0"
   },
   "devDependencies": {