incanto 0.53.0 → 0.54.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-CdbsY31G.js"></script>
+    <script type="module" crossorigin src="./assets/index-BYfiwbQx.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

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

package/schemas/scene.schema.json

@@ -4235,6 +4235,10 @@
               "type": "boolean",
               "default": true
             },
+            "worldSpace": {
+              "type": "boolean",
+              "default": false
+            },
             "rate": {
               "type": "number",
               "default": 40
@@ -4443,6 +4447,10 @@
               "type": "boolean",
               "default": true
             },
+            "worldSpace": {
+              "type": "boolean",
+              "default": false
+            },
             "rate": {
               "type": "number",
               "default": 40

package/skills/incanto-assets.md

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

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

@@ -463,7 +463,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

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

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

@@ -613,6 +613,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 +649,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

@@ -13,6 +13,37 @@ 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.** |
+
+`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 +63,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

@@ -679,6 +679,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

@@ -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.54.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.53.0",
+    "incanto": "^0.54.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.53.0",
+    "incanto": "^0.54.0",
     "three": "^0.184.0"
   },
   "devDependencies": {