lecodes-cli 0.18.2 → 0.19.2

package/runtime/sdk/gl/InstancedMesh.ts

@@ -1,132 +0,0 @@
-// One geometry drawn many times — grass tufts, crates, debris, coins, a crowd of identical props —
-// with a transform per instance and a handful of draw calls. Hardware instancing (Filament's
-// InstanceBuffer): the engine applies each instance's local matrix, so any regular material works.
-//
-// Transforms live in a CPU-side Float32Array (16 floats per instance, column-major, local to this
-// node). `setAt` / `hideAt` / `setMatrixAt` edit it and track the dirty range; `commit()` uploads
-// that range in one bridge call — call it once per frame after your edits, not per instance.
-// The native side splits the instances into chunks of the platform's per-draw cap (64 native,
-// 8 on WebGL) on child entities, and keeps a bounding box per chunk so frustum culling stays on.
-
-import { Mat4, type Mat4Like } from "../math/mat4"
-import { Quat, type QuatLike } from "../math/quat"
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import type { Geometry } from "./Geometry"
-import { Material } from "./Material"
-import type { MeshOptions } from "./Mesh"
-import { Node } from "./Node"
-
-/** One instance's placement, local to the InstancedMesh node. Omitted fields mean identity. */
-export type InstanceTransform = {
-  position?: Vec3Like
-  /** Quaternion; wins over `eulerAngles`. */
-  rotation?: QuatLike
-  /** Degrees (YXZ), like `Node.eulerAngles`. */
-  eulerAngles?: Vec3Like
-  scale?: Vec3Like | number
-}
-
-const DEG = Math.PI / 180
-
-export class InstancedMesh extends Node {
-  /** Instance capacity, fixed at construction. Unset instances are hidden. */
-  readonly count: number
-  private _geometry: Geometry
-  private _material: Material
-  private _data: Float32Array
-  private _lo = Infinity
-  private _hi = -1
-
-  constructor(geometry: Geometry, count: number, options: MeshOptions = {}) {
-    super()
-    if (!(count >= 1)) throw new Error("InstancedMesh: count must be ≥ 1")
-    this.count = Math.floor(count)
-    this._geometry = geometry
-    this._material = options.material ?? Material.unlit()
-    this._data = new Float32Array(16 * this.count)
-    _creator.createInstancedMesh(this.id, Material.idOf(this._material), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, this.count)
-    if (options.position) this.position = options.position
-    if (options.eulerAngles) this.eulerAngles = options.eulerAngles
-    if (options.scale !== undefined) this.scale = typeof options.scale === "number" ? [ options.scale, options.scale, options.scale ] : options.scale
-    if (options.name !== undefined) this.name = options.name
-    if (options.castShadows !== undefined || options.receiveShadows !== undefined) {
-      _creator.setInstancedMeshShadows(this.id, options.castShadows ?? true, options.receiveShadows ?? true)
-    }
-  }
-
-  override get geometry(): Geometry { return this._geometry }
-
-  get material(): Material { return this._material }
-  set material(m: Material) {
-    this._material = m
-    _creator.setInstancedMeshMaterial(this.id, Material.idOf(m))
-  }
-
-  /** Shadow flags for all instances (both at once — the engine sets them per draw). */
-  setShadows(cast: boolean, receive = cast): this {
-    _creator.setInstancedMeshShadows(this.id, cast, receive)
-    return this
-  }
-
-  private _touch(i: number): void {
-    if (i < this._lo) this._lo = i
-    if (i > this._hi) this._hi = i
-  }
-
-  /** Place instance `i`. Pending until `commit()`. */
-  setAt(i: number, t: InstanceTransform): this {
-    if (i < 0 || i >= this.count) throw new RangeError(`InstancedMesh: index ${i} out of 0..${this.count - 1}`)
-    const rot = t.rotation ?? (t.eulerAngles
-      ? Quat.fromEuler(cx(t.eulerAngles) * DEG, cy(t.eulerAngles) * DEG, cz(t.eulerAngles) * DEG)
-      : Quat.identity)
-    const m = Mat4.compose(t.position ?? [ 0, 0, 0 ], rot, t.scale ?? 1).toArray()
-    this._data.set(m, i * 16)
-    this._touch(i)
-    return this
-  }
-
-  /** Place instance `i` from a 4×4 column-major matrix (local to this node). */
-  setMatrixAt(i: number, m: Mat4Like): this {
-    if (i < 0 || i >= this.count) throw new RangeError(`InstancedMesh: index ${i} out of 0..${this.count - 1}`)
-    const a = m instanceof Mat4 ? m.toArray() : m
-    for (let k = 0; k < 16; k++) this._data[i * 16 + k] = a[k]
-    this._touch(i)
-    return this
-  }
-
-  /** Hide instance `i` (a zero matrix — no geometry is emitted for it). */
-  hideAt(i: number): this {
-    if (i < 0 || i >= this.count) throw new RangeError(`InstancedMesh: index ${i} out of 0..${this.count - 1}`)
-    this._data.fill(0, i * 16, i * 16 + 16)
-    this._touch(i)
-    return this
-  }
-
-  /** Bulk write: `matrices` holds 16 floats per instance, starting at instance `offset`. */
-  setMatrices(matrices: ArrayLike<number>, offset = 0): this {
-    const n = Math.min(Math.floor(matrices.length / 16), this.count - offset)
-    if (n <= 0) return this
-    this._data.set(Array.prototype.slice.call(matrices, 0, n * 16), offset * 16)
-    this._touch(offset)
-    this._touch(offset + n - 1)
-    return this
-  }
-
-  /** The 4×4 of instance `i` as stored (a copy). */
-  matrixAt(i: number): Mat4 {
-    return Mat4.from(this._data.subarray(i * 16, i * 16 + 16))
-  }
-
-  /** Upload every change since the last commit (one bridge call covering the dirty range). */
-  commit(): this {
-    if (this._hi < this._lo) return this
-    const lo = this._lo, hi = this._hi
-    this._lo = Infinity
-    this._hi = -1
-    _creator.setInstanceTransforms(this.id, this._data.subarray(lo * 16, (hi + 1) * 16), lo)
-    return this
-  }
-
-  /** Whether edits are waiting for `commit()`. */
-  get dirty(): boolean { return this._hi >= this._lo }
-}

package/runtime/sdk/gl/Light.ts

@@ -1,99 +0,0 @@
-// Lights. A directional sun (the engine's primary light) and punctual point lights. Add one to a
-// scene like any node; `intensity` and `color` stay writable so a light can be animated.
-
-import { Color, type ColorInput } from "../core/color"
-import type { Vec3Like } from "../math/vec"
-import { Node } from "./Node"
-
-export type SunOptions = {
-  /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
-  direction?: Vec3Like
-  /** Luminous intensity. */
-  intensity?: number
-  color?: ColorInput
-  /**
-   * Shadow quality (default 1):
-   *   0 - no shadows
-   *   1 - standard (1024 shadow map, hard PCF edges)
-   *   2 - high (2048 + stable, soft contact-hardening edges)
-   *   3 - best (4096 + stable, PCSS soft shadows)
-   * Higher values cost more GPU/memory.
-   */
-  shadowsQuality?: 0 | 1 | 2 | 3
-}
-
-export type PointOptions = {
-  /**
-   * Luminous POWER in lumens — the same physical scale as the sun's lux and `environmentIntensity`,
-   * so a light keeps its look when the scene's exposure changes. A candle is ~12 lm, a bare 60 W
-   * bulb ~800, a car headlight ~1500, a fireball millions. Default 1000.
-   */
-  intensity?: number
-  color?: ColorInput
-  /**
-   * Metres of influence — past it the light contributes nothing. This is the performance knob:
-   * overlapping point lights are the expensive case, so keep it as small as the look allows.
-   * Default 10.
-   */
-  range?: number
-  /** Point-light shadows are a cubemap render per light; off by default. */
-  castShadows?: boolean
-}
-
-export class Light extends Node {
-  private _intensity = 0
-  /** @internal sun direction as created (the engine keeps it; Lightmap.load reads it back). */
-  _direction: [number, number, number] = [ 0, -1, 0 ]
-  /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
-  static lastSun: Light | null = null
-
-  /** A directional sun light. */
-  static sun(options: SunOptions = {}): Light {
-    const light = new Light()
-    const [ dx, dy, dz ] = options.direction ?? [ 0.548267, -0.473983, -0.689016 ]
-    light._direction = [ dx, dy, dz ]
-    light._intensity = options.intensity ?? 100000
-    Light.lastSun = light
-    _creator.createSunLight(
-      light.id, dx, dy, dz,
-      light._intensity,
-      Color.toPackedRgb(options.color ?? 0xffffff),
-      options.shadowsQuality ?? 1,
-    )
-    return light
-  }
-
-  /**
-   * A point light — a lamp, a muzzle flash, a fireball. Position it like any node.
-   *
-   * Feature-detected: hosts that predate it create the node and light nothing, which keeps a scene
-   * that adds atmosphere on top of its sun renderable everywhere. Check `Light.supportsPoint`
-   * before making one carry the scene.
-   */
-  static point(options: PointOptions = {}): Light {
-    const light = new Light()
-    light._intensity = options.intensity ?? 1000
-    _creator.createPointLight?.(
-      light.id,
-      light._intensity,
-      Color.toPackedRgb(options.color ?? 0xffffff),
-      options.range ?? 10,
-      options.castShadows ?? false,
-    )
-    return light
-  }
-
-  /** Whether this host can create point lights at all. */
-  static get supportsPoint(): boolean { return _creator.createPointLight !== undefined }
-
-  /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
-  get intensity(): number { return this._intensity }
-  set intensity(value: number) {
-    this._intensity = value
-    _creator.setLightIntensity?.(this.id, value)
-  }
-
-  set color(value: ColorInput) {
-    _creator.setLightColor?.(this.id, Color.toPackedRgb(value))
-  }
-}

package/runtime/sdk/gl/Lightmap.ts

@@ -1,179 +0,0 @@
-// Baked shadows for static 3D geometry (docs/lightmap-plan.md). A scene FILE does all of this by
-// itself: `env: { lightmap: { data, texture } }` 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).
-// Hand-built scenes register what never moves with `Lightmap.add`, bake once with
-// `lecodes lightmap bake` (the desktop host traces the live scene and writes lightmap.ktx2 +
-// lightmap.bake), and `Lightmap.load` applies the atlas at runtime:
-//
-//   const crate = await Model.load(asset('./assets/props/crate.glb'), { lightmap: true })
-//   Lightmap.add(holder)                    // a Model, a Mesh, or a node holding them
-//   Lightmap.add(ground)                    // Mesh.plane works too
-//   ...
-//   await Lightmap.load(scene, { data: asset('./assets/lightmap/lightmap.bake'),
-//                                texture: asset('./assets/lightmap/lightmap.ktx2') })
-//
-// Both files are asset() handles because the compiler stages exactly the files it sees (the data
-// file is JSON with a .bake extension — a .json would be scanned as a code module). `load` is a
-// no-op when the bake is missing or the host predates the feature, so the project stays runnable —
-// and in BAKE mode (`lecodes lightmap bake`) it is where the bake fires: the same call marks "the
-// scene is complete". Atlas channels: R = sun visibility, G = ambient occlusion; the shader keeps
-// the real-time sun for dynamic casters and multiplies the baked mask in with an ambient floor.
-
-import { fetch } from "../runtime/fetch"
-import { Texture } from "./Texture"
-import { Material } from "./Material"
-import { Mesh } from "./Mesh"
-import { Model } from "./Model"
-import { Node } from "./Node"
-import type { Scene } from "./Scene"
-
-export type LightmapLoadOptions = {
-  /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
-  sunStrength?: number
-  /** Multiplier on the ambient (IBL) share in the shadow math — how bright a fully shadowed texel
-   *  stays. 1 reproduces filament's own real-time shadow darkness (the shader reads the scene's sun
-   *  and IBL from filament's per-frame uniforms); raise it for lighter shadows, lower for deeper. Default 1. */
-  ambientScale?: number
-}
-
-export type LightmapInfo = {
-  size: number
-  texel: number
-  /** keys applied / keys in the file / registered statics without a rect */
-  applied: number
-  total: number
-  missing: string[]
-}
-
-type Entry = { key: string, model?: Model, mesh?: Mesh }
-
-type BakeConfig = {
-  outDir: string, size?: number, texel?: number, sunRays?: number, aoRays?: number,
-  aoDistance?: number, bias?: number, sunAngle?: number,
-}
-
-const bakeConfig = (): BakeConfig | null => {
-  const g = (globalThis as unknown as { __lecodesLightmap?: BakeConfig }).__lecodesLightmap
-  return g && typeof g.outDir === "string" ? g : null
-}
-
-/** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
-const 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
-}
-
-export class Lightmap {
-  /** True while `lecodes lightmap bake` runs the app — skip menus and build the scene straight away. */
-  static get baking(): boolean { return bakeConfig() !== null }
-
-  private static entries: Entry[] = []
-  private static ordinals = new Map<string, number>()
-  private static warned = false
-
-  /** Register static geometry — a Model, a Mesh, or any node whose subtree holds them. Statics are
-   *  both receivers and occluders in the bake. `key` names the entry in lightmap.bake (default:
-   *  the node's name + a running number, `container#3`); pass one when names are not stable. */
-  static add(node: Node, key?: string): Node {
-    const base = key ?? `${node.name || "node"}#${Lightmap.next(node.name || "node")}`
-    const found: Entry[] = []
-    const walk = (n: Node): void => {
-      if (n instanceof Model) { found.push({ key: base, model: n }); return }
-      if (n instanceof Mesh) { found.push({ key: base, mesh: n }); return }
-      for (const c of n.children) walk(c)
-    }
-    walk(node)
-    if (found.length === 0) { console.warn(`Lightmap.add: ${base} holds no Model or Mesh`); return node }
-    if (found.length > 1) found.forEach((e, i) => { e.key = `${base}/${i}` })
-    Lightmap.entries.push(...found)
-    return node
-  }
-
-  /** @internal Scene-file runtime: one model/mesh node under its path key (no subtree walk). */
-  static _register(node: Model | Mesh, key: string): void {
-    Lightmap.entries.push(node instanceof Model ? { key, model: node } : { key, mesh: node })
-  }
-
-  private static next(name: string): number {
-    const n = Lightmap.ordinals.get(name) ?? 0
-    Lightmap.ordinals.set(name, n + 1)
-    return n
-  }
-
-  /** Forget every registration (a scene rebuild). */
-  static clear(): void {
-    Lightmap.entries = []
-    Lightmap.ordinals.clear()
-  }
-
-  /** 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). */
-  static async load(scene: Scene, files: { data: string, texture: string }, options: LightmapLoadOptions = {}): Promise<LightmapInfo | null> {
-    const bake = bakeConfig()
-    if (bake) { Lightmap.bake(bake); return null }
-    if (!_creator.lightmapApply) {
-      if (!Lightmap.warned) { Lightmap.warned = true; console.warn("Lightmap: this host has no lightmap support — rendering without the bake") }
-      return null
-    }
-    let data: { size: number, texel: number, sun?: number[] | null, instances: { key: string, receiver: boolean, st?: number[] }[] }
-    try {
-      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
-    }
-    const texture = await Texture.load(files.texture)
-    const ambientScale = options.ambientScale ?? 1
-    const strength = options.sunStrength ?? 1
-    const rects = new Map<string, number[]>()
-    for (const inst of data.instances) if (inst.receiver && inst.st) rects.set(inst.key, inst.st)
-    let applied = 0
-    const missing: string[] = []
-    for (const e of Lightmap.entries) {
-      const st = rects.get(e.key)
-      if (!st) { missing.push(e.key); continue }
-      if (e.model) {
-        const n = _creator.lightmapApply(e.model.id, texture._id, st[0], st[1], st[2], st[3], ambientScale, strength)
-        if (n === 0) { console.warn(`Lightmap: ${e.key} was not loaded with { lightmap: true } — skipped`); continue }
-        _creator.setGlbShadows?.(e.model.id, false, true)
-      } else if (e.mesh) {
-        Lightmap.swapMeshMaterial(e.mesh, texture, st, ambientScale, strength)
-        e.mesh.castShadows = false
-      }
-      applied++
-    }
-    if (missing.length) console.warn(`Lightmap: ${missing.length} static(s) have no rect in the bake (${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "…" : ""}) — rebake`)
-    return { size: data.size, texel: data.texel, applied, total: rects.size, missing }
-  }
-
-  /** A Mesh keeps its look (colour / map / roughness / metallic) but moves to the lightmap material. */
-  private static swapMeshMaterial(mesh: Mesh, texture: Texture, st: number[], ambientScale: number, strength: number): void {
-    const src = mesh.material
-    const u = src?.uniforms ?? {}
-    const m = Material.lightmap()
-    m.set("baseColorFactor", hex8(u.baseColor))
-    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)
-    m.set("lightmap", texture)
-    m.set("lightmapST", [ st[0], st[1], st[2], st[3] ])
-    m.set("ambientScale", ambientScale)
-    m.set("sunStrength", strength)
-    mesh.setMaterial(m)
-  }
-
-  private static bake(cfg: BakeConfig): void {
-    if (!_creator.lightmapBake) { console.error("[lightmap] error: this host has no bake module (build the desktop host with CREATOR_GL_LIGHTMAP, or update lecodes desktop)"); return }
-    const ids = Uint32Array.from(Lightmap.entries.map((e) => (e.model ?? e.mesh)!.id))
-    const keys = Lightmap.entries.map((e) => e.key).join("\n")
-    if (ids.length === 0) { console.error("[lightmap] error: nothing registered — call Lightmap.add on the static props before Lightmap.load"); return }
-    _creator.lightmapBake(cfg.outDir, ids, keys, cfg.size ?? 4096, cfg.texel ?? 0.02, cfg.sunRays ?? 32, cfg.aoRays ?? 64,
-      cfg.aoDistance ?? 2, cfg.bias ?? 0.02, cfg.sunAngle ?? 0.5)
-  }
-}

package/runtime/sdk/gl/Material.ts

@@ -1,245 +0,0 @@
-// 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.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
-  private _useMapFlag = false
-
-  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. The useBaseColorMap writes
-  // stay for older hosts whose shaders still branch on the flag — current engines ignore it.
-  set map(value: Texture | Canvas | null) {
-    if (value === null) {
-      this.uniforms.baseColorMap = null
-      if (this._useMapFlag) this.uniforms.useBaseColorMap = false
-    } 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
-      if (this._useMapFlag) this.uniforms.useBaseColorMap = true
-    }
-  }
-
-  // --- 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. */
-  static unlit(options: MaterialColorOptions = {}): Material {
-    const m = new Material({ _id: _creatorUtils.fetchLocal("unlit.filamat") } 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._useMapFlag = false
-    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)
-    m._useMapFlag = false
-    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)
-    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 }
-}