incanto 0.1.0

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

@@ -0,0 +1,242 @@
+---
+name: incanto-building-2d-games
+description: Build 2D web games with Incanto — y-down pixel coordinates, string-keyed assets, sprites/spritesheets, following camera, screen-space HUD. Use when creating or modifying 2D scenes.
+---
+
+# Building 2D Games with Incanto
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+Prerequisite: `incanto-scene-json-authoring.md` (this directory) for the file format. This skill covers the 2D taxonomy.
+
+## Coordinate convention (Phaser/Godot prior)
+
+**1 unit = 1 px · (0,0) top-left · +y DOWN · positive rotation = clockwise (degrees).**
+
+## Boot sequence
+
+```ts
+import { createGame2D } from 'incanto/2d';
+import { PlayerControl } from './behaviors';
+import sceneJson from './my.scene.json';
+
+const game = await createGame2D({
+  canvas: document.querySelector('canvas')!,
+  scene: sceneJson,             // cloned internally — no cast, no structuredClone
+  behaviors: { PlayerControl }, // registered for you (hot-replace tolerant)
+});
+// game.engine / game.scene / game.renderer / game.physics
+// game.dispose() — ONE call tears everything down (SPA unmount)
+```
+
+One call does register → load → physics → input → renderer → start. Physics is
+`'auto'`: Rapier is enabled iff the tree has physics bodies (force with
+`physics: true|false`). Keyboard attaches to `window` (`keyboard: false`
+disables, or pass a target). `seed` / `fixedHz` / `pixelRatio` / `antialias`
+pass through. Gesture-blocked audio retries on the first canvas pointerdown.
+The manual `Engine` + `loadScene` + `Renderer2D` boot still exists for full
+control.
+
+## Assets (scene JSON `assets{}` — referenced as `"$key"`)
+
+```json
+"assets": {
+  "hero": { "type": "texture", "url": "hero.png", "filter": "nearest" },
+  "hero_run": { "type": "spritesheet", "url": "run.png", "frameWidth": 16, "frameHeight": 16 }
+}
+```
+- `filter: "nearest"` = pixel-art mode (no smoothing, no mipmaps). Default is `linear`.
+- Data URLs work as `url` (you can generate textures at runtime and inject them before `loadScene`).
+- Unknown `$refs` are hard `UNKNOWN_ASSET` errors listing declared keys.
+
+## 2D node taxonomy
+
+All 2D nodes extend `Node2D`: `position [x,y]` px · `rotation` deg · `scale [x,y]` ·
+`renderOrder` (draw order, higher = on top — the SAME prop name as 3D; legacy
+`zIndex` still loads as an alias) · `visible`.
+
+### `ColorRect2D` (no-art prototyping)
+A solid-colored rectangle — no texture, no asset file. Props: `size [100,100]`,
+`color '#ffffff'`, `opacity 1`, `anchor [0.5,0.5]`. The prototyping workhorse
+(paddles, walls, platforms, flashes); swap in a `Sprite2D` when art arrives.
+
+### `Sprite2D`
+| Prop | Default | Notes |
+|---|---|---|
+| `texture` | `""` | `'$key'`; empty = hidden |
+| `anchor` | `[0.5,0.5]` | `[0,0]` = top-left sits on the origin |
+| `flipX` / `flipY` | `false` | |
+| `tint` | `"#ffffff"` | multiplies the texture |
+| `opacity` | `1` | |
+
+### `AnimatedSprite2D` (extends Sprite2D — but use `sheet`, not `texture`)
+```json
+{ "sheet": "$hero_run", "autoplay": "run",
+  "animations": { "run": { "frames": [0, 7], "fps": 12, "loop": true },
+                   "hit": { "frames": [8, 8, 10], "fps": 10, "loop": false } } }
+```
+- `frames` with EXACTLY two ASCENDING numbers = inclusive `[start, end]` RANGE; any other
+  shape (longer arrays, or a descending pair) = explicit frame list. Frame indices are
+  row-major across the sheet.
+- API: `play(name)` (hard `UNKNOWN_ANIMATION` error if missing), `stop()`,
+  `currentAnimation`, `currentFrame`, `playing`; emits `animationFinished(name)` on
+  non-loop completion. `autoplay` starts on ready.
+
+**⚠️ STAND THE FEET ON THE GROUND — the `anchor` is almost never the feet.** A
+character that looks like it FLOATS above the platform (or sinks into it) is the #1
+sprite bug, and the fix is mechanical — you do NOT need to eyeball it. Two facts
+combine: (1) a sheet frame has TRANSPARENT PADDING below the art, and (2) the artist
+`origin`/anchor is usually the hip/centre, NOT the feet. So when the node sits where
+physics rests (a `CharacterBody2D` capsule rests its BOTTOM on the floor → the node is
+the collider CENTRE, `halfH` above the floor) but the sprite's feet render above that,
+the character floats on the invisible lower half of the collider.
+
+**Step 1 — find the feet row `feetFrameY` (pixels down the frame).** Easiest: read the
+sheet's companion metadata (`bunx incanto-assets info <name>`, or the `<sheet>.json`
+next to it). It has `frame` (the frame size), `origin` (the artist pivot — usually the
+hip, which is exactly why it's not the feet), and `body {offset, size}` (the character
+box). The feet ≈ the body BOTTOM: `feetFrameY = body.offset.y + body.size.y`
+(e.g. medieval-knight `76 + 60 = 136` in a 192px frame). No metadata? Measure exactly:
+draw the sheet to a `<canvas>` in the browser and scan for the lowest row whose alpha
+> 0 within frame 0.
+
+**Step 2 — solve the anchor.** The collider extends `halfH` below the node (capsule
+total height = `height + 2·radius`; e.g. `radius 18, height 30` → 66 tall → `halfH 33`).
+The sprite's feet render at `node + (feetFrameY − anchor.y·frameH)·scale`; set that equal
+to the collider bottom (`node + halfH`) and solve:
+
+```
+anchor.y = (feetFrameY − halfH / scale) / frameH
+```
+
+e.g. knight `(136 − 33/0.72) / 192 ≈ 0.46` (NOT the sheet's 0.61). For a colliderLESS
+patroller (a plain Node2D enemy) there's no `halfH` — pick `anchor.y` so the feet render
+on the floor at the y you patrol it at: `anchor.y = (feetFrameY − (floorY − patrolY)/scale) / frameH`.
+
+Equivalent fixes if you prefer: nudge the `Skin` down with a `position` offset, or give
+the collider an `offset` so its bottom meets the feet. The anchor route is cleanest.
+ALWAYS confirm in the browser (`bun run dev`) that the feet touch the surface.
+
+### `Camera2D`
+| Prop | Default | Notes |
+|---|---|---|
+| `follow` | `""` | NodePath to track (e.g. `"../Player"`) |
+| `smoothing` | `0` | 0 = snap; 0.85–0.95 = smooth chase (frame-rate independent) |
+| `zoom` | `1` | 2 = world pixels doubled |
+| `limits` | `[]` | `[minX,minY,maxX,maxY]` — view rect clamped inside |
+| `current` | `false` | mark exactly one |
+Camera `position` is the view CENTER. With no camera, the view shows (0,0)–(w,h).
+
+### `Label`
+`text`, `fontSize 16`, `color '#ffffff'`, `font 'monospace'`, `align 'left'|'center'|'right'`.
+CanvasTexture-rendered; mutate `label.text` freely (re-rasterizes only on change).
+
+### `UILayer`
+Plain container; everything under it renders in SCREEN space (ignores the camera) —
+HUD, score, menus. Put `Label`s and `Sprite2D`s under it with screen-pixel positions.
+`anchor` (default `top-left`) pins the layer origin to a screen corner/edge/center —
+see "Responsive layout" below.
+
+## Responsive layout (viewport + anchors)
+
+```json
+"viewport": { "design": [960, 540], "fit": "expand" }
+```
+
+Author the WORLD in fixed design pixels — the renderer maps them onto whatever
+canvas size the page provides. Fits: `expand` (the design rect is always fully
+visible; extra world shows beyond it — default), `letterbox` (exactly the design
+rect, centered bars), `integer` (whole-number scaling for pixel art). World
+geometry belongs in design px in the JSON — never hand-place it with
+`window.innerWidth` math in TS.
+
+`UILayer.anchor` (`top-left` default · `top` · `top-right` · `left` · `center` ·
+`right` · `bottom-left` · `bottom` · `bottom-right`) keeps HUD coordinates tiny
+offsets that survive any canvas size: a `Label` at `[-16, 16]` under a
+`top-right` layer hugs the corner everywhere. Misspelled anchors fail at load
+listing the valid set. With a viewport design, UI coordinates are design px.
+
+## Patterns
+
+- Group pickups/enemies (`"groups": ["coins"]`) and query `scene.tree.getNodesInGroup('coins')`.
+- Destroy with `node.queueFree()` (safe mid-update; flushed at end of frame).
+- Sound: an `AudioPlayer` node — zero-asset procedural SFX via `preset`
+  (coin/jump/hurt/explosion/…) OR an audio file via `src` (`volume`/`loop`/`autoplay`;
+  `play()`/`stop()`, `finished` signal). Global volume via `engine.audio`
+  (master/sfx/music + mute). Browsers gate audio behind a gesture; `createGame2D`
+  retries blocked plays on the first pointerdown. Headless-safe no-op. Full guide:
+  **incanto-audio.md**.
+- Reference example: [examples/2d-phaser-sprite-character-gravity](https://github.com/rareboe/Incanto/tree/main/examples/2d-phaser-sprite-character-gravity) —
+  spritesheet character with a walk/jump/attack behavior state machine.
+- Pointer→world mapping (the InputMap covers keyboard actions; pointer projection is
+  this one-liner):
+  `world = camera.clampedCenter(w,h) + (pointer - viewport/2) / camera.zoom`.
+
+## Game flow recipes
+
+- **Scene transition** (level 2, title → game):
+  ```ts
+  import { loadScene } from 'incanto';
+  game.engine.setScene(loadScene(level2Json));
+  ```
+  `setScene` frees the old root, clears + redeclares the input map from the new
+  scene's `input{}`, and emits `sceneChanged` — `createGame2D`'s touch overlay
+  rebuilds itself on that signal, and the renderer loads the new scene's assets
+  on demand. Register any extra behaviors/node types BEFORE the `loadScene` call.
+- **Game over / restart**: swap to a fresh load of the SAME JSON —
+  `engine.setScene(loadScene(levelJson))`. `loadScene` treats the JSON as
+  read-only (everything it keeps is cloned), so reloading the same imported
+  object yields a clean run; only clone (`structuredClone(levelJson)`) first if
+  your own code mutated that object. (`createGame`'s `scene` option already
+  structuredClones internally.)
+- **Pause / resume**: `engine.stop()` halts the loop (clock and accumulator
+  reset — no banked time on resume); `engine.start()` resumes.
+- **Save / load** (a behavior, localStorage):
+  ```ts
+  localStorage.setItem('save', JSON.stringify({ score: this.score }));
+  const save = JSON.parse(localStorage.getItem('save') ?? '{}');
+  ```
+
+## Rendering crispness
+
+`Renderer2D` defaults MATCH PHASER: `antialias: true`, `pixelRatio: 1` (the
+browser upscales on hiDPI screens — edges read soft). Texture sampling is
+linear by default; declare `"filter": "nearest"` on a texture/spritesheet
+asset for pixel art. For crisp retina rendering pass
+`pixelRatio: window.devicePixelRatio` to `createGame2D` (or the `Renderer2D`
+constructor).
+
+## Particles (effects in one node)
+
+```json
+{ "name": "Torch", "type": "Particles2D", "props": { "preset": "fire" } }
+{ "name": "Boom", "type": "Particles2D",
+  "props": { "preset": "explosion", "rate": 0, "burst": 60 } }
+```
+
+Presets: `fire smoke sparks fireworks explosion flash lightning rain snow magic`
+(unknown names fail at load listing these). The preset seeds every value;
+any prop you write overrides it (`colorStart`, `colorEnd`, `speed: [min,max]`,
+`directionDeg` (-90 = up), `spreadDeg`, `gravity`, `sizeStart/End`,
+`alphaStart/End`, `blend: "add"|"normal"`, `maxParticles`). Two props add
+per-particle variety (each keyed off the particle's stable random seed, so it
+never flickers): **`paletteColors: ["#hex", …]`** — when set, every particle
+picks ONE palette colour at birth (multi-colour confetti) instead of the single
+`colorStart`→`colorEnd` ramp; **`shimmer`** (Hz, 0 = off) — a per-particle alpha
+twinkle so sparks glitter on their own rhythm. Both work in 2D and 3D and apply
+to any preset (fire embers, magic shimmer, multi-colour fireworks). **Blend vs
+backdrop:** `blend: "add"` GLOWS but only over a DARK backdrop (night sky, caves)
+— over a BRIGHT scene (daylight grass) additive washes toward white and the
+sparks nearly vanish. For colourful particles on a bright scene use
+`blend: "normal"` (OPAQUE saturated dots that read on anything) with biggish
+sizes (small soft sprites read as pale haloes — the bigger the dot, the more its
+solid core carries the colour). `rate: 0` +
+`burst: N` makes a one-shot that emits `finished` — connect it to clean up:
+
+```json
+{ "signal": "finished", "from": "Boom", "to": ".", "handler": "onBoomDone" }
+```
+
+`node.replay()` re-arms a one-shot. Simulation is deterministic under the
+engine seed — runScript verifies particle gameplay reproducibly.

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

@@ -0,0 +1,245 @@
+---
+name: incanto-building-3d-games
+description: Build 3D web games with Incanto — Node3D taxonomy, scene environment, Engine + Renderer3D setup. Use when creating or modifying 3D scenes, meshes, cameras, or lights.
+---
+
+# Building 3D Games with Incanto
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+Prerequisite: read `incanto-scene-json-authoring.md` (this directory) for the scene file format, node paths, and
+connections. This skill covers the 3D node taxonomy and runtime setup.
+
+## Model files
+
+GLB/glTF/VRM files load via `ModelInstance3D` — see `incanto-3d-models.md` for the
+asset declaration, `targetHeight` sizing, and the `bunx incanto-model` inspector that
+reports a file's real bounding box and animation names.
+
+## Boot sequence (the only TypeScript you need to start)
+
+```ts
+import { createGame3D } from 'incanto/3d';
+import sceneJson from './my.scene.json';
+
+const game = await createGame3D({
+  canvas: document.querySelector('canvas')!,
+  scene: sceneJson,          // cloned internally — no cast, no structuredClone
+  pointer: true,             // pointer-look + lock-on-click (FPS pattern); default off
+  // behaviors: { ... },     // registered for you (hot-replace tolerant)
+});
+// game.engine / game.scene / game.renderer / game.physics
+// game.dispose() — ONE call tears everything down (SPA unmount)
+```
+
+One call does register → load → physics → input → renderer → start. Physics is
+`'auto'`: Rapier is enabled iff the tree has physics bodies (force with
+`physics: true|false`). Keyboard attaches to `window` (`keyboard: false`
+disables); `pointer: { lockOnClick: false }` for look without lock. `seed` /
+`fixedHz` / `pixelRatio` pass through. The manual `Engine` + `loadScene` +
+`Renderer3D` boot still exists for full control.
+
+Imperative per-frame logic can hang off `game.engine.updated.connect((dt) => { ... })`; for
+structured game logic attach Behaviors to nodes (see `incanto-behaviors-and-scripts.md`).
+
+Game flow (scene transitions, restart, pause, save) works identically in 3D —
+see "Game flow recipes" in `incanto-building-2d-games.md`.
+
+## 3D node taxonomy
+
+All 3D nodes extend `Node3D` and therefore have the transform props:
+
+| Prop | Default | Notes |
+|---|---|---|
+| `position` | `[0,0,0]` | meters; +Y up |
+| `rotation` | `[0,0,0]` | **degrees**, Euler XYZ |
+| `scale` | `[1,1,1]` | |
+| `visible` | `true` | hides the whole subtree's rendering |
+
+### `MeshInstance3D`
+| Prop | Default | Notes |
+|---|---|---|
+| `mesh` | `"box"` | `box \| sphere \| capsule \| plane \| cylinder \| gem` — `gem` is a faceted crystal (icosahedron); with `material.flatShading: true` + low `roughness` it reads as a sparkling jewel (spin/tumble it for the sparkle) |
+| `size` | `[1,1,1]` | box: extents · sphere/gem: radius = x · capsule: radius = x, height = y · plane: x·z ground (laid FLAT on XZ) · cylinder: radius = x, height = y |
+| `material` | `{}` | `{color: '#hex', metalness: 0..1, roughness: 0..1, opacity: 0..1, wireframe, flatShading, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `map`/`normalMap` are texture URLs (lazy-loaded, headless-safe; map samples sRGB, normalMap linear), tiled `repeat` times across each face — box/plane UVs span 0..1 per face, so for worldspace density use `repeat: [length/tile, height/tile]` (e.g. a 6×2.5 m brick wall at one tile per 2 m → `[3, 1.25]`). `color` tints the map (near-white keeps the texture's own color). NB: under ACES a very bright `emissiveIntensity` blows out to white — keep it modest (~1–2) + a saturated color for a vivid GLOWING look. Unknown keys, malformed `repeat`, or `repeat` without a map hard-fail at load |
+| `castShadow` / `receiveShadow` | `false` | |
+
+### `Camera3D`
+`fov: 60`, `near: 0.1`, `far: 1000`, `current: false`.
+Mark exactly ONE camera `current: true` (otherwise the first camera in tree order is used).
+Aspect ratio is automatic. To frame an origin-centered scene, a good default is
+`position: [7, 6, 9]`, `rotation: [-26, 36, 0]`.
+
+### Lights
+- `DirectionalLight3D` — `color: '#ffffff'`, `intensity: 1`, `castShadow: false`.
+  Sun-style; its `position` sets the incoming direction (it aims at the origin).
+  Shadow knobs: `shadowArea` (half-extent of the shadow box, default ±75),
+  `shadowMapSize` (default 2048), and `shadowFollowsCamera` (default false). In a
+  big roaming world a fixed shadow box must be huge → low-res → the player's own
+  shadow nearly vanishes; set `shadowFollowsCamera: true` with a SMALL `shadowArea`
+  (~60–80) so the box tracks the camera and contact shadows stay crisp everywhere.
+- `OmniLight3D` — `color`, `intensity` (physical units — values like 20–40 are normal),
+  `range` (0 = unlimited).
+
+### Vegetation & water
+
+`Foliage3D` (curved-blade shader grass: clumps, rolling wind, distance LOD,
+character bend), `Flowers3D` (instanced flower PLANTS — stems, leaves,
+multi-petal heads; lush/sparse/none density dial, Voronoi patches),
+`Tree3D` (ez-tree
+groves: branchy trunks + textured leaf billboards — conifer/broadleaf/dead ×
+simple/medium/high cost tiers, count×tris budget-checked at load) and
+`Water3D` (animated plane) dress a level in a handful of nodes. Full prop
+tables and the generator CLI: `incanto-environment.md` (this directory).
+
+### Scene-level `environment` header (not a node)
+```json
+"environment": {
+  "ambient": { "color": "#ffffff", "intensity": 0.45 },
+  "background": "#0e1220"
+}
+```
+Without `ambient`, unlit faces are pitch black — almost always set it (0.3–0.6;
+drop to ~0.15–0.2 when a `sky` provides image-based ambience — see the
+atmosphere recipe below).
+
+## Composition rules
+
+- Group moving parts under a plain `Node3D` pivot and rotate the pivot — children inherit
+  the transform (a spinning `Pivot` parent makes child meshes orbit — no math in scripts).
+- Plain `Node` (non-3D) children are fine anywhere; they're transparent to rendering
+  (their 3D descendants attach to the nearest `Node3D` ancestor).
+- Mutate node props (plain JSON values) — never touch three.js objects. The renderer
+  pushes props each frame. Replace arrays whole (`node.rotation = [0, a, 0]`) or mutate
+  in place; both work.
+
+## Reference example
+
+A minimal 3D scene — ground plane + 3 orbiting primitives + sun +
+lamp + camera, verified rendering. Copy it as a starting point.
+
+## Atmosphere (sky, fog, shadows, exposure)
+
+The whole rendering stage is scene JSON — this is THE recipe that turns a flat
+demo into a commercial-looking outdoor scene:
+
+```json
+"environment": {
+  "sky": { "type": "atmosphere", "elevationDeg": 35, "azimuthDeg": 140, "turbidity": 2.4 },
+  "fog": { "near": 120, "far": 700 },
+  "shadows": true,
+  "exposure": 1,
+  "ambient": { "color": "#ffffff", "intensity": 0.18 },
+  "background": "#9bc4e2"
+}
+```
+
+- `sky` (physical atmosphere, three Sky shader): sun via `elevationDeg`
+  (−90..90 above horizon) + `azimuthDeg` (0 = +Z, 90 = +X) **or** a raw
+  `sunPosition: [x, y, z]` — never both. `turbidity` (haze, 2 ≈ clear day,
+  ~7 dusty) and `rayleigh` (blue scattering, 1 ≈ earth). Defaults are a
+  pleasant mid-morning. The sky does three jobs at once: backdrop, PBR
+  image-based ambience (PMREM, regenerated only when the sky changes), and the
+  scene's unified SUN — it aims the main `DirectionalLight3D` (highest
+  intensity; lights are never auto-created) and feeds `Water3D` /
+  `Foliage3D` `sunDirection` uniforms while those props sit at their defaults
+  (an explicitly authored prop wins).
+- `fog`: linear `THREE.Fog` — `{ color?, near?, far? }` meters. Without
+  `color` under a sky, a horizon-ish haze is derived from the sky itself.
+  Water and mesh-grass shaders fog identically to standard materials.
+- `clouds`: a VOLUMETRIC cloud deck — the renderer raymarches a world-space
+  altitude slab and composites real, parallax-correct clouds you fly through
+  (a fullscreen pass, like the underwater caustics — no node, no geometry).
+  `{ coverage?, density?, base?, top?, color?, shadeColor?, speed?, scale? }`:
+  `coverage` 0..1 (how much sky is cloudy, ~0.5), `density` optical thickness
+  (~1–2.2), `base`/`top` the deck's world-Y band (e.g. 95→340 — cruise above
+  it and dive through), `color` sunlit + `shadeColor` shaded underside, `speed`
+  wind drift, `scale` feature size in world units (~230, bigger = larger soft
+  masses). Lit by the scene sun; melts into the `fog` color at distance. COST:
+  one extra fullscreen pass per frame — keep `Water3D` at `quality:"simple"`
+  (zero re-renders) when pairing with clouds to hold 60fps. Absent = zero cost.
+  Ideal for flight/sky scenes; see `examples/dogfight-3d`.
+- `shadows`: `true` | `false` | `{ "mapSize": 1024|2048, "radius": n }`.
+  Truthy makes the main DirectionalLight cast (PCF soft, terrain + trees +
+  meshes cast/receive, mesh grass RECEIVES only). One static ortho box (±75 m
+  default; lights with `castShadow`+`shadowArea` keep their own) — no
+  cascaded shadow maps yet, so giant worlds get soft, not razor, shadows.
+  `false` force-disables shadow maps.
+- `exposure`: ACES filmic tone mapping is always on (exposure 1 default) —
+  raise/lower for bright beach vs moody dusk.
+- `iblIntensity`: multiplies the sky's image-based ambient fill (≥0, default
+  1; the sky base is 0.55). Lower it (~0.5) for a hot-sun-vs-small-ambient
+  stage that carves a deep shadow side on crowns — the "moody" look — while
+  a higher exposure keeps the lit side bright.
+- All keys hard-validate at apply time with errors listing valid options;
+  scenes without them render exactly as before (flat `background`, no fog).
+- Sun balance that reads well under ACES + sky ambience: sun intensity
+  ~1.5–2, ambient ~0.15–0.2 (a strong flat ambient washes shadows out).
+- `runGenerator('terrain', …)` worlds: pair with `terrainEnvironment(theme)`
+  from `incanto/env` — the themed sky/fog/shadows header in one call.
+- `runGenerator('maze', …)` likewise pairs with `mazeEnvironment(theme)` —
+  a moody low-sun/fog grade (dungeon stone, overcast hedge, dusk canyon).
+
+## HDRI environments (image-based lighting)
+
+`environment.preset: "sunset"` (any drei preset name: apartment/city/dawn/
+forest/lobby/night/park/studio/sunset/warehouse) or `environment.hdri: <url>`
+loads an equirect HDR for lighting/reflections; add `"skybox": true` to also
+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
+
+```ts
+import { assetUrls, preloadUrls } from 'incanto';
+await preloadUrls(assetUrls(sceneJson.assets), (done, total) =>
+  bar.style.width = `${(done / total) * 100}%`);
+```
+Warms the HTTP cache before the engine starts; failures warn, never block.
+
+## Particles
+
+`Particles3D` mirrors `Particles2D` (same presets — `fire`, `explosion`,
+`magic`… and the same one-shot `rate: 0` + `burst` → `finished` pattern) as
+point sprites in meters: preset distances auto-scale ÷100 (presets are authored
+in 2D px). See incanto-building-2d-games for the full prop list.
+
+Points render through a built-in soft sprite with a SOLID opaque core (not hard
+squares), so colours read even at small sizes, and `'normal'` blend fades cleanly
+to transparent (per-particle RGBA alpha). `paletteColors` (per-particle
+multi-colour) + `shimmer` (per-particle twinkle) work in 3D too — see the 2D skill.
+
+- **Size gotcha:** on-screen size is `(sizeStart + sizeEnd) / 2 ÷ 100` meters
+  (sizeAttenuation), so the 2D-px `custom` defaults (8/2 → 0.05 m) are
+  near-invisible a few meters away — author sizes in the TENS (e.g. 64/14 → ~0.4 m).
+- **Blend vs backdrop:** `'add'` only GLOWS over a DARK backdrop; over a BRIGHT
+  scene (daylight grass) it washes to white — use `'normal'` (opaque) for colourful
+  daytime particles.
+- **VFX over grass / transparent scenery — raise `renderOrder` (e.g. 100).**
+  Foliage3D grass is a TRANSPARENT material (renderOrder ~2) drawn LATER in the
+  transparent pass, so a default particle (renderOrder 0) gets painted OVER even
+  when geometrically ABOVE the blades — it's draw ORDER, not depth (so toggling
+  `depthTest` does nothing about it). `renderOrder:100` draws the VFX after the
+  grass; that alone fixes it. Leave `depthTest` at its default `true` so the VFX is
+  still correctly hidden by SOLID objects (tree trunks, the player). Only set
+  `depthTest:false` for a deliberately always-on-top effect (it then draws through
+  solid cover too).
+
+A celebratory FIREWORK: a few stacked one-shots choreographed by their lifetimes —
+a brief BIG white flash (`blend:'add'`, the pop), a multi-jewel confetti shell
+(`blend:'normal', burst:60, speed:[150,360], drag:1.9, sizeStart:96/sizeEnd:22,
+paletteColors:[…saturated…], shimmer:8`), a lingering ember glitter
+(`blend:'normal', gravity:[0,0], shimmer:5`) — all bursting UP (`directionDeg:-90,
+spreadDeg:180`) with `renderOrder:100`, each parented to a stable
+node (NOT the collectible's container), self-removing on `finished`.
+
+## Terrain
+
+`Terrain3D` is procedural heightfield terrain with biome texture splatting —
+one node, themed (`island`/`alpine`/`plains`/`desert`/`custom`), deterministic
+from a `seed`, with `heightAt(x, z)` for spawning/placement and a
+`{shape: 'heightfield'}` collider recipe (Terrain3D as the CHILD of a
+`StaticBody3D`). Full themes table, custom layer format and the water/beach
+pairing live in the **incanto-environment** skill.

package/skills/incanto-editor.md

@@ -0,0 +1,163 @@
+---
+name: incanto-editor
+description: The visual scene composer shipped in the incanto package — bunx incanto-editor serves a page that renders a scene with the installed engine, lets you compose nodes and edit every prop, saves back to the file, and speaks a postMessage protocol for iframe embedding. Use when the user wants to visually arrange or tweak a scene, or when integrating the editor into a host service.
+---
+
+# Scene Editor
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+## Launch
+
+```bash
+bunx incanto-editor                          # PROJECT mode: discovers every *.scene.json
+bunx incanto-editor src/game.scene.json      # SINGLE mode: one fixed file
+bunx incanto-editor level.scene.json --output build/level.scene.json --port 5179 --host 0.0.0.0
+```
+
+**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.
+
+Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
+
+- **Explorer** — two collapsible sections: **ASSETS** on top (icon rows by
+  type; keys with a `group/` prefix nest under collapsible folders (any depth),
+  each showing its recursive asset count — refs are `$group/key`; click the
+  icon for a blurb, the row to edit in the inspector; DRAG asset rows onto a
+  folder (or the section background = root) to move them — references rewrite
+  automatically, as they do when a group is renamed; the folder button creates
+  a group, and deleting a non-empty group asks first) and the
+  **SCENE tree** below — type icons left of each name (click one for a balloon
+  explaining the type), chevron collapse/expand with depth guide lines,
+  ctrl/cmd-click **multi-select**, and **drag-and-drop restructuring**: drop ONTO
+  a row to make the dragged node(s) its children, drop on a row's top/bottom edge
+  to reorder before/after. Dragging a selected row moves the whole selection.
+  Illegal drops (engine rules — e.g. a CharacterController2D outside a
+  CharacterBody2D) are ROLLED BACK entirely with the error in the banner; the
+  tree never shows a state the engine would reject. Right-click for
+  duplicate / rename (or double-click the name) / cut / copy / paste-as-child /
+  delete — all act on the multi-selection. `+` adds a child of any registered
+  type, `✕` deletes the selection. Selecting the ⚙ scene row edits the header
+  (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.
+  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
+  cube tips (center = uniform); right-dragging a handle scales in any mode.
+  **Esc cancels the drag in progress** and reverts the value; **hold Shift to
+  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
+  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
+  registered node types appear automatically. Edits re-validate through the real
+  loader: hard `IncantoError`s appear in a banner. Validation is STRUCTURE-level —
+  physics semantics are checked when physics actually runs.
+- **Inspector** — schema-driven from the node registry, with STRUCTURED editors for
+  the hard parts: `collider` (shape dropdown + per-shape dimensions, mirrored by
+  the wireframe), `network` (mode dropdown + sync-key chips + throttle),
+  `script` (attach/detach + name + props, with copy-paste Behavior boilerplate in
+  its help), `groups` (tag chips). Every one has a `?` help popover with examples.
+  Values equal to the default are removed (delta-only, like the serializer).
+
+**3D scenes** get full camera navigation: drag orbits, right/middle/Shift-drag pans,
+wheel zooms, `F` frames the contents, and **`0` / the `game cam` button** returns to the
+GAME's own camera — exactly what running the scene shows (the free camera re-syncs so
+the next drag continues from there). A clickable ORIENTATION GIZMO (top right): the filled
+X/Y/Z handles snap to right/top/front views, hollow ones to the opposite sides. The
+hint bar swaps to the camera controls. AMBIENT VISUALS preview LIVE while logic time
+stays frozen: ModelInstance3D plays its `animation`, Particles2D/Particles3D emit,
+Water3D waves bob, Foliage3D sways — behaviors, physics and timers still wait for
+play. The inspector suggests model/animation values from the scene's assets (plus
+embedded clip names).
+
+**▶ Play** runs the scene AS COMPOSED in the same pane: physics enabled, keyboard
+attached, CharacterController2D and every engine-native feature live — tune a
+collider or gravity, hit play, feel it, Esc back, keep editing. Game `script`s and
+their signal wiring run only in your real game (a notice says so while simulating).
+
+A **docs** button opens the in-editor node documentation: an overview of how
+Incanto scenes work plus a tab per category with a detailed entry and live
+props table for every node type — in English AND Korean (the 한/EN toggle also
+localizes the inspector's help popovers and type balloons; values stay English).
+
+Node types are FIXED once created (retyping would smuggle children past
+parent rules) — but the ROOT is deletable like any node: the scene goes
+empty and the next node added becomes the new root. The add-node dropdown
+leads with the scene's dimension (3D defaults to MeshInstance3D) and
+DISABLES types the engine would reject at the current target — probed by
+validating a candidate scene, so any loader rule (e.g. CharacterController2D
+needs a CharacterBody2D parent) is honored automatically, for children and
+for root candidates alike.
+
+Every node carries an immutable `uid` (assigned at creation; legacy scenes are
+backfilled when opened) shown read-only above the name — click to copy. Saved
+files are formatted biome-compatibly (80-col inline-when-fits), so saving from
+the editor never breaks `pnpm lint`.
+
+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).
+
+## Generate environments
+
+The **✦ button** beside the add-node controls opens the Generate dialog — the
+`incanto/env` generators inside the editor, driven by the same `GENERATORS`
+catalog as the `incanto-env` CLI and filtered to the open scene's dimension
+(3D: arena, terrain, meadow, forest, maze, rocks, clouds, island; 2D:
+platforms2d, maze2d, dungeon2d). The param form is built from the catalog
+metadata — numbers clamp to their min/max, option lists become dropdowns — so
+a new generator needs zero editor changes. The seed starts random (↻ rerolls);
+the same seed always generates the same level. **insert** runs the generator
+and splices the subtree under the selected node (the root when nothing is
+selected) through the normal validated path: sibling names uniquify, every
+node gets a fresh uid, the whole insert is ONE undo step, and the new subtree
+arrives selected in the tree. Esc / backdrop / ✕ dismiss the dialog.
+
+## Embedding (host frontends / agent8 containers)
+
+Run the CLI inside the container (`--host 0.0.0.0`), iframe the served URL — the same
+flow as a build preview. **The iframe URL must carry the host's origin**:
+
+```html
+<iframe src="http://<container>:5179/?parentOrigin=https://your.app"></iframe>
+```
+
+Messages are posted ONLY to that pinned origin (never `*`); without the param an
+embedded editor posts nothing. The page posts to its parent window:
+
+```ts
+{ type: 'incanto-editor:ready',  input, output, version }   // input/output null until a scene opens (project mode)
+{ type: 'incanto-editor:open',   input, output }             // a scene was opened/switched (project mode)
+{ type: 'incanto-editor:change', dirty }                    // Save-button state
+{ type: 'incanto-editor:save',   input, output, data }      // data = full scene JSON
+{ type: 'incanto-editor:error',  message }                  // loader/save errors
+```
+
+The page can never choose filesystem paths — `input`/`output` are fixed at launch;
+the API only reads the input and writes the output. Saves are rejected (422, file
+untouched) unless the body is scene-shaped (`format: 1`, `type: "scene"`, `name`,
+`root`). On the default loopback bind, non-loopback `Host` headers are rejected
+(DNS-rebinding defense) and cross-origin writes are refused; `--host 0.0.0.0`
+trusts the surrounding network — use it only inside containers.
+
+## Scope
+
+The EDIT view freezes game time — nothing falls or fires until you press play;
+only ambient visuals (model animations, particles, water, foliage sway) keep
+moving. The PLAY view simulates everything engine-native but cannot execute the
+game's TypeScript behaviors. 3D scenes render and edit via the inspector; direct
+viewport manipulation is 2D-only for now. Runtime-injected textures (asset URLs
+like `"GENERATED_AT_RUNTIME"`) render as a magenta checkerboard — position/size
+stay visible; the real art appears in the running game.