incanto 0.28.0 → 0.30.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

@@ -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
@@ -110,6 +163,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: