incanto 0.5.0 → 0.7.0

package/skills/incanto-behaviors-and-scripts.md

@@ -167,3 +167,28 @@ import { Sprite2D } from 'incanto/2d'; // node classes live in their dimension e
 const coin = new Sprite2D('Coin');
 coin.uid = newUid(); // n_xxxxxxxxxxxxxxxx (crypto, 16 base36 chars)
 ```
+
+## Time & frame-rate independence (Unity Time equivalents)
+
+Movement is frame-rate independent when you multiply by `dt` — the seconds
+(already `timeScale`-adjusted) your update callbacks receive:
+
+```ts
+override update(dt: number): void {
+  // 1 meter per second at ANY fps — 30, 60, or 144:
+  node.position[0] += 1 * dt;
+}
+```
+
+| Unity | Incanto |
+|---|---|
+| `Time.deltaTime` | the `dt` argument of `update(dt)` / `fixedUpdate(dt)` |
+| `Time.time` | `engine.time` (elapsed game seconds, scaled; resets per scene) |
+| `Time.unscaledTime` | `engine.unscaledTime` (real seconds — UI during slow-mo) |
+| `Time.timeScale` | `engine.timeScale` (1 realtime · 0.5 slow-mo · 0 frozen) |
+| `Time.fixedDeltaTime` | the `dt` of `fixedUpdate` (1/60 by default) |
+
+`engine.timeScale` scales variable AND fixed updates together — physics,
+timers, animations and behaviors all slow down as one. Bullet-time:
+`engine.timeScale = 0.3`; freeze frames: `hitStop(engine, 0.08)` from
+`incanto/gameplay`.

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

@@ -366,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-node-reference.md

@@ -21,8 +21,10 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `texture` | `""` | string |
 | `anchor` | `[0.5,0.5]` | array |
@@ -42,9 +44,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `texture` | `""` | string |
 | `size` | `[1,1]` | array |
 | `billboard` | `"y"` | one of: `y` `full` `none` |
@@ -70,8 +74,10 @@ Signals: `animationFinished(name)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
 
@@ -83,9 +89,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `collider` | `{}` | object |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -115,9 +123,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `mode` | `"screen"` | one of: `screen` `y` `none` |
 
 ## `Camera2D` — `incanto/2d`
@@ -126,8 +136,10 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `follow` | `""` | string |
 | `smoothing` | `0` | number |
@@ -141,9 +153,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `fov` | `60` | number |
 | `near` | `0.1` | number |
 | `far` | `1000` | number |
@@ -155,8 +169,10 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
 | `velocity` | `[0,0]` | array |
@@ -171,9 +187,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `collider` | `{}` | object |
 | `velocity` | `[0,0,0]` | array |
 | `snapToGround` | `true` | boolean |
@@ -197,9 +215,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `view` | `"free"` | one of: `free` `firstPerson` `quarter` `side` |
 | `camDistance` | `4` | number |
 | `eyeHeight` | `0.64` | number |
@@ -230,8 +250,10 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `size` | `[100,100]` | array |
 | `color` | `"#ffffff"` | string |
@@ -244,9 +266,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `color` | `"#ffffff"` | string |
 | `intensity` | `1` | number |
 | `castShadow` | `false` | boolean |
@@ -260,9 +284,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `density` | `"sparse"` | one of: `lush` `sparse` `none` |
 | `area` | `[20,20]` | array |
 | `seed` | `1` | number |
@@ -280,9 +306,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `kind` | `"grass"` | one of: `grass` `flowers` `reeds` |
 | `style` | `"mesh"` | one of: `blades` `simple` `mesh` `tufts` |
 | `tuftStyle` | `"grass"` | one of: `grass` `fern` |
@@ -317,8 +345,10 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `type` | `"revolute"` | one of: `fixed` `revolute` `rope` `spring` |
 | `target` | `""` | string |
@@ -334,9 +364,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `type` | `"spherical"` | one of: `fixed` `spherical` `rope` `spring` |
 | `target` | `""` | string |
 | `anchor` | `[0,0,0]` | array |
@@ -351,8 +383,10 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `text` | `""` | string |
 | `fontSize` | `16` | number |
@@ -366,9 +400,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `sections` | `[]` | array |
 | `slices` | `24` | number |
 | `smooth` | `4` | number |
@@ -382,9 +418,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `mesh` | `"box"` | one of: `box` `sphere` `capsule` `plane` `cylinder` `gem` |
 | `size` | `[1,1,1]` | array |
 | `material` | `{}` | object |
@@ -397,9 +435,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `model` | `""` | string |
 | `animation` | `""` | string |
 | `targetHeight` | `0` | number |
@@ -432,8 +472,10 @@ _No props (structural fields only)._
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 
 ## `Node3D` — `incanto/3d`
@@ -442,9 +484,11 @@ _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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 
 ## `OmniLight3D` — `incanto/3d`
 
@@ -452,9 +496,11 @@ _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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `color` | `"#ffffff"` | string |
 | `intensity` | `1` | number |
 | `range` | `0` | number |
@@ -465,8 +511,10 @@ _No props (structural fields only)._
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"effects"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
@@ -497,9 +545,11 @@ 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 |
+| `orderGroup` | `"effects"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
 | `rate` | `40` | number |
@@ -530,8 +580,10 @@ Signals: `finished`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
 | `mass` | `1` | number |
@@ -549,9 +601,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `collider` | `{}` | object |
 | `mass` | `1` | number |
 | `gravityScale` | `1` | number |
@@ -568,8 +622,10 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `texture` | `""` | string |
 | `anchor` | `[0.5,0.5]` | array |
@@ -584,9 +640,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `texture` | `""` | string |
 | `size` | `[1,1]` | array |
 | `billboard` | `"y"` | one of: `y` `full` `none` |
@@ -605,8 +663,10 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 |---|---|---|
 | `position` | `[0,0]` | array |
 | `rotation` | `0` | number |
+| `static` | `false` | boolean |
 | `scale` | `[1,1]` | array |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `collider` | `{}` | object |
 
@@ -618,9 +678,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `collider` | `{}` | object |
 
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -631,9 +693,11 @@ 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 |
+| `orderGroup` | `"terrain"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `size` | `[200,200]` | array |
 | `maxHeight` | `28` | number |
 | `seed` | `1` | number |
@@ -663,9 +727,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `tier` | `"medium"` | one of: `simple` `medium` `high` |
 | `type` | `"conifer"` | one of: `conifer` `broadleaf` `dead` `bush` |
 | `seed` | `1` | number |
@@ -731,9 +797,11 @@ Signals: `bannerShown`
 |---|---|---|
 | `position` | `[0,0,0]` | array |
 | `rotation` | `[0,0,0]` | array |
+| `static` | `false` | boolean |
 | `scale` | `[1,1,1]` | array |
 | `visible` | `true` | boolean |
 | `renderOrder` | `0` | number |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `voxels` | `[]` | array |
 
 Signals: `blocksChanged`
@@ -744,9 +812,11 @@ 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 |
+| `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `size` | `[40,40]` | array |
 | `color` | `"#2a6fbe"` | string |
 | `opacity` | `0.8` | number |

package/skills/incanto-scene-json-authoring.md

@@ -106,6 +106,25 @@ physically adjacent, and makes subtree copy/move one-object operations. Flat
 addressing needs are covered by uid (`getNodeByUid`). Full reasoning:
 docs/adr/0001 in the repo.
 
+## Draw order: orderGroup + renderOrder
+
+Every visual node has TWO ordering props: `orderGroup` (a named band —
+`background < terrain < default < characters < effects < overlay`) and
+`renderOrder` (fine offset INSIDE the band). Effective order =
+band base + renderOrder. Type defaults: particles ship in `effects`,
+Terrain3D in `terrain`, everything else `default`.
+
+```json
+{ "name": "Hero", "type": "Sprite2D",
+  "props": { "orderGroup": "characters" } },
+{ "name": "Smoke", "type": "Particles2D",
+  "props": { "renderOrder": 5 } }          // effects band, +5 within it
+```
+
+In 3D the bands order the TRANSPARENT pass (opaque geometry is depth-
+tested regardless); in 2D they are the layering system. 2D `zIndex` is an
+accepted alias for `renderOrder`.
+
 ## Parents and children
 
 EVERY node type can hold children — `children` is universal, so any node works