incanto 0.27.0 → 0.29.0

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

@@ -30,11 +30,43 @@ independent; enable the one matching your scene.
 
 2D collider shapes: `{"shape":"rect","size":[w,h]}` · `{"shape":"circle","radius":r}` ·
 `{"shape":"capsule","radius":r,"height":h}`.
-3D: `{"shape":"box","size":[x,y,z]}` · `{"shape":"sphere","radius":r}` · `{"shape":"capsule",...}` ·
-`{"shape":"trimesh","vertices":[...],"indices":[...]}` · `{"shape":"heightfield"}` (STATIC-only;
-reads the grid from a `Terrain3D` child — see the incanto-environment skill).
+3D: `{"shape":"auto"}` · `{"shape":"box","size":[x,y,z]}` · `{"shape":"sphere","radius":r}` ·
+`{"shape":"capsule",...}` · `{"shape":"trimesh","vertices":[...],"indices":[...]}` ·
+`{"shape":"heightfield"}` (STATIC-only; reads the grid from a `Terrain3D` child — see the
+incanto-environment skill).
 Malformed colliders are hard `BAD_FORMAT` errors at enable time.
 
+**`{"shape":"auto"}` is the one to reach for on props.** It shapes the collider like the
+`MeshInstance3D` the body CARRIES — box→cuboid, sphere→ball, cylinder/capsule→their own
+shapes, `gem`→a convex hull of its real vertices — so a blocker can never disagree with what
+the player sees. Hand-typed extents drift: a box "around" a bridge ends up wider than the
+bridge and you stop in mid-air; a sphere "for" a stone ends up inside it and you clip through
+the corners. Give the body its mesh as a CHILD and let the shape follow:
+
+```json
+{ "name": "DeckBody", "type": "StaticBody3D",
+  "props": { "position": [0, 3.2, -8], "rotation": [0, 34, 0], "collider": { "shape": "auto" } },
+  "children": [ { "name": "Deck", "type": "MeshInstance3D",
+    "props": { "mesh": "box", "size": [14, 0.22, 2.2] } } ] }
+```
+
+Bodies ignore an ANCESTOR's rotation, so a yawed structure puts each body at top level with
+its own `rotation` — the child mesh then turns with it, visual and collider together.
+
+**`auto` works on a `ModelInstance3D` (GLB/glTF/VRM) too** — the shape comes from the model's
+real triangles, baked through their own transforms, so an offset or `targetHeight`-fitted model
+collides where it is DRAWN:
+
+- on a **static** body (`StaticBody3D`, `Area3D`) → a triangle mesh: the model keeps its holes,
+  so you walk THROUGH an archway instead of into it. Level art can be dense; a collider over
+  ~20k triangles logs a note suggesting a low-poly collision model.
+- on a **moving** body (`RigidBody3D`, `CharacterBody3D`) → the convex hull. Rapier's triangle
+  meshes are hollow shells; a dynamic one falls through the world.
+
+The body simply does not exist until the model has downloaded — nothing is invented in the
+meantime — and it appears the step the asset lands. A body is ONE shape, so `auto` fits one
+mesh or one model and warns when the body carries more.
+
 - **`StaticBody2D/3D`** — immovable (ground, walls). Props: `collider`.
 - **`RigidBody2D/3D`** — simulated. Props: `collider`, `mass 1`, `gravityScale 1`,
   `fixedRotation false`, `friction 0.5`, `restitution 0`, `linearVelocity` (write to launch,
@@ -200,9 +232,16 @@ change scan was removed for performance).
 ## Debug drawing
 
 `physics.debugDraw = true` (the instance `enablePhysics2D/3D` returns) renders
-every collider as light-green wireframe lines IN THE GAME VIEW — Rapier's own
-debug geometry, so what you see is exactly what the solver sees. Default OFF;
-toggle it live whenever physics feels wrong.
+every collider as light-green wireframe lines IN THE GAME VIEW — the shape data
+the solver holds, so what you see is what it collides with. Default OFF; toggle
+it live whenever physics feels wrong.
+
+`physics.debugScope = node` narrows those lines to ONE node: its own colliders,
+its descendants', or the nearest body above it when it owns none (so a visual
+mesh child shows the body it belongs to). Null again for the whole world. Without
+it, a map with terrain is a wall of grid lines and the shape you came to check is
+somewhere inside it. The debug overlay's **Colliders** menu item cycles
+off → all → selected over exactly these two fields.
 
 ## Placement rules
 

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

@@ -168,12 +168,61 @@ VITE_INCANTO_DEBUG=1 bun run dev   # overlay on; plain `bun run dev` / prod buil
 A ☰ debug menu (top-left) toggles three draggable/resizable panels over the
 live game: **Explorer** (the scene tree — click any node), **Inspector** (the
 selected node's current state; numbers/strings/booleans/vectors editable
-in-place), **Logs** (an `engine.log` tail with level filters and an optional
+in-place, and an OBJECT prop like `collider` opens into a row per key with the
+`shape` as a dropdown — picking a shape writes a complete valid collider, never
+a box's `size` under a sphere's tag; bulky values like a 54-row `transforms`
+fold behind `▸ Array(54)` and expand on click, one row per element), **Logs** (an `engine.log` tail with level filters and an optional
 browser-console capture toggle) — plus **Stats**, an always-on-top chip pinned
 top-right (`60 fps · 12.1 ms` / `nodes 34 · tris 18.2k · calls 21`, refreshed
-~2×/s; the same numbers any code can read via `game.stats()`). Manual boots:
+~2×/s; the same numbers any code can read via `game.stats()`) — and
+**Colliders**, a switch that draws every physics shape as light-green wireframe
+in the game view. Manual boots:
 `(await import('incanto/debug')).attachDebugOverlay(engine)`.
 
+The Inspector HOLDS STILL while you use it: it stops refreshing whenever an
+input has focus or the pointer is inside the panel, and it keeps your scroll
+position across refreshes. Live values resume the moment you move away.
+
+**Colliders is the answer to "why did I stop in mid-air / fall through the
+floor".** What you see is the shape data the solver holds — put it next to the
+art and a collider that disagrees with its mesh is obvious in one glance.
+
+One click cycles **off → all → selected** (the menu stays open while you cycle —
+the item's label shows the state you landed on):
+
+- `all` is every collider in the world. On a real map that means a terrain
+  heightfield's grid over everything, which is why the third state exists.
+- `selected` draws only what the Explorer has picked: that node's colliders, its
+  descendants', or — if it owns none — the nearest BODY above it, so clicking a
+  visual `MeshInstance3D` shows the collider it hangs under rather than nothing.
+  A scatter field gives you all of its rows.
+
+From code: `physics.debugDraw = true` and `physics.debugScope = node` (null for
+everything).
+
+**✎ edit this scene** is the last item in that menu, and it is the fastest loop
+in the engine: the page you are playing in BECOMES the scene editor, from the
+camera you were standing at — no reload, no second tab. Drag a boulder out of
+the path, then **▶ play ▸ ⤢ run as the game** and the page is the game again,
+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:
+
+```ts
+createGame3D({
+  ...,
+  debug: import.meta.env.VITE_INCANTO_DEBUG === '1',
+  editor: { save: (json) => fetch('/api/scene', { method: 'PUT', body: JSON.stringify(json) }) },
+});
+```
+
+What crosses the switch is the AUTHORED scene JSON, not the live tree — physics
+has moved the live one, and "edit this scene" must not mean "edit wherever the
+simulation happened to be". Unsaved edits survive the round trip both ways; a
+page reload is what drops them.
+
 **Security — `debug` defaults to `false` and there is NO URL/query toggle**, so
 a DEPLOYED build can never be switched on by an end user (no more `?incanto_debug=1`).
 Enable it only from your own dev environment via the env-var gate above. The

package/templates-app/beacon-isle-3d/docs/project-3d-rules.md

@@ -35,4 +35,9 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
 11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
     proves the loop headlessly, then `bun run dev` and actually PLAY what you
     changed (move, shoot, clear a wave) before declaring it done.
+12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
+    debug menu — Explorer/Inspector (click a node, see and edit its live props),
+    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
+    wireframe). Blocked in mid-air or falling through the floor is a Colliders
+    question; a mystery frame-rate is a Stats question. Never ship the flag on.
 </userRequest>

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

package/templates-app/tps-3d/docs/project-3d-rules.md

@@ -35,4 +35,9 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
 11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
     proves the loop headlessly, then `bun run dev` and actually PLAY what you
     changed (move, shoot, clear a wave) before declaring it done.
+12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
+    debug menu — Explorer/Inspector (click a node, see and edit its live props),
+    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
+    wireframe). Blocked in mid-air or falling through the floor is a Colliders
+    question; a mystery frame-rate is a Stats question. Never ship the flag on.
 </userRequest>

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

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

package/templates-app/village-quest-3d/docs/project-3d-rules.md

@@ -35,4 +35,9 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
 11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
     proves the loop headlessly, then `bun run dev` and actually PLAY what you
     changed (move, shoot, clear a wave) before declaring it done.
+12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
+    debug menu — Explorer/Inspector (click a node, see and edit its live props),
+    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
+    wireframe). Blocked in mid-air or falling through the floor is a Colliders
+    question; a mystery frame-rate is a Stats question. Never ship the flag on.
 </userRequest>

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

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