npm - incanto - Versions diffs - 0.29.0 → 0.31.0 - Mend

incanto 0.29.0 → 0.31.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 (55) hide show

package/bin/incanto-editor.mjs +101 -28
package/dist/2d.d.ts +28 -6
package/dist/2d.js +3 -3
package/dist/3d.d.ts +81 -7
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-CNKXGfpr.js → create-game-DqOjMBUS.js} +61 -48
package/dist/{create-game-CbuLWorm.js → create-game-z5XaB1p5.js} +27 -15
package/dist/debug-draw-BM3DsvtT.js +18 -0
package/dist/debug.d.ts +1 -1
package/dist/debug.js +8 -3
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/editor.js +1346 -1231
package/dist/{register-C44aSduO.js → environment-presets--DigHNg4.js} +42 -11
package/dist/{gameplay-L05WgWd1.js → gameplay-BftxM_It.js} +14 -5
package/dist/gameplay.d.ts +1 -1
package/dist/gameplay.js +1 -1
package/dist/index.d.ts +12 -3
package/dist/index.js +6 -6
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-CCVTrKOd.js → physics-2d-D9wquBvK.js} +30 -4
package/dist/{physics-3d-BZZLtwJu.js → physics-3d-CnPygVGo.js} +41 -5
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/{editor-switch-CAKlJMIY.js → teardown-ByzfDPyu.js} +83 -4
package/dist/test.d.ts +2 -7
package/dist/test.js +43 -14
package/dist/vite.d.ts +87 -1
package/dist/vite.js +262 -3
package/editor/assets/{agent8-DEVkEa3d.js → agent8-o27_Y1xN.js} +1 -1
package/editor/assets/{debug-zGAtpDF0.js → debug-DfcWX3uW.js} +3 -2
package/editor/assets/index-C9fb5QcT.js +10696 -0
package/editor/index.html +1 -1
package/package.json +1 -1
package/skills/incanto-editor.md +61 -8
package/skills/incanto-physics-and-input.md +15 -0
package/skills/incanto-verifying-your-game.md +68 -0
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/beacon-isle-3d/vite.config.ts +7 -0
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/vite.config.ts +7 -0
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/vite.config.ts +7 -0
package/dist/debug-draw-CZmOYjL2.js +0 -13
package/editor/assets/index-Bx4UtWYY.js +0 -10586

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-Bx4UtWYY.js"></script>
+    <script type="module" crossorigin src="./assets/index-C9fb5QcT.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.29.0",
+  "version": "0.31.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/skills/incanto-editor.md CHANGED Viewed

@@ -18,9 +18,50 @@ bunx incanto-editor level.scene.json --output build/level.scene.json --port 5179
 **Project mode** (no file argument — the usual way) scans the current directory for
 `*.scene.json` (skipping node_modules/dist/hidden dirs): one scene auto-opens; several
-show a picker; the picker can also CREATE a new scene (`levels/arena.scene.json` →
-minimal 2D scene, parent dirs made). A `scenes` button switches files anytime. The page
-can only ever address `*.scene.json` files under the launch directory.
+open the scene browser. The page can only ever address `*.scene.json` files under the
+launch directory.
+### The scene browser (`scenes`)
+The `scenes` button opens the project as a tree, not a list of paths:
+- **Every `.json` in the project is listed** — a scene is JSON by definition, so
+  nothing else could be one — and each row says whether it IS a scene, read from
+  the file rather than guessed from its name. A scene declares itself:
+  `{"format": 1, "type": "scene", "name", "root"}`, the same four keys the loader
+  demands. Scene rows show `3d · 24 nodes`; anything else is dimmed and marked
+  `not a scene`, and opening it fails with the reason (`"type" must be "scene",
+  and this file has no "type"`). So a scene you saved as `level.json` is right
+  there and opens; `package.json` is right there and tells you why it will not.
+  (Non-scene contents never leave the server — only the reason does.)
+- **Folders**, sorted, with a scene count each; a chain that holds nothing else
+  collapses into one row (`src / scenes`). Small projects open fully expanded.
+- **The scene you are editing** is marked and revealed, and the cursor starts on it.
+- **A filter box** — type any part of a path; matches show wherever they are hiding.
+  Keyboard from that box: `↑↓` move · `→` open a folder · `←` close it · `⏎` load ·
+  `Esc` close (backdrop and ✕ work too).
+- 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
+  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.
+**The same browser opens inside a running game.** When the game's dev server serves
+the project's scenes, `☰ debug ▸ ✎ edit this scene` gives you the whole project: the
+editor opens on the scene the game is running, and `scenes` switches to any other one,
+saves back to ITS file, and `play ▸ run as the game` boots whichever scene you loaded.
+That needs one plugin in `vite.config.ts` (already there in every `incanto-new`
+project):
+```ts
+import { incantoScenes } from 'incanto/vite';
+export default defineConfig({ plugins: [incantoScenes()] });
+```
+Without it the `scenes` button is still there and says what to add — a missing
+one-line plugin should be a sentence you can act on, not a button that quietly
+is not there. The editor still edits the scene the game booted with meanwhile.
 Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
@@ -45,9 +86,16 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   (dimension, gravity with real inputs, environment/input/assets/multiplayer).
 - **Viewport with DIRECT MANIPULATION** — a mode toolbar (top left) + the
   Unity/Godot keys: **W move · E rotate · R scale** (active mode highlighted).
-  A collider-visibility toggle sits beside the mode tools: light-green
-wireframes for every body (2D shapes AND 3D box/sphere/capsule), persisted,
-and carried into play mode as the engine's physics debugDraw.
+  A collider-visibility toggle sits beside the mode tools, and it shows the
+  colliders the ENGINE builds, not a drawing of the `collider` prop: it attaches
+  Rapier to the edit view with `simulate: false` and turns on the same
+  `debugDraw` the play view uses. So a mesh-fitted body, an InstancedMesh3D
+  scatter's hulls, a terrain and a character capsule all appear — none of them
+  are in the scene JSON — and rotation, scale and offset are wherever physics
+  actually puts them. Nothing is simulated: bodies are posed from the tree each
+  tick (an outline follows a gizmo drag) and the solver never runs, so the scene
+  does not fall over while you edit it. Persisted, and carried into play mode
+  unchanged.
   Move: axis arrows (X red, Y green, Z blue in 3D) + center square for free
   movement. Rotate: drag the ring(s) — one ring in 2D, three world-axis rings
   in 3D — with a live degree readout at the cursor. Scale: the same arrows with
@@ -56,8 +104,13 @@ and carried into play mode as the engine's physics debugDraw.
   SNAP** — rotations to 15°, positions to the grid (10 px in 2D, 0.5 u in 3D),
   scales to 0.25 steps (the readout shows the snapped value).
   2D additionally supports click-pick, body drag, wheel zoom-at-cursor,
-  right/middle/Shift-drag pan, Alt+wheel scale, and collider wireframes;
-  `F` frames the scene in both dimensions. The add-node dropdown is grouped by
+  right/middle/Shift-drag pan, Alt+wheel scale, and collider wireframes.
+  **`F` frames the SELECTED node** (its whole subtree; a light or empty node has
+  no bounds, so the camera goes to it at a readable distance) — and the whole
+  scene when nothing is selected, which is the Maya/Unity/Unreal meaning of the
+  key. Same as the ⌖ frame button, and as `frame in view` in the tree's
+  right-click menu. This is how you find a node you selected in the tree that is
+  nowhere near the camera; double-click in the tree stays RENAME. The add-node dropdown is grouped by
   category (Core / 2D / 2D Physics / 3D / 3D Physics / Network, plus a trailing
   Other catch-all so an unclaimed type can never vanish from the list). The
   dropdown, inspector and in-editor docs are registry/schema-driven — newly

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

@@ -243,6 +243,21 @@ it, a map with terrain is a wall of grid lines and the shape you came to check i
 somewhere inside it. The debug overlay's **Colliders** menu item cycles
 off → all → selected over exactly these two fields.
+### Colliders without a simulation
+`enablePhysics3D(engine, { simulate: false })` (and the 2D twin) builds the world
+and never advances it: the body set is kept in step with the tree, every body is
+posed FROM the tree each tick and propagated to its colliders, and then it stops
+— no solver, no collision events, no write-back into node props. `debugDraw`
+works exactly as above.
+This is how the scene editor shows colliders while you edit: the real shapes,
+including the ones that are not in the scene JSON at all (a mesh-fitted body, an
+InstancedMesh3D scatter's hulls, a terrain, a character capsule), sitting where
+the tree says, without your scene falling over while you look at it. Use it for
+any "show me the collision geometry" tool. Do NOT use it to freeze a running
+game — that is `engine.timeScale = 0`, which keeps the world coherent.
 ## Placement rules
 `CharacterController2D` MUST be a direct child of a `CharacterBody2D` — the

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

@@ -155,6 +155,74 @@ export default { plugins: [incantoScenes()] };
 Invalid `*.scene.json` saves keep the last good scene running and surface the
 IncantoError in the terminal AND as a browser overlay.
+The same plugin serves this project's scenes to the editor, so the one you switch
+into from the running game (`☰ debug ▸ ✎ edit this scene`) can open, create and save
+ANY scene in the project — not just the one the game booted with. `incantoScenes({
+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`).
+## 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.
+## 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()`**.
+## 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`**.
 ## 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.29.0",
+    "incanto": "^0.31.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/beacon-isle-3d/vite.config.ts CHANGED Viewed

@@ -1,5 +1,12 @@
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 export default defineConfig({
   base: './',
+  // Dev-server only, and both are why the editor is useful here:
+  // - incantoScenes(): validates every *.scene.json the moment you save it,
+  //   AND serves this project's scenes, so the editor (☰ debug ▸ edit this
+  //   scene ▸ scenes) can open, create and save any scene in the project.
+  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
+  plugins: [incantoScenes(), incantoLibrary()],
 });

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

package/templates-app/tps-3d/vite.config.ts CHANGED Viewed

@@ -1,5 +1,12 @@
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 export default defineConfig({
   base: './',
+  // Dev-server only, and both are why the editor is useful here:
+  // - incantoScenes(): validates every *.scene.json the moment you save it,
+  //   AND serves this project's scenes, so the editor (☰ debug ▸ edit this
+  //   scene ▸ scenes) can open, create and save any scene in the project.
+  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
+  plugins: [incantoScenes(), incantoLibrary()],
 });

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

package/templates-app/village-quest-3d/vite.config.ts CHANGED Viewed

@@ -1,5 +1,12 @@
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
 import { defineConfig } from 'vite';
 export default defineConfig({
   base: './',
+  // Dev-server only, and both are why the editor is useful here:
+  // - incantoScenes(): validates every *.scene.json the moment you save it,
+  //   AND serves this project's scenes, so the editor (☰ debug ▸ edit this
+  //   scene ▸ scenes) can open, create and save any scene in the project.
+  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
+  plugins: [incantoScenes(), incantoLibrary()],
 });

package/dist/debug-draw-CZmOYjL2.js DELETED Viewed

@@ -1,13 +0,0 @@
-//#region src/core/debug-draw.ts
-const sources = /* @__PURE__ */ new Set();
-/** @internal physics runtimes self-register on enable. */
-function registerDebugSource(source) {
-	sources.add(source);
-	return () => sources.delete(source);
-}
-/** @internal renderers pull their dimension's sources. */
-function debugSources(dimension) {
-	return [...sources].filter((s) => s.dimension === dimension);
-}
-//#endregion
-export { registerDebugSource as n, debugSources as t };