lecodes-sdk 0.19.2 → 0.20.2

package/src/gl/Light.ts

@@ -67,6 +67,11 @@ export class Light extends Node {
   _direction: [number, number, number] = [ 0, -1, 0 ]
   /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
   static lastSun: Light | null = null
+  /** @internal the colour as created / last set (a settings menu recreates a sun from these). */
+  _color: ColorInput = 0xffffff
+  /** @internal sun shadow options as created (creation-time in the engine). */
+  _shadowsQuality = 1
+  _shadowDistance = 100
 
   /** A directional sun light. */
   static sun(options: SunOptions = {}): Light {
@@ -74,6 +79,9 @@ export class Light extends Node {
     const [ dx, dy, dz ] = options.direction ?? [ 0.548267, -0.473983, -0.689016 ]
     light._direction = [ dx, dy, dz ]
     light._intensity = options.intensity ?? 100000
+    light._color = options.color ?? 0xffffff
+    light._shadowsQuality = options.shadowsQuality ?? 1
+    light._shadowDistance = options.shadowDistance ?? 100
     Light.lastSun = light
     _creator.createSunLight(
       light.id, dx, dy, dz,
@@ -95,6 +103,7 @@ export class Light extends Node {
   static point(options: PointOptions = {}): Light {
     const light = new Light()
     light._intensity = options.intensity ?? 1000
+    light._color = options.color ?? 0xffffff
     light._baked = options.baked ?? true
     Light._points.add(light)
     _creator.createPointLight?.(
@@ -130,6 +139,13 @@ export class Light extends Node {
   }
 
   set color(value: ColorInput) {
+    this._color = value
     _creator.setLightColor?.(this.id, Color.toPackedRgb(value))
   }
+  get color(): ColorInput { return this._color }
+  /** Sun direction as created (the engine keeps it; a settings menu rebuilds a sun from it). */
+  get direction(): [number, number, number] { return this._direction }
+  /** Sun shadow options as created — creation-time in the engine, so a change means a new sun. */
+  get shadowsQuality(): number { return this._shadowsQuality }
+  get shadowDistance(): number { return this._shadowDistance }
 }

package/src/gl/Lightmap.ts

@@ -241,7 +241,8 @@ export class Lightmap {
     if (pageFiles.length < pages) {
       console.warn(`Lightmap: the bake took ${pages} atlas pages but the scene lists ${pageFiles.length} — add the other page files (${(data.textures ?? []).slice(pageFiles.length).join(", ")}) to env.lightmap.texture`)
     }
-    const textures = await Promise.all(pageFiles.slice(0, pages).map((f) => Texture.load(f)))
+    // baked lighting is exempt from Texture.maxSize: a capped atlas blurs every shadow edge
+    const textures = await Promise.all(pageFiles.slice(0, pages).map((f) => Texture.load(f, { fullSize: true })))
     // the light atlas: the bake carries the point lights only when the scene passes their atlas
     const lightFiles = list(files.light)
     let lightTextures: Texture[] = []
@@ -252,7 +253,7 @@ export class Lightmap {
         console.warn(`Lightmap: the bake carries ${data.lights?.length ?? 0} baked point light(s) but the scene passes no \`light\` atlas (${data.lightTextures[0]}) — the lamps stay real-time`)
       } else {
         if (lightFiles.length < pages) console.warn(`Lightmap: the light atlas has ${pages} pages but the scene lists ${lightFiles.length}`)
-        lightTextures = await Promise.all(lightFiles.slice(0, pages).map((f) => Texture.load(f)))
+        lightTextures = await Promise.all(lightFiles.slice(0, pages).map((f) => Texture.load(f, { fullSize: true })))
         lightScale = (data.lightScale ?? 0) * (options.lightBoost ?? 1)
         volumeScale = (data.lightScale ?? 0) * (options.volumeBoost ?? options.lightBoost ?? 1)
       }

package/src/gl/Locomotion.ts

@@ -29,7 +29,9 @@
 
 import { Aspect } from "../core/Aspect"
 import { Vec3, cx, cz, type Vec3Like } from "../math/vec"
-import { Animator, type FeetOptions, type WarpOptions } from "./animation/Animator"
+import { Animator } from "./animation/Animator"
+import type { FeetOptions } from "./animation/Feet"
+import type { WarpOptions } from "./animation/Warp"
 import { CharacterController } from "./CharacterController"
 import type { Node } from "./Node"
 
@@ -288,8 +290,8 @@ 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)
-    if (this.warp !== undefined) anim.warp = this.warp
-    anim.feet = this.feet === undefined ? { lock: true } : this.feet === true ? { lock: true, ik: true } : this.feet === false ? { lock: false, ik: false } : this.feet
+    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()
   }
 
@@ -303,7 +305,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     if (slot < 0) { console.warn(`Locomotion: no clip '${n}' on ${this.node.name || "the character"}`); return }
     this._names.set(slot, n)
     const o = typeof clip === "string" ? undefined : clip
-    const measured = anim.curves(n)
+    const measured = anim.clipInfo(n)
     const angle = o?.angle ?? (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)
@@ -422,7 +424,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     const named = t ? t[this._gait] : undefined
     if (named !== undefined) return named * this._mag
     const clip = (this.set.gaits ?? [])[GAITS.indexOf(this._gait)]
-    const measured = clip !== undefined ? this.anim?.curves(name(clip))?.speed : undefined
+    const measured = clip !== undefined ? this.anim?.clipInfo(name(clip))?.speed : undefined
     return (measured ?? 0) * this._mag
   }
 

package/src/gl/Material.ts

@@ -36,8 +36,49 @@ const applyUniform = (id: number, key: string, value: UniformValue): void => {
 
 export type MaterialColorOptions = { color?: ColorInput, map?: Texture | Canvas | null }
 
+/** How a stencil test / write on a material compares and what it writes. `test` runs against the
+ *  scene's stencil buffer (`Scene.stencil` must be on); the ops say what the buffer gets when the
+ *  fragment passes / fails the stencil test / fails the depth test (`replace` writes `ref`). */
+export type StencilTest = "always" | "never" | "less" | "lessEqual" | "greater" | "greaterEqual" | "equal" | "notEqual"
+export type StencilOp = "keep" | "zero" | "replace" | "increment" | "decrement" | "invert"
+export type MaterialStencil = {
+  /** Write the stencil buffer at all. Default `false`. */
+  write?: boolean
+  /** The reference value, 0..255. Default 0. */
+  ref?: number
+  /** Default `"always"`. */
+  test?: StencilTest
+  onPass?: StencilOp
+  onFail?: StencilOp
+  onDepthFail?: StencilOp
+  readMask?: number
+  writeMask?: number
+}
+
+/** Render state a material instance can override at run time (Filament keeps the defaults in the
+ *  shader package; these are per-instance overrides on top). */
+export type MaterialStateOptions = {
+  /** Test against the scene's depth buffer. `false` draws over everything already drawn — an
+   *  editor gizmo, a marker that must never hide behind a wall. Pair it with a high
+   *  `Mesh.renderPriority` so nothing drawn later covers it. Default `true`. */
+  depthTest?: boolean
+  /** Write to the depth buffer. Leave it on for something drawn over the scene whose own parts must
+   *  still occlude each other (a gizmo's cone in front of its shaft). Unset = the shader's default
+   *  (on for opaque, off for a blended one). */
+  depthWrite?: boolean
+  /** Draw both faces (no back-face culling): a plane seen from behind, a ribbon, cloth, a flat
+   *  marker. Default `false` = the shader's culling (back faces dropped). */
+  doubleSided?: boolean
+  /** A stencil test / write for this material — see `MaterialStencil`. The selection-outline
+   *  recipe: the object writes `{ write: true, ref: 1, onPass: "replace" }`, and a slightly larger
+   *  copy of it draws with `{ test: "notEqual", ref: 1 }` + `depthTest: false` in `renderPriority` 7. */
+  stencil?: MaterialStencil
+}
+/** @deprecated the name before doubleSided / stencil joined it — the same type */
+export type MaterialDepthOptions = MaterialStateOptions
+
 /** `Material.unlit` options. */
-export type UnlitMaterialOptions = MaterialColorOptions & {
+export type UnlitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
   /** Alpha-blend this material instead of drawing it opaque. Opaque is the default: a blended draw
    *  writes no depth, is sorted back-to-front and casts no shadow, which is rarely what a flat
    *  colour wants. Turn it on for anything that must show what is behind it — a glass pane, a
@@ -46,6 +87,27 @@ export type UnlitMaterialOptions = MaterialColorOptions & {
   transparent?: boolean
 }
 
+/** `Material.decal` options — the projected-decal material a `DecalSet` draws with. */
+export type DecalMaterialOptions = {
+  /** The atlas (a `DecalSet`'s `sheet` cuts it into cells). */
+  map?: Texture
+  /** A tangent-space normal atlas (same cell grid; +X = the image's right, +Y = its top; LINEAR —
+   *  `Texture.fromPixels(…, { srgb: false })`). Turns the decal into a RELIEF decal: instead of
+   *  painting a colour it bends the surface's lighting, so a footprint or a dent shows on any
+   *  surface without a colour of its own. With `map` too, the colour multiplies in (a crater
+   *  darkens by the map's alpha). The sun term applies in shadow as well (no shadow read). */
+  normalMap?: Texture
+  /** Relief strength — the normal map's xy scale. Default 1. */
+  bump?: number
+  /** Soft fraction (0..1) of the box's half depth at both ends. Default 0.3. */
+  edge?: number
+  /** Cosine of the surface angle past which the decal fades (0.3 ≈ 72°); 0 = project onto
+   *  anything. Default 0.3. */
+  angleFade?: number
+  /** HDR boost of the image (0 = none). */
+  emissive?: number
+}
+
 /** `Material.particles` options — the default point-sprite material for particle systems. */
 export type ParticlesMaterialOptions = {
   /** Sprite texture — a single image or a flipbook sheet of frames. Unset = soft round dot. */
@@ -92,13 +154,16 @@ export const _sheetColsRows = (sheet: number | [number, number] | undefined): [n
 }
 
 /** `Material.lit` options — PBR scalars on top of the color/map pair. */
-export type LitMaterialOptions = MaterialColorOptions & {
+export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
   /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
   roughness?: number
   /** Metallic factor, 0 (dielectric) … 1 (metal). Unset = the shader's default. */
   metallic?: number
 }
 
+/** `Material.lightmapShading` tiers — see the setter. */
+export type LightmapShading = "full" | "baked" | "baked-lite"
+
 export class Material {
   /** @internal native material-instance handle. */
   _id: number
@@ -133,6 +198,33 @@ export class Material {
     if (this._colorKey) this.uniforms[this._colorKey] = Color.toHexString(c)
   }
 
+  /** Depth test against the scene (write-only; see `MaterialDepthOptions`). A host that predates
+   *  the call leaves the material as the shader has it. */
+  set depthTest(on: boolean) {
+    if (_creator.setMaterialDepthTest) _creator.setMaterialDepthTest(this._id, on)
+    else warnOnce("depthTest", "[material] this host has no setMaterialDepthTest — depthTest ignored")
+  }
+  /** Depth write (write-only; see `MaterialStateOptions`). */
+  set depthWrite(on: boolean) {
+    if (_creator.setMaterialDepthWrite) _creator.setMaterialDepthWrite(this._id, on)
+    else warnOnce("depthWrite", "[material] this host has no setMaterialDepthWrite — depthWrite ignored")
+  }
+  /** Both faces drawn (write-only; see `MaterialStateOptions`). */
+  set doubleSided(on: boolean) {
+    // 0 = no culling, 2 = back faces culled (the shader's usual default)
+    if (_creator.setMaterialCulling) _creator.setMaterialCulling(this._id, on ? 0 : 2)
+    else warnOnce("doubleSided", "[material] this host has no setMaterialCulling — doubleSided ignored")
+  }
+  /** The stencil test / write (write-only; `null` = back to none). See `MaterialStencil`. */
+  set stencil(s: MaterialStencil | null) {
+    if (!_creator.setMaterialStencil) { warnOnce("stencil", "[material] this host has no setMaterialStencil — stencil ignored"); return }
+    const o = s ?? {}
+    const clamp = (v: number | undefined, d: number): number => Math.max(0, Math.min(255, Math.round(v ?? d)))
+    _creator.setMaterialStencil(this._id, !!o.write, STENCIL_TEST.indexOf(o.test ?? "always"), clamp(o.ref, 0),
+      STENCIL_OP.indexOf(o.onPass ?? "keep"), STENCIL_OP.indexOf(o.onFail ?? "keep"), STENCIL_OP.indexOf(o.onDepthFail ?? "keep"),
+      clamp(o.readMask, 255), clamp(o.writeMask, 255))
+  }
+
   // lit/unlit shade baseColor × baseColorMap (factor×map; engines default both to white), so
   // removing the map means resetting baseColorMap to the white 1×1 — no flag to clear. (Materials
   // used to carry a `useBaseColorMap` bool for shaders that branched instead of multiplying; the
@@ -158,6 +250,7 @@ export class Material {
     if (options.map) m.map = options.map
     if (options.roughness !== undefined) m.uniforms.roughness = options.roughness
     if (options.metallic !== undefined) m.uniforms.metallic = options.metallic
+    applyDepth(m, options)
     return m
   }
 
@@ -177,6 +270,7 @@ export class Material {
     m._colorKey = "baseColor"
     if (options.color !== undefined) m.color = options.color
     if (options.map) m.map = options.map
+    applyDepth(m, options)
     return m
   }
 
@@ -205,6 +299,28 @@ export class Material {
     return m
   }
 
+  /** Projected-decal material (`DecalSet`): samples the atlas where the decal's box meets the opaque
+   *  scene behind it. Blended, no depth write, no shadows — the engine keeps the scene depth bound
+   *  while a set with live decals is on screen. */
+  static decal(options: DecalMaterialOptions = {}): Material {
+    // Both fetchLocal literals inline so the compiler's preload header captures the shader names.
+    const m = options.normalMap
+      ? new Material({ _id: _creatorUtils.fetchLocal("decal-relief.filamat") } as any)
+      : new Material({ _id: _creatorUtils.fetchLocal("decal.filamat") } as any)
+    m.uniforms.time = 0
+    m.uniforms.edge = options.edge ?? 0.3
+    m.uniforms.angleFade = options.angleFade ?? 0.3
+    if (options.normalMap) {
+      m.uniforms.normalMap = options.normalMap
+      m.uniforms.bump = options.bump ?? 1
+      m.uniforms.useColor = options.map ? 1 : 0
+    } else {
+      m.uniforms.emissive = options.emissive ?? 0
+    }
+    if (options.map) m.map = options.map
+    return m
+  }
+
   /** Material that samples a VideoPlayer's texture. */
   static video(map?: Texture): Material {
     const m = new Material({ _id: _creatorUtils.fetchLocal("video.filamat") } as any)
@@ -218,8 +334,13 @@ export class Material {
    *  `metallicFactor`) plus `lightmap`, `lightmapST`, `ambientScale`, `sunStrength` (the sun / IBL terms come from
    *  filament's per-frame uniforms inside the shader). */
   static lightmap(): Material {
-    // Inline literal: the compiler's preload header captures the shader name from it.
-    const m = new Material({ _id: _creatorUtils.fetchLocal("lightmap.filamat") } as any)
+    // Inline literals: the compiler's preload header captures the shader names from them.
+    const id = Material.lightmapShading === "baked"
+      ? _creatorUtils.fetchLocal("lightmap-baked.filamat")
+      : Material.lightmapShading === "baked-lite"
+        ? _creatorUtils.fetchLocal("lightmap-baked-lite.filamat")
+        : _creatorUtils.fetchLocal("lightmap.filamat")
+    const m = new Material({ _id: id } as any)
     m.set("baseColorFactor", "#ffffffff").set("roughnessFactor", 1).set("metallicFactor", 0)
     m.set("lightmapST", [ 1, 1, 0, 0 ]).set("ambientScale", 1).set("sunStrength", 1).set("hasNormalMap", 0)
     // lightScale 0 = no baked point lights until Lightmap.load binds a light atlas / volume
@@ -247,6 +368,21 @@ export class Material {
   static _lightmapTemplate(): Material { return (Material._lmTemplate ??= Material.lightmap()) }
   private static _lmTemplate: Material | undefined
 
+  static _lightmapShading: LightmapShading = "full"
+  /** Which shader lightmapped models take — a graphics-quality tier, engine-wide. `"full"` is filament's
+   *  lit path over the baked atlas (IBL specular, real-time point lights such as a muzzle flash, sun
+   *  shadows on dynamic objects). `"baked"` keeps the baked light and an approximated ambient but drops
+   *  the lit path: ~40 % cheaper per pixel on a fill-bound GPU. `"baked-lite"` is that minus the normal,
+   *  metallic/roughness and occlusion map reads (the factors stand in, the atlas keeps the baked AO;
+   *  emissive still glows): +20 % more at 1080p on the same GPU. Read when a lightmapped model LOADS, so set
+   *  it before the level (a settings menu applies it on the next level load), like `Texture.maxSize`. */
+  static get lightmapShading(): LightmapShading { return Material._lightmapShading }
+  static set lightmapShading(mode: LightmapShading) {
+    if (mode === Material._lightmapShading) return
+    Material._lightmapShading = mode
+    Material._lmTemplate = undefined   // the next load builds a template on the new shader
+  }
+
   /** Shadow-catcher material (transparent except where shadows fall). */
   static shadow(color: ColorInput = "#000000aa"): Material {
     const m = new Material({ _id: _creatorUtils.fetchLocal("shadow.filamat") } as any)
@@ -277,3 +413,15 @@ export class Material {
   /** @internal */
   static idOf(material: Material): number { return material._id }
 }
+
+const applyDepth = (m: Material, o: MaterialStateOptions): void => {
+  if (o.depthTest !== undefined) m.depthTest = o.depthTest
+  if (o.depthWrite !== undefined) m.depthWrite = o.depthWrite
+  if (o.doubleSided !== undefined) m.doubleSided = o.doubleSided
+  if (o.stencil !== undefined) m.stencil = o.stencil
+}
+/** the wire order of the stencil enums (creator-gl material.cpp switches on the same numbers) */
+const STENCIL_TEST: StencilTest[] = [ "always", "never", "less", "lessEqual", "greater", "greaterEqual", "equal", "notEqual" ]
+const STENCIL_OP: StencilOp[] = [ "keep", "zero", "replace", "increment", "decrement", "invert" ]
+const warned = new Set<string>()
+const warnOnce = (key: string, msg: string): void => { if (!warned.has(key)) { warned.add(key); console.warn(msg) } }

package/src/gl/Mesh.ts

@@ -20,6 +20,8 @@ export type MeshOptions = {
   name?: string
   castShadows?: boolean
   receiveShadows?: boolean
+  /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
+  renderPriority?: number
 }
 
 export class Mesh extends Node {
@@ -31,17 +33,33 @@ export class Mesh extends Node {
       const mat = material ?? Material.unlit()
       this._geometry = geometry
       this._materials = [ mat ]
-      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1)
+      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
     }
   }
 
   override get geometry(): Geometry | undefined { return this._geometry }
+  /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
+   *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
+  setGeometry(geometry: Geometry): this {
+    this._geometry = geometry
+    _creator.setMesh(this.id, Material.idOf(this._materials![0]!), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
+    return this
+  }
 
   /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
   override get material(): Material { return this._materials![0]! }
   override set material(m: Material) { this.setMaterial(m, 0) }
 
   set culling(v: boolean) { _creator.setCulling(this.id, v) }
+  /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
+   *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
+   *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
+   *  after it can cover it. Write-only; a host that predates the call ignores it. */
+  set renderPriority(v: number) {
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+    else if (!Mesh._warnedPriority) { Mesh._warnedPriority = true; console.warn("[mesh] this host has no setRenderPriority — renderPriority ignored") }
+  }
+  private static _warnedPriority = false
   set castShadows(v: boolean) { _creator.setCastShadows(this.id, v) }
   set receiveShadows(v: boolean) { _creator.setReceiveShadows(this.id, v) }
 
@@ -79,5 +97,6 @@ const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
   if (o.name !== undefined) mesh.name = o.name
   if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
   if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
+  if (o.renderPriority !== undefined) mesh.renderPriority = o.renderPriority
   return mesh
 }

package/src/gl/Particles.ts

@@ -3,8 +3,8 @@
 //
 // All emitter/curve config crosses the bridge as ONE Float32Array of [tag, payloadLen, ...payload]
 // records (_creator.setParticleSystemConfig) — the constructor batches every option into a single
-// call, live setters send a one-record buffer. The tag values mirror PsTag in
-// creator-gl/src/particles.h (guarded by tests/particles-tags.test.ts).
+// call, live setters send a one-record buffer. The tag values mirror CPART_TAG_* in
+// creator-particles/include/creator-particles/creator-particles.h (guarded by tests/particles-tags.test.ts).
 //
 // Curves over a particle's lifetime are built with curve()/colorCurve() chains — see the builders
 // below. A builder's whole state is the flat `_data` array (the exact record payload), so the
@@ -18,7 +18,7 @@ import { Node } from "./Node"
 
 type Range<T> = T | { min: T, max: T }
 
-// --- config record tags (keep in sync with PsTag in creator-gl/src/particles.h) -----------------
+// --- config record tags (keep in sync with CPART_TAG_* in creator-particles.h) ------------------
 
 const TAG_SHAPE = 1
 const TAG_LIFETIME = 2

package/src/gl/Scene.ts

@@ -13,8 +13,10 @@ import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
 import { _requestCameraPermission } from "../plugins/permission"
 import { Camera } from "./Camera"
+import { SceneAudio } from "./SceneAudio"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
+import { Texture } from "./Texture"
 import { Node, nodeRegistry } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
@@ -107,6 +109,9 @@ export type SceneOptions = {
    *  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
+  /** 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
   /** Render the 3D at this fraction of the viewport (0.25–1) and upscale; the UI stays at native
    *  resolution. A fixed, predictable cut of per-pixel GPU work — `0.75` is ~45 % cheaper and
    *  barely visible in motion, `0.5` quarters it. Headless renders ignore it. */
@@ -128,6 +133,10 @@ export type SceneOptions = {
    *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
    *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
   anisotropy?: number
+  /** Engine-wide cap on texture size, 0 / unset = none (see `Texture.maxSize`): a KTX2 above it
+   *  loses its top mip levels on load, a glTF image is downsampled. Applied before this scene's
+   *  assets load; like `anisotropy` it does not touch textures already loaded. */
+  maxTextureSize?: number
   /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
    *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
    *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
@@ -148,17 +157,16 @@ const installRenderSyncedFrames = (): void => {
   framesInstalled = true
   _installAspectFrames((early, late) => {
     if (typeof _creator.setEarlyUpdate !== "function") return false
-    // the frame stamp invalidates every Node's local-matrix cache once per frame (physics / character
-    // controllers / animation rewrite transforms natively between frames)
-    _creator.setEarlyUpdate((dt: number) => { glState.frame++; early(dt) })
+    // (The per-phase read-cache stamp — `_phaseStamp` in core/Aspect.ts — advances inside the phase
+    // runners themselves, so it is right on this path and on the setLoop fallback alike.)
+    _creator.setEarlyUpdate(early)
     _creator.setLateUpdate(late)
     return true
   }, (fixed) => {
-    // The fixed phase runs INSIDE the engine's substep loop (physics/world.cpp) when the host has the
-    // hook; each substep moves bodies natively, so the frame stamp bumps per step too. Feature-detected:
-    // an older host returns false and the dispatcher steps its own 1/60 accumulator.
+    // The fixed phase runs INSIDE the engine's substep loop (creator-physics' frame protocol) when the host has the
+    // hook. Feature-detected: an older host returns false and the dispatcher steps its own 1/60 accumulator.
     if (typeof _creator.setFixedUpdate !== "function") return false
-    _creator.setFixedUpdate((dt: number) => { glState.frame++; fixed(dt) })
+    _creator.setFixedUpdate(fixed)
     return true
   })
   // Time.scale / Time.paused reach the engine's own clocks (physics, animators, particles) through
@@ -172,6 +180,8 @@ export class Scene implements Presentable {
   /** @internal the IBL intensity this scene was built with (Lightmap.load's ambient floor). */
   _environmentIntensity = 20000
   readonly camera: Camera
+  /** The listener + global 3D audio knobs (docs/audio-plan.md). */
+  readonly audio: SceneAudio = new SceneAudio()
 
   /** @internal touch listeners, read by the dispatch system. */
   readonly _clickListeners: Array<(ev: ClickEvent<Node | null>) => void> = []
@@ -220,9 +230,11 @@ export class Scene implements Presentable {
       // `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)
     }
+    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
     // place by the time assets bind their samplers.
-    if (options.anisotropy !== undefined) _creator.setTextureAnisotropy?.(options.anisotropy)
+    if (options.anisotropy !== undefined) Texture.anisotropy = options.anisotropy
+    if (options.maxTextureSize !== undefined) Texture.maxSize = options.maxTextureSize
     if (options.hdr) {
       if (options.hdr.strength !== undefined) device.hdr.strength = options.hdr.strength
       if (options.hdr.paperWhite !== undefined) device.hdr.paperWhite = options.hdr.paperWhite
@@ -280,6 +292,28 @@ export class Scene implements Presentable {
   setAntialias(enabled: boolean, scale = 4): void {
     _creator.setSceneMultiSampleAntiAliasing(this._id, enabled, 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
+   *  frame). Off = hard-edged particles, no decals, no pre-pass. Engine-wide, live. */
+  setDepthEffects(enabled: boolean): void {
+    _creator.setDepthEffects?.(enabled)
+  }
+  /** LOD distance (a graphics-settings menu): the engine's LOD thresholds × `bias`. 2 = every level
+   *  switches at half the distance (a model must look twice as big on screen to keep its detail),
+   *  0.5 = full detail twice as far, 1 = the defaults. Engine-wide, live. Only GLBs that carry
+   *  `_LOD<n>` meshes (`lecodes assets doctor --lod`) have levels to switch. */
+  setLodBias(bias: number): void {
+    _creator.setLodBias?.(bias)
+  }
+  /** Runtime form of `bloom` / `bloomIntensity` (a graphics-settings menu). */
+  setBloom(enabled: boolean, intensity = 0.2): void {
+    _creator.setBloomOptions(this._id, enabled, intensity, 1)
+  }
+  /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
+  setStencil(enabled: boolean): void {
+    if (_creator.setSceneStencil) _creator.setSceneStencil(this._id, enabled)
+    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)

package/src/gl/SceneAudio.ts

@@ -0,0 +1,26 @@
+// `scene.audio` (docs/audio-plan.md §2): the listener and the global 3D knobs. The listener is the
+// scene's active camera by default — a `CameraPlace` switch or a follow rig changes nothing, the
+// engine reads whatever camera it renders with. Set a node to listen from somewhere else (the
+// player's head in a third-person game, so sounds pan around the character, not the camera).
+
+import { audioSupported } from "../audio/support"
+import type { Node } from "./Node"
+
+export class SceneAudio {
+  private _listener: Node | null = null
+  private _doppler = 1
+
+  /** The node the engine listens from; null (default) = the active camera. */
+  get listener(): Node | null { return this._listener }
+  set listener(node: Node | null) {
+    this._listener = node
+    if (audioSupported) _creatorAudio.setListener(node ? node.id : 0)
+  }
+
+  /** Multiplies every source's doppler amount (0 = off everywhere). Default 1. */
+  get dopplerFactor(): number { return this._doppler }
+  set dopplerFactor(v: number) {
+    this._doppler = v
+    if (audioSupported) _creatorAudio.setListenerOptions(v)
+  }
+}

package/src/gl/Texture.ts

@@ -2,7 +2,41 @@
 
 import { fetch, type FetchResponse, type File } from "../runtime/fetch"
 
+/** `Texture.load` options. */
+export type TextureLoadOptions = {
+  /** `true` (default): colour, stored sRGB. `false`: data (normal map, mask, heightmap) — kept linear. */
+  srgb?: boolean
+  /** Ignore `Texture.maxSize` for this texture (a lightmap page, a lookup table). */
+  fullSize?: boolean
+}
+/** `_creator.createTexture` flags bit: linear data (creator-gl CREATOR_TEXTURE_LINEAR). */
+const TEXTURE_FLAG_LINEAR = 1
+/** `_creator.createTexture` flags bit: exempt from `Texture.maxSize` (creator-gl CREATOR_TEXTURE_FULL_SIZE). */
+const TEXTURE_FLAG_FULL_SIZE = 2
+
 export class Texture {
+  static _maxSize = 0
+  /** Engine-wide cap on texture size (a "texture quality" setting), 0 = none. A KTX2 wider or
+   *  taller than this loses its top mip levels on load (nothing resampled, less memory and
+   *  bandwidth), a glTF PNG/JPEG is downsampled. Reaches textures loaded AFTER it is set — a loaded
+   *  level keeps its textures — so set it up front (`SceneOptions.maxTextureSize`, or before the
+   *  level loads) and apply a menu change on the next level load. Lightmap pages are exempt
+   *  (`TextureLoadOptions.fullSize`). A host may pin it (desktop `CREATOR_TEXTURE_MAX_SIZE`). */
+  static _anisotropy = 2
+  /** Engine-wide anisotropic filtering, 1 (off) … 16 (default 2; `SceneOptions.anisotropy` sets it up
+   *  front). A sampler is baked when its texture is bound, so like `maxSize` this reaches textures
+   *  loaded AFTER it — set it before the level loads. Measured on a lightmapped interior at 720p:
+   *  4× costs ~20 % of the frame over 1× on an integrated GPU. A host may pin it. */
+  static get anisotropy(): number { return Texture._anisotropy }
+  static set anisotropy(level: number) {
+    Texture._anisotropy = level >= 1 ? Math.min(16, level) : 1
+    _creator.setTextureAnisotropy?.(Texture._anisotropy)
+  }
+  static get maxSize(): number { return Texture._maxSize }
+  static set maxSize(size: number) {
+    Texture._maxSize = size > 0 ? Math.floor(size) : 0
+    _creator.setTextureMaxSize?.(Texture._maxSize)
+  }
   /** @internal native texture handle. */
   readonly _id: number
   readonly width: number
@@ -47,17 +81,23 @@ export class Texture {
     _creator.updateTexturePixels?.(this._id, x, y, width, height, data)
   }
 
-  static load(source: string | FetchResponse | File): Promise<Texture> {
+  /** Decode an image (PNG / JPG, or a KTX2 the core transcodes) into a texture. `srgb` (default
+   *  true) says the bytes are COLOUR, stored sRGB so the GPU linearises them on sample; pass
+   *  `false` for DATA — a normal map, a mask, a heightmap — which must come back as stored (a
+   *  flat normal read through sRGB bends by ~35°). A KTX2 decides by its own header. Image
+   *  textures get a mip chain (trilinear) on hosts that build one. */
+  static load(source: string | FetchResponse | File, options: TextureLoadOptions = {}): Promise<Texture> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {
         if (resp.status >= 400) {
           return Promise.reject(new Error(`Failed to fetch texture from ${source}. HTTP ${resp.status}`))
         }
-        return Texture.load(resp)
+        return Texture.load(resp, options)
       })
     }
+    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)
+      _creator.createTexture((source as any)._id, (id, w, h) => resolve(new Texture(w, h, id)), reject, flags)
     })
   }
 }

package/src/gl/Vehicle.ts

@@ -25,13 +25,12 @@
 //
 // Layering, and why it is where it is: docs/vehicle-rework-plan.md.
 
-import { Aspect } from "../core/Aspect"
+import { Aspect, _phaseStamp } from "../core/Aspect"
 import type { FieldMeta } from "../core/fields"
 import { Mat4 } from "../math/mat4"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
 import { cw, type QuatLike } from "../math/quat"
 import { Gizmos } from "../scene/gizmos"
-import { glState } from "./state"
 import { Gearbox } from "./Gearbox"
 import { Node } from "./Node"
 import { DEFAULT_FRICTION, Physics } from "./Physics"
@@ -314,12 +313,13 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     if (this._id) _creator.vehicleSetTransmission(this._id, ratio, clamp(clutch, 0, 1))
   }
 
-  // --- readouts (one native read per frame, shared by the car and every wheel) -------------------
+  // --- readouts (one native read per PHASE — early sees the pre-step state, late the settled one —
+  //     shared by the car and every wheel; keyed on core/Aspect's _phaseStamp) -------------------
 
   private _read(): Float32Array {
-    if (this._id && this._stateFrame !== glState.frame) {
+    if (this._id && this._stateFrame !== _phaseStamp.value) {
       _creator.vehicleGetState(this._id, this._state)
-      this._stateFrame = glState.frame
+      this._stateFrame = _phaseStamp.value
     }
     return this._state
   }