npm - incanto - Versions diffs - 0.30.0 → 0.32.0 - Mend

incanto 0.30.0 → 0.32.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 (49) hide show

package/bin/incanto-play.mjs +7 -2
package/dist/2d.d.ts +12 -5
package/dist/2d.js +3 -3
package/dist/3d.d.ts +67 -6
package/dist/3d.js +4 -4
package/dist/{audit-C6rMyict.js → audit-C4kmDK0o.js} +16 -0
package/dist/{behavior-BAc0erXF.d.ts → behavior-D_jMpFh8.d.ts} +117 -55
package/dist/{create-game-5z_QVtLx.js → create-game-bKHgHcsZ.js} +19 -10
package/dist/{create-game-DuBTv2zI.js → create-game-gXI7PYl0.js} +61 -46
package/dist/debug.d.ts +1 -1
package/dist/debug.js +7 -2
package/dist/{duplicate-BgtFrFo4.js → duplicate-KRPtUtzl.js} +1 -1
package/dist/{editor-switch-B0wB_DSr.d.ts → editor-switch-BJb-CWfA.d.ts} +12 -1
package/dist/{register-DJ0SByQg.js → environment-presets--DigHNg4.js} +42 -11
package/dist/{gameplay-Cfr6aFZ1.js → gameplay-BftxM_It.js} +2 -2
package/dist/gameplay.d.ts +1 -1
package/dist/gameplay.js +1 -1
package/dist/index.d.ts +13 -3
package/dist/index.js +7 -7
package/dist/{loader-B242FF6N.d.ts → loader-BYBrqTxP.d.ts} +1 -1
package/dist/{loader-BZqOKfI2.js → loader-BlaRQGaA.js} +482 -6
package/dist/net.d.ts +1 -1
package/dist/net.js +3 -3
package/dist/{pathfinding-BwD974Ss.d.ts → pathfinding-BwhqPD3i.d.ts} +1 -1
package/dist/{physics-2d-3kOQCtgd.js → physics-2d-D9wquBvK.js} +4 -3
package/dist/{physics-3d-CeRH-Ff_.js → physics-3d-CnPygVGo.js} +5 -4
package/dist/react.d.ts +1 -1
package/dist/react.js +1 -1
package/dist/{register-MelqEdza.js → register-CUY284Is.js} +3 -3
package/dist/{register-BTg0EM7s.js → register-Dzkd6-os.js} +56 -380
package/dist/{register-DWcWq4QG.js → register-tkR_8tWg.js} +4 -4
package/dist/{registry-BVJ2HbCn.js → registry-CJdGpT2V.js} +6 -2
package/dist/test-WwRIlXsK.js +642 -0
package/dist/test.d.ts +55 -8
package/dist/test.js +3 -364
package/dist/{touch-031PxtCR.js → touch-BoNg_MnF.js} +2 -1
package/dist/vite.js +1 -1
package/editor/assets/{agent8-CAp0i5qn.js → agent8-C5k1nTCH.js} +1 -1
package/editor/assets/{debug-BoEYfbqK.js → debug-BT_0mjk-.js} +3 -2
package/editor/assets/{index-BO6WU8by.js → index-gfyrByWw.js} +90 -90
package/editor/index.html +1 -1
package/package.json +1 -1
package/skills/README.md +14 -2
package/skills/incanto-building-2d-games.md +16 -0
package/skills/incanto-building-3d-games.md +16 -0
package/skills/incanto-verifying-your-game.md +118 -0
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/village-quest-3d/package.json +1 -1

package/editor/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-BO6WU8by.js"></script>
+    <script type="module" crossorigin src="./assets/index-gfyrByWw.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.30.0",
+  "version": "0.32.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/skills/README.md CHANGED Viewed

@@ -2,8 +2,20 @@
 Full agent skills for building games with this **installed version** of Incanto.
 An AI agent should start with `incanto-scene-json-authoring.md`, then the domain skill
-for the task at hand. `incanto-node-reference.md` (+ `../schemas/scene.schema.json`)
-is generated from the engine source and lists every node type, prop, and default.
+for the task at hand, and **finish every task with `incanto-verifying-your-game.md`**
+— you cannot see the game, and that skill is how you find out whether it works.
+`incanto-node-reference.md` (+ `../schemas/scene.schema.json`) is generated from the
+engine source and lists every node type, prop, and default.
+**Never hand a game back without reading these four.** Each answers a failure that
+otherwise looks like nothing at all — see `incanto-verifying-your-game.md`:
+| read | it is not clean when |
+| --- | --- |
+| `bunx incanto-check` | the scene will not load, or renders black (no light) |
+| `stats().errors` | something threw and was skipped to keep the game alive |
+| `assetErrors()` | a model or texture 404'd — the thing is simply not there |
+| `framing` | the camera points the wrong way, or nothing is lit |
 These files are the source of truth; the thin platform-delivery entries live in the
 repo's root `skills/` folder and merely point here.

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

@@ -277,3 +277,19 @@ engine seed — runScript verifies particle gameplay reproducibly.
 Mark unchanging subtrees (tile decor, backgrounds) `static: true` — the
 renderer syncs them once and skips them every frame. Flip to `false` to
 resume live syncing.
+## Before you hand it back
+You cannot see this game. `incanto-verifying-your-game.md` is how you find out
+whether it works — run it after every edit, not once at the end:
+```bash
+bunx incanto-check                       # will it load? is anything lit?
+printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+```
+`framing` tells you what the camera can actually SEE (on screen / off screen /
+behind it), what lights the scene, and which colliders intersect. Then read
+`stats().errors` (something threw and got skipped) and `assetErrors()` (a model
+404'd). All four are silent failures otherwise — the screen just looks wrong,
+or empty, and nothing throws.

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

@@ -562,3 +562,19 @@ if (cells) follow.setPath(cells.map(([cx, cy]) => nav.toWorld(cx, cy)));
   dense-forest frame). Use when shadow CASTERS don't move — pair moving
   characters with sprite/blob shadows. After a one-off world edit call
   `renderer.refreshShadows()`.
+## Before you hand it back
+You cannot see this game. `incanto-verifying-your-game.md` is how you find out
+whether it works — run it after every edit, not once at the end:
+```bash
+bunx incanto-check                       # will it load? is anything lit?
+printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+```
+`framing` tells you what the camera can actually SEE (on screen / off screen /
+behind it), what lights the scene, and which colliders intersect. Then read
+`stats().errors` (something threw and got skipped) and `assetErrors()` (a model
+404'd). All four are silent failures otherwise — the screen just looks wrong,
+or empty, and nothing throws.

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

@@ -12,6 +12,20 @@ You usually cannot SEE the game (no browser in most agent environments). The
 scene state itself is your screenshot. The loop is: **edit → check → scripted
 run → read the capture → fix**. Never hand a game back without steps 2–3.
+**The four things to read before you call it done.** Three of them are new, and
+each answers a failure that used to look like nothing at all:
+| read this | when it is not clean | see |
+| --- | --- | --- |
+| `incanto-check` | the scene will not load, or renders black | §1, §5b |
+| `stats().errors` | something threw and was skipped to keep the game alive | §6b |
+| `assetErrors()` | a model/texture 404'd — the thing is simply not there | §6c |
+| `framing` | the camera is pointed the wrong way, or nothing is lit | §6a |
+A run that finishes is not a run that worked. `runScript()` fails the run when
+`stats().errors` is non-zero, and prints the engine's warnings under the
+failures — but `framing` and `assetErrors()` you have to ASK for.
 ## 1. After EVERY scene edit: `incanto-check`
 ```bash
@@ -144,6 +158,25 @@ const res = validateScene(sceneJson);          // { ok } | { ok: false, error }
 if (!res.ok) console.error(res.error.code, res.error.details); // details.path/prop/signal/validOptions
 ```
+## 5b. What a green `incanto-check` now covers
+`validateScene` / `incanto-check` hard-fail on all of these, so they never reach
+a browser:
+- **Every prop's type AND its enum values** — `"mesh": "crystal"` names what is
+  valid instead of printing `ok` and throwing at boot. All 31 enum props.
+- **`input{}`** — a declaration's shape (`"keys": "Space"` instead of
+  `["Space"]`, an unknown `type`, a wrong `touch`). This used to be checked only
+  by `Engine.setScene`, i.e. never headlessly.
+- **`assets{}`** — every entry an object with a non-empty `url`.
+- **`environment.preset`** — resolved only inside Renderer3D before, so a typo
+  survived every check and died at boot.
+And `auditScene` (the warnings `incanto-check` prints) gained the loudest
+"why is my screen black" of all: **nothing lights this 3D scene** — no light
+node, no `environment` sky/hdri/preset, no ambient intensity. Ambient defaults to
+0, so such a scene renders nothing, throws nothing and logs nothing.
 ## 6. Catch broken edits at save time (vite)
 ```ts
@@ -161,6 +194,91 @@ ANY scene in the project — not just the one the game booted with. `incantoScen
 root })` bounds that to a directory other than vite's; nothing outside it is readable
 or writable, and none of it exists in a build (`configureServer`).
+## 6a. See what the camera sees — without a GPU
+`describe()` tells you a gem is at `[4, 1, -2]`. It cannot tell you whether you
+can SEE it, which is the question you actually had. `framing()` answers that,
+from geometry alone — no renderer, no canvas, no browser:
+```
+> framing
+camera /World/Player/Cam at [0, 2, 8] looking [0, -0.2, -0.97] fov 60
+lit by: /World/Sun (DirectionalLight3D), environment.sky
+3 on screen, 1 off screen, 2 behind the camera
+  onScreen  /World/Island (MeshInstance3D) [0, 0, 0] screen [0.02, -0.11] 8.2m
+  behind    /World/Chest (ModelInstance3D) [0, 0, 40] 32m
+  offscreen /World/Gem (MeshInstance3D) [80, 0, 0] screen [4.4, 0] 80.1m
+  overlap   /World/Platform ∩ /World/Gem
+```
+Read it for the three visual failures that look identical from a node list:
+- **`behind`** — the thing is fine, the camera has its back to it. Indistinguishable
+  from "my model did not load" until you can see this line.
+- **`lit by: NOTHING`** — the scene renders black. No error, no log, nothing wrong
+  with any node.
+- **`overlap`** — two declared colliders intersect: the gem is inside the platform.
+Also `incanto-play`'s `framing` command, and `describeFraming(scene)` /
+`framingText(report)` from `incanto/test` for the structured form. A node counts
+as on screen when its `size` box (or collider) is, not only its origin — so a
+200 m island whose origin sits off to the left is correctly `onScreen`.
+**For actual pixels**, turn on `preserveDrawingBuffer` — WebGL clears the buffer
+the instant a frame composites, so `canvas.toDataURL()` and every screenshot
+built on it come back BLANK without it:
+```ts
+createGame3D({ ..., preserveDrawingBuffer: true });
+// or in the scene: "environment": { "rendering": { "preserveDrawingBuffer": true } }
+```
+Then drive the page with whatever browser tool you have. It costs a buffer copy
+per frame, which is why it is off by default.
+## 6b. A thrown error no longer stops the game
+One exception used to end everything: `requestAnimationFrame` reschedules AFTER
+your callback returns, so a throw in any behavior's `update` killed the loop
+permanently — no message, `stats().running` still `true`, a game that just
+stopped. It no longer can.
+- The thing that threw is **reported once** (which node, which script, which
+  phase) to `engine.log` AND the console, then **skipped**. Its children and
+  every other node keep running.
+- **Your SCRIPT and the engine's NODE are skipped separately.** A typo in a
+  behavior attached to a `CharacterController3D` stops that behavior — the
+  character still walks and the camera still turns. Only a throw from the node's
+  own update quarantines the node.
+- `engine.stats().errors` counts everything swallowed to stay alive. **A game
+  that looks fine with `errors: 3` is a broken game** — read `engine.log`.
+- `engine.erroredNodes()` lists them; `engine.resumeErroredNodes()` puts them
+  back after you fix the code.
+- `runScript()` FAILS the run when the count is non-zero. "It finished" must not
+  mean "nothing broke" — that is right for a player and wrong for a harness.
+So the check after every edit is still `ok`, plus: **read `stats().errors`**.
+## 6c. Engine diagnostics you can actually read
+Every internal warning the engine produces — a GLB that 404'd, a body with no
+collider, a retarget that dropped bones, an exception swallowed inside a physics
+trigger handler — used to go to `console.*` and nowhere else, which is the one
+channel a headless tool cannot read. The symptom was always the same: the model
+simply never appears, and `logs` comes back empty.
+They now go to **`engine.log` as well as the console**, so:
+- `runScript().logs` contains them, and `describe()` prints them under the
+  failures (`! warn: …`).
+- The debug overlay's **Logs** panel shows them live.
+- `game.assetErrors()` lists every asset that failed **with its reason and ref**
+  — the direct answer to "why is my model not there". The store itself is
+  reachable as `renderer.assets` in both dimensions.
+So the after-every-edit check is: `ok`, then **`stats().errors`**, then
+**`assetErrors()`**.
 ## 7. See inside the RUNNING game (debug overlay)
 ```ts

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

package/templates-app/tps-3d/package.json CHANGED Viewed

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.30.0",
+    "incanto": "^0.32.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/package.json CHANGED Viewed

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.30.0",
+    "incanto": "^0.32.0",
     "three": "^0.184.0"
   },
   "devDependencies": {