lecodes-cli 0.18.0 → 0.18.2

package/runtime/sdk/gl/Geometry.ts

@@ -20,6 +20,11 @@ export class Geometry {
   normals: Float32Array
   indices: Uint16Array
   uv: Float32Array
+  /** Lightmap UV set (2 floats per vertex, non-overlapping, inside the unit square) — the
+   *  `Lightmap` atlas samples a Mesh through it. The box and cylinder builders fill it (their `uv`
+   *  tiles per face, which would fold every face onto the same texels); absent = the host reuses
+   *  `uv`, which is right for a plane. */
+  uv1?: Float32Array
   /** @internal native mesh-type enum (0 triangles / 1 edges / 2 vertices). */
   _meshKind = 0
 
@@ -50,29 +55,75 @@ export class Geometry {
     this._meshKind = kind === "edges" ? 1 : kind === "vertices" ? 2 : 0
   }
 
-  static box(): Geometry { return createCube() }
+  /** A box; `size` (default 1) scales the vertices AND lays the lightmap chart out in proportion to
+   *  the faces' areas (a floor's top face gets the texels, not its 1 m side strips). */
+  static box(size: Vec3Like | number = 1): Geometry { return createCube(size) }
   static sphere(options?: SphereOptions): Geometry { return createSphere(options) }
   static cylinder(options?: CylinderOptions): Geometry { return createCylinder(options) }
   static plane(options?: PlaneOptions): Geometry { return createPlane(options) }
 }
 
+// Gutter between lightmap charts (fraction of the chart square): the bake dilates each rect by a
+// few texels and the shader samples bilinearly, so neighbouring faces must not touch in uv1.
+const LM_GUTTER = 0.03
+
+type Rect = { x: number, y: number, w: number, h: number }
+
+/** Shelf-pack rectangles (metres) into the unit square at the largest uniform scale — every face
+ *  gets texels in proportion to its area, so a 64×1×64 floor's top face isn't squeezed into the
+ *  same cell as its 1 m side strips. Returns rects in input order. */
+const packCharts = (dims: [number, number][]): Rect[] => {
+  const order = dims.map((_, i) => i).sort((a, b) => dims[b][1] - dims[a][1])
+  const attempt = (scale: number): Rect[] | null => {
+    const out: Rect[] = new Array(dims.length)
+    let x = 0, y = 0, rowH = 0
+    for (const i of order) {
+      const w = dims[i][0] * scale, h = dims[i][1] * scale
+      if (x > 0 && x + w > 1) { y += rowH + LM_GUTTER; x = 0; rowH = 0 }
+      if (w > 1 || y + h > 1) return null
+      out[i] = { x, y, w, h }
+      x += w + LM_GUTTER
+      rowH = Math.max(rowH, h)
+    }
+    return out
+  }
+  let lo = 0, hi = 1 / Math.max(...dims.map((d) => Math.max(d[0], d[1])))
+  let best = attempt(hi)
+  if (!best) {
+    for (let it = 0; it < 40; it++) {
+      const mid = (lo + hi) / 2
+      const r = attempt(mid)
+      if (r) { best = r; lo = mid } else hi = mid
+    }
+  }
+  return best ?? dims.map(() => ({ x: 0, y: 0, w: 1, h: 1 }))
+}
+
 // --- cube ---
-const createCube = (): Geometry => {
+const createCube = (size: Vec3Like | number = 1): Geometry => {
+  const sx = typeof size === "number" ? size : cx(size)
+  const sy = typeof size === "number" ? size : cy(size)
+  const sz = typeof size === "number" ? size : cz(size)
   const vertices = new Float32Array(6 * 4 * 3)
   const normals = new Float32Array(6 * 4 * 3)
-  const uv = new Float32Array(6 * 4 * 3)
+  const uv = new Float32Array(6 * 4 * 2)
+  const uv1 = new Float32Array(6 * 4 * 2)
   const indices = new Uint16Array(6 * 6)
   let cnt = 0, indicesCnt = 0
   const sides = [ -0.5, 0.5 ]
+  // face extents along the (a, b) parameters below: ±x faces span (z, y), ±y faces (x, z), ±z faces (x, y)
+  const charts = packCharts([ [ sz, sy ], [ sz, sy ], [ sx, sz ], [ sx, sz ], [ sx, sy ], [ sx, sy ] ])
   for (let i = 0; i < 6; i++) {
     const s = cnt
     const side = i % 2 === 0 ? -0.5 : 0.5
+    const c = charts[i]
     for (const a of sides) {
       for (const b of sides) {
         uv.set([ a + 0.5, b + 0.5 ], cnt * 2)
-        if (i === 0 || i === 1) { vertices.set([ side, b, -a ], cnt * 3); normals.set([ side * 2, 0, 0 ], cnt * 3) }
-        if (i === 2 || i === 3) { vertices.set([ a, side, -b ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3) }
-        if (i === 4 || i === 5) { vertices.set([ a, b, side ], cnt * 3); normals.set([ 0, 0, side * 2 ], cnt * 3) }
+        uv1.set([ c.x + (a + 0.5) * c.w, c.y + (b + 0.5) * c.h ], cnt * 2)
+        if (i === 0 || i === 1) { vertices.set([ side * sx, b * sy, -a * sz ], cnt * 3); normals.set([ side * 2, 0, 0 ], cnt * 3) }
+        if (i === 2 || i === 3) { vertices.set([ a * sx, side * sy, -b * sz ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3) }
+        if (i === 4 || i === 5) { vertices.set([ a * sx, b * sy, side * sz ], cnt * 3); normals.set([ 0, 0, side * 2 ], cnt * 3) }
         cnt++
       }
     }
@@ -81,7 +132,9 @@ const createCube = (): Geometry => {
     else indices.set([ s2, s1, s, s1, s2, s3 ], indicesCnt)
     indicesCnt += 6
   }
-  return new Geometry(vertices, normals, indices, uv)
+  const g = new Geometry(vertices, normals, indices, uv)
+  g.uv1 = uv1
+  return g
 }
 
 // --- sphere ---
@@ -143,6 +196,8 @@ const createCylinder = (options: CylinderOptions = {}): Geometry => {
   const vertices = new Float32Array(verticesCount * 3)
   const normals = new Float32Array(verticesCount * 3)
   const uv = new Float32Array(verticesCount * 2)
+  // lightmap chart: the side strip across the upper half, the two caps as discs in the lower half
+  const uv1 = new Float32Array(verticesCount * 2)
   const indices = new Uint16Array(edges * 6 + edges * 6)
   const sides = [ -0.5, 0.5 ]
   let cnt = 0, indicesCnt = 0
@@ -159,6 +214,7 @@ const createCylinder = (options: CylinderOptions = {}): Geometry => {
         if (smooth) normals.set([ x, 0, y ], cnt * 3)
         else normals.set([ normalX, 0, normalY ], cnt * 3)
         uv.set([ (i + j) / edges, side + 0.5 ], cnt * 2)
+        uv1.set([ (i + j) / edges, 0.55 + (side + 0.5) * 0.43 ], cnt * 2)
         cnt++
       }
     }
@@ -168,19 +224,24 @@ const createCylinder = (options: CylinderOptions = {}): Geometry => {
   }
   for (const side of sides) {
     const center = cnt
-    vertices.set([ 0, side, 0 ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3); cnt++
+    const capU = side > 0 ? 0.75 : 0.25   // lightmap disc centre per cap
+    vertices.set([ 0, side, 0 ], cnt * 3); normals.set([ 0, side * 2, 0 ], cnt * 3)
+    uv1.set([ capU, 0.25 ], cnt * 2); cnt++
     for (let i = 0; i < edges; i++) {
       const x = Math.cos(i / edges * Math.PI * 2), y = Math.sin(i / edges * Math.PI * 2)
       if (side > 0) vertices.set([ x * radiusTop, side, y * radiusTop ], cnt * 3)
       else vertices.set([ x * radiusBottom, side, y * radiusBottom ], cnt * 3)
       normals.set([ 0, side * 2, 0 ], cnt * 3)
+      uv1.set([ capU + x * 0.22, 0.25 + y * 0.22 ], cnt * 2)
       if (side < 0) indices.set([ center, center + i + 1, center + 1 + ((i + 1) % edges) ], indicesCnt)
       else indices.set([ center + 1 + ((i + 1) % edges), center + i + 1, center ], indicesCnt)
       indicesCnt += 3
       cnt++
     }
   }
-  return new Geometry(vertices, normals, indices, uv)
+  const g = new Geometry(vertices, normals, indices, uv)
+  g.uv1 = uv1
+  return g
 }
 
 // --- plane ---

package/runtime/sdk/gl/Light.ts

@@ -1,4 +1,5 @@
-// Lights. Currently a directional sun (the engine's primary light). Add it to a scene like any node.
+// 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"
@@ -21,17 +22,78 @@ export type SunOptions = {
   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,
-      options.intensity ?? 100000,
+      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

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

@@ -58,6 +58,12 @@ export type ParticlesMaterialOptions = {
   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`
@@ -169,6 +175,7 @@ export class Material {
     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)
@@ -188,6 +195,24 @@ export class Material {
     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)

package/runtime/sdk/gl/Mesh.ts

@@ -24,7 +24,6 @@ export type MeshOptions = {
 
 export class Mesh extends Node {
   private _geometry?: Geometry
-  private _materials: Material[] = []
 
   constructor(geometry?: Geometry, material?: Material) {
     super()
@@ -32,29 +31,15 @@ export class Mesh extends Node {
       const mat = material ?? Material.unlit()
       this._geometry = geometry
       this._materials = [ mat ]
-      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind)
+      _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 }
 
-  get material(): Material { return this._materials[0] }
-  set material(m: Material) { this.setMaterial(m, 0) }
-
-  setMaterial(material: Material, index = 0): this {
-    this._materials[index] = material
-    _creator.setMaterial(this.id, Material.idOf(material), index)
-    return this
-  }
-  getMaterial(index = 0): Material | null {
-    const existing = this._materials[index]
-    if (existing) return existing
-    const id = _creator.getMaterial(this.id, index)
-    if (id === 0) return null
-    const mat = new Material(id)
-    this._materials[index] = mat
-    return mat
-  }
+  /** 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) }
@@ -63,10 +48,8 @@ export class Mesh extends Node {
   // --- factories ---
 
   static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
-    const geo = Geometry.box()
-    const [ sx, sy, sz ] = sizeToVec(options.size ?? 1)
-    if (sx !== 1 || sy !== 1 || sz !== 1) geo.scale(sx, sy, sz)
-    return apply(new Mesh(geo, options.material), options)
+    // 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 {

package/runtime/sdk/gl/Model.ts

@@ -7,11 +7,14 @@
 import { fetch, type FetchResponse } from "../runtime/fetch"
 import { Node } from "./Node"
 import { Animator } 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
 
   constructor(internalId: number) {
     super(internalId)
@@ -24,13 +27,21 @@ export class Model extends Node {
   clone(): Model {
     const id = _creator.cloneEntity(this.id)
     _creator.setGlbCulling(id, false)
-    return new Model(id)
+    const m = new Model(id)
+    m._lightmapped = this._lightmapped
+    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: { culling?: boolean, onProgress?: (p: { loaded: number, total?: number }) => void } = {},
+    options: {
+      culling?: boolean
+      onProgress?: (p: { loaded: number, total?: number }) => void
+      /** Load through the lightmap material so `Lightmap.load` can bind a baked atlas (the GLB needs
+       *  TEXCOORD_1 — `lecodes assets doctor --lightmap-uv`). Hosts without lightmap support ignore it. */
+      lightmap?: boolean
+    } = {},
   ): Promise<Model> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
@@ -39,9 +50,12 @@ export class Model extends Node {
       })
     }
     return new Promise<Model>((resolve, reject) => {
+      const lightmapped = !!options.lightmap && !!_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
         if (options.culling !== true) _creator.setGlbCulling(entityId, false)
         resolve(model)
       }, reject)