incanto 0.71.0 → 0.73.0

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

@@ -103,7 +103,11 @@ Rules the engine enforces with **hard errors** (it never warns silently):
    On export, default-equal values are omitted automatically.
 3. Prop keys and value kinds are validated against the type's schema:
    unknown key → `UNKNOWN_PROP` (message lists valid keys); wrong JSON kind
-   (e.g. string where the default is boolean) → `PROP_TYPE_MISMATCH`.
+   (e.g. string where the default is boolean) → `PROP_TYPE_MISMATCH`. A prop
+   whose default is `null` means AUTO — the engine decides — and validates the
+   other kinds it declares (`drape`/`collide`/`islandEdge`/`Chase.ground` take
+   a boolean, `snapToGround` a boolean or a lift in metres, `reflectivity` a
+   number); the editor offers the boolean ones as auto / on / off.
    A few props accept TWO kinds — `Flowers3D.density` takes a preset name or
    plants per m², `Water3D.underwater` takes `true`/`false` or a settings
    object — and `incanto-node-reference.md` names both in its Kind column
@@ -398,6 +402,37 @@ that do exist at the failing spot).
 - Current limitation: exporting expands instances into full trees (the `instance` reference is
   not preserved on export yet).
 - Cycles (`a` instances `b` instances `a`) and missing resolvers → `UNRESOLVED_INSTANCE`.
+- A placement's props go in `overrides`. `props` on an `instance:` node is a
+  hard `BAD_FORMAT` error — it used to be accepted and read by nothing, so a
+  position written there was silently the sub-scene's own.
+
+### Giving the loader the sub-scenes (the half that is not JSON)
+
+`loadScene` never reads files: it asks `resolveScene(path)` for the JSON behind
+an `instance:` string, synchronously, and without one a scene with a prefab in
+it does not load. Every CLI (`incanto-check`, `-playtest`, `-verify`, `-feel`,
+`-play`) passes one already, resolved against the SCENE's own folder — your
+game and your harness are the two places you write it yourself:
+
+```ts
+// main.ts — vite. Every *.scene.json beside this file, keyed by the path an
+// `instance:` names.
+const prefabs = import.meta.glob('./*.scene.json', { eager: true, import: 'default' });
+const resolveScene = (path: string): unknown => prefabs[`./${path}`] ?? null;
+await createGame2D({ canvas, scene: sceneJson, resolveScene });
+```
+
+```ts
+// verify.ts — bun, no bundler: import the prefab and hand it over by path.
+import crateJson from './src/crate.scene.json';
+const resolveScene = (path: string) => (path === 'crate.scene.json' ? crateJson : null);
+await runScript(sceneJson, { durationMs: 4000, resolveScene, steps: [...] });
+```
+
+`examples/tiles-2d` is the worked example in 2D: two crates that ARE
+`crate.scene.json`, one of them adding a rope child of its own. `examples/tps-3d`
+is the 3D one: the arena's cover blocks and pillars are `cover.scene.json` and
+`pillar.scene.json`, placed with a `position` override each.
 
 ## Error codes you will see (all hard failures at load)
 
@@ -417,6 +452,7 @@ that do exist at the failing spot).
 | `UNKNOWN_SIGNAL` | connection (or emit/on) names a signal the from node never declares | use a declared signal, or declare it (`static signals` / `declareSignal`) |
 | `UNKNOWN_BEHAVIOR` | `script.name` not registered | `registerBehavior(name, Class)` before `loadScene` |
 | `UNRESOLVED_INSTANCE` | no resolver, unknown path, or instance cycle | provide/fix `resolveScene`, break the cycle |
+| `WRONG_DIMENSION` | a `*3D` node in a 2D scene (or the reverse), or `createGame2D` given a 3D scene | use the matching node type / the matching `createGame*` |
 | `DUPLICATE_NODE_TYPE` | two classes registered under one type name | rename one type, or `{ replace: true }` for hot reload |
 | `DUPLICATE_BEHAVIOR` | two classes registered under one behavior name | rename one, or `{ replace: true }` for hot reload |
 | `TREE_VIOLATION` | invalid name, re-parenting without detach, cycles, double root | follow the rule in the message |

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

@@ -41,6 +41,10 @@ $ bunx incanto verify                       # finds your scene AND your behaviou
 passes what was measured — plays, draws not measured.
 next: nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`
 ```
+`--runs N` gives the `plays` rung more seeds (default 8). Eight see a one-in-eight event
+64% of the time; `bun run sweep` asks the six shipped starters for sixteen, and a starter that
+falls out of the world once in twelve runs is how the arena in tps-3d got its `Respawn`.
+
 
 ### `agrees` — do two clients hold the same values?
 
@@ -72,7 +76,10 @@ encodes so you do not have to remember them:
   warned about is printed under it with a `!` — `loads` runs `incanto-check`,
   and the ladder used to read only whether it passed and drop the warnings, so a
   scene the check describes as "It will render black" came back as
-  `✓ loads — the scene is legal and its assets resolve`;
+  `✓ loads — the scene is legal and its assets resolve` (LOCAL art is looked for on
+  disk; REMOTE urls are asked with a HEAD request — a 404 drops the claim to
+  `the scene is legal`, and a host that cannot be reached is a `note:`, never a
+  failure);
 - an **unmeasured** rung (`?`) is not a failure. "No dev server" means the
   question was never asked; treating that as a broken game sends you editing a
   scene that is fine;
@@ -218,7 +225,7 @@ const result = await runScript(sceneJson, {
   durationMs: 3000,
   seed: 42,                            // same seed → identical run
   steps: [
-    { atMs: 0,    vector: ['move', 1, 0] },          // hold right
+    { atMs: 0,    vector: ['move', 1, 0] },          // hold right (y is DOWN: forward is [0, -1])
     { atMs: 1000, press: 'jump' },
     { atMs: 1100, release: 'jump' },
     { atMs: 1500, label: 'jump apex reached',
@@ -252,6 +259,16 @@ captures; `result.logs` holds everything behaviors logged via `this.log`.
 Steps that never execute (atMs beyond the run) are reported as failures —
 an assert cannot "pass" by not running.
 
+**A game that has ended does not advance.** `GameFlow` stops the clock
+(`timeScale 0`) on a win or a loss, and a pause does the same; after that every
+`ctx.engine.step()` is a no-op and every value you read is the last one before
+it stopped. A harness that lost its player three times inside one `do:` then
+measured `0.00` for everything after it. The report now names each `do:`/`assert:`
+step that ran with the clock stopped (`! at 4000ms [measure apex]: the clock
+was stopped …`, also `result.stalled`) — read that line before reading the
+zeros. Measure before the game ends, or `restartScene` / read `Flow.state` in
+the step.
+
 Note: `validateScene`/`runScript` register node types and your `behaviors`
 into the process-global registries (hot-replacing same names). In a test
 suite, isolate with `clearRegistry()`/`clearBehaviors()` between files if

package/templates-app/beacon-isle-3d/PROJECT/Status.md

@@ -36,3 +36,11 @@
 
 - Boss attack telegraphs (charge-up glow, ground slam particles).
 - A hurt/attack clip for shades once one lands in the catalog.
+
+## This round's surfaces, on the island (2026-09-04)
+
+`Pad` (StaticBody3D, `restitution 1`, `snapToGround: 0.1`) with a dead `Ball` dropped on it,
+and `Walker` (CharacterBody3D + `Chase` on a child, `slopeLimitDeg 50`, `stepHeight 0.5`) on
+the west slope, `loseRange 25` so it never joins the quest. `verify.ts` measures the rebound
+(2.4 m of 3), the chase up the slope (8.5 m of 10, +1.75 m) and that the walker stays on the
+terrain (0.97 m over `heightAt`).

package/templates-app/beacon-isle-3d/PROJECT/Structure.md

@@ -22,3 +22,6 @@ verify.ts                audit + quest E2E + hunt + death/respawn + replay
   keeps lit wards; `IsleDirector.onReady` re-applies their glow.
 - The whole Terrain subtree is static EXCEPT Sea and Clouds (auditScene
   catches the freeze-the-water mistake if you regress this).
+
+- `Pad`, `Ball`, `Walker` — the harness's fixtures for a trampoline and a ground chaser on the
+  heightfield.

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