incanto 0.1.0

package/skills/README.md

@@ -0,0 +1,9 @@
+# incanto skills (shipped)
+
+Full agent skills for building games with this **installed version** of Incanto.
+An AI agent should start with `incanto-scene-json-authoring.md`, then the domain skill
+for the task at hand. `incanto-node-reference.md` (+ `../schemas/scene.schema.json`)
+is generated from the engine source and lists every node type, prop, and default.
+
+These files are the source of truth; the thin platform-delivery entries live in the
+repo's root `skills/` folder and merely point here.

package/skills/incanto-3d-character.md

@@ -0,0 +1,229 @@
+---
+name: incanto-3d-character
+description: The 3D character stack — CharacterController3D (floating-capsule movement with sprint/jump/fall tuning and an animation-driving movement state) and its camera rigs (free orbit / first person / quarter / side). Use when building any playable 3D character.
+---
+
+# 3D characters: CharacterController3D
+
+One node turns a dynamic body into a playable character with a camera:
+
+```json
+{
+  "name": "Player", "type": "RigidBody3D",
+  "props": { "fixedRotation": true, "friction": 0,
+             "collider": { "shape": "capsule", "radius": 0.32, "height": 0.96 } },
+  "children": [
+    { "name": "Controller", "type": "CharacterController3D",
+      "props": { "view": "free", "camDistance": 4 } },
+    { "name": "Skin", "type": "ModelInstance3D",
+      "props": { "model": "$avatar", "targetHeight": 1.6 } }
+  ]
+}
+```
+
+MUST sit under a dynamic `RigidBody3D` (hard error otherwise) with a capsule
+collider and `fixedRotation: true`. Set **`friction: 0`** on that body — the
+character rides the hover spring, not floor contact, so friction would just brake
+movement. Declare `move` (vector2) / `jump` /
+`sprint` actions in the scene input map, and call
+`engine.input.attachPointer(canvas, { lockOnClick: true })` for mouse look.
+
+## Movement model (vibe-starter-3d parity)
+
+Impulse-based on the dynamic body: target speed = `maxSpeed ×
+(1 + (sprintMultiplier−1)·intensity)` where keyboard intensity is 0.6
+(any move key) or 1.0 (+sprint). Defaults: maxSpeed 2.5, sprint ×2 → walk
+≈4 m/s, sprint ≈5 m/s. `jumpVelocity` 4 (+20% at full sprint), falls get
+gravityScale 2.5 with a −20 m/s terminal clamp, and a hover spring holds the
+capsule BOTTOM `floatHeight` above the ground (5-ray probe). Author the Skin
+y-offset as `-(halfHeight + radius + floatHeight)` so the feet sit at the
+capsule bottom (the example templates do this).
+
+## Views
+
+| view | what it does | key props |
+|---|---|---|
+| `free` | third-person orbit, mouse yaw/pitch, camera-relative WASD | `camDistance` (4), `pitchMin/Max` |
+| `firstPerson` | camera at the eye (`eyeHeight` 0.64), pointer-lock look | `camDistance` ~0.01 |
+| `quarter` | fixed isometric pitch 35.264°, NO mouse look | `camDistance` 40, `mouseLook: false` |
+| `side` | camera at +z `camDistance`, lock movement to ±x | `mouseLook: false` |
+
+The controller drives the scene's `current` Camera3D every frame (smoothed).
+Wheel zooms only when `zoomMax > zoomMin`.
+
+In `free` view the camera AIMS at the character every frame (`lookAt`), so the
+character stays centered even while the camera is catching up or pulled in by a
+collision — no jitter.
+
+**Camera collision (spring arm).** For the orbit views (`free`/`quarter`/`side`)
+the camera won't clip through walls or the ground: each frame it raycasts from
+the eye toward the camera and, if a collider blocks the boom, smoothly pulls the
+camera in front of it (plus a ground backstop so it never drops below the floor).
+This is on by default (`cameraCollision: true`); set it `false` to get the old raw
+orbit. Only the STATIC/fixed world stops it — give walls/floors/terrain a
+`StaticBody3D` collider (collider-less meshes are invisible to the ray, same as to
+the player). MOVABLE bodies are ignored on purpose: both dynamic ones (projectiles,
+`RigidBody3D`) and kinematic ones (enemies/NPCs are `CharacterBody3D`), so a passing
+enemy never yanks the camera in. `firstPerson` skips it (the camera is at the eye).
+
+## Animations
+
+`controller.state` is `idle | walk | run | fastRun | airborne`; the
+`movementStateChanged` signal fires on transitions — map states to clips
+(`$animation` assets retarget onto VRM automatically):
+
+```ts
+controller.on('movementStateChanged', (state) => {
+  skin.animation = { idle: '$idle', run: '$run', fastRun: '$runFast',
+                     airborne: '$jump', walk: '$walk' }[state];
+});
+```
+
+Setting `animation` to a new clip **crossfades** (0.2s blend) from the current
+one — idle↔walk↔run↔jump transitions are smooth, not a hard cut.
+
+## Reskin one model with `tint` (many variants from one GLB)
+
+`ModelInstance3D` has a `tint` prop (hex, `""` = off) that MULTIPLIES into every
+material — turn the one base humanoid into a whole cast WITHOUT extra assets: a
+sickly-green zombie, a blue ally, a red boss. It clones each material per instance
+(the shared source is never mutated, so the player stays untinted) and preserves the
+texture/shading detail (it's a multiply, not a flat repaint). Pair it with a
+shambling clip + glowing eyes for an enemy that reads as a different creature.
+
+```json
+{ "name": "Skin", "type": "ModelInstance3D",
+  "props": { "model": "$avatar", "targetHeight": 1.7, "tint": "#5f8f4a",
+             "animation": "$walk", "castShadow": true } }
+```
+
+The controller also yaw-rotates the sibling at `skinPath` ('../Skin') toward
+the move direction at `turnSpeed` rad/s (100 = instant snap) — the body
+itself never rotates. The skin MOUNTS at 180° (facing away from the default
+camera, original parity) and then faces wherever it moves; `skinYawOffset`
+adds a correction for models whose native forward is not +z.
+
+## Facing a direction in 3D — the +Z-FORWARD rule (read before turning ANY skin)
+
+This trips people up REPEATEDLY, so here is the one rule. agent8's `base-model` (and
+any model you give `skinYawOffset: 0`) is **+Z-FORWARD**: its face looks down +Z at
+rotation 0. To turn it to face a world heading `(dx, dz)`:
+
+```ts
+const dx = targetX - selfX; // heading you want to face: movement delta, OR (target - self)
+const dz = targetZ - selfZ; // 3D ground plane: x and z (index 0 and 2), NEVER y
+skin.rotation = [skin.rotation[0], Math.atan2(dx, dz) * RAD2DEG, skin.rotation[2]];
+// RAD2DEG = 180/Math.PI ; rotations are DEGREES, Euler XYZ
+```
+
+That is the EXACT formula `CharacterController3D` uses for move-facing
+(`atan2(mx, mz) + skinYawOffset`). Do NOT add 180° to it.
+
+**Same formula to LOOK AT / AIM at any target** (turret, NPC turning to face the player,
+an enemy that idles facing you): use the direction from self TO the target —
+`dx = target.position[0] - self.position[0]`, `dz = target.position[2] - self.position[2]`,
+then `rotation[1] = atan2(dx, dz)*RAD2DEG`. Movement-facing is just this with the
+target being "where I'm walking." There is ONE facing formula; only the direction differs.
+
+- **The 180° is NOT a facing formula.** It is only the AT-REST MOUNT — the character
+  starts turned away from the behind-the-shoulder camera until it first moves. Adding
+  180° to *move-facing* makes the character run BACKWARDS (it shows you its back while
+  charging at you). That is the #1 recurring bug when driving a custom enemy/NPC skin.
+- **Don't hand-mix conventions.** `Shoot.faceAim` looks like it omits the 180 because
+  its input is a camera *look* vector that already encodes it — a different context.
+  For a MOVEMENT/heading vector, the answer is plain `atan2(dx, dz)`, full stop.
+- **Model not +Z-forward?** Don't guess a 90/180 — set `skinYawOffset` (controller) or
+  add the same constant to your `atan2`, then verify.
+- **ALWAYS verify facing — never ship it on reasoning alone.** In the browser, the
+  decisive check is a dot product: the skin object's world **+Z basis** (matrixWorld
+  columns `[8],[10]` = its front in x,z) dotted with the unit direction it should face
+  must be ≈ **+1** (−1 means it's backwards). Or just look: a charging enemy must show
+  its FACE, not its back. (Headless, no three.js: with the yaw you set, the model's
+  forward is `(sin(yaw), cos(yaw))`; dot it with the desired unit dir — `< 0` = wrong way.)
+
+**NON-player models (enemies/NPCs) face + animate via the SAME rules, by hand.**
+`CharacterController3D` automates this for the player; a custom-driven model does it
+itself — face with the formula above, and drive `skin.animation` from your AI state (see
+incanto-gameplay-behaviors.md "Driving a model's animation from a custom AI"). Ground a
+moving non-controller body yourself — it won't auto-fall (see incanto-3d-models.md
+"Grounding a model").
+
+Mouse look is GATED: deltas only accumulate while pointer-locked or a
+button is held — a free-roaming cursor never spins the camera. Vertical look is
+STANDARD (non-inverted): mouse UP looks up (in free view the camera swings down so
+it looks up at the character against the sky), mouse DOWN looks down.
+
+## First-person weapon viewmodel + the tracer-from-the-muzzle rule
+
+A weapon VIEWMODEL is just a `MeshInstance3D`/group child of the **root** `Camera`
+(`/root/Camera/Gun`) — it rides the view for free. Pose it each frame in your Shoot
+behavior and add a recoil impulse on fire (kick back +z, flip up −x, ease back); pulse a
+barrel `OmniLight` for the muzzle flash. Size it for the near plane: a 0.46 m body at
+0.5 m with fov 80 fills half the screen (it's viewed broadside), so keep viewmodel meshes
+small (~0.3 m) and tucked lower-right.
+
+**The tracer must visibly fly FROM the muzzle TO the target.** This recurred many times;
+there are TWO independent things to get right — the START POINT and the ROD ORIENTATION:
+
+**(1) Start at a real muzzle NODE.** Put a tiny `Node3D` (`Muzzle`) at the front-centre
+of the barrel mesh (the barrel cylinder's tip), as a child of the gun so it rides the
+view + recoil. Read ITS world position each shot — that IS where the muzzle is on screen,
+at any aim angle:
+
+```ts
+// muzzle = /root/Camera/Gun/Muzzle ; o = muzzle._ensureObject3D()
+o.updateWorldMatrix(true, false);
+const e = o.matrixWorld.elements;
+const from = [e[12], e[13], e[14]];               // tracer ORIGIN = the barrel tip
+```
+
+Never reconstruct the muzzle from `eye + camera-basis × offset` (it drifts from the
+rig-driven camera, and the camera `right` basis is easy to invert — correct is
+`[-fwd.z, 0, fwd.x]`). The node's matrix is the one source of truth.
+
+**(2) `end` is the TARGET, and orient the rod with the CORRECT Euler.** Draw the tracer
+from `from` to the hit point (enemy torso, or `eye + fwd*range` if you missed) — a line
+muzzle→target converges on the crosshair. A streak parallel to camera-forward (offset
+from the muzzle) never converges and looks like it fires off to the side.
+
+The rod is a +Z-stretched box; orienting it is the subtle trap. `Node3D` rotation is Euler
+order **XYZ**, whose +Z basis column is `(sin ry, −sin rx·cos ry, cos rx·cos ry)`. So to
+aim the rod's +Z along unit `(Dx,Dy,Dz)`:
+
+```ts
+const ry = Math.atan2(Dx, Math.hypot(Dy, Dz));    // NOT atan2(dx, hypot(dx,dz))
+const rx = Math.atan2(-Dy, Dz);
+t.rotation = [rx*RAD2DEG, ry*RAD2DEG, 0];
+```
+
+The "obvious" `[-atan2(dy, hypot(dx,dz)), atan2(dx,dz), 0]` is only correct for a LEVEL
+shot — for XYZ order the yaw denominator must be `hypot(Dy,Dz)`, not the ground `hypot(dx,
+dz)`. With the wrong form the rod skews off-axis when you aim up/down, so its near end
+drifts AWAY from the muzzle (the box is centred on the midpoint, so a tilt swings both
+ends). THIS — not the start point — was the actual "fires from the centre" bug; moving
+the origin around never fixed it.
+
+**Verify by MEASUREMENT, not eyeballing.** In the browser, project the muzzle node's world
+position and the rod's two endpoints to screen with the camera matrices, and assert: near
+end ≈ muzzle (a few px), far end on the crosshair, and `rodAxis · (target−muzzle) ≈ 1`.
+Do it at a steep look-DOWN angle (a level shot hides the skew because gun and centre
+overlap). Pitch sign gotcha when scripting the aim: `fwd.y = −sin(pitch)`, so to aim DOWN
+pitch is POSITIVE.
+
+**Make it THIN and make it FADE.** A hitscan tracer lives in WORLD space, so a thick,
+opaque, long-lived rod looks like a "wooden stick" left hanging beside you when you fire
+while moving (the camera moves, the rod doesn't). Keep the cross-section tiny (~0.02 m), a
+white/bright emissive (reads as light, not lumber), and FADE its opacity to 0 over a short
+life (~45 ms): each frame set `tracer.material.opacity = start * remain / life` — `syncTree`
+re-applies `material.opacity` every frame, so mutating the node's material prop just works.
+A snappy fading flash never reads as a stationary plank.
+
+**Best feel for a hitscan shot = a muzzle FLASH + a SHORT dash, not a full beam.** A rod
+spanning the whole muzzle→target distance (often tens of metres) is the worst "stick"
+offender. Instead: (1) pop a tiny `Particles3D` burst at the muzzle each shot — `burst`
+~14, `spreadDeg 360` (a 3D sphere; Particles3D sets `spreadZ`), `lifetime [0.05,0.16]`,
+high `drag` so it's a tight pop, `blend:'add'`, `depthTest:false` so the gun doesn't occlude
+it — that's the "shot bursting" punch the player reads as firing; and (2) cap the tracer to
+a SHORT segment (~2.5 m) anchored at the muzzle (`centre = from + dir*seg/2`, `size.z = seg`,
+`min(fullDist, TRACER_LEN)`), not the full distance. The flash sells the shot; the impact is
+sold by the hitmarker + a death burst at the target — the streak doesn't need to reach.

package/skills/incanto-3d-models.md

@@ -0,0 +1,151 @@
+---
+name: incanto-3d-models
+description: Loading GLB/glTF and VRM models in Incanto — the ModelInstance3D node, declaring model assets, sizing with targetHeight, playing embedded animations, and the incanto-model CLI that reports a file's hierarchy/bounding box/animations so you can place it correctly. Use when putting 3D model files into a scene.
+---
+
+# 3D Models (GLB · glTF · VRM)
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+## ALWAYS inspect before you place
+
+A file name tells you nothing about a model's size or contents. The package ships an
+inspector — run it FIRST and read the numbers:
+
+```bash
+bunx incanto-model public/models/knight.glb
+#   size:   1.1 × 1.8 × 0.6  center: [0, 0.9, 0]     ← stands 1.8 units tall
+#   anim Idle: 2.4s
+#   anim Run: 0.8s                                       ← exact clip names for `animation`
+bunx incanto-model avatar.vrm --json                   # full machine-readable report
+```
+
+The report gives you: the TRANSFORMED scene bounding box (size/center/min/max — skinned
+meshes measured in bind pose), the node hierarchy, per-mesh vertex/triangle counts,
+animation clip names + durations, materials/textures/skins, and for VRM the avatar
+meta (name/authors) + humanoid bone count. Decision rules:
+
+- **size.y** tells you the model's natural height → pick `targetHeight` (characters in a
+  meters-scale scene: 1.6–1.9) or leave 0 and use the node's `scale`.
+- **center** ≠ [0,0,0] means the model is off-origin — compensate with the node `position`
+  (a center.y of half the height usually means feet at origin: good).
+- **animation names** are exact strings for the `animation` prop.
+
+## Scene JSON
+
+```json
+"assets": {
+  "knight": { "type": "model", "url": "/models/knight.glb" },
+  "avatar": { "type": "model", "url": "/models/avatar.vrm" }
+},
+"root": { "name": "World", "type": "Node3D", "children": [
+  { "name": "Knight", "type": "ModelInstance3D",
+    "props": { "model": "$knight", "targetHeight": 1.8, "animation": "Idle",
+               "position": [0, 0, 0], "castShadow": true } },
+  { "name": "Sun", "type": "DirectionalLight3D", "props": { "position": [3, 5, 4] } },
+  { "name": "Cam", "type": "Camera3D", "props": { "position": [0, 2, 6], "current": true } }
+] }
+```
+
+`ModelInstance3D` props: `model` (`$key` or a direct URL), `targetHeight` (>0 uniformly
+scales so the bounding box stands that many units tall — composes with the node `scale`,
+reactive at runtime), `animation` (see below), `tint` (hex; `""`=off — multiplies into
+every material to RESKIN one shared GLB into many variants, e.g. base human → green
+zombie; clones materials per instance so other instances are untouched),
+`castShadow`/`receiveShadow`, plus the usual Node3D transform.
+
+**`targetHeight` + skinned rigs (the implausible-scale warning).** Mixamo-style humanoid
+rigs hide their true size behind a ~0.01 armature scale + bone-driven vertex scaling, so
+a bounding box can't measure them. If `targetHeight` would imply a scale `<0.05×` or
+`>20×`, the engine WARNS and renders at the model's authored (1×) scale instead — this is
+EXPECTED and fine: humanoid GLBs already ship at ~1.6–1.9 m, so they look right at 1×.
+Don't fight the warning. If a NON-humanoid (a 1:100 prop) really is mis-sized, use the
+node `scale` instead of `targetHeight`. Always `bunx incanto-model <file>` first to see
+the real `size.y`.
+
+## Grounding a model on the floor / terrain
+
+A model's feet sit at the model's OWN origin, which is usually `y=0` but not always —
+`bunx incanto-model` reports `center.y`. Two cases:
+
+- **Static placement:** set the node's `position[1]` so the feet rest on the ground
+  (e.g. on a Terrain3D, `position[1] = terrain.heightAt(x, z)`; offset by `-center.y`
+  if the model's origin isn't at its feet).
+- **A MOVING body driven by a custom AI (enemy/NPC) — IT WON'T AUTO-FALL.** A
+  `CharacterBody3D`/`RigidBody3D` whose position you set every frame from script is
+  effectively kinematic: nothing integrates gravity, so it floats at its spawn height.
+  Ground it yourself in the behavior's `update()`:
+
+  ```ts
+  // keep the husk on the rolling terrain every frame (AI moved only x/z)
+  const t = this.node.getRoot().getNodeOrNull('World/Terrain/Ground/Surface'); // your Terrain3D
+  if (t) { const p = body.position; body.position = [p[0], t.heightAt(p[0], p[2]) + footLift, p[2]]; }
+  ```
+
+  `heightAt(x, z)` takes WORLD x/z and returns the WORLD surface y. (`incanto/gameplay`
+  movement behaviors like `ZombieAI` deliberately move only in the ground plane and leave
+  the up axis to you, exactly so you can ground it like this — or let real physics do it.)
+
+## Troubleshooting a 3D model
+
+| Symptom | Likely cause → fix |
+|---|---|
+| Faces sideways/backwards | Wrong yaw — see incanto-3d-character.md "+Z-FORWARD rule" (don't add 180° to move-facing; use `skinYawOffset` for non-+Z models). |
+| Giant / tiny | `bunx incanto-model` → read `size.y` → set `targetHeight` to your scene scale. Implausible-scale warning on a humanoid? Accept it (renders at 1×). |
+| Floats / sinks | Origin offset (`center.y`) or an AI-driven body that won't fall — ground it (above). |
+| No animation | Clip name typo (match `bunx incanto-model` output EXACTLY, case-sensitive), or the model/asset isn't declared, or you set `animation` before the model finished loading (it applies once ready), or a GLB clip's bone names don't match the model. |
+| Black silhouette | No light — add a DirectionalLight3D or `environment.ambient`. |
+
+## Animation assets — clips as data
+
+Animations are first-class assets: `{type:"animation", url, clip?}` loads a GLB's clips
+INTO MEMORY (never drawn). `animation` then accepts either an EMBEDDED clip name from the
+model file, or an animation-asset reference:
+
+```json
+"assets": {
+  "knight": { "type": "model",     "url": "/models/knight.glb" },
+  "avatar": { "type": "model",     "url": "/models/avatar.vrm" },
+  "run":    { "type": "animation", "url": "/anims/run.glb" }
+},
+…  { "props": { "model": "$knight", "animation": "Idle"  } }   // embedded clip
+…  { "props": { "model": "$avatar", "animation": "$run" } }    // asset clip
+```
+
+- GLB models bind asset clips by NODE NAME — the animation file's rig must use the same
+  bone names as the model (e.g. both exported from the same skeleton).
+- **VRM models retarget automatically**: Mixamo-rigged animation GLBs
+  (`mixamorigHips`…) are mapped through the mixamo→VRM humanoid rigmap
+  (rest-pose-compensated rotations, hips height scaling, VRM 0.x axis flips) and played
+  on the VRM's normalized rig. Unmapped bones are logged. This is how you give any VRM
+  avatar a Mixamo walk/run/idle: export the Mixamo animation as GLB (without skin works),
+  declare it as an animation asset, set `animation: "$walk"`.
+- `clip` in the asset declaration selects a clip when the file holds several
+  (default: the first).
+
+Models need LIGHT (standard materials): add a DirectionalLight3D or scene
+`environment.ambient` or you will see black silhouettes.
+
+## How loading works
+
+`Renderer3D` owns an `AssetStore3D` (GLTFLoader + `@pixiv/three-vrm`'s VRMLoaderPlugin).
+Models load async and pop in when ready; every node mounts a skeleton-aware CLONE, so one
+asset can back any number of instances. VRM specifics: 0.x files get their facing fixed
+(`rotateVRM0`), unnecessary vertices removed, skeletons combined.
+
+## In the editor
+
+Declare the assets in the ⚙ scene row (`assets` JSON) — or open a scene that has them —
+and the inspector's `model`/`animation` fields offer DROPDOWN suggestions (model `$key`s;
+embedded clips + animation `$key`s). Selecting an animation plays it LIVE in the edit
+viewport (game-logic time stays frozen; only model animation previews).
+
+## Limits (be honest with users)
+
+- A VRM mounts its source scene: humanoid rig + springbones stay live via `vrm.update`,
+  but ONE node per VRM asset (a second node warns and stays empty). GLB models clone
+  freely.
+- GLB↔GLB cross-file animation needs matching bone names (no generic retargeting);
+  no animation blending yet.
+- Bounding boxes for skinned meshes are bind-pose.

package/skills/incanto-assets.md

@@ -0,0 +1,118 @@
+---
+name: incanto-assets
+description: Where game art comes from in Incanto — the FULL built-in catalog shipped in the package (2D sprites with animations, tilesets, item pickups, effects, AND 3D foliage textures: tree leaves, tree bark, terrain/ground splat textures), how to reference each in scene JSON (the catalog `url` contract), the incanto-assets CLI (list/info/copy), external/MCP-provided asset URLs, art-free prototyping with ColorRect2D and data URIs, and the library sprite-animation JSON convention. Use when a game needs sprites, tiles, models, leaf/bark/terrain textures, or any visual asset.
+---
+
+# Assets — where the art comes from
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+Resolve art in this order: ① built-ins (zero setup) → ② asset MCP servers /
+known URLs → ③ art-free primitives. Never invent asset URLs.
+
+## 1. Built-in assets (in the package)
+
+```bash
+bunx incanto-assets list                  # the full catalog (see categories below)
+bunx incanto-assets info medieval-knight  # description + animation names
+bunx incanto-assets copy medieval-knight --out public/assets
+```
+
+`list --json` prints every entry. Each entry carries a **`url`** — the drop-in
+reference you put in scene JSON so the asset LOADS (the contract, see §1b).
+
+### Categories — the whole built-in set
+
+| kind        | examples                                                      | what they're for                              |
+|-------------|--------------------------------------------------------------|-----------------------------------------------|
+| `character` | `medieval-knight`, `goblin`, `ghost`, `2dbasic`              | animated 2D sprite SHEETS (idle/move/attack…) |
+| `tile`      | `floor00`, `wall00`, `minecraft-tiles`                       | 2D tile textures / tilesheets                 |
+| `item`      | `coin`, `gem`, `gold`, `hp_potion`, `box`, `trap`, `map`, …  | 2D pickup sprites                             |
+| `effect`    | `swoosh`                                                     | 2D effect sprites                             |
+| `foliage`   | `leaves_oak/ash/pine/aspen`                                  | **Tree3D** `leafTexture` (leaf-cluster cutout)|
+| `foliage`   | `bark_oak/birch/pine_{color,normal,roughness}`              | **Tree3D** trunk bark (sampled by default)    |
+| `foliage`   | `ground_grass`, `ground_dirt`, `ground_dirt_normal`        | **Terrain3D** grassland ground textures       |
+| `audio`     | `explosion`, `gold-loot`, `slash`, `heal`, `ui-click`, …    | **AudioPlayer** `src` sound files (see below)  |
+
+### 1b. The `url` contract — referencing each kind
+
+Every catalog entry has a `url` that is directly usable; there are two classes:
+
+- **Foliage (leaves / bark / ground)** — `url` is a hosted image on the agent8 CDN
+  (`agent8-games.verse8.io`, the ONLY sanctioned external host) — the exact texture
+  Tree3D/Terrain3D sample **zero-setup by default**, so a bare node already works.
+  Override only to swap the look; drop a `url` straight into the matching prop:
+
+  ```jsonc
+  // Tree3D — a bare node already loads oak leaves from the agent8 CDN; override
+  // leafTexture only to swap in a different built-in cutout (e.g. ash)
+  { "type": "Tree3D", "props": { "type": "broadleaf",
+      "leafTexture": "https://agent8-games.verse8.io/assets/3D/default/textures/vegetation/ash_color.png" } }
+
+  // MeshInstance3D material — built-in ground/bark color as a map (+ a normal map)
+  { "type": "MeshInstance3D", "props": { "material": {
+      "map":       "https://agent8-games.verse8.io/assets/3D/default/textures/vegetation/ground/grass.jpg",
+      "normalMap": "https://agent8-games.verse8.io/assets/3D/default/textures/vegetation/ground/dirt_normal.jpg" } } }
+  ```
+
+  `Terrain3D.textureBase` is a directory base (`<base>/<layer>.png`), not a
+  single file — leave it at the default agent8 set or point it at your own base.
+
+- **Audio (`kind: "audio"`)** — `url` is `incanto/assets/audio/<file>`, the
+  drop-in for `AudioPlayer.src` (e.g. `"src": "incanto/assets/audio/explosion.mp3"`).
+  For zero-asset sound, prefer the procedural SFX **presets** instead of a file.
+  Full guide: **incanto-audio.md** (presets, AudioPlayer, volume buses).
+
+- **Packaged 2D sprites (character / tile / item / effect)** — `url` is
+  `incanto/assets/<file>` (e.g. `incanto/assets/items/coin.png`). This is the
+  **bundler-import / copy** reference. In a bundler game (vite, the usual target)
+  import it; otherwise `incanto-assets copy` puts the file in your project. These
+  props are `$asset` REFS, not URLs — the url lives in the scene `assets{}` entry:
+
+  ```ts
+  import coinUrl from 'incanto/assets/items/coin.png';
+  // scene assets: { "coin": { "type": "texture", "url": coinUrl } }
+  // node:         { "type": "Sprite2D", "props": { "texture": "$coin" } }
+  ```
+
+  `copy` does this for you and prints the ready-to-paste JSON — for animated
+  sheets it includes the full `animations` map (idle/move/attack…) derived from
+  the sheet metadata. `Sprite2D.texture` / `AnimatedSprite2D.sheet` take a
+  `"$assetKey"` ref (the engine hard-fails on a raw URL).
+
+The scene **composer (incanto-editor)** wires all of this for you: the inspector
+shows an asset PICKER on every texture/sheet/map prop — browse the built-ins by
+name (with kind + description), and picking one inserts the loadable value
+(foliage → the CDN url; 2D sprite → a `$asset` ref + the scene `assets{}` entry).
+
+## 2. External art (asset MCP servers, CDNs, your files)
+
+Any URL works in scene `assets{}` — `{ "type": "spritesheet", "url": "<from
+your asset tool>", "frameWidth": …, "frameHeight": … }`. When an asset source
+hands you a sheet WITH a library-convention animation JSON (`{frame: {width,
+height}, animations: {idle: {start, end, frameRate, repeat}}}`), convert it
+mechanically:
+
+```ts
+import { spriteFromLibraryMeta } from 'incanto/2d';
+const { asset, props } = spriteFromLibraryMeta(animJson, {
+  url: sheetUrl, assetKey: 'hero',
+});
+// asset → scene assets.hero; props → an AnimatedSprite2D's props. Done.
+```
+
+For 3D files, ALWAYS inspect before placing: `bunx incanto-model file.glb`
+(bounds, animations, rig — see incanto-3d-models).
+
+## 3. No art yet? Ship gameplay anyway
+
+- `ColorRect2D` — solid rectangles for paddles/walls/platforms/flashes.
+- `Particles2D` presets — fire/explosion/magic with zero files.
+- `AudioPlayer` SFX **presets** — coin/jump/hurt/explosion/… with zero files
+  (the audio analog; see incanto-audio.md).
+- 1×1 data-URI + `tint` + `scale` on a Sprite2D for anything else;
+  canvas-generated `data:` URLs also work as asset urls.
+
+Swap in real art later by changing ONLY the `assets{}` entry — node props
+stay untouched.