lecodes-sdk 1.2.0 → 2.0.1

package/src/g2/Node2D.ts

@@ -11,7 +11,8 @@
 
 import { AspectHost } from "../core/Aspect"
 import type { CompAxis, CompWriter } from "../core/compWrite"
-import { Registry } from "../core/registry"
+import { DEAD_HANDLE, Pins, registerFreedKind } from "../core/pins"
+import { OWNED_KIND_ENTITY_2D } from "../ui/tree"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { ensurePointerEvents } from "./touch"
@@ -55,11 +56,15 @@ export type Node2DEvents = {
 export type Contact2D = { point: Vec2, normal: Vec2, speed: number }
 
 /** id → Node2D, so host callbacks (animation events) route back to the owning JS object. */
-export const node2dRegistry = new Registry<Node2D>()
+/** @internal The 2D nodes native owns right now (in a scene / under a parent), by entity id — what a
+ *  contact or a pointer hit resolves to. See core/pins.ts. */
+export const nodes2d = new Pins<Node2D>()
 
 export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
-  /** Native entity handle. */
-  readonly id: number
+  /** @internal The entity's owned handle (`_h.id` = the entity id; DEAD_HANDLE once destroyed). */
+  _h: Handle
+  /** Native entity id. */
+  get id(): number { return this._h.id }
 
   /** Optional debug/editor name (plain JS data — scene2d files stamp their node names here). */
   name?: string
@@ -98,13 +103,18 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
     else if (this._xfKind === 1) _creator2d.characterSetFromEntity(this._xf)
   }
 
-  private _parent: Node2D | null = null
-  private _children: Node2D[] = []
-
-  constructor(internalId?: number) {
+  constructor(internalId?: number | Handle) {
     super()
-    this.id = internalId ?? _creator2d.createEntity()
-    node2dRegistry.set(this.id, this)
+    registerFreedKind(OWNED_KIND_ENTITY_2D, nodes2d)
+    if (internalId === undefined) {
+      const h = _creator2d.createEntity()
+      this._h = typeof h === "number" ? { id: h } : h   // a number only from a test stub
+    } else if (typeof internalId === "number") {
+      this._h = { id: internalId }   // engine-owned: findable while the engine keeps it
+      nodes2d.pin(this)
+    } else {
+      this._h = internalId
+    }
   }
 
   // --- transform (Y-up, LOCAL to the parent; at zoom 1, units == logical pixels) ---
@@ -185,10 +195,20 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
   set visible(v: boolean) { this._visible = v; _creator2d.setVisible(this.id, v) }
 
   // --- hierarchy (parent/child; transforms above are LOCAL to the parent) ---
-  get parent(): Node2D | null { return this._parent }
+  // The tree lives in the engine (phase 10): parent / children are read back; a node the SDK never
+  // wrapped (none today — every 2D entity is created here) reads as absent.
+  get parent(): Node2D | null {
+    const p = _creator2d.getParent(this.id)
+    return p !== 0 ? nodes2d.get(p) ?? null : null
+  }
   set parent(p: Node2D | null) { this.setParent(p) }
 
-  get children(): readonly Node2D[] { return this._children }
+  get children(): readonly Node2D[] {
+    const out: Node2D[] = []
+    const n = _creator2d.getChildCount(this.id)
+    for (let i = 0; i < n; i++) { const c = nodes2d.get(_creator2d.getChild(this.id, i)); if (c) out.push(c) }
+    return out
+  }
 
   /** Attach children to this node (each keeps its current world transform). Returns this. */
   add(...children: Node2D[]): this {
@@ -198,7 +218,7 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
 
   /** Detach a direct child (reparents it to root, keeping its world transform). Returns this. */
   remove(child: Node2D): this {
-    if (child._parent === this) child.setParent(null)
+    if (child.parent === this) child.setParent(null)
     return this
   }
 
@@ -209,14 +229,9 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
    */
   setParent(parent: Node2D | null, keepWorld = true): this {
     if (parent === this) return this
-    if (this._parent) {
-      const arr = this._parent._children
-      const i = arr.indexOf(this)
-      if (i >= 0) arr.splice(i, 1)
-    }
-    this._parent = parent
-    if (parent) parent._children.push(this)
     _creator2d.setParent(this.id, parent?.id ?? 0, keepWorld)
+    if (parent) nodes2d.pin(this)                                    // the parent owns it now
+    else if (!_creator2d.entityIsOwned(this.id)) nodes2d.unpin(this.id)   // loose again: its handle owns it
     if (keepWorld) this._syncLocalFromNative()   // native recomputed our local transform
     return this
   }
@@ -278,28 +293,31 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
     this.dispatch(channel, ...args)
   }
 
+  /** Destroy this node and its whole subtree (children go with it — the 3D / UI contract). Every
+   *  aspect in the subtree detaches first (physics bodies released, updaters unregistered). */
   destroy(): void {
-    // Aspects go first: onDetach runs (a body-owning aspect releases its handle), updaters are
-    // unregistered so a destroyed node never ticks again, listeners are dropped. Children survive
-    // (native reparents them to the root), so only this node's aspects detach.
-    this._detachAll()
-    // Native frees this entity's physics bodies inside destroyEntity (they used to leak — an invisible
-    // collider stayed in the world, and recycled entity ids then delivered its contacts to whoever
-    // inherited the id). Clear the routing so a stale aspect can't push a dead handle.
+    if (this._h.id === 0) return
+    const subtree: Node2D[] = []
+    const collect = (n: Node2D) => { subtree.push(n); for (const c of n.children) collect(c) }
+    collect(this)
+    for (let i = subtree.length - 1; i >= 0; i--) subtree[i]._detachAll()
+    const id = this.id
+    // Dead NOW — entity ids are recycled, and the runtime's freed report lands a drain later.
+    for (const n of subtree) { nodes2d.unpin(n.id); n._dead() }
+    _creator2d.destroyEntity(id)
+  }
+
+  /** @internal The wrapper's resource is gone: no more native calls from here. */
+  _dead(): void {
     this._xf = 0
     this._xfKind = 0
     this._physicsDriven = false
-    // Detach from parent; native reparents our children to root (keepWorld), so resync their caches.
-    if (this._parent) {
-      const arr = this._parent._children
-      const i = arr.indexOf(this)
-      if (i >= 0) arr.splice(i, 1)
-      this._parent = null
-    }
-    const orphans = this._children.slice()
-    this._children.length = 0
-    node2dRegistry.delete(this.id)
-    _creator2d.destroyEntity(this.id)
-    for (const c of orphans) { c._parent = null; c._syncLocalFromNative() }
+    this._h = DEAD_HANDLE
+  }
+  /** @internal The runtime freed the entity underneath (an ancestor destroyed or dropped). */
+  _freed(): void {
+    if (this._h.id === 0) return
+    this._detachAll()
+    this._dead()
   }
 }

package/src/g2/Physics2D.ts

@@ -19,7 +19,7 @@
 
 import { Aspect } from "../core/Aspect"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
-import { node2dRegistry, type Node2D } from "./Node2D"
+import { nodes2d, type Node2D } from "./Node2D"
 import { Shape2D } from "./Shape2D"
 import {
   PhysicsGroup2D, _addGroup, _watchGroupChanges, _unwatchGroupChanges,
@@ -51,7 +51,7 @@ export interface RayHit {
 }
 
 // Resolve a native entity id to its Node2D (0 = none).
-const node2dById = (id: number): Node2D | null => (id ? node2dRegistry.get(id) ?? null : null)
+const node2dById = (id: number): Node2D | null => (id ? nodes2d.get(id) ?? null : null)
 
 export class Physics2D extends Aspect<"physics", Node2D> {
   static readonly aspect = "physics"

package/src/g2/Scene2D.ts

@@ -3,11 +3,13 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem, _detachAllSystems, type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect"
-import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
+import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
+import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
+import { TREE_DEST_SCENE2D, ensureEmitter, registerDest } from "../ui/tree"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
-import { node2dRegistry, type Node2D } from "./Node2D"
+import { nodes2d, type Node2D } from "./Node2D"
 import { ensurePointerEvents } from "./touch"
 
 // Route aspect update(dt) through the render-synced native phases (c2dRender early = before physics,
@@ -88,7 +90,7 @@ export class Scene2D implements Presentable {
    *  hit-test for tap/click picking — pair with camera.screenToWorld(). */
   pick(worldPoint: Vec2Like): Node2D | null {
     const id = _creator2d.pickSprite(this.id, cx(worldPoint), cy(worldPoint))
-    return id ? node2dRegistry.get(id) ?? null : null
+    return id ? nodes2d.get(id) ?? null : null
   }
 
   /** Scene-level pointer events. The handler fires for every tap/press in the scene, with
@@ -106,11 +108,14 @@ export class Scene2D implements Presentable {
   }
 
   add(...nodes: Node2D[]): this {
-    for (const n of nodes) _creator2d.addEntityToScene(this.id, n.id)
+    for (const n of nodes) { _creator2d.addEntityToScene(this.id, n.id); nodes2d.pin(n) }   // the scene owns it now
     return this
   }
   remove(...nodes: Node2D[]): this {
-    for (const n of nodes) _creator2d.removeEntityFromScene(this.id, n.id)
+    for (const n of nodes) {
+      _creator2d.removeEntityFromScene(this.id, n.id)
+      if (!_creator2d.entityIsOwned(n.id)) nodes2d.unpin(n.id)   // loose again: its handle owns it
+    }
     return this
   }
 
@@ -162,10 +167,14 @@ export class Scene2D implements Presentable {
     this.cl.push(callback)
     return this
   }
-  onBackPressed(callback: () => void): this {
+  /** Hardware/system back while the scene is current. */
+  onBack(callback: () => void): this {
     this._backButtonCallback = callback
     return this
   }
+  /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+   *  rename; removed with the release that recompiles them. */
+  onBackPressed(callback: () => void): this { return this.onBack(callback) }
 
   /** @internal UIImage source marker (UIImage.toSrc): `UIImage(scene)` shows this scene live — the
    *  host draws it into the image node's box every frame with the scene's own camera (a minimap, a
@@ -174,9 +183,20 @@ export class Scene2D implements Presentable {
     return { scene2d: this.id }
   }
 
-  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
-  _viewDesc(): object {
-    return this._vd ??= { type: "scene2d", sceneId: this.id, _p: this }
+  /** @internal The destination tuple (ui/presentable.ts). */
+  _dest(): DestTuple {
+    registerDest(TREE_DEST_SCENE2D, this.id, this)
+    return [TREE_DEST_SCENE2D, this.id, "", ""]
+  }
+  /** @internal presentation lifecycle from the runtime */
+  _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
+  /** @internal */
+  _emitClose(): void { for (const cb of this.cl.slice()) cb() }
+  /** @internal */
+  _emitBack(): boolean {
+    if (!this._backButtonCallback) return false
+    this._backButtonCallback()
+    return true
   }
 
   /** Make this the active scene — shows it as the current destination (replaces a screen /
@@ -185,25 +205,17 @@ export class Scene2D implements Presentable {
     _bumpNavEpoch()
     // Reassert this scene's texture filter (the sampler is global — see Scene2DOptions.filter).
     if (this._filter !== undefined) _creator2d.setDefaultFilter(this._filter === 'linear')
-    if (_navSupported()) {
-      // The host activates the engine (openScene) as part of presenting the destination.
-      _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
-    } else {
-      _creator2d.openScene(this.id)
-      for (const cb of this.ol) cb()
-    }
+    // The runtime activates the engine (openScene) as part of presenting the destination.
+    ensureEmitter()
+    registerDest(TREE_DEST_SCENE2D, this.id, this)
+    _creatorTree.open(TREE_DEST_SCENE2D, this.id, "", "", _transitionId(options?.transition, TRANSITION_NONE))
     Scene2D._active = this
     _setCurrent(this)
     return this
   }
-  close(): this {
+  close(options?: DismissOptions): this {
     _bumpNavEpoch()
-    if (_navSupported()) {
-      _creatorUI.closeView!()
-    } else {
-      _creator2d.closeScene()
-      for (const cb of this.cl) cb()
-    }
+    _creatorTree.close(TREE_DEST_SCENE2D, this.id, _transitionId(options?.transition, TRANSITION_NONE))
     if (Scene2D._active === this) Scene2D._active = null
     if (Presentable.current === this) _setCurrent(null)
     return this

package/src/g2/Texture2D.ts

@@ -37,7 +37,7 @@ export class Texture2D {
       })
     }
     return new Promise<Texture2D>((resolve, reject) => {
-      _creator2d.createTexture((source as any)._id, (id, w, h) => resolve(new Texture2D(id, w, h)), reject)
+      _creator2d.createTexture((source as any)._h.id, (id, w, h) => resolve(new Texture2D(id, w, h)), reject)
     })
   }
 

package/src/g2/loop.ts

@@ -6,7 +6,7 @@
 // pulls none of this in.
 
 import { Vec2 } from "../math/vec"
-import { node2dRegistry } from "./Node2D"
+import { nodes2d } from "./Node2D"
 
 export const onUpdate = (callback: (dt: number) => void): void => _creator2d.onUpdate(callback)
 export const offUpdate = (callback: (dt: number) => void): void => _creator2d.offUpdate(callback)
@@ -18,7 +18,7 @@ export const ensureAnimEvents = (): void => {
   if (animEventsRegistered) return
   animEventsRegistered = true
   _creator2d.setOnAnimEvent(({ entityId, clipId, type }) => {
-    node2dRegistry.get(entityId)?._dispatchAnimEvent(clipId, type)
+    nodes2d.get(entityId)?._dispatchAnimEvent(clipId, type)
   })
 }
 
@@ -37,8 +37,8 @@ export const ensurePhysicsEvents = (): void => {
   if (physicsEventsRegistered) return
   physicsEventsRegistered = true
   _creator2d.setOnPhysicsEvent((a, b, type, px, py, nx, ny, speed) => {
-    const na = node2dRegistry.get(a)
-    const nb = node2dRegistry.get(b)
+    const na = nodes2d.get(a)
+    const nb = nodes2d.get(b)
     if (!na || !nb) return
     const channel = type === 1 || type === 3 ? "exit" : "enter"
     // Box2D's manifold normal points from A TOWARD B. Each listener wants the normal of the surface

package/src/gl/CameraPlace.ts

@@ -1,52 +1,52 @@
-// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
-// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
-// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
-// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
-//
-//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
-//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
-//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
-//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
-//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
-//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
-//     releases.
-//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
-// See docs/scene-camera-place-plan.md.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Gizmos } from "../scene/gizmos"
-import type { Camera } from "./Camera"
-import type { Node } from "./Node"
-
-export class CameraPlace extends Aspect<"cameraPlace", Node> {
-  static readonly aspect = "cameraPlace"
-  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
-  fov = 60
-  /** Near clip distance. */
-  near = 0.01
-  /** Far clip distance = view range. */
-  far = 1000
-  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
-   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
-  active = false
-  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
-  static fields: FieldMeta<CameraPlace> = {
-    fov: { label: "FOV", min: 1, max: 179, step: 1 },
-    near: { min: 0.001, max: 10, step: 0.01 },
-    far: { min: 1, max: 100000, step: 1 },
-    active: { label: "Active camera" },
-  }
-  static editor = { rebuild: true }
-
-  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
-  applyTo(camera: Camera): void {
-    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
-  }
-
-  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
-   *  clicking it selects the node. Play mode never calls this. */
-  rebuild(): void {
-    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
-  }
-}
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}

package/src/gl/Foliage.ts

@@ -1,13 +1,22 @@
 // Foliage — the vegetation tier of the lightmap material family (creator-gl materials/src/foliage.mat).
 //
 // A model loaded with `Model.load(src, { foliage: true })` (scene files: `foliage: true` on a `model`
-// node) takes a shader whose vertices sway in the wind, bend away from BENDERS (the hero, enemies —
+// node) takes a shader whose vertices bend in the wind, lean away from BENDERS (the hero, enemies —
 // any node registered with `Foliage.bend`) and thin out over a distance range, and whose fragment
 // tints every copy a little differently. All of it is level-wide state the engine keeps: the wind
-// and the sway options apply to every foliage model, present and future; benders are read from
+// and the options apply to every foliage model, present and future; benders are read from
 // their live world transforms each frame (the 8 nearest the camera reach the shader); a fade is per
 // ASSET — every copy of that model, present and future.
 //
+// THE WIND (2026-09-23) is the model of Unity HDRP's Wind.hlsl, what NatureManufacture's vegetation is
+// authored for: a scrolling noise field read at each plant's root bends the whole plant about its root
+// (the angle grows with the distance from the root: a cantilever's curve), a second, finer field read at
+// each vertex moves the leaves (their shiver) — no fixed periods, the turbulence turns a tree off the mean
+// wind, the gusts ride a slow third field. What differs per PLANT comes from the model, not from here:
+// the material's drag / stiffness / permanent lean / shiver drag ride the GLB's material extras
+// (`lecodes.wind`, written by `lecodes assets scene` from the Unity material), or default by the plant's
+// size (grass under ~2 m, trees over ~5 m); the per-vertex shiver weight is the GLB's COLOR_0.a.
+//
 // Hosts without the tier (no `foliageSet*` bridge) ignore every call; the models then load through
 // the ordinary lightmap tier where that exists, else the standard shader.
 import { Model } from "./Model"
@@ -16,20 +25,21 @@ import { Node } from "./Node"
 export type FoliageWind = {
   /** Direction on the ground (x, z); normalised by the engine. Default [1, 0.3]. */
   direction?: [number, number]
-  /** Metres of sway at `bendHeight` (taller parts sway more). Default 0.07. 0 = still. */
-  strength?: number
-  /** Radians per second of the main sway. Default 1.2. */
+  /** The wind speed in m/s — the plants' permanent bend and how fast the field drifts past them. Default 8.3
+   *  (30 km/h, the pack's demo). 0 = still. */
   speed?: number
-  /** 0..1: how much the strength breathes over a slow envelope. Default 0.6. */
+  /** 0..2: the random share of the speed — how far the bend wanders off the mean wind and how much the leaves move.
+   *  Default 0.4. */
+  turbulence?: number
+  /** 0..1: the gusts' strength — waves of extra wind that travel over the level, calm between. Default 0.35. */
   gust?: number
+  /** m/s the gust pattern travels at. Default 5.6 (20 km/h). */
+  gustSpeed?: number
 }
 
 export type FoliageOptions = {
   /** The wind, or `false` for none. */
   wind?: FoliageWind | false
-  /** Height above the instance origin (m) where the full sway / touch applies; the base never moves.
-   *  Default 1.5. */
-  bendHeight?: number
   /** Metres the TOP of a small plant leans away from a bender standing at its centre; the whole plant leans
    *  as one, rooted at its base. Plants over ~2 m react less, trees over ~5 m not at all (the engine
    *  measures each asset). Default 0.6. 0 = no touch reaction. */
@@ -39,20 +49,51 @@ export type FoliageOptions = {
   variation?: number
   /** 0..1: wrapped sun lighting — thin leaves let light through. Default 0.5. */
   sunWrap?: number
+  /** A multiplier on every material's shiver drag (the leaves' own motion on top of the bend): 1 = as the
+   *  model's materials say, 0 = the leaves ride the bend alone. Default 1. */
+  shiver?: number
+  /** 0..1: the sun through a thin leaf lit from behind (a back-lit crown glows). Default 0.35. */
+  translucency?: number
+  /** 0..1: how much of a light's shadow a leaf card takes. A crown scatters light through itself, so its cards take the
+   *  shadow map partly — at 1 a distant crown is a dark silhouette lit only on its top layer. Bark always takes the
+   *  shadow in full. Default 0.6. */
+  leafShadow?: number
+  /** 0..1: how far the baked per-vertex sky visibility (the crown's interior, the trunk under it) darkens the ambient.
+   *  Default 0.7. */
+  skyAo?: number
+  /** 0..1: a leaf card's shading normal, from the card's own plane (0) to the crown's hull normal (1) — what hides that a
+   *  crown is flat quads: each card is lit as the part of the volume it sits in. Default 0.7. */
+  canopy?: number
+  /** The cards' normal-map strength (a strong map brings the planes back). Default 0.5. */
+  normalMap?: number
+  /** A card seen edge-on dissolves over this much of |N·V| — no paper edges on the silhouette. Default 0.15, 0 = none. */
+  edgeFade?: number
+  /** Coverage held over distance: the cards' alpha × (1 + coverage × mip level), so a far crown does not thin out as its
+   *  atlas mips away. Default 0.25, 0 = none; past ~0.5 a crown turns into a solid mass. */
+  coverage?: number
 }
 
+const DEFAULT_WIND: Required<FoliageWind> = { direction: [ 1, 0.3 ], speed: 8.3, turbulence: 0.4, gust: 0.35, gustSpeed: 5.6 }
+
 const state: Required<Omit<FoliageOptions, "wind">> & { wind: Required<FoliageWind> | false } = {
-  wind: { direction: [ 1, 0.3 ], strength: 0.07, speed: 1.2, gust: 0.6 },
-  bendHeight: 1.5,
+  wind: { ...DEFAULT_WIND },
   touch: 0.6,
   variation: 0.35,
   sunWrap: 0.5,
+  shiver: 1,
+  translucency: 0.35,
+  leafShadow: 0.6,
+  skyAo: 0.7,
+  canopy: 0.7,
+  normalMap: 0.5,
+  edgeFade: 0.15,
+  coverage: 0.25,
 }
 
 const pushWind = (): void => {
   const w = state.wind
-  if (w === false) _creator.foliageSetWind?.(1, 0, 0, 1, 0)
-  else _creator.foliageSetWind?.(w.direction[0], w.direction[1], w.strength, w.speed, w.gust)
+  if (w === false) _creator.foliageSetWind?.(1, 0, 0, 0, 0, 0)
+  else _creator.foliageSetWind?.(w.direction[0], w.direction[1], w.speed, w.turbulence, w.gust, w.gustSpeed)
 }
 
 export const Foliage = {
@@ -61,19 +102,33 @@ export const Foliage = {
   configure(options: FoliageOptions): void {
     if (options.wind !== undefined) Foliage.wind(options.wind)
     let sway = false
-    if (options.bendHeight !== undefined) { state.bendHeight = options.bendHeight; sway = true }
     if (options.touch !== undefined) { state.touch = options.touch; sway = true }
     if (options.variation !== undefined) { state.variation = options.variation; sway = true }
     if (options.sunWrap !== undefined) { state.sunWrap = options.sunWrap; sway = true }
-    if (sway) _creator.foliageSetOptions?.(state.bendHeight, state.touch, state.variation, state.sunWrap)
+    if (sway) _creator.foliageSetOptions?.(state.touch, state.variation, state.sunWrap)
+    let leaf = false
+    if (options.shiver !== undefined) { state.shiver = options.shiver; leaf = true }
+    if (options.translucency !== undefined) { state.translucency = options.translucency; leaf = true }
+    if (options.leafShadow !== undefined) { state.leafShadow = options.leafShadow; leaf = true }
+    if (options.skyAo !== undefined) { state.skyAo = options.skyAo; leaf = true }
+    if (leaf) _creator.foliageSetLeaf?.(state.shiver, state.translucency, state.leafShadow, state.skyAo)
+    let look = false
+    if (options.canopy !== undefined) { state.canopy = options.canopy; look = true }
+    if (options.normalMap !== undefined) { state.normalMap = options.normalMap; look = true }
+    if (options.edgeFade !== undefined) { state.edgeFade = options.edgeFade; look = true }
+    if (options.coverage !== undefined) { state.coverage = options.coverage; look = true }
+    if (look) _creator.foliageSetLook?.(state.canopy, state.normalMap, state.edgeFade, state.coverage)
   },
 
   /** The wind: fields given replace the current ones; `false` = calm. Live. */
   wind(wind: FoliageWind | false): void {
     if (wind === false) state.wind = false
     else {
-      const cur = state.wind === false ? { direction: [ 1, 0.3 ] as [number, number], strength: 0.07, speed: 1.2, gust: 0.6 } : state.wind
-      state.wind = { direction: wind.direction ?? cur.direction, strength: wind.strength ?? cur.strength, speed: wind.speed ?? cur.speed, gust: wind.gust ?? cur.gust }
+      const cur = state.wind === false ? DEFAULT_WIND : state.wind
+      state.wind = {
+        direction: wind.direction ?? cur.direction, speed: wind.speed ?? cur.speed, turbulence: wind.turbulence ?? cur.turbulence,
+        gust: wind.gust ?? cur.gust, gustSpeed: wind.gustSpeed ?? cur.gustSpeed,
+      }
     }
     pushWind()
   },

package/src/gl/Geometry.ts

@@ -109,9 +109,8 @@ export class Geometry {
     if (typeof source !== "string") return Geometry.fromData(source)
     const url = source
     const resp = await fetch(url, { useOnce: true })
-    if (resp.status >= 400) { resp.dispose(); throw new Error(`Geometry.load: ${url} → HTTP ${resp.status}`) }
+    if (resp.status >= 400) { throw new Error(`Geometry.load: ${url} → HTTP ${resp.status}`) }
     const data = resp.json<GeometryData>()
-    resp.dispose()
     return Geometry.fromData(data)
   }
 }

package/src/gl/Light.ts

@@ -38,6 +38,13 @@ export type SunOptions = {
    * the same quality and puts fewer casters in the shadow pass. 30-40 is plenty in first person.
    */
   shadowDistance?: number
+  /**
+   * How many shadow-map cascades split `shadowDistance` (default 1). One map over the whole range gives a tall
+   * tree 5-10 cm shadow texels on its own trunk; 3 cascades put a tight map on the first metres and coarser
+   * ones behind, fit to their texel grids so the shadow does not swim as the camera moves. Each cascade is
+   * another caster pass, so it costs in proportion to what casts: forests, not a lightmapped level.
+   */
+  shadowCascades?: 1 | 2 | 3 | 4
 }
 
 export type PointOptions = {
@@ -99,6 +106,7 @@ export class Light extends Node {
   /** @internal sun shadow options as created (creation-time in the engine). */
   _shadowsQuality = 1
   _shadowDistance = 100
+  _shadowCascades = 1
 
   /** A directional sun light. */
   static sun(options: SunOptions = {}): Light {
@@ -109,6 +117,7 @@ export class Light extends Node {
     light._color = options.color ?? 0xffffff
     light._shadowsQuality = options.shadowsQuality ?? 1
     light._shadowDistance = options.shadowDistance ?? 100
+    light._shadowCascades = options.shadowCascades ?? 1
     Light.lastSun = light
     _creator.createSunLight(
       light.id, dx, dy, dz,
@@ -116,6 +125,7 @@ export class Light extends Node {
       Color.toPackedRgb(options.color ?? 0xffffff),
       options.shadowsQuality ?? 1,
       options.shadowDistance ?? 100,
+      light._shadowCascades,
     )
     return light
   }