incanto 0.4.3 → 0.6.0

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

@@ -53,7 +53,30 @@ scales so the bounding box stands that many units tall — composes with the nod
 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.
+`metalness`/`roughness` (0..1 overrides applied to EVERY material; `-1`=keep authored —
+low-poly kits usually ship fully rough, so `metalness: 0.6, roughness: 0.25` turns flat
+paint into a glinting clear-coat under the scene's sky IBL; per-instance clones like
+tint), `castShadow`/`receiveShadow`, plus the usual Node3D transform.
+
+## Animating named sub-nodes (wheels, turrets, doors) — `poseNode`
+
+Many GLBs ship articulated parts as NAMED nodes (`bunx incanto-model <file>` lists them —
+e.g. the Kenney vehicles have `wheel-front-left` … `wheel-back-right`). From a behavior,
+rotate one per frame with `poseNode(name, [rxDeg, ryDeg, rzDeg])` (local Euler XYZ):
+
+```ts
+// spin the wheels by travel + steer the fronts (Kenney car GLB)
+const model = car.getNodesByName('CarModel')[0] as ModelInstance3D;
+this.spin += this.speed * dt * 60; // degrees of roll
+for (const w of ['wheel-back-left', 'wheel-back-right'])
+  model.poseNode(w, [this.spin, 0, 0]);
+for (const w of ['wheel-front-left', 'wheel-front-right'])
+  model.poseNode(w, [this.spin, steerDeg, 0]);
+```
+
+Poses are queued if the model hasn't finished loading, re-applied every sync, and
+unknown names are ignored (no throw). This is intent-level articulation — for full
+skeletal animation use `animation` clips instead.
 
 **`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

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

@@ -240,3 +240,9 @@ solid core carries the colour). `rate: 0` +
 
 `node.replay()` re-arms a one-shot. Simulation is deterministic under the
 engine seed — runScript verifies particle gameplay reproducibly.
+
+## `static: true` for big scenes
+
+Mark unchanging subtrees (tile decor, backgrounds) `static: true` — the
+renderer syncs them once and skips them every frame. Flip to `false` to
+resume live syncing.

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

@@ -62,9 +62,34 @@ All 3D nodes extend `Node3D` and therefore have the transform props:
 |---|---|---|
 | `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, depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false, depthTest/Write true). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `depthTest: false` (+ a high `renderOrder`) makes a flat `plane`/`cylinder` an ALWAYS-ON-TOP ground decal — AoE telegraphs, selection/spawn rings — that never z-fights with or is hidden by bumpy terrain (`depthWrite: false` keeps it from occluding later effects). `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 |
+| `material` | `{}` | `{color: '#hex', metalness: 0..1, roughness: 0..1, opacity: 0..1, clearcoat: 0..1, clearcoatRoughness: 0..1, envMapIntensity: >=0, wireframe, flatShading, depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false, depthTest/Write true). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `depthTest: false` (+ a high `renderOrder`) makes a flat `plane`/`cylinder` an ALWAYS-ON-TOP ground decal — AoE telegraphs, selection/spawn rings — that never z-fights with or is hidden by bumpy terrain (`depthWrite: false` keeps it from occluding later effects). `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). CAR PAINT: `clearcoat: 1` adds a glossy lacquer layer with its own reflection over a metallic base (`clearcoatRoughness` ~0.05-0.1 = mirror lacquer) — THE premium vehicle-paint look; `envMapIntensity` scales how strongly the surface mirrors the scene's sky/HDRI (glass windows want ~2, matte surfaces <1; needs a `sky`/`hdri` environment to reflect — at night with no sky there is nothing to mirror). 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` | |
 
+### `LoftMesh3D` (smooth swept hulls — vehicle bodies, canopies)
+
+A SMOOTH curved surface swept through cross-sections — what box/capsule assemblies can
+never give you. Superellipse sections are Catmull-Rom-interpolated along Z with per-vertex
+normals, so highlights and sky reflections SWEEP across it like sheet metal. Use it for car
+bodies, glass canopies, boat hulls, fuselages, submarines.
+
+| Prop | Default | Notes |
+|---|---|---|
+| `sections` | `[]` | ≥2 stations, ascending `z`: `{z, width, height, y, corner?}` — `width`/`height` are the full cross-section extents, `y` is the section CENTRE height, `corner` 0 = boxy slab … 1 = full ellipse (default 0.7; the lower half always stays flatter — vehicle floors are flat). Malformed sections hard-fail at load |
+| `slices` | `24` | vertices around each ring (8..64) |
+| `smooth` | `4` | interpolated rings per section gap (1..16) |
+| `material` | `{}` | same object as MeshInstance3D **minus textures** (`map`/`normalMap`/`repeat` hard-fail — a loft has no UVs) |
+| `castShadow` / `receiveShadow` | `false` | |
+
+Supercar recipe (hand-tuned against McLaren F1 proportions — see `examples/racing-3d`):
+one hull loft (low rounded nose ~`corner 0.9` → wide fender-crown stations at the axles →
+coke-bottle waist pinch → tall rear haunches → squared kamm tail `corner ~0.25`), plus a
+second small loft as the GLASS bubble canopy (`metalness 1, roughness 0.03,
+envMapIntensity ~1.7`), plus a dark interior loft inside it, with rectilinear
+`MeshInstance3D` details (splitter, wing, light bars, mirrors) on top. Paint that stays
+saturated in sunlight: `metalness ~0.45, roughness ~0.35, clearcoat 1,
+clearcoatRoughness 0.06, envMapIntensity ~0.9` — high metalness washes the base colour
+out into the sky reflection.
+
 ### `Sprite3D` / `AnimatedSprite3D` (2D billboard sprites — the 2.5D look)
 A 2D image drawn as a camera-facing quad inside the 3D world (Octopath / Don't
 Starve / classic MapleStory in a 3D scene). Unlit — the art shows as-is. The
@@ -251,6 +276,13 @@ demo into a commercial-looking outdoor scene:
   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`.
+- `bloom`: a glow post pass — bright pixels bleed light, so emissive
+  materials (tail-lights, neon, lava, muzzle flashes) and sun glints actually
+  GLOW. `{ threshold?, strength? }`: `threshold` 0..1 post-tonemap brightness
+  above which pixels bloom (default 0.75 — keeps it to lights/glints; lower =
+  dreamier), `strength` how strongly the blurred glow is added back (default
+  0.85; ~1.2 = neon night). One extra half-res blur pass per frame — cheap.
+  Caustics/clouds composites take precedence (pipelines don't stack yet).
 - `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
@@ -334,3 +366,16 @@ 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.
+
+## Performance levers for big scenes
+
+- **`static: true`** (any Node3D): the renderer syncs that subtree ONCE and
+  skips it every frame after — mark terrain, buildings, rocks, fences,
+  whole decor groups. Do NOT mark animated nodes (Water3D, Particles3D,
+  animated models, cameras): they freeze (the engine warns once). Set
+  `static = false` at runtime to resume live syncing after an edit.
+- **`environment.shadows.static: true`**: the shadow pass renders once per
+  scene/environment change instead of every frame (measured ~42% of a
+  dense-forest frame). Use when shadow CASTERS don't move — pair moving
+  characters with sprite/blob shadows. After a one-off world edit call
+  `renderer.refreshShadows()`.

package/skills/incanto-gameplay-behaviors.md

@@ -705,3 +705,63 @@ signal into a built-in's method through a `connection`).
 Generated, always-current prop/signal tables for every behavior live in
 `incanto-node-reference.md` (the "Gameplay behaviors" section).
 ```
+
+## Game feel ("juice")
+
+```ts
+import { CameraShake, Cooldown, hitStop, screenFlash } from 'incanto/gameplay';
+```
+
+- **Cooldown** — fire-rate gate, replaces hand-rolled clock math:
+  `private gun = new Cooldown(0.2);` then per update `this.gun.tick(dt);
+  if (firing && this.gun.tryUse()) shoot();`. `progress` (0..1) drives a
+  UiBar reload indicator; `reset()` for reload pickups.
+- **Camera shake** — `FollowCamera` has it built in:
+  `(cam.behavior as FollowCamera).shake(8)` (2D pixels; use ~0.2 in 3D
+  meters). For cameras WITHOUT a follow script attach the standalone
+  `CameraShake` behavior — it composes with any other position writer and
+  returns the camera exactly to base.
+- **screenFlash(color?, opacity?, seconds?)** — full-screen damage/pickup
+  flash (DOM, headless no-op).
+- **hitStop(engine, seconds?)** — freezes `engine.timeScale` for REAL
+  seconds then restores; stacked calls extend. Sells melee impacts.
+- **engine.timeScale** — 1 realtime, 0.5 slow motion, 0 pause: scales
+  variable AND fixed updates together (physics, timers, behaviors).
+
+## Game flow (win / lose / restart)
+
+Attach `GameFlow` to the scene root (`"script": { "name": "GameFlow" }`),
+declare a `restart` input action, and put a `%Banner` UiBanner in your HUD:
+
+```ts
+const flow = this.node.getRoot().behavior as GameFlow;
+flow.gameOver('YOU DIED');   // freezes engine.timeScale, sticky banner, waits for restart
+flow.win('AREA CLEAR');
+flow.pause(); flow.resume();
+```
+
+Terminal states ignore further transitions; the restart action (or
+`flow.restart()`) reloads the scene from its source JSON — fresh nodes,
+physics, input. Listen to the `flowChanged(state)` signal for custom UI.
+`restartScene(engine)` is exported standalone.
+
+## Boot loading overlay
+
+```ts
+import { preloadSceneAssets } from 'incanto';
+await preloadSceneAssets(sceneJson.assets);   // black screen + bar + %, auto-removes
+```
+
+Replaces the ~125-line hand-rolled loading screen; `createLoadingOverlay()`
+gives you the raw overlay when you preload something else.
+
+## Persistence (high scores, unlocks, settings)
+
+```ts
+import { createSaveStore } from 'incanto';
+const save = createSaveStore('my-game');       // namespaced localStorage
+save.set('highScore', Math.max(score, save.get('highScore', 0)));
+```
+
+JSON round-tripped; headless/private-mode falls back to in-memory (never
+throws). `clear()` wipes only your namespace.

package/skills/incanto-hud.md

@@ -0,0 +1,58 @@
+---
+name: incanto-hud
+description: Screen-space HUD widgets (HudLayer + UiText / UiBar / UiBanner) — health bars, score text, wave banners declared in scene JSON, no hand-rolled DOM or CSS. Use for any in-game UI overlay in 2D or 3D games.
+---
+
+# HUD widgets
+
+Declare your HUD in the scene JSON — no `index.html` markup, no CSS, no
+`document.querySelector` in behaviors:
+
+```json
+{
+  "name": "HUD", "type": "HudLayer",
+  "children": [
+    { "name": "Health", "type": "UiBar",
+      "props": { "anchor": "topLeft", "value": 100, "max": 100, "label": "HP" } },
+    { "name": "Score", "type": "UiText",
+      "props": { "anchor": "topRight", "text": "Score: 0", "size": 20 } },
+    { "name": "Banner", "type": "UiBanner" }
+  ]
+}
+```
+
+`HudLayer` is a fixed, pointer-transparent DOM overlay above the canvas — it
+works identically over the 2D and 3D renderers and is a silent no-op in
+headless tests (core nodes, no three.js). Widgets pick one of 9 anchors:
+`topLeft top topRight left center right bottomLeft bottom bottomRight`.
+Widgets stacked on the same anchor form a column.
+
+## Driving widgets from behaviors
+
+Plain node access — same as everything else:
+
+```ts
+import type { UiBanner, UiBar, UiText } from 'incanto';
+
+const hp = this.node.getNode('%Health') as UiBar;
+hp.value = health.current;          // fill animates; turns red below 30%
+
+(this.node.getNode('%Score') as UiText).text = `Score: ${score}`;
+
+const banner = this.node.getNode('%Banner') as UiBanner;
+banner.show('WAVE 2', { color: '#f87171', seconds: 2 }); // queued, fades
+banner.show('YOU DIED', { color: '#ef4444', seconds: 0 }); // sticky until next show()
+```
+
+## Widget reference
+
+- **UiText** — `text`, `size` (px), `color`, `shadow` (readability outline).
+- **UiBar** — `value`/`max` (ratio clamped 0..1), `width`/`height`, `color`,
+  `lowColor` + `lowThreshold` (default 0.3), `background`, `label` caption.
+- **UiBanner** — `show(text, {color, seconds})` queues center-screen
+  announcements with fade in/out; `seconds: 0` = sticky; `clear()` empties
+  the queue; signal `bannerShown(text)`. Props: `size` (font px), `seconds`
+  (default duration).
+
+Pair with the `Health` / `ScoreKeeper` gameplay behaviors: listen to their
+signals and write the widget props — that is the whole HUD wiring.

package/skills/incanto-node-reference.md

@@ -21,6 +21,7 @@ description: GENERATED complete reference of every Incanto node type — props,
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -42,6 +43,7 @@ Signals: `animationFinished(name)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -70,6 +72,7 @@ Signals: `animationFinished(name)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -83,6 +86,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -115,6 +119,7 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -126,6 +131,7 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -141,6 +147,7 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -155,6 +162,7 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -171,6 +179,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -197,6 +206,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -230,6 +240,7 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -244,6 +255,7 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -260,6 +272,7 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -280,6 +293,7 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `2` | number |
@@ -304,12 +318,56 @@ Signals: `movementStateChanged(state)`
 | `drape` | `false` | boolean |
 | `terrain` | `""` | string |
 
+## `HudLayer` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `zIndex` | `100` | number |
+| `visible` | `true` | boolean |
+
+## `Joint2D` — `incanto/2d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0]` | array |
+| `rotation` | `0` | number |
+| `static` | `false` | boolean |
+| `scale` | `[1,1]` | array |
+| `renderOrder` | `0` | number |
+| `visible` | `true` | boolean |
+| `type` | `"revolute"` | one of: `fixed` `revolute` `rope` `spring` |
+| `target` | `""` | string |
+| `anchor` | `[0,0]` | array |
+| `targetAnchor` | `[0,0]` | array |
+| `length` | `0` | number |
+| `stiffness` | `50` | number |
+| `damping` | `5` | number |
+
+## `Joint3D` — `incanto/3d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `type` | `"spherical"` | one of: `fixed` `spherical` `rope` `spring` |
+| `target` | `""` | string |
+| `anchor` | `[0,0,0]` | array |
+| `targetAnchor` | `[0,0,0]` | array |
+| `length` | `0` | number |
+| `stiffness` | `50` | number |
+| `damping` | `5` | number |
+
 ## `Label` — `incanto/2d`
 
 | Prop | Default | Kind |
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -319,12 +377,30 @@ Signals: `movementStateChanged(state)`
 | `font` | `"monospace"` | string |
 | `align` | `"left"` | string |
 
+## `LoftMesh3D` — `incanto/3d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `sections` | `[]` | array |
+| `slices` | `24` | number |
+| `smooth` | `4` | number |
+| `material` | `{}` | object |
+| `castShadow` | `false` | boolean |
+| `receiveShadow` | `false` | boolean |
+
 ## `MeshInstance3D` — `incanto/3d`
 
 | Prop | Default | Kind |
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -340,6 +416,7 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -350,6 +427,8 @@ Signals: `movementStateChanged(state)`
 | `animationLoop` | `true` | boolean |
 | `receiveShadow` | `false` | boolean |
 | `tint` | `""` | string |
+| `metalness` | `-1` | number |
+| `roughness` | `-1` | number |
 
 Signals: `animationFinished(name)`
 
@@ -373,6 +452,7 @@ _No props (structural fields only)._
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -383,6 +463,7 @@ _No props (structural fields only)._
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -393,6 +474,7 @@ _No props (structural fields only)._
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -406,6 +488,7 @@ _No props (structural fields only)._
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -438,6 +521,7 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -471,6 +555,7 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -490,6 +575,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -509,6 +595,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -525,6 +612,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -546,6 +634,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
 | `visible` | `true` | boolean |
@@ -559,6 +648,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -572,6 +662,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -604,6 +695,7 @@ Signals: `timeout`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -628,12 +720,51 @@ Signals: `timeout`
 |---|---|---|
 | `anchor` | `"top-left"` | one of: `top-left` `top` `top-right` `left` `center` `right` `bottom-left` `bottom` `bottom-right` |
 
+## `UiBanner` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"center"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `size` | `42` | number |
+| `seconds` | `2` | number |
+
+Signals: `bannerShown`
+
+## `UiBar` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `value` | `100` | number |
+| `max` | `100` | number |
+| `width` | `180` | number |
+| `height` | `14` | number |
+| `color` | `"#4ade80"` | string |
+| `lowColor` | `"#ef4444"` | string |
+| `lowThreshold` | `0.3` | number |
+| `background` | `"rgba(0,0,0,0.5)"` | string |
+| `label` | `""` | string |
+
+## `UiText` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `text` | `""` | string |
+| `size` | `16` | number |
+| `color` | `"#ffffff"` | string |
+| `shadow` | `true` | boolean |
+
 ## `VoxelGrid3D` — `incanto/3d`
 
 | Prop | Default | Kind |
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
@@ -647,6 +778,7 @@ Signals: `blocksChanged`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `1` | number |
@@ -678,6 +810,12 @@ Ready-made `Behavior`s auto-registered by `createGame2D`/`createGame3D` (opt out
 with `gameplay: false`). Attach via `"script": {"name": "...", "props": {...}}` and
 wire their signals through scene `connections`. Full guide: `incanto-gameplay-behaviors.md`.
 
+### `CameraShake`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `falloff` | `0.28` | number |
+
 ### `Chase`
 
 | Prop | Default | Kind |
@@ -718,6 +856,16 @@ Signals: `dealtDamage(amount, target)`
 | `smoothing` | `0` | number |
 | `deadzone` | `0` | number |
 
+### `GameFlow`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `restartAction` | `"restart"` | string |
+| `freezeOnEnd` | `true` | boolean |
+| `bannerPath` | `"%Banner"` | string |
+
+Signals: `flowChanged`
+
 ### `Health`
 
 | Prop | Default | Kind |

package/skills/incanto-physics-and-input.md

@@ -133,6 +133,53 @@ Injected state combines with key state (vectors clamped to unit length).
 - Reference: [examples/2d-phaser-sprite-character-gravity](https://github.com/rareboe/Incanto/tree/main/examples/2d-phaser-sprite-character-gravity) — gravity, jump, attack lockout, custom
   `Player` node type. Verified in Chromium end-to-end.
 
+## Joints (Joint2D / Joint3D)
+
+Link two bodies: put the joint node as a CHILD of body A, point `target` at
+body B (any node path — `%Name` is typical):
+
+```json
+{ "name": "Ball", "type": "RigidBody2D",
+  "props": { "collider": { "shape": "circle", "radius": 10 } },
+  "children": [
+    { "name": "Rope", "type": "Joint2D",
+      "props": { "type": "rope", "target": "%Anchor", "length": 100 } }
+  ]}
+```
+
+Types — 2D: `fixed` (weld) · `revolute` (pin/hinge) · `rope` (max distance)
+· `spring` (pull toward `length` with `stiffness`/`damping`). 3D swaps
+`revolute` for `spherical` (ball joint). `length: 0` measures the body
+distance at creation. `anchor`/`targetAnchor` are local offsets (px / m).
+Chains work (pendulums, bridges: each link a body + joint to the previous).
+
+## Raycasts
+
+Both runtimes expose the same query (2D in PIXELS y-down, 3D in meters):
+
+```ts
+const hit = physics.castRay(origin, dir, maxLen, excludeBody?, { staticOnly?: true });
+// → { distance, normal, node } | null   (sensors never block rays)
+```
+
+Exclude the shooter's own body when casting from inside it.
+
+## Gamepad
+
+`engine.input.attachGamepad(engine)` polls the first connected pad every
+frame (headless no-op). Buttons are codes `Pad0`..`Pad16` in the SAME space
+as keys — declare them in actions: `"jump": { "keys": ["Space", "Pad0"] }`
+(standard mapping: Pad0=A/×, Pad1=B/○, Pad9=Start). Sticks:
+`input.padAxes(0)` / `padAxes(1)` → deadzoned `{x, y}`. Unplugging releases
+everything (no stuck inputs).
+
+## Changing colliders at runtime
+
+REPLACE the object — `body.collider = { shape: 'rect', size: [w, 60] }` —
+and physics rebuilds the body that step. In-place mutation of the existing
+collider object (`body.collider.size[0] = w`) is NOT watched (the per-step
+change scan was removed for performance).
+
 ## Debug drawing
 
 `physics.debugDraw = true` (the instance `enablePhysics2D/3D` returns) renders