lecodes-sdk 0.20.0 → 1.0.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

@@ -71,6 +71,13 @@ export type LightmapLoadOptions = {
    *  and its underside does not — the same shading the atlas gives the statics. Before that the volume
    *  was one flat 0.5·E on every face and this knob was the workaround. Kept as a trim. */
   volumeBoost?: number
+  /** What an OCCLUDER-only static (a prop without lightmap UVs — traced into the receivers' atlas but
+   *  carrying no rect of its own) does in real time. `"baked"` (default): its shadow is in the bake, so
+   *  it stops casting and the shadow pass draws only the movers — on a level of thousands of foliage
+   *  cards that is a third of the GPU frame. `"realtime"`: it keeps casting, which is the only way its
+   *  shadow reaches OTHER non-receiver props (a rock under a tree); the honest fix for that is lightmap
+   *  UVs on the props (`lecodes assets doctor --lightmap-uv`), which makes them receivers. */
+  occluderShadows?: "baked" | "realtime"
 }
 
 export type LightmapInfo = {
@@ -87,6 +94,8 @@ export type LightmapInfo = {
   applied: number
   total: number
   missing: string[]
+  /** Occluder-only statics whose real-time shadow was switched off (`occluderShadows: "baked"`). */
+  occluders: number
 }
 
 export type LightmapFiles = {
@@ -98,7 +107,7 @@ export type LightmapFiles = {
   volume?: string
 }
 
-import type { Terrain } from "./Terrain"
+import type { Terrain } from "./terrain/Terrain"
 
 type Entry = { key: string, model?: Model, mesh?: Mesh, terrain?: Terrain }
 
@@ -241,7 +250,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 +262,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)
       }
@@ -273,12 +283,29 @@ export class Lightmap {
     // the light volume next: it claims every lightmap-material instance, the atlas rects below win back the statics
     const volume = files.volume ? await Lightmap.loadVolume(files.volume, volumeScale, lightGamma, ambientScale, strength, aoStrength) : null
     const rects = new Map<string, { st: number[], page: number }>()
-    for (const inst of data.instances) if (inst.receiver && inst.st) rects.set(inst.key, { st: inst.st, page: inst.page ?? 0 })
-    let applied = 0
+    // an OCCLUDER-only static (no lightmap UVs): the bake traced its shadow onto every receiver, so it
+    // has nothing left to cast in real time — the shadow pass then draws only the movers. Twig & Twine's
+    // 9 441 props (5 M alpha-masked spruce cards) cost the GPU a third of the frame as live casters.
+    const occluders = new Set<string>()
+    for (const inst of data.instances) {
+      if (inst.receiver && inst.st) rects.set(inst.key, { st: inst.st, page: inst.page ?? 0 })
+      else if (!inst.receiver) occluders.add(inst.key)
+    }
+    const bakedOccluders = (options.occluderShadows ?? "baked") === "baked"
+    let applied = 0, shadowless = 0
     const missing: string[] = []
     for (const e of Lightmap.entries) {
       const r = rects.get(e.key)
-      if (!r || r.page >= textures.length) { missing.push(e.key); continue }
+      if (!r || r.page >= textures.length) {
+        if (occluders.has(e.key)) {
+          if (bakedOccluders) {
+            if (e.model) e.model.castShadows = false
+            else if (e.mesh) e.mesh.castShadows = false
+            shadowless++
+          }
+        } else missing.push(e.key)
+        continue
+      }
       const st = r.st
       const texture = textures[r.page]
       const light = r.page < lightTextures.length ? lightTextures[r.page] : null
@@ -303,7 +330,8 @@ export class Lightmap {
     // the lights the bake carries go dark: the atlas holds them for the statics, the volume for the movers
     let lights = 0
     if (lightTextures.length > 0 && data.lights?.length) lights = Lightmap.switchOffBaked(data.lights)
-    const info: LightmapInfo = { size: data.size, texel: data.texel, pages, applied, total: rects.size, missing, lights }
+    if (shadowless > 0) console.log(`[lightmap] ${shadowless} occluder-only static(s) cast no real-time shadow (baked); the shadow pass draws the movers only`)
+    const info: LightmapInfo = { size: data.size, texel: data.texel, pages, applied, total: rects.size, missing, lights, occluders: shadowless }
     if (volume) info.volume = { dims: volume.dims, cell: volume.cell }
     return info
   }

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
@@ -228,6 +349,22 @@ export class Material {
     return m
   }
 
+  /** `Material.lightmap()`'s masked twin (`blending: masked`, same shader and parameters): what the engine
+   *  gives a lightmapped model's alpha-MASK materials. The cutoff comes from the glTF material. */
+  static lightmapMasked(): Material {
+    const id = Material.lightmapShading === "baked"
+      ? _creatorUtils.fetchLocal("lightmap-baked-masked.filamat")
+      : Material.lightmapShading === "baked-lite"
+        ? _creatorUtils.fetchLocal("lightmap-baked-lite-masked.filamat")
+        : _creatorUtils.fetchLocal("lightmap-masked.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)
+    m.set("bakedAo", 1).set("lightScale", 0)
+    m.set("probeMin", [ 0, 0, 0, 0 ]).set("probeInvSize", [ 0, 0, 0, 0 ])
+    return m
+  }
+
   /** The terrain splat material (docs/terrain-plan.md §1.5): four albedo (+ normal-map) layers blended by
    *  a control map on the terrain's own grid, per-layer `tiling` (metres per repeat) / `roughness` /
    *  `normalScale` / `triplanar`, lightmap-aware (the same `lightmap` / `lightmapST` block as
@@ -246,6 +383,26 @@ export class Material {
    *  the GLB provider instantiates; the template itself never draws). */
   static _lightmapTemplate(): Material { return (Material._lmTemplate ??= Material.lightmap()) }
   private static _lmTemplate: Material | undefined
+  /** @internal The tier's MASKED twin, handed to the engine next to the template: a model's glTF MASK
+   *  materials (foliage cards) take it instead of falling back to the ubershader's full lit path. */
+  static _lightmapMaskedTemplate(): Material { return (Material._lmMaskedTemplate ??= Material.lightmapMasked()) }
+  private static _lmMaskedTemplate: 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
+    Material._lmMaskedTemplate = undefined
+  }
 
   /** Shadow-catcher material (transparent except where shadows fall). */
   static shadow(color: ColorInput = "#000000aa"): Material {
@@ -277,3 +434,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

@@ -1,83 +1,120 @@
-// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/plane) and
-// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
-
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import {
-  Geometry,
-  type CylinderOptions,
-  type PlaneOptions,
-  type SphereOptions,
-} from "./Geometry"
-import { Material } from "./Material"
-import { Node } from "./Node"
-
-/** Common transform/render options every primitive factory accepts. */
-export type MeshOptions = {
-  material?: Material
-  position?: Vec3Like
-  eulerAngles?: Vec3Like
-  scale?: Vec3Like | number
-  name?: string
-  castShadows?: boolean
-  receiveShadows?: boolean
-}
-
-export class Mesh extends Node {
-  private _geometry?: Geometry
-
-  constructor(geometry?: Geometry, material?: Material) {
-    super()
-    if (geometry) {
-      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)
-    }
-  }
-
-  override get geometry(): Geometry | undefined { return this._geometry }
-
-  /** 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) }
-  set castShadows(v: boolean) { _creator.setCastShadows(this.id, v) }
-  set receiveShadows(v: boolean) { _creator.setReceiveShadows(this.id, v) }
-
-  // --- factories ---
-
-  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
-    // the size goes into the geometry (not a scale after): the lightmap chart is laid out per face area
-    return apply(new Mesh(Geometry.box(options.size ?? 1), options.material), options)
-  }
-
-  static sphere(options: MeshOptions & SphereOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.sphere(options), options.material), options)
-  }
-
-  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
-  }
-
-  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.plane(options), options.material), options)
-  }
-
-  /** Wrap a custom Geometry. */
-  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
-    return apply(new Mesh(geometry, options.material), options)
-  }
-}
-
-const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
-
-const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
-  if (o.position) mesh.position = o.position
-  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
-  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
-  if (o.name !== undefined) mesh.name = o.name
-  if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
-  if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
-  return mesh
-}
+// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/capsule/plane) and
+// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
+
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import {
+  Geometry,
+  type CapsuleOptions,
+  type CylinderOptions,
+  type PlaneOptions,
+  type SphereOptions,
+} from "./Geometry"
+import { Material } from "./Material"
+import { Node } from "./Node"
+
+/** Common transform/render options every primitive factory accepts. */
+export type MeshOptions = {
+  material?: Material
+  position?: Vec3Like
+  eulerAngles?: Vec3Like
+  scale?: Vec3Like | number
+  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 {
+  private _geometry?: Geometry
+
+  constructor(geometry?: Geometry, material?: Material) {
+    super()
+    if (geometry) {
+      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, 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)
+    // the host rebuilds the renderable for a new geometry (creator-gl createMesh destroys + builds), which
+    // resets its priority / culling / shadow flags to the defaults — an overlay redrawn every frame lost its
+    // renderPriority 7 after one frame and hid inside the model. What was set on this mesh is set again.
+    if (this._renderPriority !== undefined) this.renderPriority = this._renderPriority
+    if (this._culling !== undefined) this.culling = this._culling
+    if (this._castShadows !== undefined) this.castShadows = this._castShadows
+    if (this._receiveShadows !== undefined) this.receiveShadows = this._receiveShadows
+    return this
+  }
+  private _renderPriority?: number
+  private _culling?: boolean
+  private _castShadows?: boolean
+  private _receiveShadows?: boolean
+
+  /** 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) { this._culling = v; _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) {
+    this._renderPriority = v
+    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) { this._castShadows = v; _creator.setCastShadows(this.id, v) }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; _creator.setReceiveShadows(this.id, v) }
+
+  // --- factories ---
+
+  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
+    // the size goes into the geometry (not a scale after): the lightmap chart is laid out per face area
+    return apply(new Mesh(Geometry.box(options.size ?? 1), options.material), options)
+  }
+
+  static sphere(options: MeshOptions & SphereOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.sphere(options), options.material), options)
+  }
+
+  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
+  }
+
+  /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
+  static capsule(options: MeshOptions & CapsuleOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.capsule(options), options.material), options)
+  }
+
+  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.plane(options), options.material), options)
+  }
+
+  /** Wrap a custom Geometry. */
+  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
+    return apply(new Mesh(geometry, options.material), options)
+  }
+}
+
+const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
+
+const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
+  if (o.position) mesh.position = o.position
+  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
+  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
+  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
+}