incanto 0.27.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

@@ -359,6 +359,7 @@ tops radially away with a smooth falloff as a character wades through.
 | `flowers` | `0` | DEPRECATED — confetti heads; use a `Flowers3D` node (load-time check 0–0.2) |
 | `seed` | `1` | placement seed — identical field across runs/machines |
 | `drape` | `null` | **AUTO by default**: whenever the scene has a Terrain3D, every blade roots on the ground under it (samples `heightAt`) — omit this prop and rolling terrain just works. `true` forces it (keeps retrying until a terrain appears — streamed worlds), `false` opts out (flat carpet at the node's Y) |
+| `avoidWater` | `true` | blades keep OUT of the water — any instance whose ground sits under a `Water3D` or `River3D` surface is dropped, so a creek that cuts its bed through a meadow gets banks instead of blades waving in the current. `false` plants reeds and paddy fields |
 | `terrain` | `""` | drape target node path; empty = **auto-find the first Terrain3D** in the tree. A non-empty path that is NOT a Terrain3D fails at load — no silent floating |
 
 > **Rolling terrain just works.** Since 0.14 draping is on by default: with a
@@ -415,6 +416,7 @@ billboard confetti. Deterministic from the `seed` PROP.
 | `clustering` | `0.6` | 0 uniform … 1 tight Voronoi patches (load-time check) |
 | `sway` | `0.5` | head-bob wind strength; 0 disables |
 | `drape` | `null` | AUTO by default — plants root on the scene's Terrain3D when one exists; `true` forces, `false` opts out — see the Foliage3D drape note above |
+| `avoidWater` | `true` | plants keep OUT of the water (see the Foliage3D note) — `false` for lilies and marsh planting |
 | `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 
 ## Tree3D
@@ -518,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
@@ -817,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
@@ -977,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:
@@ -991,6 +1057,10 @@ underneath decides everything else.
   runs faster), which is what puts rapids where a real river has them;
 - **whitewater**: grade × speed makes rapids, the bank shear line makes edge
   froth, a thinning column riffles over rock. Foam then rides downstream.
+- **a dry bank**: `Foliage3D` and `Flowers3D` refuse to plant where a river
+  runs (`avoidWater`, on by default), so a creek cutting its bed through a
+  meadow gets bare wet ground at the edge instead of blades waving in the
+  current;
 - **what stands in the water**: drop boulders in the channel and the current
   answers them — a cushion of white piled on the upstream face, a torn wake
   opening downstream, and the surface sheen bending around the stone. Nothing
@@ -1048,6 +1118,23 @@ should be.
 const path = traceDownhillPath(terrain.heightAt, { x: peakX, z: peakZ, step: 7 });
 ```
 
+**Placing things against a self-carved bed?** Ask the engine what the cut will
+be — never mirror it by hand. `riverCarveChannels` is the same function the node
+runs at load, so a generator that assigns its result to a scratch Terrain3D gets
+the EXACT ground the game will have; a hand-rolled approximation puts the player
+inside a hill.
+
+```ts
+const carved = new Terrain3D('probe');
+Object.assign(carved, terrainProps);
+carved.channels = riverCarveChannels({
+  path, widths, depth,
+  cell: size / resolution,   // the terrain's own grid
+  groundAt: (x, z) => rawTerrain.heightAt(x, z),
+});
+const groundAt = (x: number, z: number) => carved.heightAt(x, z); // place against THIS
+```
+
 
 ### Waterfalls happen — you do not author them
 

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 |
@@ -331,6 +340,7 @@ Signals: `movementStateChanged(state)`
 | `clustering` | `0.6` | number |
 | `sway` | `0.5` | number |
 | `drape` | `null` | null |
+| `avoidWater` | `true` | boolean |
 | `terrain` | `""` | string |
 
 ## `Foliage3D` — `incanto/3d`
@@ -344,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` |
@@ -363,6 +374,7 @@ Signals: `movementStateChanged(state)`
 | `flowers` | `0` | number |
 | `seed` | `1` | number |
 | `drape` | `null` | null |
+| `avoidWater` | `true` | boolean |
 | `terrain` | `""` | string |
 
 ## `HudLayer` — `incanto`
@@ -383,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`
 
@@ -420,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 |
@@ -456,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 |
@@ -474,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 |
@@ -491,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 |
@@ -543,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`
 
@@ -555,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 |
@@ -604,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 |
@@ -660,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 |
@@ -681,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 |
@@ -728,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` |
@@ -766,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)`
@@ -781,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 |
@@ -836,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 |
@@ -855,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 |
@@ -950,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`
@@ -965,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 |
@@ -978,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 |
@@ -1008,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 |