incanto 0.28.0 → 0.29.0

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

@@ -97,10 +97,19 @@ never be one node each. One instanced node draws them all at once:
 ```
 
 - Each row: `[x, y, z, yawDeg?, scale?]` — dense enough to GENERATE hundreds
-  (pair with `terrain.heightAt` for y).
+  (pair with `snapToGround` or `terrain.heightAt` for y).
 - Same `mesh`/`size`/`material` surface as MeshInstance3D. Replace the whole
-  `transforms` array to update. No per-instance colliders — add a few
-  StaticBody3D boxes only where gameplay needs blocking.
+  `transforms` array to update.
+- **`collider` makes the whole field SOLID**: `"collider": {}` gives every row
+  its own static collider SHAPED LIKE THE MESH — a faceted `gem` stone collides
+  as that stone's own hull, not as a ball tucked inside it, so you can't clip
+  through the corners that stick out. Sized from `size` × that row's scale and
+  turned by its yaw. All of them hang off one fixed body, so a fifty-stone
+  scatter costs fifty shapes and no per-frame work. A boulder field the player
+  walks straight through is the tell that a world is scenery rather than a
+  place.
+  `{ "shape": "sphere", "radius": r }` / `{ "shape": "box", "size": [x,y,z] }`
+  opt out into a cheaper approximation when a rough blocker is all you want.
 
 ### `LoftMesh3D` (smooth swept hulls — vehicle bodies, canopies)
 
@@ -367,14 +376,82 @@ show it as the background (otherwise `background` color applies). Standard
 materials need this OR explicit lights to be visible. An explicit HDRI wins
 over the `sky`'s image-based ambience.
 
-## Preloading with a progress bar
+## NEVER compute a Y against the terrain by hand
+
+This is the single most repeated mistake in scene authoring, and it is not a
+careless one: the number is right when you write it and wrong the moment
+anything reshapes the ground under it — a river carving its bed, a basin, a new
+seed, a generator that mirrors a carve slightly differently. Boulders in
+mid-air, a player buried to the waist, bridge posts hanging over a creek: all
+the same bug.
+
+**Say what you mean instead.** Every `Node3D` takes `snapToGround`:
+
+```json
+{ "name": "Boulder", "type": "MeshInstance3D",
+  "props": { "mesh": "gem", "size": [1.2, 0.8, 1.1],
+             "position": [12, 0, -30],      // y is IGNORED
+             "snapToGround": 0.4 } }        // half its height → it rests on the ground
+```
+
+- `true` — put the node's origin on the ground.
+- a number — the same, lifted that many metres (a prop whose origin is at its
+  middle wants half its height).
+- `false` — "this hangs in the air ON PURPOSE" (a bridge deck, a lantern, a
+  cloud). The grounding check below skips these, so mark them.
+- omitted — `y` is used exactly as authored.
+
+Resolved at load, in the same frame the terrain is built, and it honours an
+ancestor's yaw, so props under a turned rig land where they look.
+
+**And check it.** `findFloatingProps` from `incanto/test` reports every prop
+whose underside is off the ground, instanced fields row by row:
+
+```ts
+import { findFloatingProps } from 'incanto/test';
+const off = findFloatingProps(gameJson);
+ok(`every prop meets the ground (${off.length})`, off.length === 0);
+for (const o of off) console.error(`  ${o.path}: ${o.gap > 0 ? 'floats' : 'buried'} ${o.gap} m`);
+```
+
+Put it in your `verify.ts` next to `auditScene`. It costs nothing and it is the
+difference between shipping a floating bridge and not.
+
+## The loading screen has to cover the WHOLE boot
+
+Downloading the assets is the first half. Building a dressed scene and
+compiling its GPU programs is the second, and on a big outdoor scene the second
+is the longer one (measured on the creek template: 1.5 s of assets, then **7 s
+of shader compile** — 49 programs). A bar that reaches 100% on the last
+downloaded byte and then leaves the player looking at a blank canvas is worse
+than no bar at all.
+
+So run ONE bar across both, with `createGame3D`'s `onProgress`:
 
 ```ts
 import { assetUrls, preloadUrls } from 'incanto';
+
+const progress = (fraction: number, label: string) => {
+  bar.style.width = `${Math.round(fraction * 100)}%`;
+  text.textContent = `${Math.round(fraction * 100)}% · ${label}`;
+};
 await preloadUrls(assetUrls(sceneJson.assets), (done, total) =>
-  bar.style.width = `${(done / total) * 100}%`);
+  progress((done / total) * 0.5, 'assets'));
+const game = await createGame3D({
+  canvas, scene: sceneJson,
+  onProgress: (f, label) => progress(0.5 + f * 0.5, label),
+});
+document.querySelector('#loading')?.remove();   // now it is really ready
 ```
-Warms the HTTP cache before the engine starts; failures warn, never block.
+
+`onProgress` reports `scene` → `physics` → `renderer` → `shaders` → `ready`,
+and yields a frame at each step so the bar actually repaints (a callback fired
+inside one synchronous block updates nothing a player can see). `createGame3D`
+also draws its FIRST FRAME before it resolves, so the compile lands while your
+screen is still up rather than after you remove it.
+
+Preloading warms the HTTP cache before the engine starts; failures warn, never
+block.
 
 ## Particles
 

package/skills/incanto-editor.md

@@ -110,6 +110,157 @@ Save activates only when the working scene differs from the original
 (`Ctrl/Cmd+S`); undo is `Ctrl/Cmd+Z`. Saving writes pretty-printed JSON to
 `--output` (default: the input file).
 
+## The agent8 asset library (📚)
+
+Every field that takes a resource carries a **📚** button:
+
+| Field | Writes |
+|---|---|
+| `ModelInstance3D.model` | scene asset (`model`) + the `$ref` |
+| `ModelInstance3D.animation` | scene asset (`animation`) + the `$ref` — or type an embedded clip name |
+| `Sprite2D.texture`, `AnimatedSprite2D.sheet` | scene asset (`texture` / `spritesheet`) + the `$ref` |
+| `TileMap2D.texture` | scene asset (`texture`) + the `$ref` |
+| `Sprite3D.texture`, `AnimatedSprite3D.sheet` | the URL (3D sprites take raw URLs) |
+| material `map` / `normalMap`, `Tree3D.leafTexture`, `AudioPlayer.src` | the URL |
+| ASSETS ＋ form, and any asset's `url` | the URL (+ a suggested key) |
+
+It opens the agent8 catalog that opens the agent8 catalog: shelves down the
+left (**Everything** / 2D · sprite characters / 3D · characters, monsters,
+objects, vehicles, weapons, polyhaven, textures), keyword search, and a detail
+pane with the description, tags, format/size/mime and the URL. **Everything** is
+the tagless shelf — the one that searches the whole catalog and the only way to
+reach assets the tag tree does not name (sounds, one-off props).
+
+The preview is the real thing: an image renders as an image, a **GLB is
+rendered by the engine itself** (turntable, drag to spin, `targetHeight: 1` so
+everything frames the same) — the same loader the game will use, so what you
+see is what the scene gets.
+
+Picking does the whole job, not half of it:
+
+- a **URL field** (material map, leaf texture, audio src) gets the URL;
+- a **`$assetKey` field** (`ModelInstance3D.model`, sprite texture/sheet) gets a
+  scene `assets{}` entry AND the ref that resolves to it — one action, no
+  separate "declare the asset" step. An entry with the same url is reused, so
+  browsing to the model you already have does not duplicate it;
+- the ASSETS **＋** form fills the url and suggests the key from the file name.
+
+A sheet lands as a `spritesheet`, not a plain `texture` — the engine hard-fails
+on the latter in an `AnimatedSprite2D.sheet` — with `frameWidth`/`frameHeight`
+taken from the catalog's metadata when it carries them, and LEFT BLANK when it
+does not (an invented frame size renders wrong art in silence; a blank field
+asks you the question).
+
+**Sprite configs are the good pick.** Many sprite characters ship a sibling
+`<name>.json` (frame grid + named frame ranges) and the card wears an
+`animated` badge. Picking one declares the sheet asset with its frame size AND
+writes the node's `animations` + `autoplay` — one click gives you a sprite that
+actually animates, instead of a still frame and a homework assignment.
+
+What is on the shelves depends on the account behind your token. The public
+catalog at the time of writing:
+
+```
+3d  5,325   characters 392 · objects 1,992 · textures 2,538 · polyhaven 2,723
+            animations 24 · shaders 14 · vehicles 12 · weapons 6 · monsters 6
+2d    436   projects 361 (ui, characters, sounds) · sprite_characters 54
+            building 9 · minecraft 7 · characterportraits 5
+```
+
+Tags are lowercase — the catalog's own convention, and the query is
+case-sensitive. If a shelf you expect is missing it is missing upstream: browse
+from **Everything** and the tree shows what is actually there.
+
+A field that knows where its art lives opens there — a model at
+`3d / characters`, a clip at `3d / animations`, a material map at
+`3d / textures`, a sprite sheet at `2d / sprite_characters` — and the rest start
+at the root. It is a hint, not a cage: the breadcrumb walks anywhere. Either way
+the kind filter applies, so a "model" field never offers you a .png.
+
+**Access.** The catalog is per-account and its CORS list has no localhost in it,
+so the page cannot call it directly — `incanto-editor` proxies it at
+`GET /api/library`. Give the server a Verse8 token:
+
+```bash
+bunx incanto-editor --token <v8 access token>
+INCANTO_V8_TOKEN=<token> bunx incanto-editor      # same thing
+```
+
+With no token the 📚 panel asks for one and keeps it in the browser
+(`localStorage`), which is the right answer for a shared machine — the token is
+sent only to your own editor server, never written to disk by it, and forwarded
+upstream as a bearer. `INCANTO_LIBRARY_URL` points the proxy somewhere else
+(a mirror, or a stub in tests).
+
+A game hosting the editor (the live play ⇄ edit switch) has no catalog of its
+own — but its dev server can serve the same proxy, and then the 📚 works there
+too:
+
+```ts
+// vite.config.ts
+import { incantoLibrary, incantoScenes } from 'incanto/vite';
+export default defineConfig({ plugins: [incantoScenes(), incantoLibrary()] });
+```
+```ts
+// main.ts
+createGame3D({
+  ...,
+  debug: import.meta.env.VITE_INCANTO_DEBUG === '1',
+  editor: { library: true },   // "my dev server serves /api/library"
+});
+```
+
+`incantoLibrary()` is `apply: 'serve'` — dev only, nothing reaches a build, and
+the token stays in the terminal that started the server (`INCANTO_V8_TOKEN`, or
+`incantoLibrary({ token })`). `editor: { library: fn }` plugs in your own
+transport instead. With neither, the buttons are simply absent.
+
+## Play, and the switch into the running game
+
+**▶ play** means two different things and the editor asks which:
+
+- **▶ preview here** — the scene simulates inside the editor viewport with the
+  game's TypeScript behaviors STRIPPED. Engine-native motion only (physics,
+  animation, water) — a quick look, not the game.
+- **⤢ run as the game** — the page BECOMES the game: `createGame3D` boots the
+  working scene with your behaviors, your loading screen and the debug overlay.
+  This is the real thing, and it carries the edits you have not saved.
+
+From that game, the ☰ debug menu's **✎ edit this scene** switches straight back
+to the editor — same window, no reload, and the edit camera picks up the pose
+the player was looking from. **✕ exit** in the editor returns to the game
+without playing. The pair is one loop you can ride all session:
+
+```
+game  --(☰ debug ▸ ✎ edit this scene)-->  editor
+editor --(▶ play ▸ ⤢ run as the game)-->  game
+```
+
+What crosses is the AUTHORED scene, never the stepped tree: a running scene has
+been moved by physics and spawned into by behaviors, and editing that would mean
+editing wherever the simulation happened to be. Games hosting the editor
+themselves (`createGame3D({ editor: … })`) get a **save** button only when they
+pass `editor.save` — otherwise edits live as long as the session does.
+
+## Animating a model from the inspector
+
+Select a `ModelInstance3D` and everything about what it is DOING sits in one
+**animation** card: the clip, whether it loops, how fast, and where in the clip
+it starts. The clip list is the model's own embedded clips plus the scene's
+animation assets, and 📚 pulls a clip-only GLB from the agent8 library
+(`3d / animations`) — picking one declares the asset and writes the ref.
+
+- **speed** −3…3. `1` is as authored, `0` freezes the pose, negative plays
+  backwards. It retimes the clip already playing, so dragging it is smooth.
+- **animationOffset** seconds into the clip. Changing it re-seeks live, which
+  makes it a scrubber as well as a stagger control — give copies different
+  offsets so a row of torches stops flickering in lockstep.
+- The **upper-body layer** (a second clip on the upper body only) is folded away
+  until you use it.
+
+The edit viewport keeps ambient visuals moving, so all of this animates while
+you are editing — you see the change, not a still frame.
+
 ## Painting TileMap2D levels
 
 Select a `TileMap2D` node and the inspector grows a **🖌 paint tiles** tool:

package/skills/incanto-environment.md

@@ -520,6 +520,64 @@ automatic, no props.
     { "name": "Terrain", "type": "Terrain3D",
       "props": { "size": [200, 200], "maxHeight": 6, "seed": 1, "theme": "island" } }
   ] }
+**`reflectivity` (0..1, null = the preset's own)** dials how much sky the
+surface throws back at grazing angles. Turn it DOWN under a bright or overcast
+sky: that sky's radiance runs far past 1, so a high ceiling paints the water
+white — and a Water3D doing that beside a River3D (which paints an AUTHORED sky
+palette and never blows out) reads as two unrelated materials meeting at a line.
+The river template's plunge pool runs 0.06 for exactly that reason.
+
+### Condition a traced course before a river runs it
+
+```ts
+import { smoothCourse, traceDownhillPath } from 'incanto/3d';
+const path = smoothCourse(traceDownhillPath(heightAt, opts), widestWidth / 2);
+```
+
+**Do this every time you feed `traceDownhillPath` into a River3D.** A steepest-
+descent trace zigzags at the terrain's noise scale and can hook back within
+metres of a reach it already ran. A ribbon on that course cannot be well formed:
+tight corners fold its inner edge, and a hook stacks two sheets of water on the
+same ground — which renders as translucent sheets of paper pasted over one
+another, with no rendering fix available. `smoothCourse` relaxes the bends to
+what the width can take, drops sub-width noise, and CUTS the course where it
+folds back (a creek does not flow over its own reach; ending is the better
+answer).
+
+### A river's course sets its maximum width
+
+A `River3D` surface is a RIBBON swept along `path`, and a swept ribbon cannot be
+wider than the bend it is taking — past that, its inner edge folds through
+itself. The engine holds the INNER bank inside the local turn radius (the outer
+bank keeps every metre the ground gives it, which is what a real bend looks
+like: point bar inside, cut bank outside).
+
+The failure this prevents is worth recognising, because it is the one visual bug
+this node keeps producing: **bare channel floor beside the water — the creek
+appears to stop in the middle of its own bed.** It means the ground is wetter
+than the course can carry. River3D says so at load:
+
+```
+[incanto] River3D 'Creek': the course is too tight for the water it holds —
+41 of 608 stations leave bare channel beside the ribbon (worst at 210 m: ground
+wet to 11.3 m from the centre, a bend that can only carry 2.1 m). Fix by EASING
+THE BENDS in `path` (fewer, straighter points), NARROWING `widths` there, or
+placing standing water (a Water3D) if that reach is really a pool.
+```
+
+Three rules that keep a river out of this entirely:
+
+1. **Widths ≤ ⅓ of the tightest bend.** A `traceDownhillPath` result zig-zags;
+   thin it or raise its `step` before handing it to a wide river.
+2. **A wide slow reach is still the river.** Don't put a Water3D pool at the
+   foot of a River3D — they are different shaders with different sky and foam
+   models, they cannot be tuned to match, and they meet along a visible seam.
+   Open the `widths` profile instead (`[2.4, 4.5, 7, 9]` is a spring→pool run).
+3. **Verify it, don't eyeball it.** `findRiverCoverageGaps(rings)` (exported from
+   `incanto/3d`) reports the reaches where the ribbon falls short, and a probe a
+   metre outside each bank — ground still BELOW the waterline out there — counts
+   bare channel headlessly. The river template gates on both.
+
 That snippet is the canonical PHYSICS recipe: the `heightfield` collider has
 no params of its own — it pulls the height grid from its Terrain3D CHILD, so
 visuals and collision can never drift apart. It is static-only (load-time
@@ -819,6 +877,12 @@ the scene root a cutout has nothing to stand in for, and the loader says so.
 | `size` | `[2, 1, 1]` | box extent in meters, centered on the node — which PART of the parent holds water back |
 | `enabled` | `true` | live toggle — a scuttled hull can start letting the sea in |
 
+**A plunge pool is a `Water3D`, not a river.** A `River3D` is a current: a
+ribbon fitted to the ground it runs over. Run one across a carved basin and it
+lays a strip of water over the bowl with its edges hanging in mid-air — end the
+creek at the lip and put a pool in the basin instead. Size a square surface to
+`side = radius · √2` so its corners land on the rim rather than over the bank.
+
 **A cutout cannot punch a hole in open water**, because nothing is ever cut out
 of the water. The mask is the parent's own silhouette, so water can only be
 hidden behind geometry the player is already looking at. Overshoot the box and
@@ -979,7 +1043,7 @@ underneath decides everything else.
 | `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 waterfall the course turns out to contain — the node finds the drops and hangs a Particles3D plume on each (0 = off) |
+| `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) |
 | `sunDirection` / `sunColor` / `sunIntensity` | sky / `#fff6e0` / `1` | glint (the environment sun wins while `sunDirection` is default) |
 
 **What the node derives for you**, all from `path` + the ground:

package/skills/incanto-node-reference.md

@@ -49,6 +49,7 @@ Signals: `animationFinished(name)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `texture` | `""` | string |
 | `size` | `[1,1]` | array |
 | `billboard` | `"y"` | one of: `y` `full` `none` |
@@ -94,6 +95,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -128,6 +130,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `mode` | `"screen"` | one of: `screen` `y` `none` |
 
 ## `BoneAttachment3D` — `incanto/3d`
@@ -141,6 +144,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `target` | `""` | string |
 | `bone` | `""` | string |
 
@@ -155,6 +159,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `target` | `""` | string |
 | `bone` | `"Head"` | string |
 | `lookAt` | `""` | string |
@@ -190,6 +195,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `fov` | `60` | number |
 | `near` | `0.1` | number |
 | `far` | `1000` | number |
@@ -224,9 +230,9 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `true` | boolean |
 | `collider` | `{}` | object |
 | `velocity` | `[0,0,0]` | array |
-| `snapToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -252,6 +258,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `view` | `"free"` | one of: `free` `firstPerson` `quarter` `side` |
 | `camDistance` | `4` | number |
 | `eyeHeight` | `0.64` | number |
@@ -304,6 +311,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `color` | `"#ffffff"` | string |
 | `intensity` | `1` | number |
 | `castShadow` | `false` | boolean |
@@ -322,6 +330,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `density` | `"sparse"` | one of: `lush` `sparse` `none` |
 | `area` | `[20,20]` | array |
 | `seed` | `1` | number |
@@ -345,6 +354,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `2` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `kind` | `"grass"` | one of: `grass` `flowers` `reeds` |
 | `style` | `"mesh"` | one of: `blades` `simple` `mesh` `tufts` |
 | `tuftStyle` | `"grass"` | one of: `grass` `fern` |
@@ -385,12 +395,14 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `mesh` | `"box"` | one of: `box` `sphere` `capsule` `plane` `cylinder` `gem` |
 | `size` | `[1,1,1]` | array |
 | `material` | `{}` | object |
 | `transforms` | `[]` | array |
 | `castShadow` | `false` | boolean |
 | `receiveShadow` | `false` | boolean |
+| `collider` | `null` | null |
 
 ## `Joint2D` — `incanto/2d`
 
@@ -422,6 +434,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `type` | `"spherical"` | one of: `fixed` `spherical` `rope` `spring` |
 | `target` | `""` | string |
 | `anchor` | `[0,0,0]` | array |
@@ -458,6 +471,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `sections` | `[]` | array |
 | `slices` | `24` | number |
 | `smooth` | `4` | number |
@@ -476,6 +490,7 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `mesh` | `"box"` | one of: `box` `sphere` `capsule` `plane` `cylinder` `gem` |
 | `size` | `[1,1,1]` | array |
 | `material` | `{}` | object |
@@ -493,11 +508,14 @@ Signals: `movementStateChanged(state)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `model` | `""` | string |
 | `animation` | `""` | string |
 | `targetHeight` | `0` | number |
 | `castShadow` | `false` | boolean |
 | `animationLoop` | `true` | boolean |
+| `animationSpeed` | `1` | number |
+| `animationOffset` | `0` | number |
 | `animationUpper` | `""` | string |
 | `animationUpperLoop` | `false` | boolean |
 | `upperBodyRoot` | `"Spine"` | string |
@@ -545,6 +563,7 @@ _No props (structural fields only)._
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 
 ## `OmniLight3D` — `incanto/3d`
 
@@ -557,6 +576,7 @@ _No props (structural fields only)._
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `color` | `"#ffffff"` | string |
 | `intensity` | `1` | number |
 | `range` | `0` | number |
@@ -606,6 +626,7 @@ Signals: `finished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"effects"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
 | `rate` | `40` | number |
@@ -662,6 +683,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
 | `mass` | `1` | number |
 | `gravityScale` | `1` | number |
@@ -683,6 +705,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `path` | `[]` | array |
 | `width` | `6` | number |
 | `widths` | `[]` | array |
@@ -730,6 +753,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `texture` | `""` | string |
 | `size` | `[1,1]` | array |
 | `billboard` | `"y"` | one of: `y` `full` `none` |
@@ -768,6 +792,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `collider` | `{}` | object |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -783,6 +808,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"terrain"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `size` | `[200,200]` | array |
 | `maxHeight` | `28` | number |
 | `seed` | `1` | number |
@@ -838,6 +864,7 @@ Signals: `timeout`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `width` | `0.3` | number |
 | `color` | `"#ffffff"` | string |
 | `opacity` | `0.8` | number |
@@ -857,6 +884,7 @@ Signals: `timeout`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `tier` | `"medium"` | one of: `simple` `medium` `high` |
 | `type` | `"conifer"` | one of: `conifer` `broadleaf` `dead` `bush` |
 | `seed` | `1` | number |
@@ -952,6 +980,7 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `voxels` | `[]` | array |
 
 Signals: `blocksChanged`
@@ -967,6 +996,7 @@ Signals: `blocksChanged`
 | `visible` | `true` | boolean |
 | `renderOrder` | `1` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `size` | `[40,40]` | array |
 | `color` | `"#2a6fbe"` | string |
 | `opacity` | `0.8` | number |
@@ -980,6 +1010,7 @@ Signals: `blocksChanged`
 | `mirrorInterval` | `33` | number |
 | `swellSteepness` | `0.35` | number |
 | `foam` | `true` | boolean |
+| `reflectivity` | `null` | null |
 | `interaction` | `true` | boolean |
 | `splash` | `true` | boolean |
 | `sunDirection` | `[0.5,0.8,0.3]` | array |
@@ -1010,6 +1041,7 @@ Signals: `entered(body)` · `exited(body)`
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
+| `snapToGround` | `null` | null |
 | `size` | `[2,1,1]` | array |
 | `enabled` | `true` | boolean |
 

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