lecodes-sdk 0.19.0

package/src/gl/Material.ts

@@ -0,0 +1,279 @@
+// A material instance over creator-gl. Uniforms are set through a Proxy that lowers each JS value to
+// the right native uniform call. The common materials are static factories (Material.lit/unlit/
+// video/shadow); Material.load brings in a custom compiled shader. Ported from worker/src/Material.ts,
+// with the Lit/Unlit/... subclasses collapsed into factories and color accepting any ColorInput.
+
+import { Color, type ColorInput } from "../core/color"
+import { fetch, type FetchResponse } from "../runtime/fetch"
+import { Texture } from "./Texture"
+// Type-only (erased at build) so a 3D material never pulls the 2D-canvas runtime; the guard is inline.
+import type { Canvas } from "../canvas/Canvas"
+
+/** Duck-type a Canvas without importing it (keeps 3D material free of 2D-canvas code). */
+const isCanvasSource = (v: unknown): v is Canvas =>
+  typeof v === "object" && v !== null && (v as { __canvas?: unknown }).__canvas === true
+
+type UniformValue = string | Texture | number | boolean | number[] | Float32Array | null
+
+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))
+  } 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)
+  } else if (value instanceof Float32Array) {
+    _creator.setUniformArray(id, key, value)
+  } else if (Array.isArray(value)) {
+    _creator.setUniformArray(id, key, Float32Array.of(...value))
+  } else {
+    _creator.setUniformNull(id, key)
+  }
+}
+
+export type MaterialColorOptions = { color?: ColorInput, map?: Texture | Canvas | null }
+
+/** `Material.unlit` options. */
+export type UnlitMaterialOptions = MaterialColorOptions & {
+  /** 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
+   *  fading marker, a sprite whose texture has cut-out alpha. Only then does `color`'s own alpha
+   *  (`"#ffffff80"`) mean anything; the opaque material has no alpha channel at all. */
+  transparent?: boolean
+}
+
+/** `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. */
+  map?: Texture | null
+  /** Flipbook grid: `N` = an N×N sheet, `[cols, rows]` = a non-square one. Frames run
+   *  left-to-right, top-to-bottom; drive the index via `particles.frame`. Default 1. */
+  sheet?: number | [number, number]
+  /** Extra brightness multiplier for a glow look (0 = off). */
+  emissive?: number
+  /** (`render` quad / stretch) a second sheet on the same grid, ADDED as `emissiveMap × emissiveColor`
+   *  — keyed by `map`'s alpha, not tinted by the particle colour. A fireball = a smoke `map` whose
+   *  colour curve goes dark + a fire `emissiveMap` that keeps glowing while alpha lasts. */
+  emissiveMap?: Texture | null
+  /** Multiplier for `emissiveMap`; an `[r, g, b]` array may exceed 1 (HDR glow). Default 0 (off). */
+  emissiveColor?: ColorInput
+  /** (`render` quad / stretch) crossfade each flipbook frame into the next by the fractional frame
+   *  index instead of snapping — smooth sheet playback at any frame rate. Default false. */
+  frameBlend?: boolean
+  /** Compositing: `"alpha"` (default — smoke, dust) or `"add"` (fire, sparks, magic). */
+  blend?: "alpha" | "add"
+  /** Soft radial falloff toward the sprite edge. Defaults to true without a map, false with one. */
+  soft?: boolean
+  /** Soft particles: fade each sprite out over this many metres as it cuts into the scene geometry
+   *  behind it (Unity's "Soft Particles Factor"), so smoke and dust no longer slice through the
+   *  ground and walls with a hard edge. 0 = off (default). Reads the scene's depth buffer, which the
+   *  engine keeps bound while any soft system is on screen — the extra depth pass is only paid then.
+   *  Filament hosts (desktop / web / Android / Apple); web-lite draws such sprites unfaded. */
+  depthFade?: number
+  /** How each particle is drawn: `'point'` (default — GPU point sprites, cheapest), `'quad'`
+   *  (real camera-facing quads — no driver size cap, geometric rotation), or `'stretch'`
+   *  (quads stretched along velocity — sparks, rain, speed streaks). `'ribbon'` is what `Trail`
+   *  uses internally. */
+  render?: "point" | "quad" | "stretch" | "ribbon"
+  /** (`render: 'stretch'`) extra sprite length in world units per unit of speed:
+   *  length = size + stretch·|velocity|. Default 0.05. */
+  stretch?: number
+}
+
+/** @internal — the sheet option as whole [cols, rows], both ≥ 1. The particles shader divides
+ *  by these with no guard of its own, so this clamp is the only thing between it and a NaN UV. */
+export const _sheetColsRows = (sheet: number | [number, number] | undefined): [number, number] => {
+  const [ c, r ] = typeof sheet === "number" ? [ sheet, sheet ] : sheet ?? [ 1, 1 ]
+  return [ Math.max(1, Math.floor(c) || 1), Math.max(1, Math.floor(r) || 1) ]
+}
+
+/** `Material.lit` options — PBR scalars on top of the color/map pair. */
+export type LitMaterialOptions = MaterialColorOptions & {
+  /** 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
+}
+
+export class Material {
+  /** @internal native material-instance handle. */
+  _id: number
+  readonly shader: FetchResponse | "unknown"
+  readonly uniforms: Record<string, UniformValue>
+
+  private _colorKey: string | null = null
+
+  constructor(shader: FetchResponse | number) {
+    if (typeof shader === "number") {
+      this.shader = "unknown"
+      this._id = shader
+    } else {
+      this.shader = shader
+      this._id = _creator.createMaterial((shader as any)._id)
+    }
+    const store: Record<string, UniformValue> = {}
+    const id = () => this._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 a uniform (chainable). */
+  set(key: string, value: UniformValue): this {
+    this.uniforms[key] = value
+    return this
+  }
+
+  set color(c: ColorInput) {
+    if (this._colorKey) this.uniforms[this._colorKey] = Color.toHexString(c)
+  }
+
+  // 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
+  // last of those, the Apple unlit fork, is gone. Hosts still TRANSLATE the uniform when an older
+  // compiled bundle sets it — that's their compatibility path, not something the SDK emits.)
+  set map(value: Texture | Canvas | null) {
+    if (value === null) {
+      this.uniforms.baseColorMap = null
+    } else {
+      // A Canvas bakes to a (cached) 3D texture on assign — same as Sprite accepting a Canvas in 2D.
+      this.uniforms.baseColorMap = isCanvasSource(value) ? Texture.fromCanvas(value) : value
+    }
+  }
+
+  // --- factories ---
+
+  /** 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)
+    m._colorKey = "baseColor"
+    if (options.color !== undefined) m.color = options.color
+    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
+    return m
+  }
+
+  /** 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
+    if (options.transparent) {
+      id = _creatorUtils.fetchLocal("unlit-transparent.filamat")
+      if (id < 0) console.warn("[material] this host ships no unlit-transparent.filamat — drawing opaque")
+    }
+    if (id < 0) id = _creatorUtils.fetchLocal("unlit.filamat")
+    const m = new Material({ _id: id } as any)
+    m._colorKey = "baseColor"
+    if (options.color !== undefined) m.color = options.color
+    if (options.map) m.map = options.map
+    return m
+  }
+
+  /** Default particle material — camera-facing point sprites with tint/opacity/rotation/flipbook
+   *  driven by the particle curves. Uniforms all default to 0 on a fresh instance, so every look
+   *  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)
+    m.uniforms.sheetSize = _sheetColsRows(options.sheet)
+    m.uniforms.emissive = options.emissive ?? 0
+    m.uniforms.additive = options.blend === "add" ? 1 : 0
+    m.uniforms.softness = (options.soft ?? !options.map) ? 1 : 0
+    m.uniforms.depthFade = options.depthFade ?? 0
+    if (quad) {
+      m.uniforms.mode = options.render === "ribbon" ? 2 : options.render === "stretch" ? 1 : 0
+      m.uniforms.stretch = options.stretch ?? (options.render === "stretch" ? 0.05 : 0)
+      if (options.emissiveMap) m.uniforms.emissiveMap = options.emissiveMap
+      if (options.emissiveColor !== undefined) m.uniforms.emissiveColor = Color.toRgb01(options.emissiveColor)
+      if (options.frameBlend) m.uniforms.frameBlend = 1
+    }
+    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)
+    if (map) m.uniforms.baseColorMap = map
+    return m
+  }
+
+  /** The lightmap material (docs/lightmap-plan.md): PBR base colour × a baked shadow/AO atlas on UV1.
+   *  Models take it through `Model.load(…, { lightmap: true })`; `Lightmap.load` builds one per static
+   *  Mesh. Parameters use gltfio's names (`baseColorFactor`, `baseColorMap`, `roughnessFactor`,
+   *  `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)
+    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
+    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
+   *  `Material.lightmap`). `Terrain` builds and owns one per terrain; the uniforms are primed here so an
+   *  unset layer is white and an unbaked terrain is fully lit. */
+  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)
+    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("ambientScale", 1).set("sunStrength", 1).set("bakedAo", 1).set("lightScale", 0)
+    return m
+  }
+
+  /** @internal the shared template instance `Model.load({ lightmap })` hands the engine (its MATERIAL is what
+   *  the GLB provider instantiates; the template itself never draws). */
+  static _lightmapTemplate(): Material { return (Material._lmTemplate ??= Material.lightmap()) }
+  private static _lmTemplate: Material | undefined
+
+  /** 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)
+    m._colorKey = "color"
+    m.color = color
+    return m
+  }
+
+  /** Load a custom compiled shader (.mat URL) as a material. */
+  static load(url: string): Promise<Material> {
+    // "id:<n>" — the artifact is a LOCAL file the host already resolved through fetchLocal (a
+    // compile with no asset server: the desktop host reads it from next to the bundle). There is
+    // nothing to fetch, so the material is ready synchronously; -1 means the host found no such
+    // file, which would otherwise reach createMaterial as a bad handle.
+    if (url.startsWith("id:")) {
+      const id = Number(url.slice(3))
+      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 fetch(url, { useOnce: true }).then((resp) => {
+      if (resp.status >= 400) return Promise.reject(new Error(`Failed to fetch shader from ${url}. HTTP ${resp.status}`))
+      return new Material(resp)
+    })
+  }
+
+  /** @internal */
+  static idOf(material: Material): number { return material._id }
+}

package/src/gl/Mesh.ts

@@ -0,0 +1,83 @@
+// 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
+}

package/src/gl/Model.ts

@@ -0,0 +1,124 @@
+// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
+// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
+// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
+//   const hero = await Model.load(asset('./hero.glb'))
+//   hero.anim.play('Run', { loop: true })
+
+import { fetch, type FetchResponse } from "../runtime/fetch"
+import { Node } from "./Node"
+import { Animator, _pushLod, type LodMode } from "./animation/Animator"
+import { Material } from "./Material"
+
+export class Model extends Node {
+  /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
+   *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
+  declare readonly anim: Animator
+  /** @internal loaded through the lightmap material (docs/lightmap-plan.md); clones inherit it. */
+  _lightmapped = false
+  /** @internal what `load` does without an explicit `lightmap` option: `'dynamic'` while a scene file with
+   *  `env.lightmap.volume` runs (Lightmap sets it), so weapons, spawns and make() subtrees read the volume. */
+  static _lightmapDefault: false | "dynamic" = false
+  /** @internal the shadow pair, mirrored here because the bridge writes both at once. */
+  _castShadows = true
+  /** @internal */
+  _receiveShadows = true
+  /** @internal */
+  _culling = true
+  /** @internal -1 = auto (see `lod`) */
+  _lodMesh = -1
+
+  constructor(internalId: number) {
+    super(internalId)
+    this.aspect(Animator)
+  }
+
+  /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
+   *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
+   *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
+   *  is never wanted. */
+  get castShadows(): boolean { return this._castShadows }
+  set castShadows(v: boolean) { this._castShadows = v; this._applyShadows() }
+
+  /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
+  get receiveShadows(): boolean { return this._receiveShadows }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; this._applyShadows() }
+
+  /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
+   *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
+   *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
+   *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
+   *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
+   *  mesh, a debugging aid); `true` forces it on regardless of the host. */
+  get culling(): boolean { return this._culling }
+  set culling(v: boolean) { this._culling = v; _creator.setGlbCulling(this.id, v) }
+  /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
+   *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
+   *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
+   *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
+   *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
+  get lod(): LodMode { return this._lodMesh < 0 ? "auto" : (this._lodMesh as 0 | 1 | 2 | 3) }
+  set lod(v: LodMode) { this._lodMesh = v === "auto" ? -1 : Math.max(0, Math.min(3, Math.round(v))); _pushLod(this) }
+
+  /** @internal the default for a fresh instance (load / clone), decided once per host. */
+  static _cullingDefault(): boolean {
+    if (Model._cullDefault === undefined) Model._cullDefault = !!_creator.skinnedCullingSupported?.()
+    return Model._cullDefault
+  }
+  private static _cullDefault: boolean | undefined
+
+  /** @internal both flags travel together — the bridge walks the instance once. */
+  _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
+
+  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
+   *  the same parent and scene and sharing this model's current transform. The clone has its own
+   *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
+  clone(): Model {
+    const id = _creator.cloneEntity(this.id)
+    const m = new Model(id)
+    m._lightmapped = this._lightmapped
+    if (!this._culling) { m._culling = false; _creator.setGlbCulling(id, false) }   // the engine default is on
+    if (this._lodMesh >= 0) { m._lodMesh = this._lodMesh; _pushLod(m) }
+    // the clone is a FRESH gltfio instance — it comes back with the asset's own shadow flags,
+    // not this model's, so a cleared flag has to be re-applied
+    m._castShadows = this._castShadows
+    m._receiveShadows = this._receiveShadows
+    if (!this._castShadows || !this._receiveShadows) m._applyShadows()
+    return m
+  }
+
+  /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
+  static load(
+    source: string | FetchResponse,
+    options: {
+      /** Frustum culling — see `culling` (default: on where the host refits skinned bounds, else off). */
+      culling?: boolean
+      onProgress?: (p: { loaded: number, total?: number }) => void
+      /** Baked lighting (docs/lightmap-plan.md). `true` = a STATIC: loads through the lightmap material so
+       *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
+       *  --lightmap-uv`). `'dynamic'` = a mover: the same material, lit by the level's light VOLUME instead
+       *  (no UV1 needed). Omitted: `'dynamic'` while a scene file with `env.lightmap.volume` is running,
+       *  else off. `false` = the standard shader. Hosts without lightmap support ignore it. */
+      lightmap?: boolean | "dynamic"
+    } = {},
+  ): Promise<Model> {
+    if (typeof source === "string") {
+      return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
+        if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`))
+        return Model.load(resp, options)
+      })
+    }
+    return new Promise<Model>((resolve, reject) => {
+      const mode = options.lightmap ?? Model._lightmapDefault
+      const lightmapped = !!mode && !!_creator.setNextGlbLightmapped
+      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()))
+      _creator.createGlb((source as unknown as { _id: number })._id, (entityId: number) => {
+        if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
+        const model = new Model(entityId)
+        model._lightmapped = lightmapped
+        const culling = options.culling ?? Model._cullingDefault()
+        if (!culling) { model._culling = false; _creator.setGlbCulling(entityId, false) }
+        resolve(model)
+      }, reject)
+    })
+  }
+}