lecodes-sdk 1.1.0 → 2.0.0

package/src/gl/Scene.ts

@@ -7,7 +7,9 @@
 
 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, _navEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
+import { _bumpNavEpoch, _navEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
+import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
+import { TREE_DEST_SCENE3D, TREE_FLAG_BACK, ensureEmitter, registerDest, unregisterDest } from "../ui/tree"
 import { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
@@ -17,7 +19,7 @@ import { SceneAudio } from "./audio/SceneAudio"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
 import { Texture } from "./Texture"
-import { Node, nodeRegistry } from "./Node"
+import { Node, nodes } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 
@@ -32,6 +34,21 @@ export type AmbientOcclusionOptions = {
   quality?: "low" | "medium" | "high" | "ultra"
 }
 
+/** `SceneOptions.taa` / `scene.setAntialias("taa", 4, taa)`: the temporal anti-aliasing knobs. */
+export type TaaOptions = {
+  /** Render the 3D at this fraction (0.5–1) and TAA-upscale it to the viewport; 1 = none. */
+  upscale?: number
+  /** The history's share, 0 (max smoothing) … 1 (none); 0.12 default. */
+  feedback?: number
+  /** Post-TAA sharpen 0–1; defaults to 0.5 with `upscale` below 1, else 0. */
+  sharpness?: number
+  /** A first-person viewmodel: everything closer than this many metres to the camera is treated as
+   *  fixed on screen — its history is read at the same pixel, not reprojected by the camera's motion,
+   *  which would trail the weapon on every turn (TAA has no per-object motion vectors). 1 covers arms
+   *  and weapon at eye height; 0 (the default) = off. A wall walked into within the band smears a little. */
+  viewmodel?: number
+}
+
 export type FogOptions = {
   /** A TINT on the in-scattered ambient, not an absolute colour: the engine multiplies it by the
    *  environment luminance, so white (the default) means "fog as bright as the ambient" and the fog
@@ -105,10 +122,18 @@ export type SceneOptions = {
    *  at every distance — the skybox included — so the sky itself takes the fog colour and the horizon
    *  blends on its own; `cutoff` opts geometry beyond a distance back out. */
   fog?: FogOptions
-  /** Multisample anti-aliasing: `true` = 4×, `2`/`4` = that many samples, `false` = off (FXAA
-   *  takes over). Unset keeps the host default (desktop 4×, mobile/web off). The biggest single
-   *  fill-rate cost after resolution — turn it down on big screens before anything else. */
-  antialias?: boolean | 2 | 4
+  /** Anti-aliasing: `true` = 4× MSAA, `2`/`4` = that many samples, `false` = off (FXAA takes over),
+   *  `"taa"` = temporal anti-aliasing (Filament's TAA: one full-screen history blend instead of the
+   *  multisampled buffers — cheaper than MSAA on an integrated GPU and it also calms specular and
+   *  foliage shimmer; see `taa` for its knobs). Unset keeps the host default (desktop 4×, mobile/web
+   *  off). The biggest single fill-rate cost after resolution — turn it down on big screens first. */
+  antialias?: boolean | 2 | 4 | "taa"
+  /** The TAA's knobs (`antialias: "taa"`): `upscale` = render the 3D at this fraction (0.5–1) and let
+   *  TAA reconstruct the full resolution — the cheap way to a lower render cost with most of the
+   *  detail kept (`renderScale` shrinks the buffer and stretches it instead); `feedback` = the
+   *  history's share, 0.12 by default (raise it toward 0.3 if fast motion ghosts); `sharpness` =
+   *  a post-TAA sharpen 0–1, useful with `upscale`. */
+  taa?: TaaOptions
   /** Keep a stencil buffer for this scene (off by default: it costs memory and a clear per frame).
    *  Needed before any material's `stencil` test or write does anything. */
   stencil?: boolean
@@ -214,7 +239,7 @@ export class Scene implements Presentable {
       // `asset()` hands back "id:<n>" (already staged); a bare name is resolved on the spot; -1 is
       // "no probe named", which leaves the host on the project-wide `ibl.ktx` (the old behaviour).
       const src = typeof options.ibl === "string" ? options.ibl : undefined
-      const iblId = src === undefined ? -1 : src.startsWith("id:") ? Number(src.slice(3)) : _creatorUtils.fetchLocal(src)
+      const iblId = src === undefined ? -1 : src.startsWith("id:") ? Number(src.slice(3)) : _creatorFetch.local(src)
       _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000, iblId)
     }
     this._environmentIntensity = options.ibl === false ? 0 : (options.environmentIntensity ?? 20000)
@@ -229,7 +254,7 @@ export class Scene implements Presentable {
     if (options.antialias !== undefined) {
       const a = options.antialias
       // `false` must reach the host: desktop defaults to 4× MSAA, so an explicit off is a real change.
-      _creator.setSceneMultiSampleAntiAliasing(this._id, a !== false, typeof a === "number" ? a : 4)
+      this.setAntialias(a, 4, options.taa)
     }
     if (options.stencil !== undefined) this.setStencil(options.stencil)
     // Before anything else in this constructor that could load a texture: the value has to be in
@@ -252,9 +277,15 @@ export class Scene implements Presentable {
     _creator.setSceneRenderOptions?.(this._id, renderScale, !!dynamicResolution, min)
   }
 
-  /** Scene occlusion material. */
+  /** Scene occlusion material: an unlit instance in the occluder blue (the built-in `unlit`, which
+   *  every runtime carries) — one per scene, made on first use. */
   get occlusionMaterial(): Material {
-    if (!this._material) this._material = new Material(_creator.getSceneMaterial(this._id))
+    if (!this._material) {
+      const h = _creator.builtinMaterial("unlit")
+      if (!h) throw new Error("Scene.occlusionMaterial: this host carries no unlit material")
+      this._material = new Material(h)
+      this._material.uniforms.baseColor = [0.1, 0.25, 0.57, 1.0]
+    }
     return this._material
   }
 
@@ -263,7 +294,7 @@ export class Scene implements Presentable {
     if (typeof sky === "object" && sky !== null && "texture" in sky) {
       const src = sky.texture
       // `asset()` hands back "id:<n>" (already staged); a bare name is resolved on the spot.
-      const id = src.startsWith("id:") ? Number(src.slice(3)) : _creatorUtils.fetchLocal(src)
+      const id = src.startsWith("id:") ? Number(src.slice(3)) : _creatorFetch.local(src)
       _creator.setSkyboxTexture?.(this._id, id)
       return
     }
@@ -290,8 +321,19 @@ export class Scene implements Presentable {
   setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void {
     _creator.setMaterialGlobalParameter(this._id, i, x, y, z, w)
   }
-  setAntialias(enabled: boolean, scale = 4): void {
-    _creator.setSceneMultiSampleAntiAliasing(this._id, enabled, scale)
+  setAntialias(mode: boolean | 2 | 4 | "taa", scale = 4, taa?: TaaOptions): void {
+    if (mode === "taa") {
+      if (!_creator.setTemporalAntiAliasing) {   // an older host: the nearest thing it has
+        _creator.setSceneMultiSampleAntiAliasing(this._id, true, scale)
+        return
+      }
+      const up = taa?.upscale ?? 1
+      _creator.setTemporalAntiAliasing(this._id, true, taa?.feedback ?? 0.12, taa?.sharpness ?? (up < 1 ? 0.5 : 0), up < 0.5 ? 0.5 : up > 1 ? 1 : up, taa?.viewmodel ?? 0)
+      return
+    }
+    // `false` must reach the host: desktop defaults to 4× MSAA, so an explicit off is a real change.
+    _creator.setTemporalAntiAliasing?.(this._id, false, 0.12, 0, 1, 0)
+    _creator.setSceneMultiSampleAntiAliasing(this._id, mode !== false, typeof mode === "number" ? mode : scale)
   }
   /** Depth-reading effects on / off (a graphics-settings menu): soft particles and projected decals
    *  read the scene depth, which costs a depth pre-pass of every opaque draw (~12 % of a fill-bound
@@ -336,12 +378,15 @@ export class Scene implements Presentable {
     else if (enabled) console.warn("[scene] this host has no setSceneStencil — stencil ignored")
   }
 
-  add(...nodes: Node[]): this {
-    for (const n of nodes) _creator.addEntityToScene(this._id, n.id)
+  add(...list: Node[]): this {
+    for (const n of list) { _creator.addEntityToScene(this._id, n.id); nodes.pin(n) }   // the scene owns it now
     return this
   }
-  remove(...nodes: Node[]): this {
-    for (const n of nodes) _creator.removeEntityFromScene(this._id, n.id)
+  remove(...list: Node[]): this {
+    for (const n of list) {
+      _creator.removeEntityFromScene(this._id, n.id)
+      if (!_creator.entityIsOwned(n.id)) nodes.unpin(n.id)   // loose again: its handle owns it
+    }
     return this
   }
 
@@ -422,39 +467,47 @@ export class Scene 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
   }
-
-  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
-  _viewDesc(): object {
-    return this._vd ??= { type: "scene3d", sceneId: this._id, _p: 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 The destination tuple (ui/presentable.ts). */
+  _dest(): DestTuple {
+    // Addressed by the router / an attached widget: make sure the (kind, id) resolves back to us.
+    registerDest(TREE_DEST_SCENE3D, this._id, this)
+    return [TREE_DEST_SCENE3D, 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 /
-   *  another scene; only the active scene renders). */
+   *  another scene; only the active scene renders). The runtime activates the engine as part of
+   *  presenting the destination. */
   open(options?: PresentOptions): void | Promise<void> {
     _bumpNavEpoch()
-    if (_navSupported()) {
-      // The host activates the engine (openScene) as part of presenting the destination.
-      _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
-    } else {
-      _creator.openScene(this._id)
-      for (const cb of this.ol) cb()
-    }
+    ensureEmitter()
+    registerDest(TREE_DEST_SCENE3D, this._id, this)
+    _creatorTree.open(TREE_DEST_SCENE3D, this._id, "", "", _transitionId(options?.transition, TRANSITION_NONE))
     Scene._active = this
     glState.activeScene = this
     _setCurrent(this)
   }
-  close(): void {
+  close(options?: DismissOptions): void {
     _bumpNavEpoch()
-    if (_navSupported()) {
-      _creatorUI.closeView!()
-    } else {
-      _creator.closeScene()
-      for (const cb of this.cl) cb()
-    }
+    _creatorTree.close(TREE_DEST_SCENE3D, this._id, _transitionId(options?.transition, TRANSITION_NONE))
     if (Scene._active === this) Scene._active = null
     if (glState.activeScene === this) glState.activeScene = null
     if (Presentable.current === this) _setCurrent(null)
@@ -481,7 +534,7 @@ export class Scene implements Presentable {
 export type ARMode = "default" | "markers" | "arcore" | "detached"
 
 const onTrackStateChange = (entityId: number, track: boolean): void => {
-  const node = nodeRegistry.get(entityId)
+  const node = nodes.get(entityId)
   if (!node) return
   node.isTracked = track
   if (track) node._dispatchEvent("track")
@@ -508,7 +561,7 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
 
   /** Create an anchor from a tracking source (e.g. an image target). */
   createAnchor(source: FetchResponse, physicalWidth = 0.2): Node {
-    return new Node(_creator.createAnchor(this._id, physicalWidth, (source as any)._id))
+    return new Node(_creator.createAnchor(this._id, physicalWidth, (source as any)._h.id))
   }
 
   /**
@@ -543,9 +596,12 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
     }
   }
 
-  override close(): void {
-    _creator.stopAR()
-    super.close()
+  override close(options?: DismissOptions): void {
+    // The session is this scene's unless another ARScene is on screen now: a late close of a scene
+    // something already replaced must not stop the next one's session.
+    const current = Presentable.current
+    if (!(current instanceof ARScene) || current === this) _creator.stopAR()
+    super.close(options)
   }
 }
 
@@ -565,8 +621,8 @@ export class VRScene extends Scene {
     super.open(options)
   }
 
-  override close(): void {
+  override close(options?: DismissOptions): void {
     _creator.stopVR()
-    super.close()
+    super.close(options)
   }
 }

package/src/gl/Texture.ts

@@ -37,8 +37,9 @@ export class Texture {
     Texture._maxSize = size > 0 ? Math.floor(size) : 0
     _creator.setTextureMaxSize?.(Texture._maxSize)
   }
-  /** @internal native texture handle. */
-  readonly _id: number
+  /** @internal The texture's owned handle (`_h.id` = the engine id). A texture the engine or another
+   *  object owns (a canvas's, a video player's) is wrapped from its number and never freed by us. */
+  readonly _h: Handle
   readonly width: number
   readonly height: number
 
@@ -47,10 +48,10 @@ export class Texture {
   /** Vertical wrap mode (V). */
   wrapT = 1
 
-  constructor(width: number, height: number, id: number) {
+  constructor(width: number, height: number, id: Handle | number) {
     this.width = width
     this.height = height
-    this._id = id
+    this._h = typeof id === "number" ? { id } : id
   }
 
   // Wrap a Canvas's baked surface as a 3D texture (RGBA8, already rasterized → synchronous, no decode).
@@ -72,13 +73,13 @@ export class Texture {
     const channels = opts.channels ?? 4
     if (data.length < width * height * channels) throw new Error(`Texture.fromPixels: ${data.length} bytes for ${width}×${height}×${channels}`)
     const id = _creator.createTexturePixels(width, height, channels, data, opts.srgb ?? true)
-    if (id === 0xFFFFFFFF) throw new Error("Texture.fromPixels: the host refused the texture")
+    if (id.id === 0xFFFFFFFF) throw new Error("Texture.fromPixels: the host refused the texture")
     return new Texture(width, height, id)
   }
 
   /** Re-upload a rectangle of a `fromPixels` texture (same channel count). */
   update(x: number, y: number, width: number, height: number, data: Uint8Array): void {
-    _creator.updateTexturePixels?.(this._id, x, y, width, height, data)
+    _creator.updateTexturePixels?.(this._h.id, x, y, width, height, data)
   }
 
   /** Decode an image (PNG / JPG, or a KTX2 the core transcodes) into a texture. `srgb` (default
@@ -97,7 +98,7 @@ export class Texture {
     }
     const flags = (options.srgb === false ? TEXTURE_FLAG_LINEAR : 0) | (options.fullSize ? TEXTURE_FLAG_FULL_SIZE : 0)
     return new Promise<Texture>((resolve, reject) => {
-      _creator.createTexture((source as any)._id, (id, w, h) => resolve(new Texture(w, h, id)), reject, flags)
+      _creator.createTexture((source as any)._h.id, (id, w, h) => resolve(new Texture(w, h, id)), reject, flags)
     })
   }
 }

package/src/gl/animation/AnimationClip.ts

@@ -270,7 +270,7 @@ export class AnimationClip {
       })
     }
     return new Promise<[number, ClipInfo[]]>((resolve, reject) => {
-      _creator.loadClips((source as unknown as { _id: number })._id, (setId: number) => {
+      _creator.loadClips((source as unknown as { _h: Handle })._h.id, (setId: number) => {
         if (setId === 0) { reject(new Error("AnimationClip.load: the file has no animations (or is not a GLB)")); return }
         resolve([setId, readInfo(setId)])
       }, reject)

package/src/gl/animation/Locomotion.ts

@@ -37,8 +37,9 @@ import type { Node } from "../Node"
 
 /** How fast the character wants to go: the gait picks its clips and its speed. */
 export type Gait = "walk" | "run" | "sprint"
-/** What the engine shows: the idle, a start, the gait loop, a turn while moving, a stop, or a turn on the spot. */
-export type LocomotionState = "idle" | "start" | "move" | "turn" | "stop" | "spin"
+/** What the engine shows: the idle, a start, the gait loop, a turn while moving, a stop, a turn on the spot —
+ *  an ACTION (`act()`): a one-shot that owns the body until it hands over — or the STRAFE blend (`move({ strafe })`). */
+export type LocomotionState = "idle" | "start" | "move" | "turn" | "stop" | "spin" | "action" | "strafe"
 /** Who moves the body:
  *  `'hybrid'` (the default) — the clip's own recorded motion moves it; while the gait loop shows it
  *    is ADJUSTED toward what the simulation wants by at most `tuning.adjust` metres a second, and a
@@ -70,6 +71,10 @@ export type LocomotionSet = {
   turns?: LocomotionClip[]
   /** turns on the spot — what a facing still owed by a standing body plays */
   spins?: LocomotionClip[]
+  /** the STRAFE set: the same gait recorded forward, backward, to either side and on the diagonals — the members of
+   *  the directional blend `move(dir, { face, strafe: true })` shows. `angle` = the way a take travels in the body's
+   *  frame (degrees, + = left); left out, the engine reads it off the take's root. */
+  strafes?: LocomotionClip[]
 }
 
 /** The tuning. Times are seconds, speeds m/s, angles degrees. */
@@ -201,7 +206,7 @@ export type StopCandidate = {
 
 const STOP_ROW = 9
 const STOP_ROWS = 8
-const IN = { DIR_X: 0, DIR_Z: 1, MAG: 2, FACE_X: 3, FACE_Z: 4, GAIT: 5, COUNT: 6 }
+const IN = { DIR_X: 0, DIR_Z: 1, MAG: 2, FACE_X: 3, FACE_Z: 4, GAIT: 5, ACT_SEQ: 6, ACT_SLOT: 7, ACT_DIR_X: 8, ACT_DIR_Z: 9, ACT_ANGLE: 10, ACT_TURN: 11, ACT_AT: 12, ACT_EXIT: 13, ACT_FADE: 14, ACT_RATE: 15, ACT_OUT: 16, ACT_TRAVEL: 17, ACT_TRAVEL_AT: 18, ACT_TRAVEL_AFTER: 19, STRAFE: 20, ACT_DASH: 21, ACT_DASH_TIME: 22, COUNT: 23 }
 const OUT = { STATE: 0, SPEED: 1, VEL_X: 2, VEL_Y: 3, VEL_Z: 4, YAW: 5, YAW_RATE: 6, PHASE: 7, SEQ: 8, PRED: 9, YAW_LEFT: 21, CLIP_TIME: 22, EXIT_AT: 23, STOP_OFF: 24, STOP_STEPS: 25, STOP_WAIT: 26, COUNT: 27 }
 const P = {
   HALFLIFE_WALK: 0, HALFLIFE_RUN: 1, HALFLIFE_FACING: 2, SPEED_WALK: 3, SPEED_RUN: 4, SPEED_SPRINT: 5,
@@ -210,8 +215,8 @@ const P = {
   HALFLIFE_STOP: 20, ADJUST: 21, YAW_WARP: 22, EXIT_TOL: 23, RESUME_SPEED: 24, EXIT_STEPS: 25, STOP_EARLY: 26, STOP_STEPS: 27, STOP_FIT: 28, STOP_POSE: 29,
   STRIDE_SHARE: 30, STRIDE_MIN: 31, STRIDE_MAX: 32, WARP_STRIDE: 33, WARP_RATE: 34, COUNT: 35,
 }
-const KIND = { IDLE: 0, GAIT: 1, START: 2, STOP: 3, TURN: 4, MATCH: 5, SPIN: 6 }
-const STATES: LocomotionState[] = [ "idle", "start", "move", "turn", "stop", "spin" ]
+const KIND = { IDLE: 0, GAIT: 1, START: 2, STOP: 3, TURN: 4, MATCH: 5, SPIN: 6, STRAFE: 8 }
+const STATES: LocomotionState[] = [ "idle", "start", "move", "turn", "stop", "spin", "action", "strafe" ]
 const GAITS: Gait[] = [ "walk", "run", "sprint" ]
 const RAD2DEG = 180 / Math.PI
 
@@ -249,6 +254,8 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
   private _mag = 0
   private _gait: Gait = "walk"
   private _seq = -1
+  private _act = 0
+  private _strafe = false
   private readonly _in = new Float32Array(IN.COUNT)
   private readonly _out = new Float32Array(OUT.COUNT)
   private readonly _names = new Map<number, string>()
@@ -290,6 +297,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     for (const c of this.set.stops ?? []) this.enter(c, KIND.STOP)
     for (const c of this.set.turns ?? []) this.enter(c, KIND.TURN)
     for (const c of this.set.spins ?? []) this.enter(c, KIND.SPIN)
+    for (const c of this.set.strafes ?? []) this.enter(c, KIND.STRAFE)
     if (this.warp !== undefined) anim.warp.set(this.warp)
     anim.feet.set(this.feet === undefined ? { lock: true } : this.feet === true ? { lock: true, ik: true } : this.feet === false ? { lock: false, ik: false } : this.feet)
     this.pushTuning()
@@ -306,7 +314,8 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     this._names.set(slot, n)
     const o = typeof clip === "string" ? undefined : clip
     const measured = anim.clipInfo(n)
-    const angle = o?.angle ?? (measured ? measured.turn * RAD2DEG : 0)
+    // (a strafe member's angle is the way it TRAVELS, which the engine reads off its root: 1000 = measure)
+    const angle = o?.angle ?? (kind === KIND.STRAFE ? 1000 : measured ? measured.turn * RAD2DEG : 0)
     const gait = kind === KIND.GAIT ? -1 : o?.gait ? GAITS.indexOf(o.gait) : -1
     _creator.locoSetEntry(this._loco, slot, kind, angle, o?.speed ?? 0, gait)
   }
@@ -379,8 +388,11 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
   /** State the movement intent for this frame: a world direction (its length is the stick's pull,
    *  clamped to 1) and the gait. `null` = no movement — the body stops, but it keeps facing where it
    *  was last asked to, and turns there on the spot if it still owes the turn.
-   *  `face` states a facing of its own (aiming, strafing, a camera-relative shooter). */
-  move(direction: Vec3Like | null | undefined, options: { gait?: Gait, face?: Vec3Like } = {}): void {
+   *  `face` states a facing of its own (aiming, a camera-relative shooter) — and with `strafe: true` the body MOVES
+   *  where the direction points while it faces there: the loop becomes the directional blend of `set.strafes` (a
+   *  guard, a lock-on), the facing is steered standing too, state `'strafe'`. Stated every frame like the rest. */
+  move(direction: Vec3Like | null | undefined, options: { gait?: Gait, face?: Vec3Like, strafe?: boolean } = {}): void {
+    this._strafe = !!options.strafe
     const dx = direction ? cx(direction) : 0, dz = direction ? cz(direction) : 0
     const len = Math.hypot(dx, dz)
     if (len > 1e-4) {
@@ -395,6 +407,62 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     if (options.gait) this._gait = options.gait
   }
 
+  /** Play an ACTION: a one-shot that OWNS the body the way a start or a stop does — a roll, a backstep, a lunging
+   *  attack. Its recording moves the body alone (in every displacement mode but `'data'`, where the host does),
+   *  the steering and the selector stand by, and when it hands over the usual rules carry on: a direction held
+   *  starts (or, still carrying speed, runs on), nothing held stands.
+   *
+   *  `direction` is where its TRAVEL must go, world (`Vec3`, or a heading in degrees, 0 = +Z, + = toward +X). A
+   *  clip travels some way relative to the body — forward, left, back; measured off its own root, or `angle`
+   *  (degrees, + = left) — and the body is turned by what is left between that and `direction`, over `turn`
+   *  seconds (default 0.12), so the travel lands exactly where it was pointed. Which clip to play is yours to
+   *  pick: the one whose travel is nearest the direction IN THE BODY'S FRAME (`direction − facing`) leaves the
+   *  least to turn. Left out = it plays where the body faces.
+   *
+   *  `at` enters the clip that many seconds in (a wind-up skipped), `rate` plays it faster or slower (its metres
+   *  stay, the time changes), `travel` takes only that share of its recorded travel (an attack aimed at a target:
+   *  0.3 to stop at the blade's length from one that is close, 1.3 to reach one a step too far — the pose is
+   *  untouched, so keep it to a fast step; `{ share, at, after }` takes another share from clip time `at` on: a
+   *  swing's take travels on after its cut, into a body that stands at the blade's length), `dash` THROWS the body
+   *  `distance` metres along the action's direction on top of that, inside `time` seconds (default 0.12) from its first
+   *  step, eased out — the gap to a target closed in the wind-up, the blow struck from where it lands (scaling a take's
+   *  own step is a slide stretched over the whole swing), `fade` is the transition into it and `out` the one out of it (default: the tuning's
+   *  `blend`; an action ends in ITS stance, not the idle's, and a longer way out is what hides that), and `exit` is the
+   *  clip time from which a MOVE intent may take over — the cancel window: along the way the body faces at once, a
+   *  heading that needs a turn as soon as the body has slowed to where a start can answer; with nothing asked for it plays out, to
+   *  its end (an action ends in its own recovery, at rest), and the body then STANDS THE WAY THE ACTION LEFT IT:
+   *  the facing intent that outlives a released key is not a demand after an action — no turn on the spot.
+   *  WHEN an action may be asked for (out of another one, out of a start) is the caller's rule: this cuts into
+   *  whatever shows. `state` reads `'action'` while it does. False = no such clip. */
+  act(clip: string, options: { direction?: Vec3Like | number, angle?: number, turn?: number, at?: number, exit?: number, fade?: number, out?: number, rate?: number, travel?: number | { share: number, at: number, after: number }, dash?: { distance: number, time?: number } } = {}): boolean {
+    const anim = this.anim
+    if (!anim || !this._loco) return false
+    const slot = anim._slot(clip)
+    if (slot < 0) { console.warn(`Locomotion: no clip '${clip}' on ${this.node.name || "the character"}`); return false }
+    const i = this._in
+    let dx = 0, dz = 0
+    const d = options.direction
+    if (typeof d === "number") { dx = Math.sin(d / RAD2DEG); dz = Math.cos(d / RAD2DEG) }
+    else if (d) { dx = cx(d); dz = cz(d) }
+    i[IN.ACT_SEQ] = ++this._act
+    i[IN.ACT_SLOT] = slot
+    i[IN.ACT_DIR_X] = dx; i[IN.ACT_DIR_Z] = dz
+    i[IN.ACT_ANGLE] = options.angle ?? 1000            // 1000 = measure the clip's own travel
+    i[IN.ACT_TURN] = options.turn ?? 0.12
+    i[IN.ACT_AT] = options.at ?? 0
+    i[IN.ACT_EXIT] = options.exit ?? 0
+    i[IN.ACT_FADE] = options.fade ?? 0
+    i[IN.ACT_RATE] = options.rate ?? 0
+    i[IN.ACT_OUT] = options.out ?? 0
+    const tr = options.travel
+    i[IN.ACT_TRAVEL] = typeof tr === "number" ? tr : tr?.share ?? 0
+    i[IN.ACT_TRAVEL_AT] = typeof tr === "object" ? tr.at : 0
+    i[IN.ACT_TRAVEL_AFTER] = typeof tr === "object" ? tr.after : 0
+    i[IN.ACT_DASH] = options.dash?.distance ?? 0
+    i[IN.ACT_DASH_TIME] = options.dash?.time ?? 0.12
+    return true
+  }
+
   /** Face this way without moving — the facing intent on its own (`Vec3`, or a heading in degrees,
    *  0 = +Z, + = toward +X). A standing body turns to it on the spot. */
   face(direction: Vec3Like | number): void {
@@ -477,6 +545,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     i[IN.DIR_X] = this._dir.x; i[IN.DIR_Z] = this._dir.z; i[IN.MAG] = this._mag
     i[IN.FACE_X] = this._face.x; i[IN.FACE_Z] = this._face.z
     i[IN.GAIT] = Math.max(0, GAITS.indexOf(this._gait))
+    i[IN.STRAFE] = this._strafe ? 1 : 0
     _creator.locoSetInput(this._loco, i)
     _creator.locoUpdate(this._loco, dt)
     _creator.locoRead(this._loco, this._out)

package/src/gl/nav/NavMesh.ts

@@ -185,8 +185,7 @@ export class NavMesh {
     try {
       const resp = await fetch(opts.data, { useOnce: true })
       if (resp.status >= 400) { console.warn(`NavMesh: no navmesh at ${opts.data} (HTTP ${resp.status}) — run \`lecodes navmesh bake\``); return null }
-      id = _creatorNav.load((resp as unknown as { _id: number })._id)
-      resp.dispose()
+      id = _creatorNav.load((resp as unknown as { _h: Handle })._h.id)
     } catch (e) {
       console.warn(`NavMesh: could not read ${opts.data}: ${String(e)}`)
       return null
@@ -275,7 +274,7 @@ export class NavMesh {
     const e = opts?.extents
     const max = Math.min(opts?.maxCorners ?? 256, 256)
     const n = _creatorNav.findPath(this.id, cx(from), cy(from), cz(from), cx(to), cy(to), cz(to),
-      e ? cx(e) : 0, e ? cy(e) : 0, e ? cz(e) : 0, inc, exc, max, pathScratch)
+      e ? cx(e) : 0, e ? cy(e) : 0, e ? cz(e) : 0, inc, exc, max < 256 ? pathScratch.subarray(0, max * 3) : pathScratch)
     const count = Math.abs(n)
     for (let i = 0; i < count; i++) path.push(new Vec3(pathScratch[i * 3]!, pathScratch[i * 3 + 1]!, pathScratch[i * 3 + 2]!))
     path.partial = n < 0
@@ -370,7 +369,7 @@ export class NavMesh {
     if (NavMesh.baked) { console.log("[navmesh] a second NavMesh.load — skipped (one bake per run; use --entry per scene)"); return }
     NavMesh.baked = true
     if (!_creator.physicsStaticGeometry) {
-      console.error("[navmesh] error: this host cannot dump collision geometry (build the desktop host from packages/desktop, or update: lecodes desktop update)")
+      console.error("[navmesh] error: this host cannot dump collision geometry (build the desktop host from hosts/desktop, or update: lecodes desktop update)")
       return
     }
     const areaIds = NavMesh.areaIds(opts.areas)

package/src/gl/physics/Physics.ts

@@ -15,7 +15,7 @@ import { Aspect } from "../../core/Aspect"
 import type { FieldMeta } from "../../core/fields"
 import type { CompAxis, CompWriter } from "../../core/compWrite"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
-import { nodeRegistry, type Node } from "../Node"
+import { nodes, type Node } from "../Node"
 import { Shape } from "./Shape"
 
 export type MotionType = "static" | "dynamic" | "kinematic"
@@ -220,7 +220,7 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
     const id = _creator.physicsRaycast(cx(origin), cy(origin), cz(origin), cx(dir), cy(dir), cz(dir), maxDist, out)
     if (!id) return null
     return {
-      node: nodeRegistry.get(id) ?? null,
+      node: nodes.get(id) ?? null,
       point: new Vec3(out[0], out[1], out[2]),
       normal: new Vec3(out[3], out[4], out[5]),
       fraction: out[6],

package/src/gl/physics/physicsEvents.ts

@@ -2,7 +2,7 @@
 // is delivered to BOTH nodes with the other as the argument. type: 0 = enter (contact/overlap began),
 // 1 = exit (ended). Registered lazily on the first trigger/physics body or 'enter'/'exit' listener.
 
-import { nodeRegistry } from "../Node"
+import { nodes } from "../Node"
 
 let registered = false
 export const ensurePhysicsEvents = (): void => {
@@ -10,8 +10,8 @@ export const ensurePhysicsEvents = (): void => {
   if (!_creator.setOnPhysicsEvent) return // physics-less build / bridge without the hook
   registered = true
   _creator.setOnPhysicsEvent((a, b, type) => {
-    const na = nodeRegistry.get(a)
-    const nb = nodeRegistry.get(b)
+    const na = nodes.get(a)
+    const nb = nodes.get(b)
     if (!na || !nb) return
     const channel = type === 1 ? "exit" : "enter"
     na._emitCollision(channel, nb)

package/src/gl/terrain/Terrain.ts

@@ -236,9 +236,8 @@ export class Terrain {
   static async load(url: string, opts: Omit<TerrainOptions, "size" | "sizeX" | "sizeZ" | "heights" | "holes" | "control"> = {}): Promise<Terrain> {
     const resp = await fetch(url, { useOnce: true })
     if (resp.status >= 400) throw new Error(`Terrain: could not fetch ${url} (HTTP ${resp.status})`)
-    if (!_creatorUtils.fetchToBytes) { resp.dispose(); throw new Error("Terrain.load needs a newer host (no binary fetch reader)") }
-    const bytes = _creatorUtils.fetchToBytes((resp as unknown as { _id: number })._id)
-    resp.dispose()
+    if (!_creatorFetch.toBytes) { throw new Error("Terrain.load needs a newer host (no binary fetch reader)") }
+    const bytes = _creatorFetch.toBytes((resp as unknown as { _h: Handle })._h.id)
     const data = Terrain.parse(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer)
     const layers = opts.layers ?? data.layers
     return new Terrain({ ...opts, ...data, layers, cellSize: opts.cellSize ?? data.cellSize, chunk: opts.chunk ?? data.chunk })
@@ -259,6 +258,35 @@ export class Terrain {
     return new Vec3(n[0], n[1], n[2])
   }
 
+  /** The LAYER WEIGHTS at a local (x, z) — what the splat shader blends there: the control map read bilinearly
+   *  between its samples and normalised to sum 1 (`[1, 0, 0, 0]` where the map is empty, as the shader has
+   *  it). Index = the layer's in `layers`. Outside the grid the edge answers. This is how a game asks WHAT the
+   *  ground is under a point — footprints in the sand and none on the cobble, a footstep sound per layer, dust
+   *  by surface — and the blend is already in the numbers, so a transition is a fade and not a line. */
+  weightsAt(x: number, z: number): [number, number, number, number] {
+    const fx = Math.min(this.sizeX - 1, Math.max(0, x / this.cellSize)), fz = Math.min(this.sizeZ - 1, Math.max(0, z / this.cellSize))
+    const x0 = Math.floor(fx), z0 = Math.floor(fz), x1 = Math.min(this.sizeX - 1, x0 + 1), z1 = Math.min(this.sizeZ - 1, z0 + 1)
+    const u = fx - x0, v = fz - z0
+    const c = this.control
+    const w: [number, number, number, number] = [ 0, 0, 0, 0 ]
+    for (let k = 0; k < 4; k++) {
+      const a = c[(z0 * this.sizeX + x0) * 4 + k], b = c[(z0 * this.sizeX + x1) * 4 + k]
+      const d = c[(z1 * this.sizeX + x0) * 4 + k], e = c[(z1 * this.sizeX + x1) * 4 + k]
+      w[k] = (a + (b - a) * u) * (1 - v) + (d + (e - d) * u) * v
+    }
+    const sum = w[0] + w[1] + w[2] + w[3]
+    if (sum <= 1e-4 * 255) return [ 1, 0, 0, 0 ]
+    return [ w[0] / sum, w[1] / sum, w[2] / sum, w[3] / sum ]
+  }
+
+  /** The heaviest layer's index at a local (x, z) — `weightsAt` when only "which one" is asked. */
+  layerAt(x: number, z: number): number {
+    const w = this.weightsAt(x, z)
+    let best = 0
+    for (let k = 1; k < 4; k++) if (w[k] > w[best]) best = k
+    return best
+  }
+
   /** The smooth (vertex) normal at integer sample (ix, iz). */
   sampleNormal(ix: number, iz: number): Vec3 {
     const n = gridNormalAt(this._grid, ix, iz)
@@ -831,7 +859,7 @@ export class Terrain {
     }
     if (!this._controlTex) {
       const id = _creator.createTexturePixels(this.sizeX, this.sizeZ, 4, this.control, false)
-      if (id === 0xFFFFFFFF) return
+      if (id.id === 0xFFFFFFFF) return
       this._controlTex = new Texture(this.sizeX, this.sizeZ, id)
       this._controlTex.wrapS = 0
       this._controlTex.wrapT = 0
@@ -842,7 +870,7 @@ export class Terrain {
     const w = r.x1 - r.x0 + 1, h = r.z1 - r.z0 + 1
     const sub = new Uint8Array(w * h * 4)
     for (let z = 0; z < h; z++) sub.set(this.control.subarray(((r.z0 + z) * this.sizeX + r.x0) * 4, ((r.z0 + z) * this.sizeX + r.x0 + w) * 4), z * w * 4)
-    _creator.updateTexturePixels(this._controlTex._id, r.x0, r.z0, w, h, sub)
+    _creator.updateTexturePixels(this._controlTex._h.id, r.x0, r.z0, w, h, sub)
   }
 
   private async _applyLayers(normals?: TerrainOptions["normals"]): Promise<void> {