lecodes-sdk 0.20.0 → 0.20.2

package/src/gl/DecalSet.ts

@@ -0,0 +1,233 @@
+// Projected decals — bullet holes, footprints, dirt, blood. A DecalSet is one node that owns up to
+// `max` decals drawn as ONE native renderable: each decal is a box that projects its image onto the
+// opaque scene inside it (the engine reads the scene depth — creator-gl src/decals.cpp +
+// materials/src/decal.mat), so it wraps floor-wall corners, stairs and curved surfaces without any
+// geometry access. It lands on opaque surfaces only: never on particles, glass or other decals.
+//
+// Coordinates are in the SET's space: a set added at the scene root with no transform takes world
+// coordinates (the usual case); a set parented to a door rides with it and takes door-local ones.
+// Slots are a ring — a full set recycles its oldest decal, so `max` is the on-screen budget.
+
+import { Node } from "./Node"
+import { Material } from "./Material"
+import type { Texture } from "./Texture"
+import { Vec3, type Vec3Like } from "../math/vec"
+import { Quat, type QuatLike } from "../math/quat"
+import { Color, type ColorInput } from "../core/color"
+
+/** Per-decal look and life — defaults come from the set's options. */
+export type DecalOptions = {
+  /** Image width and height on the surface (world units); a number = square. Default 0.2. */
+  size?: number | [number, number]
+  /** Projection depth (world units): how far in front of and behind the hit point the decal still
+   *  lands. Default = the smaller of width / height. */
+  depth?: number
+  /** Atlas cell (row-major from the top-left) for a set with a `sheet`; `"random"` picks one.
+   *  Default 0. */
+  frame?: number | "random"
+  /** Tint multiplied into the image. Default white. */
+  tint?: ColorInput
+  /** 0..1 on top of the tint's alpha. Default 1. */
+  opacity?: number
+  /** Seconds until the decal is gone; 0 = stays until recycled. Default 0. */
+  life?: number
+  /** Seconds to fade in after spawning. Default 0. */
+  fadeIn?: number
+  /** Seconds of fade at the end of `life` (ignored with life 0). Default 0. */
+  fadeOut?: number
+}
+
+export type DecalSetOptions = DecalOptions & {
+  /** The material — `Material.decal({ map })` by default (`map` below is its shortcut). A custom
+   *  material must keep decal.mat's vertex contract. */
+  material?: Material
+  /** Atlas texture for the default material. */
+  map?: Texture
+  /** Tangent-space normal atlas (same cell grid) → a RELIEF decal that bends the surface's
+   *  lighting instead of painting a colour (`Material.decal` `normalMap`). Footprints and dents
+   *  need only this; a bullet hole gives `map` too and its colour multiplies in. */
+  normalMap?: Texture
+  /** Relief strength for `normalMap`. Default 1. Default material only. */
+  bump?: number
+  /** Atlas grid of the map: columns, or [columns, rows]. Default 1 (the whole texture). */
+  sheet?: number | [number, number]
+  /** Slot budget — the most decals alive at once. Default 256. */
+  max?: number
+  /** Soft fraction (0..1) of the box's half depth at both ends, so an oblique surface leaves the
+   *  box gently. Default 0.3. Default material only. */
+  edge?: number
+  /** Surfaces turned more than this away from the projection axis fade out — the cosine of the
+   *  angle (0.3 ≈ 72°) keeps a floor hit off the wall it meets; 0 = project onto anything.
+   *  Default 0.3. Default material only. */
+  angleFade?: number
+  /** HDR boost of the image (0 = none). Default material only. */
+  emissive?: number
+  name?: string
+  /** Coarse draw order, 0 (first) … 7 (last); default 4 — see `Mesh.renderPriority`. Decals are
+   *  blended and sort with the other blended draws of their priority. */
+  renderPriority?: number
+}
+
+/** `spawn` placement: where the image sits on the surface. */
+export type DecalSpawnOptions = DecalOptions & {
+  /** World direction the image's top points along the surface (projected onto it) — a footprint's
+   *  travel direction. Default: a random spin. */
+  up?: Vec3Like
+  /** Extra spin around the normal, radians. Default: random when `up` is not given, else 0. */
+  rotation?: number
+}
+
+/** `place` / `update` placement: a full frame, like a node looking INTO the surface (its −Z is the
+ *  projection direction, +Y the image's top). */
+export type DecalPlacement = DecalOptions & {
+  position: Vec3Like
+  /** A quaternion, or Euler degrees (YXZ) like `Node.eulerAngles`. Default identity = projecting
+   *  down −Z. */
+  rotation?: QuatLike | Vec3Like
+}
+
+const RECORD = 23
+const NO_SLOT = 0xFFFFFFFF
+
+export class DecalSet extends Node {
+  private _material: Material
+  private readonly _max: number
+  private readonly _cols: number
+  private readonly _rows: number
+  private readonly _defaults: DecalOptions
+  private readonly _rec = new Float32Array(RECORD)
+  private readonly _slots = new Map<number, DecalPlacement>()
+  private static _warned = false
+
+  constructor(options: DecalSetOptions = {}) {
+    super()
+    if (options.name) this.name = options.name
+    this._material = options.material ?? Material.decal({
+      map: options.map, normalMap: options.normalMap, bump: options.bump,
+      edge: options.edge, angleFade: options.angleFade, emissive: options.emissive,
+    })
+    this._max = Math.max(1, Math.round(options.max ?? 256))
+    const sheet = options.sheet ?? 1
+    this._cols = Math.max(1, Array.isArray(sheet) ? sheet[0] : sheet)
+    this._rows = Math.max(1, Array.isArray(sheet) ? sheet[1] : 1)
+    this._defaults = {
+      size: options.size ?? 0.2, depth: options.depth, frame: options.frame ?? 0, tint: options.tint,
+      opacity: options.opacity ?? 1, life: options.life ?? 0, fadeIn: options.fadeIn ?? 0, fadeOut: options.fadeOut ?? 0,
+    }
+    if (_creator.createDecalSet) {
+      _creator.createDecalSet(this.id, Material.idOf(this._material), this._max)
+      if (options.renderPriority !== undefined) this.renderPriority = options.renderPriority
+    } else if (!DecalSet._warned) {
+      DecalSet._warned = true
+      console.warn("[decals] this host has no createDecalSet — decals are not drawn")
+    }
+  }
+
+  get material(): Material { return this._material }
+  /** Decals alive right now. */
+  get count(): number { return _creator.decalCount ? _creator.decalCount(this.id) : 0 }
+  /** The slot budget the set was created with. */
+  get max(): number { return this._max }
+
+  /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
+  set renderPriority(v: number) {
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+  }
+
+  /** Stamp a decal on a surface: `point` on it, `normal` out of it (a raycast hit, a foot plant
+   *  with `Vec3.up`). Returns the slot for `update` / `remove` (−1 when the host draws none). */
+  spawn(point: Vec3Like, normal: Vec3Like, options: DecalSpawnOptions = {}): number {
+    const n = new Vec3(normal).normalize()
+    // Image up on the surface: the hint projected onto the plane, or any perpendicular.
+    let up = options.up ? new Vec3(options.up) : null
+    if (up) { up = up.sub(n.scale(up.dot(n))); if (up.length() < 1e-4) up = null }
+    if (!up) {
+      const helper = Math.abs(n.y) < 0.99 ? Vec3.up : Vec3.right
+      up = helper.sub(n.scale(helper.dot(n)))
+    }
+    up = up.normalize()
+    // right = up × normal keeps the frame right-handed (right × up = normal), so the image reads
+    // unmirrored from the normal's side; then the spin around the normal.
+    let right = up.cross(n)
+    const spin = options.rotation ?? (options.up ? 0 : Math.random() * Math.PI * 2)
+    if (spin !== 0) {
+      const c = Math.cos(spin), s = Math.sin(spin)
+      const r2 = right.scale(c).add(up.scale(s))
+      up = up.scale(c).sub(right.scale(s))
+      right = r2
+    }
+    return this._write(NO_SLOT, right, up, n, new Vec3(point), options)
+  }
+
+  /** Place a decal by a full frame (an editor-placed stain, a moving marker). Returns the slot. */
+  place(placement: DecalPlacement): number {
+    const slot = this._writePlacement(NO_SLOT, placement)
+    if (slot >= 0) this._slots.set(slot, placement)
+    return slot
+  }
+
+  /** Move / restyle a placed decal; fields left out keep the values it was placed with. Its birth
+   *  time (the life clock) is kept. */
+  update(slot: number, placement: Partial<DecalPlacement>): this {
+    const prev = this._slots.get(slot)
+    if (!prev) return this
+    const next = { ...prev, ...placement }
+    this._slots.set(slot, next)
+    this._writePlacement(slot, next)
+    return this
+  }
+
+  remove(slot: number): this {
+    this._slots.delete(slot)
+    if (_creator.removeDecal && slot >= 0) _creator.removeDecal(this.id, slot)
+    return this
+  }
+
+  clear(): this {
+    this._slots.clear()
+    if (_creator.clearDecals) _creator.clearDecals(this.id)
+    return this
+  }
+
+  private _writePlacement(slot: number, p: DecalPlacement): number {
+    let q: Quat
+    if (p.rotation === undefined) q = Quat.identity
+    else if (p.rotation instanceof Quat || (p.rotation as any).w !== undefined || (p.rotation as any).length === 4) q = new Quat(p.rotation as QuatLike)
+    else { const e = new Vec3(p.rotation as Vec3Like); q = Quat.fromEuler(e.x, e.y, e.z) }
+    const right = q.rotateVec3(Vec3.right)
+    const up = q.rotateVec3(Vec3.up)
+    const normal = right.cross(up)   // +Z of the frame: the node's −Z looks into the surface
+    return this._write(slot, right, up, normal, new Vec3(p.position), p)
+  }
+
+  private _write(slot: number, right: Vec3, up: Vec3, normal: Vec3, centre: Vec3, o: DecalOptions): number {
+    const d = this._defaults
+    const size = o.size ?? d.size!
+    const w = typeof size === "number" ? size : size[0]
+    const h = typeof size === "number" ? size : size[1]
+    const depth = o.depth ?? d.depth ?? Math.min(w, h)
+    const r = this._rec
+    r[0] = right.x * w; r[1] = right.y * w; r[2] = right.z * w
+    r[3] = up.x * h; r[4] = up.y * h; r[5] = up.z * h
+    r[6] = normal.x * depth; r[7] = normal.y * depth; r[8] = normal.z * depth
+    r[9] = centre.x; r[10] = centre.y; r[11] = centre.z
+    // atlas cell → rect (v grows downward: v0 is the cell's top)
+    const cells = this._cols * this._rows
+    const frameOpt = o.frame ?? d.frame!
+    const frame = frameOpt === "random" ? Math.floor(Math.random() * cells) : ((Math.floor(frameOpt) % cells) + cells) % cells
+    const col = frame % this._cols, row = Math.floor(frame / this._cols)
+    r[12] = col / this._cols; r[13] = row / this._rows; r[14] = (col + 1) / this._cols; r[15] = (row + 1) / this._rows
+    const tint = o.tint ?? d.tint
+    const [tr, tg, tb, ta] = tint === undefined ? [1, 1, 1, 1] : Color.toRgba01(tint)
+    const opacity = o.opacity ?? d.opacity!
+    r[16] = tr; r[17] = tg; r[18] = tb; r[19] = ta * opacity
+    r[20] = o.life ?? d.life!; r[21] = o.fadeIn ?? d.fadeIn!; r[22] = o.fadeOut ?? d.fadeOut!
+    if (slot === NO_SLOT) {
+      if (!_creator.addDecal) return -1
+      const s = _creator.addDecal(this.id, r)
+      return s === NO_SLOT ? -1 : s
+    }
+    if (_creator.updateDecal) _creator.updateDecal(this.id, slot, r)
+    return slot
+  }
+}

package/src/gl/Geometry.ts

@@ -25,6 +25,11 @@ export class Geometry {
    *  tiles per face, which would fold every face onto the same texels); absent = the host reuses
    *  `uv`, which is right for a plane. */
   uv1?: Float32Array
+  /** Per-vertex COLOURS: 4 bytes (r, g, b, a) per vertex, 0..255. A material that declares
+   *  `requires: [color]` reads them through `getColor()` — one mesh, many colours, no material per
+   *  shade (a debug drawer, a gradient along a curve). Absent = every vertex white, which is what
+   *  the built-in materials expect. */
+  colors?: Uint8Array
   /** @internal native mesh-type enum (0 triangles / 1 edges / 2 vertices). */
   _meshKind = 0
 

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/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
 }