npm - incanto - Versions diffs - 0.66.0 → 0.68.0 - Mend

incanto 0.66.0 → 0.68.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 (96) hide show

package/bin/_behaviors-loader.mjs +87 -0
package/bin/_pick-server.mjs +48 -0
package/bin/incanto-check.mjs +16 -2
package/bin/incanto-editor.mjs +39 -2
package/bin/incanto-feel.mjs +4 -1
package/bin/incanto-frame.mjs +37 -3
package/bin/incanto-logs.mjs +23 -3
package/bin/incanto-multiplay.mjs +50 -1
package/bin/incanto-play.mjs +3 -1
package/bin/incanto-playtest.mjs +3 -25
package/bin/incanto-verify.mjs +15 -2
package/dist/2d.d.ts +44 -7
package/dist/2d.js +6 -4
package/dist/3d.d.ts +112 -16
package/dist/3d.js +8 -6
package/dist/{audio-player-_UAcHxnC.d.ts → audio-player-DOrq7sP-.d.ts} +62 -4
package/dist/{behavior-BXNLfIJk.d.ts → behavior-DoFPYrgo.d.ts} +117 -2
package/dist/boot-failure-CKYrEcGF.js +47 -0
package/dist/{create-game-DYJCIzO0.js → create-game-DbWtVTxD.js} +91 -29
package/dist/{create-game-Dd7H4bJV.js → create-game-IZIydDwI.js} +16 -10
package/dist/debug.d.ts +1 -1
package/dist/debug.js +3 -2
package/dist/{duplicate-CqSAtdrh.js → duplicate-IWIqk0HJ.js} +1 -1
package/dist/{editor-switch-DAvWQeld.d.ts → editor-switch-CnIOiyNJ.d.ts} +1 -1
package/dist/editor.js +18 -7
package/dist/env.d.ts +1 -1
package/dist/{environment-presets-BlPsEmq6.js → environment-presets-CybQXNqS.js} +100 -11
package/dist/{gameplay-D1RADWu3.js → gameplay-DM1eu_cV.js} +46 -5
package/dist/gameplay.d.ts +75 -6
package/dist/gameplay.js +2 -2
package/dist/index.d.ts +52 -8
package/dist/index.js +9 -7
package/dist/{loader-lQDCwNag.js → loader-BC4PNtJX.js} +173 -1
package/dist/{loader-Cga7FVP4.d.ts → loader-CcB533FR.d.ts} +2 -2
package/dist/net.d.ts +2 -2
package/dist/net.js +1 -1
package/dist/{physics-2d-Cji5A6sX.js → physics-2d-B7Y6dPZO.js} +29 -2
package/dist/{physics-3d-BkHjwJgI.js → physics-3d-bG3n70Ky.js} +30 -3
package/dist/react.d.ts +2 -2
package/dist/react.js +1 -1
package/dist/{register-BmuqYTiY.js → register-3ta-2Xig.js} +148 -22
package/dist/{register-D0CxCveZ.js → register-ibCjm-wH.js} +3 -3
package/dist/{replay-IsZbNu6d.js → replay-CYvhVHHN.js} +28 -4
package/dist/{replay-BHoB6fCU.d.ts → replay-Dvn8aeBd.d.ts} +38 -4
package/dist/{schema-CFeioQRE.d.ts → schema-B6ugCV1Q.d.ts} +11 -0
package/dist/{split-screen-D_i7GRcY.js → split-screen-CYwDkbLF.js} +2 -2
package/dist/{split-screen-eJUFjhi1.d.ts → split-screen-DhrSzZIB.d.ts} +3 -3
package/dist/{src-BTLbXFPZ.js → src-D7RIqXYF.js} +1 -1
package/dist/{teardown-byR9USax.js → teardown-D2NEmxPB.js} +2 -2
package/dist/{test-DgrD0jHD.js → test-8hoHeRmo.js} +140 -32
package/dist/test.d.ts +9 -7
package/dist/test.js +3 -3
package/dist/{touch-DESwnpOc.js → touch-DEAmqGdf.js} +30 -186
package/dist/vite.d.ts +0 -7
package/dist/vite.js +13 -3
package/dist/webgl-unavailable-N9nQqesw.js +228 -0
package/editor/assets/{agent8-9N-Pd_YS.js → agent8-BrrHOjMJ.js} +1 -1
package/editor/assets/debug-BBhKuBNV.js +3 -0
package/editor/assets/{index-CeDhIPTC.js → index-eVd0BToA.js} +92 -92
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +5 -1
package/skills/incanto-3d-character.md +1 -0
package/skills/incanto-audio.md +49 -0
package/skills/incanto-building-2d-games.md +37 -0
package/skills/incanto-building-3d-games.md +56 -0
package/skills/incanto-editor.md +5 -1
package/skills/incanto-environment.md +2 -2
package/skills/incanto-gameplay-behaviors.md +29 -2
package/skills/incanto-hud.md +14 -1
package/skills/incanto-multiplayer.md +14 -0
package/skills/incanto-node-reference.md +2 -1
package/skills/incanto-performance.md +35 -0
package/skills/incanto-physics-and-input.md +23 -0
package/skills/incanto-playtesting.md +15 -1
package/skills/incanto-save-slots.md +21 -1
package/skills/incanto-scene-json-authoring.md +12 -1
package/skills/incanto-verifying-your-game.md +19 -0
package/skills/incanto-your-first-game.md +4 -4
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/beacon-isle-3d/src/game.scene.json +38 -19
package/templates-app/beacon-isle-3d/src/main.ts +8 -1
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/platformer-2d/src/game.scene.json +99 -53
package/templates-app/platformer-2d/src/main.ts +8 -1
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/game.scene.json +31 -17
package/templates-app/star-survivor/src/main.ts +8 -1
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/game.scene.json +14 -8
package/templates-app/tps-3d/src/main.ts +8 -1
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/src/grove.scene.json +20 -11
package/templates-app/village-quest-3d/src/main.ts +8 -1
package/templates-app/village-quest-3d/src/village.scene.json +10 -7
package/editor/assets/debug-CkbJICYp.js +0 -3

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-CeDhIPTC.js"></script>
+    <script type="module" crossorigin src="./assets/index-eVd0BToA.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.66.0",
+  "version": "0.68.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

@@ -2378,6 +2378,10 @@
               "type": "boolean",
               "default": true
             },
+            "platformCarry": {
+              "type": "boolean",
+              "default": true
+            },
             "turnSpeed": {
               "type": "number",
               "default": 100
@@ -7680,7 +7684,7 @@
             },
             "focusable": {
               "type": "boolean",
-              "default": false
+              "default": true
             },
             "draggable": {
               "type": "boolean",

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-audio.md CHANGED Viewed

@@ -396,6 +396,55 @@ 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.play(startedAt + chart[cursor].atSec);   // AudioPlayer.play(at)
+    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.play(at)`** and **`engine.sfx.play(params, gain, { when })`** —
+  PRESETS only. A `src` clip goes through an `<audio>` element, which has no
+  scheduling clock; `at` is ignored for one rather than approximated.
+- 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.

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

@@ -485,3 +485,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

@@ -41,8 +41,14 @@ const game = await createGame3D({
   scene: sceneJson,          // cloned internally — no cast, no structuredClone
   pointer: true,             // pointer-look + lock-on-click (FPS pattern); default off
   // behaviors: { ... },     // registered for you (hot-replace tolerant)
+  // settings: { namespace: 'my-game' },  // ← if anything else Incanto is
+  //   served from this domain. Volume, language and the quality tier persist
+  //   under `incanto:<namespace>:`, and the default is shared by everyone: a
+  //   neighbouring game's player can boot yours at quarter resolution, muted.
 });
 // game.engine / game.scene / game.renderer / game.physics
+// `game.scene` is the LIVE scene, not the one you booted with — it follows every
+// swap, including `flow.restart()`. `game.sourceJson` is the authored JSON.
 // game.dispose() — ONE call tears everything down (SPA unmount)
 ```
@@ -629,3 +635,53 @@ or empty, and nothing throws.
 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`.
+### `findFloatingProps` throws rather than reporting a clean scene it never read
+It answers "which props hover above the terrain", and it needs the scene to LOAD
+and a `Terrain3D` to measure against. It used to return `[]` for both failures —
+so a scene that would not load, a scene with no terrain and a genuinely clean
+scene all printed the same green.
+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-editor.md CHANGED Viewed

@@ -44,7 +44,11 @@ The `scenes` button opens the project as a tree, not a list of paths:
   panel — so `⏎` loads something without arrowing first.
 - Each row carries **when it was last written and how big it is**, which is usually
   how you recognise the file you were just in.
-- **create** makes a new scene at the path in the box — left empty it uses the
+- **create** makes a new scene at the path in the box — **matching the project**:
+a 3D game gets `dimension: "3d"` with a `Node3D` root, a 2D game gets 2D, read
+from the scenes already on disk. It used to hardcode 2D for everyone, and node
+types are immutable by design, so a 3D author's new scene could only be deleted
+and re-made by hand — left empty it uses the
   placeholder, which tracks the folder you are standing in, so a scene lands beside
   its siblings rather than at the project root. Parent dirs are created.
 - Loading another scene while you have unsaved EDITS asks first, and the answer

package/skills/incanto-environment.md CHANGED Viewed

@@ -799,7 +799,7 @@ hue reads grey.
 | `sunDirection` | `[0.5, 0.8, 0.3]` | TOWARD the sun, for the specular glint — match the scene's key light (non-zero, load-time check) |
 | `sunColor` | `"#fff5d6"` | glint/sheen tint |
 | `sunIntensity` | `1` | glint/sheen strength (≥ 0; 0 = off) |
-| `detailStrength` | `0.3` | animated detail-normal strength (≥ 0; 0 = vertex normals only) |
+| `detailStrength` | `0.26` | animated detail-normal strength (≥ 0; 0 = vertex normals only) |
 | `absorption` | `0.15` | Beer's-law constant per meter of water depth (≥ 0; lower = clearer/wider turquoise band; red absorbs ~3× faster than blue under the hood) |
 | `refraction` | `true` | screen-space refraction of the submerged scene |
 | `preset` | `"custom"` | **THE one-choice water type** (0.16.0): `ocean` \| `pool` \| `lake` \| `pond` bundles every wave/color/clarity/caustics knob into a hand-tuned sea state. A preset value applies ONLY where a prop still sits at its schema default — pick the type, then override any detail prop and your value wins. ocean = traveling swell + whitecaps + wide turquoise→deep absorption · pool = near-flat crystal water + strong above-water caustics · lake = calm high-reflectivity mirror, green-teal murk · pond = still, mossy, opaque quickly. `custom` (default) changes nothing |
@@ -1074,7 +1074,7 @@ underneath decides everything else.
 | `opacity` | `0.85` | upper bound on the body's opacity |
 | `foam` | `1` | whitewater dial — 0 = a glassy canal, 2 = raging |
 | `ripples` | `1` | surface-detail dial (ripple relief + glitter) |
-| `terrain` | `''` | drape target path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
+| `terrain` | `""` | drape target path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 | `carve` | `true` | cut the bed. The river trenches its own channel into the terrain it drapes on — see below |
 | `flowForce` | `1` | how hard the current sweeps bodies downstream (0 = visual only) |
 | `spray` | `1` | mist at the foot of every drop the course turns out to contain — the node finds them and hangs a Particles3D plume on each (0 = off) |

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

@@ -111,7 +111,7 @@ what breaks one that forgets the other half:
 ```json
 { "signal": "died",     "from": "Player", "to": "Score",  "handler": "loseLife" },
-{ "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "revive" }
+{ "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "reviveFull" }
 ```
 Without the second wire the player is a walking corpse after the first death —
@@ -1211,7 +1211,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 +1221,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-hud.md CHANGED Viewed

@@ -183,7 +183,20 @@ support" was not something a JSON scene could express at all.
 ```
 Arrow keys / d-pad move the focus between the **focusable** widgets under that
-layer, `Enter` / `A` activates, and the focused one wears a ring.
+layer — and only the ones the player can actually SEE: a hidden widget hides
+everything under it, and a hidden layer has no ring at all. (Until 0.67 the walk
+recursed into closed panels, so Enter on a title screen could press a button in
+the shop and spend the gold.) `hud.focusables()` returns the ring, so a game can
+ask what it is stuck with.
+A **`UiDialogue` takes focus while it is up**: Enter/A picks the highlighted
+choice, left/right move between them, and a line with no choices advances. Its
+choices are DOM buttons inside the widget rather than nodes, so this is the
+widget's own key handling — before 0.67 a choice could only be answered with a
+mouse, and `charsPerSecond: 0` rendered no buttons at all, which was an
+unanswerable soft-lock.
+ `Enter` / `A` activates, and the focused one wears a ring.
 `UiButton`/`UiSlider`/`UiToggle`/`UiSelect` are focusable by default;
 `UiText`/`UiBar`/`UiImage`/`UiPanel` are not, so arrowing never lands on a label.

package/skills/incanto-multiplayer.md CHANGED Viewed

@@ -378,3 +378,17 @@ Kernel constraints (agent8 platform facts — don't fight them):
   client transport swap (for a normal single-client game, just omit `{transport}`;
   a split-screen demo like arena-preview also drops its local-only scaffolding) PLUS
   deploying `server/` (the "Going live on agent8" section above) — not literally one line.
+## The `agrees` rung runs YOUR server
+`incanto-multiplay` loads `server/src/server.ts` (or `--server FILE`) and runs
+the match against it. It did not until 0.67: every match ran on a bare loopback
+kernel with no remote functions, so `roomState` came back `{}` instead of
+`{"matchMs": 5983.3}`, a `manager.call('claimRelic')` threw
+`Loopback kernel has no remote function 'claimRelic'`, and the report still said
+`ok=true errors=0 problems=[]`. Moving `server/src/server.ts` out of the tree
+changed nothing — a ✓ that could not have been a ✗.
+If your server cannot be loaded the run REFUSES rather than quietly measuring a
+game without its own rules.

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 |
@@ -1039,7 +1040,7 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `presse
 |---|---|---|
 | `anchor` | `"bottom"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
-| `focusable` | `false` | boolean |
+| `focusable` | `true` | boolean |
 | `draggable` | `false` | boolean |
 | `dropTarget` | `false` | boolean |
 | `charsPerSecond` | `40` | number |

package/skills/incanto-performance.md CHANGED Viewed

@@ -289,3 +289,38 @@ Set `maxFps` to 30 and confirm `fps` settles near 30 — if it settles near 20,
 is slower than the cap and the cap is not what is limiting it.
 See `incanto-verifying-your-game.md` for the full loop.
+## Identical meshes share their GPU objects
+`MeshInstance3D` used to make a private geometry AND material per node, even
+when byte-identical. Measured at 3,200 units — all runs at the same 3,209 draw
+calls, 1,741,932 triangles and an identical screenshot:
+```
+per-node geometry + material   31.0 ms wall  (renderMs 27.3)
+share one geometry             27.0 ms
++ share two materials          15.4 ms       <- 2x the headroom
+```
+13.1 ms of that cliff was GPU state churn from per-node objects. Nodes now share
+one geometry per (mesh, size) and one material per distinct `material` dict, and
+a node whose look changes gets its own again. **Nothing to do — it is the
+default.** The consequence to know: mutate node PROPS, never the three.js
+material you fished out of a node, because it may not be only yours.
+This does not replace `InstancedMesh3D`. A field of identical props is still one
+node and one draw call there (12,800 units, 11 draw calls, 2.30 ms); sharing
+helps the one-node-per-thing path, which is what a hand-authored level is.
+## The quality tier only ever takes away
+`high` no longer mentions `bloom` or `post` at all, because mentioning them
+CREATED them: on a scene that declared neither, `high` and `medium` both
+rendered a five-pass frame at 3.3 ms where `low` rendered one pass at 1.24 ms —
+62% of the frame on a chain the game never asked for, and
+`engine.scene.environment.bloom` read back `{strength: 0.8, threshold: 1}`.
+A tier is also REVERSIBLE now: it is applied against the scene FILE rather than
+against whatever the last tier left behind, so `low` → `high` restores exactly
+what you authored instead of leaving it stripped.

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-playtesting.md CHANGED Viewed

@@ -51,10 +51,24 @@ two.
 | `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` | the clock ran out AND the player never got more than 3 m (96 px) from its spawn — it is wedged, or nothing moves it |
+| `swapped` | the game changed scene. The bot binds player, destinations and the win/lose oracle ONCE, from the tree it started in, so nothing after a `goToScene` is measured — the run stops there and says so. It is not a defect, and the destinations it never got to are reported as unmeasured rather than missed. Judge a multi-scene game with a scripted `runScript`. |
 | `unfinished` | the clock ran out on a player that was getting around. Not a defect: a win that needs a SEQUENCE (talk to the NPC, then fetch, then return) is out of reach of a random walker, forever |
 | `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` |
+| `danger` | how many times the player's `Health` emitted `damaged` — and when that is ZERO, WHICH zero it is: a scene with no hazard wired at all is a walkabout and worth shouting about; a scene full of them that never landed one is a report about the BOT, which a real player would outrun less easily. Hazards are counted from the scene FILE, because a `Spawner` detaches its prefab at ready and a wave game's hazards are not in the tree yet. |
+**The bot can use the MOUSE.** If your scene has `Clickable` nodes, it presses
+and releases over them at random — through the real `Clickable`, the real
+`mouseJustPressed` edge and your real connection, with a picker that answers
+from the tree (the recipe under "Testing a mouse-driven game headlessly"). It
+drove actions and nothing else before, so a tactics game, a tower defense and a
+duel all reported the identical `? plays — 8 runs played without reaching a
+win`. A scene with nothing clickable is untouched: it does not gain an
+`engine.picker` it never had.
+A random clicker still cannot finish a game that needs a SEQUENCE — select a
+trooper, then a tile, then end the turn — and that is reported as unmeasured,
+not failed.
 **Nothing here is a guess about your design.** The scene already declares what
 winning is; this only listens.

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

@@ -89,7 +89,27 @@ game that shipped six weeks ago. Check what you read.
 Built-ins that already save: `Health` (current, dead), `ScoreKeeper` (score,
 lives, won/lost), `Collector` (total).
-## Every node you save needs a uid
+## Every node you save — and every node that VANISHES — needs a uid
+A collectible does not save state; it DISAPPEARS, and disappearing is the thing
+the save has to record. `#freed` is keyed by uid, so a pickup without one is
+silently omitted: the score that counted it restores, and the pickup restores
+too. Measured on a starter with 1 uid across 141 nodes:
+```
+coins after collecting : 9
+save["#freed"]         : undefined
+restore report         : { restored: 1, expected: 1, freed: 0 }
+coins AFTER load       : 12          <- three coins resurrected
+auditScene warnings    : []          <- and every checker was green
+```
+`captureState` now reports this as an ERROR naming the nodes, because the save
+it just wrote is already wrong. It does not guess a replacement: a uid survives
+a rename and a reparent, and a saved PATH would point at whatever node moved
+into that slot after your next edit.
 The uid is the join key, because it is the one identifier that survives a rename
 or a reparent. The editor assigns one to every node it touches. A hand-written

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

@@ -858,3 +858,22 @@ const inputToWorld = Math.atan2(at()[1] - before[1], at()[0] - before[0]);
 `examples/village-quest-3d/verify.ts` does exactly this and fails with
 "the player cannot reach it on foot" when it cannot.
+## When node refuses your TypeScript
+The bins' shebang is node, and node's type stripping **erases** types — it does
+not transform. Three ordinary things it refuses, all of which vite and bun
+compile without comment:
+| what you wrote | what node says |
+|---|---|
+| `import scene from './game.scene.json'` | needs an import attribute of "type: json" |
+| `import { quest } from './quest'` | Cannot find module …/quest |
+| `constructor(private root: Node3D)` | TypeScript parameter property is not supported in strip-only mode |
+**You do not have to change any of them.** Every bin that loads a `--behaviors`
+file re-runs itself under bun when node refuses it, so the command just works.
+If bun is not on PATH the message says which of the three it hit.
+Prefix with `bunx --bun` to skip the round trip.

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

@@ -83,13 +83,13 @@ and it is entirely JSON.
 ```jsonc
 "connections": [
   { "signal": "died",     "from": "Player", "to": "Score",  "handler": "loseLife" },
-  { "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "revive" },
+  { "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "reviveFull" },
   { "signal": "won",      "from": "Score",  "to": "Flow",   "handler": "win" },
   { "signal": "lost",     "from": "Score",  "to": "Flow",   "handler": "gameOver" }
 ]
 ```
-**`lifeLost → revive` is not optional.** A `Health` that has died stays dead:
+**`lifeLost → reviveFull` is not optional.** A `Health` that has died stays dead:
 `damage`, `heal` and regen all stop, so without that wire the player becomes a
 walking corpse after the first death — full HP bar, immune to everything,
 `died` never firing again, lives frozen, and the game quietly unlosable. It
@@ -158,7 +158,7 @@ floats over small ledges already.
 The tell for both is one line of `incanto-playtest` output:
 ```
-danger: the player took damage 0 times in 4 runs — nothing here can hurt you
+danger: nothing in this scene can hurt the player — no DamageOnContact, no hazard group
 ```
 Read it. It is the truth.
@@ -219,7 +219,7 @@ Things that cost real time, in the order you will meet them.
 | when | the trap |
 | --- | --- |
-| a game with LIVES | `died` stops a `Health` for good — wire `lifeLost → revive` or you can spend only one. |
+| a game with LIVES | `died` stops a `Health` for good — wire `lifeLost → reviveFull` or you can spend only one. **Not `revive`**: `lifeLost` carries the life COUNT and `revive(hp?)` reads it as health, so you come back at 2 HP, then 1, then 0. |
 | wiring a score | `died` carries nothing; `addScore(n)` wants one → `NaN`. Wire `dealtDamage` from the killer. |
 | enemies feel harmless | `repeatEvery` on the contact hitbox, or one hit is all you get. |
 | enemies never arrive | a chaser cannot climb — `stepHeight`, and it loses to a large downward velocity you apply yourself. |

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