npm - incanto - Versions diffs - 0.53.0 → 0.55.0 - Mend

incanto 0.53.0 → 0.55.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 (57) hide show

package/bin/incanto-check.mjs +56 -1
package/bin/incanto-verify.mjs +46 -0
package/dist/2d.d.ts +46 -3
package/dist/2d.js +3 -3
package/dist/3d.d.ts +105 -6
package/dist/3d.js +10 -6
package/dist/{behavior-Do0Da56m.d.ts → behavior-CyQoSu4n.d.ts} +114 -10
package/dist/{create-game-9D87XaiX.js → create-game-BRt6XKmP.js} +10 -6
package/dist/{create-game-CDJ1lVqK.js → create-game-CzK9_pzg.js} +10 -6
package/dist/debug.d.ts +1 -1
package/dist/debug.js +4 -2
package/dist/editor.js +7 -0
package/dist/{environment-presets-SkGanr2s.js → environment-presets-DAbEdEwh.js} +326 -11
package/dist/{gameplay-CRYw_Q-T.js → gameplay-CZ2yq37J.js} +30 -21
package/dist/gameplay.d.ts +8 -3
package/dist/gameplay.js +1 -1
package/dist/index.d.ts +6 -6
package/dist/index.js +5 -5
package/dist/{loader-Cu_7kJDy.d.ts → loader-DhI1jFW_.d.ts} +1 -1
package/dist/net.d.ts +2 -2
package/dist/net.js +1 -1
package/dist/{particle-sim-BzJ1yxoE.d.ts → particle-sim-C5OfBbmU.d.ts} +11 -0
package/dist/{pathfinding-HNGFqGUZ.d.ts → pathfinding-CXGCpRQe.d.ts} +1 -1
package/dist/{physics-2d-BhZZ-HAp.js → physics-2d-CfWAggJ1.js} +1 -1
package/dist/{physics-3d-DmyO2oaN.js → physics-3d-C_ZJ6f_d.js} +2 -2
package/dist/react.d.ts +1 -1
package/dist/react.js +1 -1
package/dist/{register-DROK2l7J.js → register-en63AEZO.js} +163 -4
package/dist/{register-BTomIiYG.js → register-p48lHE2o.js} +130 -13
package/dist/{replay-9Fy6C10F.d.ts → replay-ePMz26jw.d.ts} +1 -1
package/dist/{replay-DYNUL4BU.js → replay-t1pP0gQg.js} +1 -1
package/dist/{split-screen-DNmcX1Pz.d.ts → split-screen-BsdOHbzP.d.ts} +1 -1
package/dist/{split-screen-CaF9hO7g.js → split-screen-CSb_uZ6W.js} +1 -1
package/dist/{sprite-animation-D_p28jwU.js → sprite-animation-7qvUxF6Z.js} +19 -0
package/dist/{src-C9xyZW7M.js → src-BVOVHRL0.js} +1 -1
package/dist/{teardown-Bw2aeyGI.js → teardown-C7uVSJvx.js} +1 -1
package/dist/{test-CJRsciFk.js → test-Ca5eqELC.js} +49 -14
package/dist/test.d.ts +20 -4
package/dist/test.js +2 -2
package/dist/vite.js +2 -2
package/editor/assets/{agent8-PlFHzJsh.js → agent8-Cz4oHPtm.js} +1 -1
package/editor/assets/{debug-CebV7CDW.js → debug-r-Fi9nZh.js} +2 -2
package/editor/assets/{index-CdbsY31G.js → index-BfqmvXYD.js} +91 -91
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +185 -0
package/skills/incanto-assets.md +45 -2
package/skills/incanto-building-2d-games.md +35 -0
package/skills/incanto-building-3d-games.md +28 -3
package/skills/incanto-environment.md +3 -1
package/skills/incanto-gameplay-behaviors.md +51 -4
package/skills/incanto-node-reference.md +31 -0
package/skills/incanto-performance.md +51 -0
package/skills/incanto-verifying-your-game.md +38 -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-CdbsY31G.js"></script>
+    <script type="module" crossorigin src="./assets/index-BfqmvXYD.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.53.0",
+  "version": "0.55.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

@@ -262,6 +262,9 @@
         {
           "$ref": "#/$defs/Label"
         },
+        {
+          "$ref": "#/$defs/Label3D"
+        },
         {
           "$ref": "#/$defs/LoftMesh3D"
         },
@@ -3337,6 +3340,180 @@
       },
       "required": ["name", "type"]
     },
+    "Label3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "Label3D"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "position": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "rotation": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "static": {
+              "type": "boolean",
+              "default": false
+            },
+            "scale": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [1, 1, 1]
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "renderOrder": {
+              "type": "number",
+              "default": 0
+            },
+            "orderGroup": {
+              "type": "string",
+              "enum": ["background", "terrain", "default", "characters", "effects", "overlay"],
+              "default": "default"
+            },
+            "snapToGround": {
+              "default": null
+            },
+            "texture": {
+              "type": "string",
+              "default": ""
+            },
+            "size": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [1, 1]
+            },
+            "billboard": {
+              "type": "string",
+              "enum": ["y", "full", "none"],
+              "default": "full"
+            },
+            "anchor": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [0.5, 0]
+            },
+            "tint": {
+              "type": "string",
+              "default": "#ffffff"
+            },
+            "opacity": {
+              "type": "number",
+              "default": 1
+            },
+            "flipX": {
+              "type": "boolean",
+              "default": false
+            },
+            "pixelArt": {
+              "type": "boolean",
+              "default": true
+            },
+            "alphaTest": {
+              "type": "number",
+              "default": 0.5
+            },
+            "castShadow": {
+              "type": "boolean",
+              "default": false
+            },
+            "shadowMode": {
+              "type": "string",
+              "enum": ["silhouette", "blob"],
+              "default": "silhouette"
+            },
+            "text": {
+              "type": "string",
+              "default": ""
+            },
+            "height": {
+              "type": "number",
+              "default": 0.3
+            },
+            "color": {
+              "type": "string",
+              "default": "#ffffff"
+            },
+            "font": {
+              "type": "string",
+              "default": "sans-serif"
+            },
+            "outline": {
+              "type": "string",
+              "default": "#000000"
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "LoftMesh3D": {
       "type": "object",
       "properties": {
@@ -4235,6 +4412,10 @@
               "type": "boolean",
               "default": true
             },
+            "worldSpace": {
+              "type": "boolean",
+              "default": false
+            },
             "rate": {
               "type": "number",
               "default": 40
@@ -4443,6 +4624,10 @@
               "type": "boolean",
               "default": true
             },
+            "worldSpace": {
+              "type": "boolean",
+              "default": false
+            },
             "rate": {
               "type": "number",
               "default": 40

package/skills/incanto-assets.md CHANGED Viewed

@@ -146,6 +146,47 @@ Swap in real art later by changing ONLY the `assets{}` entry — node props
 stay untouched.
+## Art you named and never copied
+`bunx incanto-check` warns when a scene asset points at a local file the project
+does not contain:
+```
+  ok  src/game.scene.json
+      warn: $hero → assets/hero.png is not in the project (looked in public/,
+      ./, and beside the scene). It will draw nothing.
+```
+That used to be a browser-only failure — visible in `assetErrors()`, which needs
+a running game and someone to look at it — and it is the single most common way
+a scene draws nothing. Remote (`https:`) and inline (`data:`) urls are left
+alone: the command cannot know, and guessing would be worse than the bug.
+## A spritesheet grid that does not fit says so
+`frameWidth`/`frameHeight` are the two numbers nothing could check for you, and
+getting them wrong does not fail — it draws the wrong art. A size that does not
+divide the sheet slices every row a little further off centre; an animation
+naming a frame past the end of the grid reads whatever is at the wrong end of
+the image.
+Both are reported now, once, the first time the sprite draws:
+```
+[incanto] spritesheet 'hero' does not fit its frame size: 1344 px wide is not a
+whole number of 100 px frames (672, 448, 336, 224, 192, 112 would divide it).
+Every row after the first is cut off centre.
+[incanto] spritesheet 'hero' has 35 frames (0–34), and an animation asks for
+frame 40. Those frames draw whatever is at the wrong end of the sheet.
+```
+The suggested sizes are the ones that actually divide your image, so the fix is
+usually in the message. `bunx incanto-assets info <name>` prints the real frame
+size for a built-in, and the editor's 📚 picker fills it in from the catalog's
+metadata — or leaves it BLANK when the catalog does not carry it, because an
+invented frame size is exactly this bug.
 ## Textures are shared automatically (3D)
 A hundred `Sprite3D`s pointing at one atlas cost **one** fetch, one decode and
@@ -162,9 +203,11 @@ Two consequences worth knowing:
 - **`pixelArt: true` also turns mipmaps off**, which is what makes pixel art stay
   crisp at distance instead of blurring into mud.
-A texture that 404s now shows up in `game.assetErrors()` alongside models, by the
+A texture that 404s shows up in `game.assetErrors()` alongside models, by the
 URL you wrote — so "why is my sprite invisible" is answerable without opening the
-network tab. In **2D** the same question is `renderer.assets.errors()`
+network tab. **That includes vegetation**: a `Tree3D` leaf or bark URL that fails
+used to leave a grove of bare branches and say nothing anywhere, because that
+node keeps its own texture cache. In **2D** the same question is `renderer.assets.errors()`
 (`$ref`, url and reason per failed entry), and the scene EDITOR reads it: a
 failed asset is red in the explorer with the url in its tooltip and the
 consequence in its inspector.

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

@@ -291,6 +291,41 @@ solid core carries the colour). `rate: 0` +
 { "signal": "finished", "from": "Boom", "to": ".", "handler": "onBoomDone" }
 ```
+### Where a particle LIVES: `worldSpace`
+A particle is born in the emitter's LOCAL space by default, so the whole plume
+moves with the node — right for a torch on a moving platform, wrong for almost
+everything else:
+- dust under a running player is GLUED to the player instead of left behind;
+- and the standard way to place a one-shot — move the emitter, `replay()` —
+  drags the PREVIOUS burst across the level with it.
+`"worldSpace": true` makes a particle keep the place it was born:
+```jsonc
+{ "name": "Dust", "type": "Particles2D",
+  "props": { "preset": "smoke", "worldSpace": true } }
+```
+It follows a moving PARENT too, not just the node's own position. Default is
+`false` so existing scenes look exactly as they did.
+### Armed, but not yet: `emitting: false`
+A one-shot with `burst` fires on its FIRST FRAME — which is what you want for a
+firework that is meant to go off as the level opens, and not at all what you
+want for the twenty explosions authored on twenty destructible crates. Set
+`"emitting": false` to arm one and hold it:
+```jsonc
+{ "name": "Boom", "type": "Particles2D",
+  "props": { "preset": "explosion", "rate": 0, "burst": 60, "emitting": false } }
+```
+`node.replay()` fires it — that is the game asking, so `emitting: false` does
+not hold it back — and re-arms it for the next time.
 `node.replay()` re-arms a one-shot. Simulation is deterministic under the
 engine seed — runScript verifies particle gameplay reproducibly.

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

@@ -183,8 +183,31 @@ camera yaw.
 A transform container that orients itself toward the camera every rendered frame;
 **children inherit the rotation** through the scene graph. Hang world-space UI
 under it — HP bars, pickup markers, floating icons — instead of hand-rolling
-camera math in game code. (There is no 3D text node — a nameplate or damage
-number is a canvas-rendered texture on a child `Sprite3D`.)
+camera math in game code.
+### `Label3D` — text standing in the world
+A nameplate, a sign, a damage number:
+```json
+{ "name": "Name", "type": "Label3D",
+  "props": { "text": "Goblin", "height": 0.25, "position": [0, 2, 0] } }
+```
+- **`height`** is the cap height in METRES, and the quad follows what the text
+  measures — a sign is as wide as its words.
+- It **faces the camera** by default (`billboard: "full"`): a damage number read
+  from behind is a bug. `"y"` keeps it upright for a nameplate over a character.
+- **`outline`** is on by default, because white text over a bright wall is
+  unreadable and a damage number lands anywhere. `""` turns it off.
+- It IS a `Sprite3D`, so `anchor`, `tint`, `opacity`, `alphaTest`, `renderOrder`
+  and `orderGroup` all work exactly as they do there.
+A **damage number** is this node plus two lines: set `text`, then float it up
+and fade `opacity` to 0 over ~0.6 s and `queueFree()`. Re-rasterising is
+handled — the texture is rebuilt only when the text (or size/colour/font)
+changes, and the old one is disposed, so a number per hit does not leak a
+texture per hit.
 | Prop | Default | Notes |
 |---|---|---|
@@ -463,7 +486,9 @@ block.
 ## Particles
 `Particles3D` mirrors `Particles2D` (same presets — `fire`, `explosion`,
-`magic`… and the same one-shot `rate: 0` + `burst` → `finished` pattern) as
+`magic`… the same one-shot `rate: 0` + `burst` → `finished` pattern, and the
+same `worldSpace` prop, which is what stops a moved one-shot dragging the
+previous explosion across the level) as
 point sprites in meters: preset distances auto-scale ÷100 (presets are authored
 in 2D px). See incanto-building-2d-games for the full prop list.

package/skills/incanto-environment.md CHANGED Viewed

@@ -1042,7 +1042,9 @@ emitter only when you want a specific custom burst:
 (`replay` re-arms the one-shot burst; a small behavior can also move the
 emitter to the body first — the signal hands you the node:
-`onEntered(body) { splash.position = body.position; splash.replay(); }`.)
+`onEntered(body) { splash.position = body.position; splash.replay(); }` — give
+that emitter `"worldSpace": true`, or the second splash drags the first one to
+the new spot.)
 ## River3D — running water

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

@@ -815,12 +815,59 @@ import { CameraShake, Cooldown, hitStop, screenFlash } from 'incanto/gameplay';
   meters). For cameras WITHOUT a follow script attach the standalone
   `CameraShake` behavior — it composes with any other position writer and
   returns the camera exactly to base.
-- **screenFlash(color?, opacity?, seconds?)** — full-screen damage/pickup
-  flash (DOM, headless no-op).
+- **screenFlash(engine, color?, opacity?, seconds?)** — full-screen damage/
+  pickup flash. DOM, so it draws nothing headless — but it REPORTS (below), so
+  you can still check that it fired.
 - **hitStop(engine, seconds?)** — freezes `engine.timeScale` for REAL
-  seconds then restores; stacked calls extend. Sells melee impacts.
+  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.
 - **engine.timeScale** — 1 realtime, 0.5 slow motion, 0 pause: scales
-  variable AND fixed updates together (physics, timers, behaviors).
+  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
+  tested. (A stepped frame still HAPPENS while paused: `update` runs with
+  `dt = 0`, which is how the pause menu's own key polling keeps working.)
+## Did the effect fire?
+Sound has `engine.audio`; vision has **`engine.effects`**, and the question is
+the same one. `framing()` says where an emitter IS — a particle system that
+never fired and one that fired a hundred times sit at the same coordinates — and
+shake, flash and hit-stop draw nothing at all in a run with no screen.
+```ts
+session.engine.effects.clearLog();
+smashTheCrystal();
+session.step(200);
+session.engine.effects.countOf('explosion');            // 1
+session.engine.effects.countFrom('/Game/Crystal/Boom'); // 1
+session.engine.effects.recent();
+// [{ kind: 'burst', name: 'explosion', from: '/Game/Crystal/Boom', amount: 60, at: 1.2 }]
+```
+- `kind` — `burst` (a one-shot fired) · `emit` (a continuous emitter STARTED —
+  once, not once per particle) · `trail` (a `Trail3D` started laying ribbon) ·
+  `shake` · `flash` · `hitstop`.
+- `name` — the particle preset, or the flash colour.
+- `from` — the node path, or `engine` for the screen-wide ones.
+- `amount` — particles in the burst, shake magnitude, seconds frozen.
+- Bounded at 200, `clearLog()` between assertions.
+A `Trail3D`'s ribbon is a special case worth knowing: it is laid in the RENDER
+pass, because each point needs the node's real world transform (a sword arc is a
+rotating parent). So `trail.pointCount` is **0 headless** — that is the verify VM
+working, not a broken trail — and the `trail` event above is what tells you the
+wiring fired.
+It records that the effect was ASKED FOR, not that a pixel moved — the burst
+that never happened because the signal was never connected looks exactly like
+the burst that happened off-screen, and this tells them apart. For "is it
+running right now", a particle node also has **`aliveCount`**.
+A shake suppressed by `reduceMotion` records NOTHING, on purpose: it did not
+happen, and saying it did would send you hunting a camera bug that is an
+accessibility setting.
 ## Game flow (win / lose / restart)

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

@@ -479,6 +479,35 @@ Signals: `movementStateChanged(state)`
 | `font` | `"monospace"` | string |
 | `align` | `"left"` | string |
+## `Label3D` — `incanto`
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
+| `texture` | `""` | string |
+| `size` | `[1,1]` | array |
+| `billboard` | `"full"` | one of: `y` `full` `none` |
+| `anchor` | `[0.5,0]` | array |
+| `tint` | `"#ffffff"` | string |
+| `opacity` | `1` | number |
+| `flipX` | `false` | boolean |
+| `pixelArt` | `true` | boolean |
+| `alphaTest` | `0.5` | number |
+| `castShadow` | `false` | boolean |
+| `shadowMode` | `"silhouette"` | one of: `silhouette` `blob` |
+| `text` | `""` | string |
+| `height` | `0.3` | number |
+| `color` | `"#ffffff"` | string |
+| `font` | `"sans-serif"` | string |
+| `outline` | `"#000000"` | string |
 ## `LoftMesh3D` — `incanto/3d`
 | Prop | Default | Kind |
@@ -613,6 +642,7 @@ _No props (structural fields only)._
 | `visible` | `true` | boolean |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
+| `worldSpace` | `false` | boolean |
 | `rate` | `40` | number |
 | `burst` | `0` | number |
 | `lifetime` | `[0.6,1.2]` | array |
@@ -648,6 +678,7 @@ Signals: `finished`
 | `snapToGround` | `null` | null |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
+| `worldSpace` | `false` | boolean |
 | `rate` | `40` | number |
 | `burst` | `0` | number |
 | `lifetime` | `[0.6,1.2]` | array |

package/skills/incanto-performance.md CHANGED Viewed

@@ -13,6 +13,41 @@ You do not implement any of this. You decide whether to expose it.
 ---
+## First: where did the frame go?
+A settings menu is what you offer a PLAYER. This is what you ask the game.
+```ts
+game.stats();
+// { fps: 31, frameMs: 32.1, nodes: 4210, triangles: 890_000, drawCalls: 340,
+//   phases: { fixedMs: 21.4, updateMs: 2.2, renderMs: 6.1, otherMs: 2.4 } }
+```
+`fps` and `frameMs` are a total, and a total has no next question. The four
+slices say which part of the frame to look at:
+| slice | what is in it | what to do about it |
+| --- | --- | --- |
+| `fixedMs` | physics and everything on `fixedUpdate` | fewer/simpler colliders, `fixedHz`, sleep distant bodies |
+| `updateMs` | behaviors, node logic, tweens | the per-frame work your game does — profile it in your own code |
+| `renderMs` | the renderer, reported by itself | quality tier, `renderScale`, draw calls, shadows |
+| `otherMs` | the frame MINUS the three above | GC, browser layout, your own rAF work. **Allocations show up here.** |
+The debug overlay's stats chip shows the same four numbers live
+(`phys · logic · draw · other`), so you do not have to call anything to see a
+frame go wrong while you are playing.
+`otherMs` is the one worth knowing about. A frame drop that everyone reads as a
+GPU problem is often garbage collection, and it looks identical from the outside
+— this engine lost a day to exactly that. A big `otherMs` with small everything
+else means you are allocating per frame: replace arrays and objects created in
+`update()` with reused ones.
+Averages over the same rolling window as `frameMs`, so the numbers add up to it
+and are comparable to each other. Headless (`step()`), `fps`/`frameMs` are 0 and
+the slices are still real CPU times — a behavior that got slower shows up in a
+test.
 ## The short version
 ```ts
@@ -32,6 +67,22 @@ Every one of those is written to the save store and comes back on the next launc
 ---
+## Leaks: a level swap has to give the GPU back
+`stats().geometries` and `stats().textures` are the leak witnesses — they count
+what three is holding right now. Swap levels a few times and read them again:
+```ts
+const before = game.stats().geometries;
+await loadLevel(2);
+await loadLevel(1);
+game.stats().geometries; // should be ~before, not 2x before
+```
+Every node that builds geometry releases it when it is freed, and a scene swap
+frees the old tree. If your own code holds a three object (a custom behavior
+that built a mesh), dispose it in the behavior's `onExitTree`.
 ## The four levers, and what each actually costs
 | setting | values | costs | changes live |

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
 ✓ loads — the scene is legal and its assets resolve
 ? plays — nothing declares a win — 8 runs played without error, and there was no end to reach
+✓ feels — 5 of 7 fired — silent: /Game/Boss/Roar, /Game/Boss/Boom
 ? draws — the dev server is running on :5173, but no page answered
 passes what was measured — plays, draws not measured.
@@ -49,6 +50,12 @@ encodes so you do not have to remember them:
 - 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.
+`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
+never triggered plays perfectly and feels dead, and every other rung calls it
+healthy. Nothing firing at all is a failure; some nodes staying silent is
+reported by name, because the bot may simply never have reached the boss.
 Exit 1 only when a rung actually failed. `--behaviors src/behaviors.ts` matters:
 without it your game logic is stubbed and only the structure is played.
@@ -679,6 +686,37 @@ expect(session.engine.audio.countOf('hit')).toBe(1);
 time; `countOf(name)` counts one. A clip whose FILE is broken shows up in
 `assetErrors()` instead. Full guide: `incanto-audio.md`.
+## Speed: which part of the frame is expensive?
+```ts
+game.stats().phases;
+// { fixedMs: 21.4, updateMs: 2.2, renderMs: 6.1, otherMs: 2.4 }
+```
+Physics, behaviors, the renderer, and everything else. The last one is where GC
+and per-frame allocation hide, and it is the slice a screenshot can never show.
+See `incanto-performance.md`.
+## Sight: did the right thing SHOW?
+The same question as sound, about the other half of a game's feedback. Nothing
+renders in the VM, so shake, flash and freeze frames are no-ops and a particle
+system that never fired sits at exactly the same coordinates as one that fired a
+hundred times — `framing()` reports WHERE an emitter is, never whether it went
+off.
+```ts
+session.engine.effects.clearLog();
+smashTheCrystal();
+session.step(200);
+expect(session.engine.effects.countOf('explosion')).toBe(1);
+```
+`engine.effects.recent()` is the last 200 effects — `kind` (`burst` · `emit` ·
+`shake` · `flash` · `hitstop`), the preset or colour, the node path, and how big.
+`countFrom(path)` asks about one emitter, which is usually the wiring question.
+A particle node's `aliveCount` answers the other one: is it running right now.
 ## Multiplayer: do the players end up in the SAME world?
 Every rung above asks about one player. A multiplayer game's first question is

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