npm - incanto - Versions diffs - 0.67.0 → 0.69.0 - Mend

incanto 0.67.0 → 0.69.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 (87) hide show

package/assets/catalog.json +9 -5
package/bin/_pick-server.mjs +48 -0
package/bin/incanto-assets.mjs +14 -1
package/bin/incanto-check.mjs +69 -5
package/bin/incanto-frame.mjs +10 -25
package/bin/incanto-logs.mjs +8 -18
package/bin/incanto-new.mjs +29 -1
package/bin/incanto-serve.mjs +160 -0
package/bin/incanto-verify.mjs +40 -0
package/bin/incanto.mjs +1 -0
package/dist/2d.d.ts +10 -8
package/dist/2d.js +6 -4
package/dist/3d.d.ts +31 -7
package/dist/3d.js +9 -7
package/dist/{audio-player-BNUHo0JF.d.ts → audio-player-C0j2k-yB.d.ts} +80 -3
package/dist/{behavior-ZnfzKDo3.d.ts → behavior-rm8vVzu_.d.ts} +145 -1
package/dist/boot-failure-CKYrEcGF.js +47 -0
package/dist/{create-game-FAXdHta3.js → create-game-CvJ1wSRP.js} +27 -27
package/dist/{create-game-DMetd3vR.js → create-game-CwxEDlCm.js} +15 -11
package/dist/debug.d.ts +1 -1
package/dist/{duplicate-B8QnX2-r.js → duplicate-Dj4L-5AA.js} +1 -1
package/dist/{editor-switch-DAvWQeld.d.ts → editor-switch-CnIOiyNJ.d.ts} +1 -1
package/dist/editor.js +12 -6
package/dist/env.d.ts +1 -1
package/dist/{environment-presets-C-5g2pMh.js → environment-presets-BO-7XoFV.js} +58 -9
package/dist/{frame-report-DCnHFmto.d.ts → frame-report-DNxDAb1w.d.ts} +8 -0
package/dist/{frame-report-BSMny7oe.js → frame-report-Dlq13Gyj.js} +1 -0
package/dist/{gameplay-CGSv-9XR.js → gameplay-D1KixWK8.js} +175 -151
package/dist/gameplay.d.ts +51 -3
package/dist/gameplay.js +2 -2
package/dist/index.d.ts +6 -6
package/dist/index.js +8 -7
package/dist/{loader-KZESOZmE.js → loader-DZE7B07H.js} +48 -7
package/dist/{loader-DyT30ArB.d.ts → loader-DadV2QCT.d.ts} +2 -2
package/dist/net.d.ts +2 -2
package/dist/net.js +1 -1
package/dist/{physics-2d-_B6zj3zU.js → physics-2d-CF5yyjbj.js} +2 -2
package/dist/{physics-3d-i1IeAY0F.js → physics-3d-DbYaEcZy.js} +3 -3
package/dist/react.d.ts +2 -2
package/dist/react.js +1 -1
package/dist/{register-vIxU3Xbv.js → register-DbVArsns.js} +19 -10
package/dist/{register-Cs53CY7s.js → register-mmfugpaQ.js} +159 -6
package/dist/{replay-BkpDV51O.js → replay-BEHLDcQV.js} +28 -5
package/dist/{replay-D0GcEHYU.d.ts → replay-BQfkX4x7.d.ts} +38 -4
package/dist/{schema-CFeioQRE.d.ts → schema-B6ugCV1Q.d.ts} +11 -0
package/dist/{sheet-grid-BT6N_Bjs.js → sheet-grid-Cea343VO.js} +6 -2
package/dist/{split-screen-DS8RaUV_.js → split-screen-CauMwu6y.js} +2 -2
package/dist/{split-screen-DD5eYIgW.d.ts → split-screen-Cg76MCV5.d.ts} +3 -3
package/dist/{src-BLlsGJW9.js → src-CYEu-_S9.js} +1 -1
package/dist/{teardown-LB9cTnXJ.js → teardown-CMqFVxO9.js} +5 -4
package/dist/{test-81uZ967a.js → test-D6ISmuFE.js} +73 -25
package/dist/test.d.ts +17 -6
package/dist/test.js +3 -3
package/dist/vite.d.ts +70 -2
package/dist/vite.js +176 -14
package/dist/{rendering-options-ByAdi8PF.js → webgl-unavailable-Z5_g8x9H.js} +57 -2
package/editor/assets/{agent8-C2jtNKbx.js → agent8-BDvaZMQJ.js} +1 -1
package/editor/assets/{debug-DoU3KeqS.js → debug-CMULinBW.js} +1 -1
package/editor/assets/{index-CNqHojcC.js → index-CZIRr5EL.js} +92 -92
package/editor/index.html +1 -1
package/package.json +4 -3
package/schemas/scene.schema.json +4 -0
package/skills/incanto-3d-character.md +1 -0
package/skills/incanto-assets.md +16 -2
package/skills/incanto-audio.md +65 -0
package/skills/incanto-building-2d-games.md +66 -0
package/skills/incanto-building-3d-games.md +97 -2
package/skills/incanto-gameplay-behaviors.md +46 -2
package/skills/incanto-node-reference.md +1 -0
package/skills/incanto-physics-and-input.md +23 -0
package/skills/incanto-save-slots.md +27 -0
package/skills/incanto-scene-json-authoring.md +12 -1
package/skills/incanto-verifying-your-game.md +96 -2
package/skills/incanto-your-first-game.md +2 -1
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/beacon-isle-3d/src/main.ts +21 -4
package/templates-app/platformer-2d/index.html +0 -23
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/platformer-2d/src/behaviors.ts +26 -16
package/templates-app/platformer-2d/src/game.scene.json +17 -27
package/templates-app/platformer-2d/src/main.ts +32 -13
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/main.ts +25 -7
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/main.ts +34 -16
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/src/main.ts +21 -4

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-CNqHojcC.js"></script>
+    <script type="module" crossorigin src="./assets/index-CZIRr5EL.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.67.0",
+  "version": "0.69.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -54,7 +54,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
     "test": "vitest run --project unit --root ../.."
   },
   "peerDependencies": {
@@ -102,6 +102,7 @@
     "incanto-new": "bin/incanto-new.mjs",
     "incanto-frame": "bin/incanto-frame.mjs",
     "incanto-verify": "./bin/incanto-verify.mjs",
-    "incanto-logs": "./bin/incanto-logs.mjs"
+    "incanto-logs": "./bin/incanto-logs.mjs",
+    "incanto-serve": "./bin/incanto-serve.mjs"
   }
 }

package/schemas/scene.schema.json CHANGED Viewed

@@ -2378,6 +2378,10 @@
               "type": "boolean",
               "default": true
             },
+            "platformCarry": {
+              "type": "boolean",
+              "default": true
+            },
             "turnSpeed": {
               "type": "number",
               "default": 100

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

@@ -54,6 +54,7 @@ did not until now.
 | `maxJumps` | `1` | `2` = double jump. Extra jumps work in mid-air. |
 | `airControl` | `0.2` | how much ground control you keep airborne (0 = committed, 1 = full). |
 | `fallGravity` | `2.5` | gravity multiplier while falling. Higher = snappier arc. |
+| `platformCarry` | `true` | ride whatever you are standing on. Off = the controller steers in WORLD space, so standing still on a moving floor brakes you off it (measured: 95.9% of a moving deck's travel kept, 0.0% with this off). |
 Every one defaults to OFF (`0` / `1`) or to the previous hard-coded constant, so
 a scene that asks for nothing behaves exactly as before.

package/skills/incanto-assets.md CHANGED Viewed

@@ -21,13 +21,27 @@ playable character — model, locomotion clips, body, controller, skin and input
 ## 1. Built-in assets (in the package)
 ```bash
-bunx incanto-assets list                  # the full catalog (see categories below)
+bunx incanto-assets list                  # name · kind · GRID · what it is
 bunx incanto-assets info medieval-knight  # description + animation names
 bunx incanto-assets copy medieval-knight --out public/assets
 ```
 `list --json` prints every entry. Each entry carries a **`url`** — the drop-in
-reference you put in scene JSON so the asset LOADS (the contract, see §1b).
+reference you put in scene JSON so the asset LOADS (the contract, see §1b) —
+and, where the art has a grid, the numbers a node needs:
+```
+2dbasic          character  [animated] 111×83           2dbasic sprite sheet image…
+minecraft-tiles  tile                  16×16 (25 tiles) Minecraft-themed tiles…
+```
+`frameWidth`/`frameHeight` are what `AnimatedSprite2D.frameWidth` and
+`TileMap2D.tileSize` want; `columns` and `tiles` tell you the highest index a
+`legend` may name (25 tiles means 0–24, and asking for 99 draws clamp-streaks —
+the engine reports it, but the catalog is where you get the number). **The sizes
+live in these fields and nowhere else** — a frame size in the description was a
+second copy, and it drifted: `2dbasic` said 192×192 for art whose real grid is
+111×83.
 ### Categories — the whole built-in set

package/skills/incanto-audio.md CHANGED Viewed

@@ -396,6 +396,60 @@ changed under it. `engine.music` deliberately survives a scene swap (it belongs
 to the engine, not the scene): call `engine.music.stop(1)` or `crossfadeTo` when
 the music should change.
+## Sounds on a GRID: rhythm games and anything charted to a soundtrack
+A sound fired from `update()` cannot land closer than one frame to where a chart
+wants it — 16.67 ms at 60 Hz, 33.33 ms at 30, and that is the whole difference
+between a rhythm game that feels tight and one that does not. The engine's frame
+clock is exact (3600 steps land on `engine.time` 60.000000000 s and beat error
+never compounds); the last 16 ms is the gap.
+Schedule on the AUDIO clock instead. Queue a short LOOKAHEAD ahead of now, every
+frame, and let Web Audio place the sound:
+```ts
+const LEAD = 0.08;                 // schedule this far ahead of the speaker
+let cursor = 0;                    // next un-queued note
+engine.updated.connect(() => {
+  const horizon = engine.sfx.now + LEAD;
+  while (cursor < chart.length && startedAt + chart[cursor].atSec <= horizon) {
+    hit.playAt(startedAt + chart[cursor].atSec);   // NOT play() — see below
+    cursor++;
+  }
+});
+```
+- **`engine.sfx.now`** — seconds on the audio clock, the one the sound is
+  actually placed on. `0` headless and before the first sound.
+- **`AudioPlayer.playAt(when)`** and **`engine.sfx.play(params, gain, { when })`** —
+  PRESETS only. A `src` clip goes through an `<audio>` element, which has no
+  scheduling clock, so `playAt` on one plays immediately.
+- **`play()` takes no arguments, deliberately.** It is the method scenes wire
+  signals to, and a signal hands its handler whatever it carries — `collected`
+  leads with a number, so `collected → play` would have become `play(10)` and
+  scheduled the pickup sound at absolute audio-clock second 10. Scheduling has
+  its own name.
+- A time already past plays immediately (Web Audio's own rule), so a scheduler
+  that ran late is late, not silent.
+- Everything else still applies: the bus gain, `engine.audio.recent()`, and
+  `muted`. A scheduler hand-rolled on a raw `AudioContext` hits the same
+  accuracy and loses all three.
+Measured: 0 of 64 notes were given a scheduled start on the frame path; the same
+64 queued this way land at **|mean| 0.000000 ms**.
+**Charting against a music FILE** needs the playhead of the thing you can hear,
+not a counter you started next to `music.play()` (a different clock, which keeps
+counting through a gesture-block, a stall or a seek):
+```ts
+const songSeconds = engine.music.playhead;   // null = nothing playing, or no clock
+```
+It is the raw element time, so a looping track wraps to 0 each pass — a loop
+boundary to chart against, not a fault.
 ## Decision guide
 - **Need a quick game sound (coin/jump/hit/explosion/…)** → set `preset`. Done.
@@ -430,6 +484,17 @@ session.engine.audio.recent();
 its volume comes from. `countOf(name)` is the assertion you usually want;
 `clearLog()` resets between steps.
+**A LOOPING sound is recorded once, and its entry carries `loop: true`.**
+Re-recording every pass would evict the rest of the log within seconds for a
+0.2 s preset, so the count stays 1 — which used to make "the alarm loops"
+indistinguishable from "the alarm fired once and stopped". Assert the flag when
+that is the difference you care about:
+```ts
+const alarm = session.engine.audio.recent().find((e) => e.name === 'alarm');
+expect(alarm?.loop).toBe(true);
+```
 This covers every path: `AudioPlayer.play()` on both the procedural and the
 `src` route, `engine.music.play`/`crossfadeTo`, and `engine.sfx.startVoice`. It
 records the INTENT to play — that the wiring fired — not that a speaker moved;

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

@@ -212,6 +212,35 @@ offsets that survive any canvas size: a `Label` at `[-16, 16]` under a
 `top-right` layer hugs the corner everywhere. Misspelled anchors fail at load
 listing the valid set. With a viewport design, UI coordinates are design px.
+### A `UILayer` still SCALES. On a phone, use `HudLayer`
+`UILayer` ignores the camera; it does not ignore the viewport. Its contents are
+design pixels multiplied by the same scale as the world, and on a portrait phone
+that scale is small:
+```
+1280×800   scale 1.333   a fontSize 15 Label paints at 20 device px
+390×844    scale 0.406   the same Label paints at  6.1 device px
+```
+Six device pixels is an unreadable smear, and it is the flagship 2D template's
+control hint before this was fixed. The vertical framing goes the same way:
+`design: [960, 540]` under `fit: "expand"` shows a portrait phone **2077 world
+px** of height, so the play surface is a band with acres of empty sky.
+**`HudLayer` and the `Ui*` widgets are DOM at their declared CSS pixels** and are
+immune — which is why the engine's own volume sliders and touch controls stayed
+legible in the same capture that reduced the template's HUD to a grey line. Use
+them for anything a player has to READ:
+| | |
+| --- | --- |
+| `Label` under `UILayer` | part of the picture — damage numbers, world-anchored callouts, art |
+| `UiText` under `HudLayer` | part of the interface — score, hearts, hints, menus |
+See `incanto-hud.md`. It costs nothing on desktop and it is the difference
+between a readable and an unusable phone build.
 ## Patterns
 - Group pickups/enemies (`"groups": ["coins"]`) and query `scene.tree.getNodesInGroup('coins')`.
@@ -485,3 +514,40 @@ which is why a wall jump was not awkward to write but impossible.
 headless bot sessions and reports what could not be reached, which wires never
 fired, and whether anything in the level can hurt the player. See
 `incanto-playtesting.md`.
+## When the boot FAILS: say so, or the bar sits at 100% forever
+`createGame2D`/`createGame2D` reject like any promise, and the loading overlay
+every starter shows is removed on the line *after* the await. So a boot that
+fails leaves the bar at 100% with no text, and the reason in a console the
+player will never open. Measured with WebGL denied on a pristine scaffold: the
+overlay was still reading `Emberwood 100%` 8.6 seconds later.
+One `.catch` fixes it, and every shipped template now carries it:
+```ts
+import { createGame2D, showBootFailure } from 'incanto/2d';
+const game = await createGame2D({ canvas, scene: sceneJson }).catch((e) => {
+  showBootFailure(e);   // paints the reason into #loading (or its own panel)
+  throw e;
+});
+document.querySelector('#loading')?.remove();
+```
+**No WebGL is the case worth naming** — the 2D renderer is WebGL too. A machine
+with acceleration off, a blocklisted driver, a locked-down or headless browser, or a page that already
+holds too many contexts cannot make one, and three throws
+`Error('Error creating WebGL context.')` with nothing to branch on. The engine
+rethrows it as an `IncantoError` with code **`WEBGL_UNAVAILABLE`** and a message
+naming the likely causes, so you can show a real screen:
+```ts
+import { isWebGLAvailable } from 'incanto/2d';
+if (!isWebGLAvailable()) showMyOwnBrowserTooOldScreen();   // ask BEFORE booting
+```
+`isWebGLAvailable()` probes a throwaway canvas and never touches yours; it
+returns `false` outside a browser.

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

@@ -320,8 +320,66 @@ atmosphere recipe below).
 ## Reference example
-A minimal 3D scene — ground plane + 3 orbiting primitives + sun +
-lamp + camera, verified rendering. Copy it as a starting point.
+The smallest 3D scene that renders something you can see. Every line matters:
+without the light it is black, without `current: true` the camera is a guess,
+and without `ambient` the unlit faces are pitch dark.
+```json
+{
+  "format": 1,
+  "type": "scene",
+  "dimension": "3d",
+  "name": "Hello",
+  "environment": {
+    "sky": { "type": "atmosphere", "elevationDeg": 35, "azimuthDeg": 140 },
+    "ambient": { "color": "#ffffff", "intensity": 0.2 },
+    "shadows": true
+  },
+  "root": {
+    "name": "World",
+    "type": "Node3D",
+    "children": [
+      { "name": "Sun", "type": "DirectionalLight3D",
+        "props": { "position": [6, 10, 4], "intensity": 2, "castShadow": true } },
+      { "name": "Camera", "type": "Camera3D",
+        "props": { "position": [7, 6, 9], "rotation": [-26, 36, 0], "current": true } },
+      { "name": "Ground", "type": "MeshInstance3D",
+        "props": { "mesh": "plane", "size": [40, 1, 40], "receiveShadow": true,
+                   "material": { "color": "#6b8f3a", "roughness": 1 } } },
+      { "name": "Pivot", "type": "Node3D", "script": { "name": "Spin" },
+        "children": [
+          { "name": "Cube", "type": "MeshInstance3D",
+            "props": { "mesh": "box", "position": [2, 0.5, 0], "castShadow": true,
+                       "material": { "color": "#e0563f", "roughness": 0.4 } } },
+          { "name": "Ball", "type": "MeshInstance3D",
+            "props": { "mesh": "sphere", "size": [0.6, 0.6, 0.6], "position": [-2, 0.6, 0],
+                       "castShadow": true,
+                       "material": { "color": "#4f8fe0", "metalness": 0.6, "roughness": 0.2 } } },
+          { "name": "Gem", "type": "MeshInstance3D",
+            "props": { "mesh": "gem", "size": [0.5, 0.5, 0.5], "position": [0, 0.8, 2],
+                       "castShadow": true,
+                       "material": { "color": "#ffd166", "flatShading": true, "roughness": 0.1 } } }
+        ] }
+    ]
+  }
+}
+```
+Rotating the PIVOT orbits all three children — no maths in the behaviour:
+```ts
+import { Behavior } from 'incanto';
+export class Spin extends Behavior {
+  override update(dt: number): void {
+    const node = this.node as unknown as { rotation: number[] };
+    node.rotation = [0, (node.rotation[1] ?? 0) + 40 * dt, 0];
+  }
+}
+```
+Check it before you open a browser: `bunx incanto-check` says the scene is legal
+and lit, and `bunx incanto-verify` walks the whole ladder.
 ## Atmosphere (sky, fog, shadows, exposure)
@@ -648,3 +706,40 @@ It stubs unregistered behaviors (it measures geometry, not logic; a scene with
 any custom behavior used to read as clean — measured 0 floating before
 `registerBehavior`, 26 after) and throws when it cannot measure. A level built
 from mesh floors has no terrain height to read: use a physics raycast instead.
+## When the boot FAILS: say so, or the bar sits at 100% forever
+`createGame2D`/`createGame3D` reject like any promise, and the loading overlay
+every starter shows is removed on the line *after* the await. So a boot that
+fails leaves the bar at 100% with no text, and the reason in a console the
+player will never open. Measured with WebGL denied on a pristine scaffold: the
+overlay was still reading `Emberwood 100%` 8.6 seconds later.
+One `.catch` fixes it, and every shipped template now carries it:
+```ts
+import { createGame3D, showBootFailure } from 'incanto/3d';
+const game = await createGame3D({ canvas, scene: sceneJson }).catch((e) => {
+  showBootFailure(e);   // paints the reason into #loading (or its own panel)
+  throw e;
+});
+document.querySelector('#loading')?.remove();
+```
+**No WebGL is the case worth naming.** A machine with acceleration off, a
+blocklisted driver, a locked-down or headless browser, or a page that already
+holds too many contexts cannot make one, and three throws
+`Error('Error creating WebGL context.')` with nothing to branch on. The engine
+rethrows it as an `IncantoError` with code **`WEBGL_UNAVAILABLE`** and a message
+naming the likely causes, so you can show a real screen:
+```ts
+import { isWebGLAvailable } from 'incanto/3d';
+if (!isWebGLAvailable()) showMyOwnBrowserTooOldScreen();   // ask BEFORE booting
+```
+`isWebGLAvailable()` probes a throwaway canvas and never touches yours; it
+returns `false` outside a browser.

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

@@ -71,7 +71,14 @@ warn: World/Enemy: Chase.target — '%Playerr' matches no node in this scene.
 — which is the one failure that used to be completely silent (a prop path
 resolves with `getNodeOrNull`, so the scene opens and the enemy just never
-chases). `Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
+chases). That is for a behaviour the ENGINE ships: `incanto-check` reads scene
+files and cannot load your TypeScript, so a `nodePath: true` prop on a
+behaviour of YOUR OWN is invisible to it. `auditScene` from `incanto/test`
+gives the identical sentence once your behaviours are registered — which is why
+every scaffolded `verify.ts` calls it before `runScript`, and why a
+hand-written harness that skips it loses this check.
+`Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
 is a load error naming the node, not a surprise in the browser.
 **Never write `/root/<RootName>/...`.** If your root node is named `Game`, the
@@ -1189,6 +1196,16 @@ Multi-scene games: `flow.goToScene(nextSceneJson, { fadeSeconds: 0.4 })`
 fades to black, swaps, fades back (headless = instant). Title → level →
 next level is three JSON files and this one call.
+**A swap builds the physics world the incoming scene needs.** `physics: 'auto'`
+can only look at the scene the game BOOTS with, and a title screen has no
+bodies — so this used to leave the level with no physics at all: it rendered
+perfectly, nothing fell, nothing collided, nothing could be collected or hurt.
+`createGame2D`/`createGame3D` now hand the engine a way to build one, and the
+swap asks. It is asynchronous (Rapier is WASM), so the first frames after a
+swap into a physics scene run unsimulated — imperceptible, and the alternative
+was a game that never simulated. `physics: false` stays off across swaps, and a
+scene with no bodies still pays for nothing.
 ## DayNight (live 24-hour cycle)
 Drives the scene `environment` (needs an atmosphere sky): sun elevation/
@@ -1211,7 +1228,7 @@ spawners, music, or monster aggression to it. The `hour` field (0-24) is
 writable: jump to a time of day in one assignment. For one-off look changes
 use `setEnvironment3D(engine, patch)` from `incanto/3d` directly.
-## Boot loading overlay## Boot loading overlay
+## Boot loading overlay
 ```ts
 import { preloadSceneAssets } from 'incanto';
@@ -1221,6 +1238,33 @@ await preloadSceneAssets(sceneJson.assets);   // black screen + bar + %, auto-re
 Replaces the ~125-line hand-rolled loading screen; `createLoadingOverlay()`
 gives you the raw overlay when you preload something else.
+## Where a node actually IS (`position` is parent-relative)
+`node.position` is the offset from its PARENT, not the world. A scene nests
+freely — `Terrain/Clouds/Cloud1/Puff1` four deep is what the engine's own
+generator writes — so a distance check reading `position` on a nested node
+measures from the wrong origin and says nothing about it. Measured on a crate
+parented to a rock: `position` is `[0, 3.02, 0]` and the world point is
+`[13, 14.31, 80.18]` — **82 m apart**.
+```ts
+import { localFromWorld, worldPosition } from 'incanto/gameplay';
+const here = worldPosition(crate);              // [13, 14.31, 80.18]
+crate.position = localFromWorld(crate, [0, 20, 0]);   // put it at world [0,20,0]
+```
+Both work headless and in both dimensions — arity comes from the node (2 for a
+2D node, 3 for a 3D one), and an ancestor with no `position` contributes
+nothing. Do NOT reach for `_ensureObject3D().matrixWorld`: it is internal, and
+in a headless verify script there is no renderer to parent the object, so it
+hands back the LOCAL position with no warning.
+**Translation only.** They sum ancestor positions and ignore ancestor rotation
+and scale — the same contract physics already uses (`worldPosition2D` /
+`worldPosition3D`) and that `applyGroundSnap` assumes. A node under a ROTATING
+parent needs the renderer's matrix, not this.
 ## Persistence (high scores, unlocks, settings)
 ```ts

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

@@ -297,6 +297,7 @@ Signals: `movementStateChanged(state)`
 | `pitchMin` | `-1.3` | number |
 | `pitchMax` | `1.5` | number |
 | `cameraCollision` | `true` | boolean |
+| `platformCarry` | `true` | boolean |
 | `turnSpeed` | `100` | number |
 | `camLerp` | `25` | number |
 | `moveAction` | `"move"` | string |

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

@@ -479,6 +479,29 @@ rotating discs. It is what makes a floating-island game work.
 Author it the obvious way: move the platform's `position` (a behavior, a
 `PathFollow`, an `Oscillate`). Nothing else to declare.
+**The 3D PLAYER is a different rig, and it needs one prop.** A
+`CharacterController3D` must sit under a dynamic `RigidBody3D` (hard error
+otherwise), not a `CharacterBody3D` — the character bodies in a 3D game are its
+enemies and NPCs. The controller steers toward a target velocity every fixed
+step, so pressing nothing means "target zero", which in world space is a brake
+aimed at the platform's own motion. `platformCarry` (default **true**) makes
+that target relative to the floor instead. Measured on a 400 m deck moving
+4 m/s, rider pressing nothing: **95.9%** of the travel kept, **0.0%** with
+`platformCarry: false`.
+```json
+{ "name": "Ctl", "type": "CharacterController3D",
+  "props": { "view": "free", "platformCarry": false } }
+```
+Turn it off for a conveyor you want to be scenery. Vertical carry needs no prop
+either way — the hover spring rides whatever surface is under it, which is why
+a 3D elevator always looked right while a conveyor did not.
+The carry comes from the platform's POSITION DELTA, not its `linearVelocity`,
+because writing `position` calls `setTranslation` — a teleport that transfers no
+momentum to anything. Both authoring styles work.
 The carry stops the moment the character is no longer grounded on it, so walking
 off an edge or jumping is not "sticky", and it is vertical as well as horizontal
 — an elevator lifts you.

package/skills/incanto-save-slots.md CHANGED Viewed

@@ -253,6 +253,33 @@ that DOES serialize, on a node with no uid, is state that goes nowhere.
 (`Health`, `ScoreKeeper`, `Collector`); a scene file cannot be asked whether
 YOUR behavior serializes, so this walks the live tree and names those too.
+## When the browser will not store anything
+A private window, storage disabled, or an exhausted quota: `localStorage`
+throws, and the store falls back to memory. **That fallback is right** —
+refusing to save would be worse — but everything in the session still reads
+healthy, so the player only finds out by reloading and losing the run. Measured
+under Safari-private conditions: `set('highScore', 4200)` then `get(...)`
+returned 4200, with zero warnings and no way to ask.
+```ts
+if (!slots.persistent) {
+  banner.show('This browser will not keep your progress — private window?', { seconds: 6 });
+}
+```
+`SaveSlots.persistent` (and `SaveStore.persistent`) is `false` whenever writes
+live only as long as the tab. The engine also says it once per namespace: on the
+console, and — from `SavePoint` — through `engine.log`, so `incanto-logs` and
+the `says` rung of `incanto-verify` see it too.
+`SavePoint` still emits `saved(slot)` in that state, deliberately: it did save,
+for as long as the page is open, and a Continue button that never lights up
+would be a second bug. Ask `persistent` before promising the player anything.
+Headless — tests, verify scripts, SSR — `persistent` is `false` and nothing is
+logged: in-memory is the design there, not a failure.
 ## Saving from the scene — `SavePoint`
 *When* to save is a design decision (checkpoint, level end, on quit) and only

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

@@ -26,6 +26,7 @@ wiring, and composition are all in the file. TS is for *behavior only* (attached
   "constants": { "UI": 1000, "Background": -100 },
   "input": { "<action>": { "...": "...", "touch": "joystick|button (optional — mobile on-screen controls)" } },
   "multiplayer": { "room": "auto" },
+  "fragment": false,
   "root": { "name": "Level1", "type": "Node", "children": [] },
   "connections": []
 }
@@ -33,6 +34,13 @@ wiring, and composition are all in the file. TS is for *behavior only* (attached
 - `format` MUST be `1`. `type` MUST be `"scene"`. `name` non-empty.
 - `dimension` is optional: `"2d"` or `"3d"` only.
+- `fragment` (optional, default `false`) says this file is a PIECE of another
+  scene — a spawner's prefab, a sub-scene something instances — and is never
+  rendered on its own. It changes nothing at runtime; it tells the checker to
+  stop asking a prefab where its camera and its sun are. Set it on any scene
+  you load from TypeScript and hand to a spawner. (A scene another scene
+  embeds with `instance` needs no key — `incanto-check` walks the project and
+  can see that for itself.)
 - `viewport` (optional) makes scene JSON own responsive layout: author the world
   in fixed `design` pixels (`[width, height]`, positive numbers) and the renderer
   maps them onto any canvas size. `fit`: `"expand"` (design rect always fully
@@ -158,7 +166,10 @@ level 1's layers.
 ## Parents and children
 EVERY node type can hold children — `children` is universal, so any node works
-as a grouping container. The inverse is not true: some types demand a SPECIFIC
+as a grouping container. **A child's `position` is relative to its parent**, so
+nesting is also how you move a group: shift the parent and everything under it
+follows. From code, `worldPosition(node)` (`incanto/gameplay`) is where a nested
+node actually is; `node.position` is the local offset. The inverse is not true: some types demand a SPECIFIC
 parent and are therefore also invalid as the root. Today's rule:
 - `CharacterController2D` must be a direct child of a `CharacterBody2D` —

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

@@ -116,6 +116,16 @@ The sections below are the same rungs one at a time, for when you need the detai
 ## 1. After EVERY scene edit: `incanto-check`
+```bash
+bunx incanto-check                                  # structure, assets, semantics
+bunx incanto-check --behaviors src/behaviors.ts --strict-behaviors
+```
+`--strict-behaviors` makes a `script.name` that resolves nowhere a FAILURE
+instead of a stub — and it needs `--behaviors` to know what you registered.
+Without it, on any project with a behaviour of its own, it could only ever fail:
+`Unknown behavior 'Hunter' … Did you forget registerBehavior?`
 ```bash
 bunx incanto-check               # validates every *.scene.json under cwd
 bunx incanto-check --json        # machine-readable (code + details.path/prop)
@@ -637,8 +647,9 @@ the path, then **▶ play ▸ ⤢ run as the game** and the page is the game aga
 running your edit. `game.openEditor()` is the same switch from code.
 It follows `debug` (so a build with the overlay has it) and loads lazily, so a
-game that never opens it never downloads it. `editor: false` opts out;
-`editor: { save }` adds the editor's save button, wired to your own writer:
+game that never opens it never downloads it. `editor: false` opts out at
+RUNTIME — the button is absent — and `editor: { save }` adds the editor's save
+button, wired to your own writer:
 ```ts
 createGame3D({
@@ -660,6 +671,89 @@ overlay is a lazily-imported chunk — it stays out of the main bundle (no size
 cost), but it still ships in the build, so that runtime `debug` flag is the only
 thing gating it: keep it `false` (or dev-gated) in anything you publish.
+## 9. Verify the thing you SHIP, not just the thing you run
+Everything above measures a dev server. The artifact a player gets is
+`bun run build` — a bundled, minified `dist/` with different asset paths and a
+different module graph — and the boot path is the only code a BUILD adds over a
+SCENE. Two of the nastiest defects this engine has had lived exactly there: a
+`main.ts` whose scene swap left the game with no physics, and a boot that threw
+behind a loading overlay that never came down.
+`incanto-frame` and `incanto-logs` ask a dev server, and the dev server asks the
+page over vite's HMR channel. A build has no HMR, so they used to answer:
+```
+? draws — no incanto dev server found.
+? says  — no incanto dev server found.
+```
+**`incanto-serve` closes that.** It serves your build as plain static files —
+no bundler, no transform, byte-for-byte what you deploy — and adds only the
+`/__incanto/*` endpoints the CLIs already speak, plus one inline script injected
+into `index.html` at serve time. Nothing is written to disk, so what you measure
+is what you ship.
+```bash
+bun run build                 # the artifact
+bunx incanto-serve            # ./dist on :4180 (or: incanto-serve build --port 5050)
+# open http://127.0.0.1:4180/ , then:
+bunx incanto-verify           # draws and says now measure the BUILT game
+bunx incanto-logs             # what the built page is complaining about
+bunx incanto-frame --out shipped.png
+```
+**Ship-check list**, in the order things actually break:
+1. **`bun run build` at all.** Dev-only code (`import.meta.env.DEV`, a plugin
+   that is `apply: 'serve'`) can compile and then do nothing.
+2. **Open the built page.** A blank screen with a console error is the common
+   failure; `incanto-logs` reads it without you opening devtools.
+3. **`incanto-verify` against `incanto-serve`.** `draws` catches an asset base
+   path that survived dev and broke under a subdirectory deploy; `says` catches
+   the 404s.
+4. **A phone-sized window.** See `incanto-web-integration.md` — a HUD that is
+   legible at 1280×800 can be 6 px tall at 390×844.
+5. **A second load.** Saves, settings and unlocks come back; a private window
+   answers `slots.persistent === false` (see `incanto-save-slots.md`).
+The one thing `incanto-serve` is not is a production server: it is a local tool
+for looking at a build, on `127.0.0.1` by default.
+### The editor is in your build, even in a 2D game
+`editor: false` is a runtime option and **cannot remove bytes from a bundle**.
+The editor chunk is lazy — a game that never opens it never downloads it — but
+it is in `dist/`, and it imports `incanto/3d`, which imports rapier3d. Measured
+on a pristine `platformer-2d` scaffold:
+```
+2236503  assets/rapier-*.js    rapier3d      ← a 2D game can never execute this
+1692278  assets/rapier-*.js    rapier2d      ← the one it uses
+ 471186  assets/3d-*.js        the 3D adapter
+─────────
+5979588  total
+```
+A build-time decision needs a build-time lever:
+```ts
+import { incantoScenes, incantoTrim } from 'incanto/vite';
+export default defineConfig({
+  plugins: [incantoScenes(), incantoTrim({ editor: false })],
+});
+```
+```
+5979588  →  2769972 bytes     53.7% smaller, same game
+```
+Build only: the dev server keeps the editor, so `☰ debug ▸ ✎ edit this scene`
+works the whole time you are making the game and is simply absent from what you
+ship. Opening it in a trimmed build says so in one sentence rather than failing
+obscurely. Reach for this when deploy size matters — a CDN, a jam upload, an
+agent8 zip — and leave it off otherwise.
 ## 8. Debugging signals
 - `this.log.info(...)` in behaviors — shows up in `runScript().logs` (and the