lecodes-sdk 1.2.0 → 2.0.1

package/src/gl/Lightmap.ts

@@ -1,4 +1,4 @@
-// Baked lighting for static 3D geometry (packages/creator-bake). A scene FILE does all of this by
+// Baked lighting for static 3D geometry (engines/bake). A scene FILE does all of this by
 // itself: `env: { lightmap: { data, light, aux } }` marks the level as baked, every model/mesh node
 // that no Physics aspect moves is a static (keys = node paths, `lightmap: true|false` overrides),
 // and the runtime applies the bake when the level finishes loading (scene/defineScene.ts).
@@ -39,12 +39,13 @@
 // is untouched — it is the same material reading other pages). The bake's `--debug-dir` keeps the
 // float layers `lecodes lightmap inspect` reads.
 
+import { Color } from "../core/color"
 import { fetch } from "../runtime/fetch"
 import { Texture } from "./Texture"
 import { Material } from "./Material"
 import { Mesh } from "./Mesh"
 import { Model } from "./Model"
-import { Node, nodeRegistry } from "./Node"
+import { Node, nodes } from "./Node"
 import { Light } from "./Light"
 import type { Scene } from "./Scene"
 
@@ -266,12 +267,13 @@ export class Lightmap {
     // by entity id through the bridge, not `node.children`: the bundler drops that accessor from a build where
     // nothing else reads it (the leash in lightcheck, 2026-09-18: "children" was undefined on a Mesh)
     const walk = (id: number): void => {
-      const n = nodeRegistry.get(id)
+      const n = nodes.get(id)
       if (n instanceof Model || n instanceof Mesh) {
         if (on) Lightmap.movers.add(n); else Lightmap.movers.delete(n)
         if (Lightmap.volumeOn || !on) _creator.lightVolumeTrack?.(id, on)
       }
-      for (const c of _creator.getChildren(id)) walk(c)
+      const count = _creator.getChildCount(id)
+      for (let i = 0; i < count; i++) walk(_creator.getChild(id, i))
     }
     walk(node.id)
   }
@@ -285,8 +287,7 @@ export class Lightmap {
     try {
       const resp = await fetch(files.volume, { useOnce: true })
       if (resp.status >= 400) { console.warn(`Lightmap: no light grid at ${files.volume} (HTTP ${resp.status})`); return }
-      const ok = _creator.lightVolumeLoad((resp as unknown as { _id: number })._id)
-      resp.dispose()
+      const ok = _creator.lightVolumeLoad((resp as unknown as { _h: Handle })._h.id)
       if (!ok) { console.warn(`Lightmap: ${files.volume} is not a light grid — rebake`); return }
     } catch (e) {
       console.warn(`Lightmap: could not read ${files.volume}: ${String(e)}`)
@@ -313,10 +314,31 @@ export class Lightmap {
     Lightmap.bound = null
     if (Lightmap.balls) { Lightmap.balls.destroy(); Lightmap.balls = null }
     _creator.lightmapSetOptions?.(1, 0)
+    Lightmap.sunArgs = null
     _creator.lightmapSunSet?.(0, 1, 0, 0, 0, 0, false)
     _creator.lightmapDebug?.(0)
   }
 
+  /** THE MOVERS' SUN SHADOWS ON THE BAKED STATICS (a bot, a barrel, the player's rifle darkening the ground under
+   *  it): the lightmap shader reads the real-time shadow map and the bake's sun map for it, per pixel. Off, a baked
+   *  surface takes no real-time shadow at all — the cheapest lighting tier (some 4 ms of a 16 ms 720p frame on an
+   *  integrated GPU, the yard 2026-09-26); a mover still shades ITSELF and the other movers. Live: it rebinds the
+   *  level's material instances at once. */
+  static get moverShadows(): boolean { return Lightmap._moverShadows }
+  static set moverShadows(on: boolean) {
+    if (Lightmap._moverShadows === on) return
+    Lightmap._moverShadows = on
+    Lightmap.applySun()
+  }
+  private static _moverShadows = true
+  /** The loaded bake's sun (TO the sun ×3, its illuminance rgb, the sun map's levels), null without a sun map. */
+  private static sunArgs: [number, number, number, number, number, number, number] | null = null
+  private static applySun(): void {
+    const a = Lightmap.sunArgs
+    if (a && Lightmap._moverShadows) _creator.lightmapSunSet?.(a[0], a[1], a[2], a[3], a[4], a[5], true, a[6])
+    else _creator.lightmapSunSet?.(0, 1, 0, 0, 0, 0, false)
+  }
+
   /** Apply a bake — or, under `lecodes lightmap bake`, run it. Resolves to null when nothing was
    *  applied (no bake yet, a host without the feature, bake mode). */
   private static scene: Scene | null = null
@@ -333,7 +355,6 @@ export class Lightmap {
       const resp = await fetch(files.data, { useOnce: true })
       if (resp.status >= 400) { console.warn(`Lightmap: no bake at ${files.data} (HTTP ${resp.status}) — run \`lecodes lightmap bake\``); return null }
       data = resp.json()
-      resp.dispose()
     } catch (e) {
       console.warn(`Lightmap: could not read ${files.data}: ${String(e)}`)
       return null
@@ -357,8 +378,8 @@ export class Lightmap {
     _creator.lightmapSetOptions?.(lightScale, data.emissiveNits ?? 0)
     // a mover's sun shadow on the statics: only a bake that wrote the sun map under its aux pages
     const sun = data.sunMap ? data.sun : null
-    if (sun) _creator.lightmapSunSet?.(-sun.direction[0], -sun.direction[1], -sun.direction[2], sun.color[0] * sun.lux, sun.color[1] * sun.lux, sun.color[2] * sun.lux, true, data.sunMapLevels ?? 1)
-    else _creator.lightmapSunSet?.(0, 1, 0, 0, 0, 0, false)
+    Lightmap.sunArgs = sun ? [-sun.direction[0], -sun.direction[1], -sun.direction[2], sun.color[0] * sun.lux, sun.color[1] * sun.lux, sun.color[2] * sun.lux, data.sunMapLevels ?? 1] : null
+    Lightmap.applySun()
     // the reflection probes: the atlas loads like a page, the grid travels as numbers; level-wide on the host
     let probes = 0
     let probeAtlas: Texture | undefined
@@ -370,7 +391,7 @@ export class Lightmap {
       else {
         probeAtlas = await Texture.load(files.probes, { fullSize: true, srgb: false })
         // which probes a pixel reflects is in the aux pages (their probe maps); the host needs the atlas and the records' range
-        probes = _creator.lightmapProbesSet(probeAtlas._id, pb.oct, pb.levels, pb.perRow, pb.count,
+        probes = _creator.lightmapProbesSet(probeAtlas._h.id, pb.oct, pb.levels, pb.perRow, pb.count,
                                             pb.encode[0], pb.encode[1], pb.encode[2], pb.encode[3], pb.encode[4], pb.encode[5])
         if (probes !== pb.count) console.warn(`Lightmap: the host took ${probes} of ${pb.count} probe(s) — rebake`)
       }
@@ -400,9 +421,9 @@ export class Lightmap {
         for (const [ k, inst ] of groups) {
           if (inst.small && inst.light && _creator.lightmapObjectApply && n > 0) {
             const l = inst.light
-            took += _creator.lightmapObjectApply(node.id, light[0]._id, aux[0]._id, Float32Array.from([ ...l.cube.flat(), probeId(l.probes[0]), probeId(l.probes[1]), l.probes[2] ]), k)
+            took += _creator.lightmapObjectApply(node.id, light[0]._h.id, aux[0]._h.id, Float32Array.from([ ...l.cube.flat(), probeId(l.probes[0]), probeId(l.probes[1]), l.probes[2] ]), k)
           } else if (inst.receiver && inst.st && inst.page !== undefined && inst.page < n) {
-            took += _creator.lightmapApply(node.id, light[inst.page]._id, aux[inst.page]._id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
+            took += _creator.lightmapApply(node.id, light[inst.page]._h.id, aux[inst.page]._h.id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
           }
         }
         if (took === 0) console.warn(`Lightmap: ${e.key} (${groups.size} groups) was not loaded lightmapped, or the host binds no groups (rebuild it)`)
@@ -417,7 +438,7 @@ export class Lightmap {
         if (!l || !_creator.lightmapObjectApply || n === 0) continue
         if (e.mesh) e.mesh.material = Lightmap.meshMaterial(e.mesh)
         const d = Float32Array.from([ ...l.cube.flat(), probeId(l.probes[0]), probeId(l.probes[1]), l.probes[2] ])
-        if (_creator.lightmapObjectApply(node.id, light[0]._id, aux[0]._id, d) > 0) smallLit++
+        if (_creator.lightmapObjectApply(node.id, light[0]._h.id, aux[0]._h.id, d) > 0) smallLit++
         continue
       }
       if (!r && declined.has(e.key)) continue   // glass / a declined material: the bake knows it as an occluder - the light grid lights it (loadVolume)
@@ -425,7 +446,7 @@ export class Lightmap {
       const st = r.st!
       // a Mesh receiver: its lit material becomes a lightmap material carrying the same colour / map / factors
       if (e.mesh) e.mesh.material = Lightmap.meshMaterial(e.mesh)
-      const took = _creator.lightmapApply(node.id, light[r.page!]._id, aux[r.page!]._id, st[0], st[1], st[2], st[3])
+      const took = _creator.lightmapApply(node.id, light[r.page!]._h.id, aux[r.page!]._h.id, st[0], st[1], st[2], st[3])
       if (took === 0) { console.warn(`Lightmap: ${e.key} was not loaded lightmapped (Model.load { lightmap: true } / Material.lightmap())`); continue }
       applied++
     }
@@ -479,12 +500,12 @@ export class Lightmap {
     const parts = Lightmap.groupsOf(b.data.instances)
     for (const [ id, e ] of b.byEntity) {
       for (const [ k, inst ] of parts.get(e.key) ?? []) {
-        if (inst.receiver && inst.st && inst.page !== undefined && inst.page < b.pages) _creator.lightmapApply(id, tex[inst.page]._id, b.aux[inst.page]._id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
+        if (inst.receiver && inst.st && inst.page !== undefined && inst.page < b.pages) _creator.lightmapApply(id, tex[inst.page]._h.id, b.aux[inst.page]._h.id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
       }
       const r = b.rects.get(e.key)
       if (!r || r.page! >= b.pages) continue
       const st = r.st!
-      _creator.lightmapApply(id, tex[r.page!]._id, b.aux[r.page!]._id, st[0], st[1], st[2], st[3])
+      _creator.lightmapApply(id, tex[r.page!]._h.id, b.aux[r.page!]._h.id, st[0], st[1], st[2], st[3])
     }
     console.log(`[lightmap] showing the ${kind} pages`)
   }
@@ -508,7 +529,7 @@ export class Lightmap {
       ball.name = `probe#${k}`
       ball.position = [ x, y, z ]
       holder.add(ball)
-      _creator.lightmapApply(ball.id, b.light[0]._id, b.aux[0]._id, 0, 0, 0, 0)
+      _creator.lightmapApply(ball.id, b.light[0]._h.id, b.aux[0]._h.id, 0, 0, 0, 0)
       m.set("probeBall", k + 1)   // probe k alone, unoccluded
       n++
     }
@@ -527,15 +548,13 @@ export class Lightmap {
   static probe(screenX: number, screenY: number): LightmapProbe | null {
     const b = Lightmap.bound
     if (!b || !_creator.pickTriangle) return null
-    type Hit = { entity: number, nodeName: string, material: string, point: number[], distance: number, uv1?: number[], lightmapGroup?: number }
+    type Hit = { entity: number, nodeName: string, material: string, point: number[], distance: number, uv1?: [number, number], lightmapGroup?: number }
     // the nearest hit over the registered statics: one pick per entry (the all-instances pick, entity 0, walks
     // every GLB instance including the off-scene templates and is what a scene file's clones confuse)
     let hit: Hit | null = null
     for (const id of b.byEntity.keys()) {
-      const j = _creator.pickTriangle(id, screenX, screenY)
-      if (!j) continue
-      const h = JSON.parse(j) as Hit
-      if (!hit || h.distance < hit.distance) hit = h
+      const h: Hit | null = _creator.pickTriangle(id, screenX, screenY)
+      if (h && (!hit || h.distance < hit.distance)) hit = h
     }
     if (!hit) { console.log(`[probe] nothing baked under ${screenX.toFixed(0)},${screenY.toFixed(0)}`); return null }
     const entry = b.byEntity.get(hit.entity)
@@ -553,19 +572,16 @@ export class Lightmap {
     }
   }
 
-  /** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
-  private static hex8(c: unknown): string {
-    if (typeof c !== "string") return "#ffffffff"
-    if (c.length === 7) return c + "ff"
-    if (c.length === 4) return "#" + c[1] + c[1] + c[2] + c[2] + c[3] + c[3] + "ff"
-    return c
+  /** A material's colour uniform as "#rrggbbaa" (the float4 uniform path sets its alpha); white without one. */
+  private static colorUniform(c: unknown): string {
+    return typeof c === "string" ? Color.toHexString(c) : "#ffffffff"
   }
 
   /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic). */
   private static meshMaterial(mesh: Mesh): Material {
     const u = mesh.material?.uniforms ?? {}
     const m = Material.lightmap()
-    m.set("baseColorFactor", Lightmap.hex8(u.baseColor ?? u.color))
+    m.set("baseColorFactor", Lightmap.colorUniform(u.baseColor ?? u.color))
     if (u.baseColorMap instanceof Texture) m.set("baseColorMap", u.baseColorMap)
     if (typeof u.roughness === "number") m.set("roughnessFactor", u.roughness)
     if (typeof u.metallic === "number") m.set("metallicFactor", u.metallic)

package/src/gl/Material.ts

@@ -15,16 +15,25 @@ const isCanvasSource = (v: unknown): v is Canvas =>
 
 type UniformValue = string | Texture | number | boolean | number[] | Float32Array | null
 
+// A color string → the RGB or the RGBA slot. The arity is semantic (engines/gl material.cpp): RGB on a
+// float4 keeps the instance's alpha, RGBA sets it — so a color that carries alpha (below 1, or written
+// '#rgba' / '#rrggbbaa') goes RGBA, every other one RGB. Not a color → throws with the value.
+const applyColorUniform = (id: number, key: string, value: string): void => {
+  const rgba = Color.toPackedRgba(value)
+  const t = value.trim()
+  if ((rgba & 0xff) !== 0xff || (t[0] === "#" && (t.length === 5 || t.length === 9))) _creator.setUniformRgba(id, key, rgba)
+  else _creator.setUniformRgb(id, key, rgba >>> 8)
+}
+
 const applyUniform = (id: number, key: string, value: UniformValue): void => {
   if (typeof value === "string") {
-    if (value.length > 7) _creator.setUniformRgba(id, key, parseInt(value.slice(1), 16))
-    else _creator.setUniformRgb(id, key, parseInt(value.slice(1), 16))
+    applyColorUniform(id, key, value)
   } else if (typeof value === "number") {
     _creator.setUniformFloat(id, key, value)
   } else if (typeof value === "boolean") {
     _creator.setUniformBoolean(id, key, value)
   } else if (value instanceof Texture) {
-    _creator.setUniformTexture(id, key, value._id, value.wrapS, value.wrapT)
+    _creator.setUniformTexture(id, key, value._h.id, value.wrapS, value.wrapT)
   } else if (value instanceof Float32Array) {
     _creator.setUniformArray(id, key, value)
   } else if (Array.isArray(value)) {
@@ -163,26 +172,30 @@ export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
 
 
 export class Material {
-  /** @internal native material-instance handle. */
-  _id: number
+  /** @internal The material instance's owned handle (`_h.id` = the engine id). An instance the
+   *  engine created itself (a glTF part's) is wrapped from its number and never freed by us. */
+  _h: Handle
   readonly shader: FetchResponse | "unknown"
   readonly uniforms: Record<string, UniformValue>
 
   private _colorKey: string | null = null
 
-  constructor(shader: FetchResponse | number) {
+  constructor(shader: FetchResponse | Handle | number) {
     if (typeof shader === "number") {
       this.shader = "unknown"
-      this._id = shader
+      this._h = { id: shader }              // an engine-owned instance: not ours to free
+    } else if ("_h" in (shader as any)) {
+      this.shader = shader as FetchResponse
+      this._h = _creator.createMaterial((shader as any)._h.id)   // owned: dropped and unused → freed
     } else {
-      this.shader = shader
-      this._id = _creator.createMaterial((shader as any)._id)
+      this.shader = "unknown"
+      this._h = shader as Handle           // an instance the runtime already wrapped for us
     }
     const store: Record<string, UniformValue> = {}
-    const id = () => this._id
+    const id = () => this._h.id
     this.uniforms = new Proxy(store, {
       get: (t, k: string) => t[k],
-      set: (t, k: string, v: UniformValue) => { t[k] = v; applyUniform(id(), k, v); return true },
+      set: (t, k: string, v: UniformValue) => { applyUniform(id(), k, v); t[k] = v; return true },
     })
   }
 
@@ -199,18 +212,18 @@ export class Material {
   /** 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)
+    if (_creator.setMaterialDepthTest) _creator.setMaterialDepthTest(this._h.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)
+    if (_creator.setMaterialDepthWrite) _creator.setMaterialDepthWrite(this._h.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)
+    if (_creator.setMaterialCulling) _creator.setMaterialCulling(this._h.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`. */
@@ -218,7 +231,7 @@ export class Material {
     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),
+    _creator.setMaterialStencil(this._h.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))
   }
@@ -238,11 +251,20 @@ export class Material {
   }
 
   // --- factories ---
+  // The engine's own materials are asked for by NAME (`_creator.builtinMaterial`): the runtime finds the
+  // shader — in the archive its host ships, or in the host's file of that name. Every call below passes
+  // a string LITERAL: the compile reads a bundle's preload list out of them (compile/header.ts), so a
+  // name that reaches the call through a variable is a material a web host never fetches.
+
+  /** The material an instance handle is of; a host that carries none under `name` is an error naming it. */
+  private static _builtin(h: Handle | null, name: string): Material {
+    if (!h) throw new Error(`Material: this host carries no "${name}" material`)
+    return new Material(h)
+  }
 
   /** PBR lit material. */
   static lit(options: LitMaterialOptions = {}): Material {
-    // The fetchLocal literal must be inline so the compiler's preload header captures the shader name.
-    const m = new Material({ _id: _creatorUtils.fetchLocal("lit.filamat") } as any)
+    const m = Material._builtin(_creator.builtinMaterial("lit"), "lit")
     m._colorKey = "baseColor"
     if (options.color !== undefined) m.color = options.color
     if (options.map) m.map = options.map
@@ -255,16 +277,13 @@ export class Material {
   /** Unlit (flat) material — opaque unless `transparent` asks for alpha blending. */
   static unlit(options: UnlitMaterialOptions = {}): Material {
     // Blending is baked into the shader package (a material instance can't change it), so the
-    // blended twin is its own file. Both fetchLocal literals stay inline — that is what puts the
-    // shader names in the compiler's preload header. A host that predates unlit-transparent answers
-    // -1; fall back to the opaque one rather than handing createMaterial a bad handle.
-    let id = -1
+    // blended twin is its own material. A host without it draws opaque.
+    let h: Handle | null = null
     if (options.transparent) {
-      id = _creatorUtils.fetchLocal("unlit-transparent.filamat")
-      if (id < 0) console.warn("[material] this host ships no unlit-transparent.filamat — drawing opaque")
+      h = _creator.builtinMaterial("unlit-transparent")
+      if (!h) console.warn("[material] this host carries no unlit-transparent material — drawing opaque")
     }
-    if (id < 0) id = _creatorUtils.fetchLocal("unlit.filamat")
-    const m = new Material({ _id: id } as any)
+    const m = Material._builtin(h ?? _creator.builtinMaterial("unlit"), "unlit")
     m._colorKey = "baseColor"
     if (options.color !== undefined) m.color = options.color
     if (options.map) m.map = options.map
@@ -277,10 +296,9 @@ export class Material {
    *  knob is primed here; JS writes after construction override them. */
   static particles(options: ParticlesMaterialOptions = {}): Material {
     const quad = options.render !== undefined && options.render !== "point"
-    // Both fetchLocal literals inline so the compiler's preload header captures the shader names.
     const m = quad
-      ? new Material({ _id: _creatorUtils.fetchLocal("particles-quad.filamat") } as any)
-      : new Material({ _id: _creatorUtils.fetchLocal("particles.filamat") } as any)
+      ? Material._builtin(_creator.builtinMaterial("particles-quad"), "particles-quad")
+      : Material._builtin(_creator.builtinMaterial("particles"), "particles")
     m.uniforms.sheetSize = _sheetColsRows(options.sheet)
     m.uniforms.emissive = options.emissive ?? 0
     m.uniforms.additive = options.blend === "add" ? 1 : 0
@@ -301,10 +319,9 @@ export class Material {
    *  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)
+      ? Material._builtin(_creator.builtinMaterial("decal-relief"), "decal-relief")
+      : Material._builtin(_creator.builtinMaterial("decal"), "decal")
     m.uniforms.time = 0
     m.uniforms.edge = options.edge ?? 0.3
     m.uniforms.angleFade = options.angleFade ?? 0.3
@@ -321,20 +338,21 @@ export class Material {
 
   /** Material that samples a VideoPlayer's texture. */
   static video(map?: Texture): Material {
-    const m = new Material({ _id: _creatorUtils.fetchLocal("video.filamat") } as any)
+    const m = Material._builtin(_creator.builtinMaterial("video"), "video")
     if (map) m.uniforms.baseColorMap = map
     return m
   }
 
-  /** The lightmap material (packages/creator-bake): a lit PBR material whose whole DIFFUSE light is the
+  /** The lightmap material (engines/bake): a lit PBR material whose whole DIFFUSE light is the
    *  baked irradiance atlas on UV1 (`lightmapLight`, lux) — the real-time sun, lamps and diffuse IBL do not
    *  touch it; the specular IBL stays, occluded by the baked sky visibility. Models take it through
    *  `Model.load(…, { lightmap: true })`; a static Mesh gets one from here. Parameters use gltfio's names
    *  (`baseColorFactor`, `baseColorMap`, `roughnessFactor`, `metallicFactor`) plus `lightmapLight`, `lightmapAux`,
    *  `lightmapST`, `lightScale` (the level-wide value `Lightmap.load` sets) and the debug view knobs. */
   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)
+    // The lite material is only asked for (200 KB of shader) when the tier wants it.
+    const lite = Material.lightmapShading === "lite" ? Material._liteTier(_creator.builtinMaterial("lightmap-lite")) : null
+    const m = Material._builtin(lite ?? _creator.builtinMaterial("lightmap"), "lightmap")
     Material._lightmapDefaults(m)
     return m
   }
@@ -342,18 +360,33 @@ export class Material {
   /** `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 m = new Material({ _id: _creatorUtils.fetchLocal("lightmap-masked.filamat") } as any)
+    const lite = Material.lightmapShading === "lite" ? Material._liteTier(_creator.builtinMaterial("lightmap-masked-lite")) : null
+    const m = Material._builtin(lite ?? _creator.builtinMaterial("lightmap-masked"), "lightmap-masked")
     Material._lightmapDefaults(m)
     return m
   }
 
+  /** THE LIGHTMAP SHADER TIER, engine-wide: `"full"` = the target's own blob (desktop: the bicubic atlas fetch, eight
+   *  probe corners, the sun's highlight on metal), `"lite"` = the blob the phones ship (bilinear fetch, one probe
+   *  corner, no sun highlight; the movers' shadows on the statics stay) — on an integrated GPU some 30 % less per
+   *  pixel on a baked level, the picture a phone shows. Read when a lightmap material is FIRST made, which
+   *  `Model.load({ lightmap })` does once per world: set it BEFORE the level loads (a graphics preset applied at
+   *  boot, like `Texture.maxSize`); a change afterwards takes the next level. A host without the lite material
+   *  (a phone: its own blob is that shader already) takes the full one. */
+  static lightmapShading: "full" | "lite" = "full"
+  /** The lite tier's instance, or — said once — that this host has none and the full shader is used. */
+  private static _liteTier(lite: Handle | null): Handle | null {
+    if (!lite && !Material._liteWarned) { Material._liteWarned = true; console.warn("Material.lightmapShading = 'lite': this host carries no lite lightmap material — the full shader is used") }
+    return lite
+  }
+  private static _liteWarned = false
+
   /** 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`. `Terrain` builds and owns one per terrain; the uniforms are primed here so an
    *  unset layer is white. Lit real-time; a BAKED terrain takes `Material.terrainLightmap()`. */
   static terrain(): Material {
-    // Inline literal: the compiler's preload header captures the shader name from it.
-    const m = new Material({ _id: _creatorUtils.fetchLocal("terrain.filamat") } as any)
+    const m = Material._builtin(_creator.builtinMaterial("terrain"), "terrain")
     m.set("tiling", [ 8, 8, 8, 8 ]).set("roughness", [ 1, 1, 1, 1 ]).set("normalScale", [ 0, 0, 0, 0 ]).set("triplanar", [ 0, 0, 0, 0 ])
     m.set("gridSize", [ 2, 2 ]).set("cellSize", 1).set("tint", "#ffffff")
     return m
@@ -365,8 +398,7 @@ export class Material {
    *  bound bake it draws black, like any lightmapped static. No reflection probes (the sampler budget): it reflects the
    *  sky through the baked sky visibility. */
   static terrainLightmap(): Material {
-    // Inline literal: the compiler's preload header captures the shader name from it.
-    const m = new Material({ _id: _creatorUtils.fetchLocal("terrain-lightmap.filamat") } as any)
+    const m = Material._builtin(_creator.builtinMaterial("terrain-lightmap"), "terrain-lightmap")
     m.set("tiling", [ 8, 8, 8, 8 ]).set("roughness", [ 1, 1, 1, 1 ]).set("normalScale", [ 0, 0, 0, 0 ]).set("triplanar", [ 0, 0, 0, 0 ])
     m.set("gridSize", [ 2, 2 ]).set("cellSize", 1).set("tint", "#ffffff")
     m.set("lightmapST", [ 1, 1, 0, 0 ]).set("lightScale", 1).set("debugMode", 0).set("debugParams", [ 0.001, 0, 5, 0 ])
@@ -386,7 +418,7 @@ export class Material {
    *  and a per-copy tint. glTF parameters like `Material.lightmap()` plus `wind` / `sway` / `fade` / `benders`,
    *  which the engine writes itself. Not baked by the rewritten bake yet. */
   static foliage(): Material {
-    const m = new Material({ _id: _creatorUtils.fetchLocal("foliage.filamat") } as any)
+    const m = Material._builtin(_creator.builtinMaterial("foliage"), "foliage")
     Material._glbDefaults(m)
     return m
   }
@@ -394,7 +426,7 @@ export class Material {
   /** `Material.foliage()`'s masked twin (`blending: masked`): what the engine gives a foliage model's alpha-MASK
    *  materials — the cards. */
   static foliageMasked(): Material {
-    const m = new Material({ _id: _creatorUtils.fetchLocal("foliage-masked.filamat") } as any)
+    const m = Material._builtin(_creator.builtinMaterial("foliage-masked"), "foliage-masked")
     Material._glbDefaults(m)
     return m
   }
@@ -409,16 +441,28 @@ export class Material {
     m.set("lightmapST", [ 1, 1, 0, 0 ]).set("lightScale", 1).set("debugMode", 0).set("debugParams", [ 0.001, 0, 5, 0 ])
   }
 
-  /** @internal the foliage template pair, like the lightmap one (a host that lacks the tier returns id 0 from
-   *  fetchLocal — `Model.load` then falls back to the lightmap tier). */
-  static _foliageTemplate(): Material { return (Material._folTemplate ??= Material.foliage()) }
-  private static _folTemplate: Material | undefined
-  static _foliageMaskedTemplate(): Material { return (Material._folMaskedTemplate ??= Material.foliageMasked()) }
-  private static _folMaskedTemplate: Material | undefined
+  /** @internal the foliage template pair, like the lightmap one; null on a host that carries no foliage
+   *  tier — `Model.load` then falls back to the lightmap tier. */
+  static _foliageTemplate(): Material | null {
+    if (Material._folTemplate === undefined) Material._folTemplate = Material._glbTemplate(_creator.builtinMaterial("foliage"))
+    return Material._folTemplate
+  }
+  private static _folTemplate: Material | null | undefined
+  static _foliageMaskedTemplate(): Material | null {
+    if (Material._folMaskedTemplate === undefined) Material._folMaskedTemplate = Material._glbTemplate(_creator.builtinMaterial("foliage-masked"))
+    return Material._folMaskedTemplate
+  }
+  private static _folMaskedTemplate: Material | null | undefined
+  private static _glbTemplate(h: Handle | null): Material | null {
+    if (!h) return null
+    const m = new Material(h)
+    Material._glbDefaults(m)
+    return m
+  }
 
   /** 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)
+    const m = Material._builtin(_creator.builtinMaterial("shadow"), "shadow")
     m._colorKey = "color"
     m.color = color
     return m
@@ -435,7 +479,7 @@ export class Material {
       if (!(id >= 0)) {
         return Promise.reject(new Error(`Shader not found next to the app (${url}). Compile it with \`lecodes shaders compile\`.`))
       }
-      return Promise.resolve(new Material({ _id: id } as any))
+      return Promise.resolve(new Material({ _h: { id: id } } as any))
     }
     return fetch(url, { useOnce: true }).then((resp) => {
       if (resp.status >= 400) return Promise.reject(new Error(`Failed to fetch shader from ${url}. HTTP ${resp.status}`))
@@ -444,7 +488,7 @@ export class Material {
   }
 
   /** @internal */
-  static idOf(material: Material): number { return material._id }
+  static idOf(material: Material): number { return material._h.id }
 }
 
 const applyDepth = (m: Material, o: MaterialStateOptions): void => {