lecodes-sdk 2.3.0 → 2.4.0

package/src/gl/Lightmap.ts

@@ -221,13 +221,18 @@ export class Lightmap {
   /** The bake bound last (`load`): what `probe` reads rects from. */
   private static bound: Bound | null = null
 
-  /** 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 the .bake (default:
-   *  the node's name + a running number, `container#3`); pass one when names are not stable. */
+  /** Register static geometry — a Model, a Mesh, a Terrain's node, or any node whose subtree holds them. Statics are
+   *  both receivers and occluders in the bake (a model without lightmap UVs, or with materials the lightmap shader
+   *  declines — alpha cards — is an occluder alone; a terrain is ONE rect, built with `Material.terrainLightmap()`).
+   *  `key` names the entry in the .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 => {
+      // the node `Terrain.create` returned carries its terrain (Terrain.of reads the same field): the host keeps the
+      // terrain's triangles under this node's id for the bake and binds the rect to its chunks
+      if ((n as unknown as { _terrain?: unknown })._terrain) { found.push({ key: base, ground: n }); return }
       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)

package/src/gl/Material.ts

@@ -451,8 +451,17 @@ export class Material {
     return Material._folTemplate
   }
   private static _folTemplate: Material | null | undefined
+  /** Which material a foliage model's CARDS (its alpha-MASK materials) take: `"full"` = `foliage-masked`, the
+   *  shader with the card's own plane, normal map, edge fade and the ground's baked light; `"lean"` =
+   *  `foliage-cards`, the same wind with the lighting moved to the vertex (one texture read, the sun's shadow
+   *  kept) — a third of a forest frame less on a phone-class GPU (2026-10-18). Read when the first foliage
+   *  model loads; set it before. */
+  static foliageCards: "full" | "lean" = "full"
   static _foliageMaskedTemplate(): Material | null {
-    if (Material._folMaskedTemplate === undefined) Material._folMaskedTemplate = Material._glbTemplate(_creator.builtinMaterial("foliage-masked"))
+    if (Material._folMaskedTemplate === undefined) {
+      const lean = Material.foliageCards === "lean" ? _creator.builtinMaterial("foliage-cards") : null
+      Material._folMaskedTemplate = Material._glbTemplate(lean ?? _creator.builtinMaterial("foliage-masked"))
+    }
     return Material._folMaskedTemplate
   }
   private static _folMaskedTemplate: Material | null | undefined

package/src/gl/Mesh.ts

@@ -1,120 +1,120 @@
-// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/capsule/plane) and
-// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
-
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import {
-  Geometry,
-  type CapsuleOptions,
-  type CylinderOptions,
-  type PlaneOptions,
-  type SphereOptions,
-} from "./Geometry"
-import { Material } from "./Material"
-import { Node } from "./Node"
-
-/** Common transform/render options every primitive factory accepts. */
-export type MeshOptions = {
-  material?: Material
-  position?: Vec3Like
-  eulerAngles?: Vec3Like
-  scale?: Vec3Like | number
-  name?: string
-  castShadows?: boolean
-  receiveShadows?: boolean
-  /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
-  renderPriority?: number
-}
-
-export class Mesh extends Node {
-  private _geometry?: Geometry
-
-  constructor(geometry?: Geometry, material?: Material) {
-    super()
-    if (geometry) {
-      const mat = material ?? Material.unlit()
-      this._geometry = geometry
-      this._materials = [ mat ]
-      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
-    }
-  }
-
-  override get geometry(): Geometry | undefined { return this._geometry }
-  /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
-   *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
-  setGeometry(geometry: Geometry): this {
-    this._geometry = geometry
-    _creator.setMesh(this.id, Material.idOf(this._materials![0]!), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
-    // the host rebuilds the renderable for a new geometry (creator-gl createMesh destroys + builds), which
-    // resets its priority / culling / shadow flags to the defaults — an overlay redrawn every frame lost its
-    // renderPriority 7 after one frame and hid inside the model. What was set on this mesh is set again.
-    if (this._renderPriority !== undefined) this.renderPriority = this._renderPriority
-    if (this._culling !== undefined) this.culling = this._culling
-    if (this._castShadows !== undefined) this.castShadows = this._castShadows
-    if (this._receiveShadows !== undefined) this.receiveShadows = this._receiveShadows
-    return this
-  }
-  private _renderPriority?: number
-  private _culling?: boolean
-  private _castShadows?: boolean
-  private _receiveShadows?: boolean
-
-  /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
-  override get material(): Material { return this._materials![0]! }
-  override set material(m: Material) { this.setMaterial(m, 0) }
-
-  set culling(v: boolean) { this._culling = v; _creator.setCulling(this.id, v) }
-  /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
-   *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
-   *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
-   *  after it can cover it. Write-only; a host that predates the call ignores it. */
-  set renderPriority(v: number) {
-    this._renderPriority = v
-    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
-    else if (!Mesh._warnedPriority) { Mesh._warnedPriority = true; console.warn("[mesh] this host has no setRenderPriority — renderPriority ignored") }
-  }
-  private static _warnedPriority = false
-  set castShadows(v: boolean) { this._castShadows = v; _creator.setCastShadows(this.id, v) }
-  set receiveShadows(v: boolean) { this._receiveShadows = v; _creator.setReceiveShadows(this.id, v) }
-
-  // --- factories ---
-
-  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
-    // the size goes into the geometry (not a scale after): the lightmap chart is laid out per face area
-    return apply(new Mesh(Geometry.box(options.size ?? 1), options.material), options)
-  }
-
-  static sphere(options: MeshOptions & SphereOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.sphere(options), options.material), options)
-  }
-
-  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
-  }
-
-  /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
-  static capsule(options: MeshOptions & CapsuleOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.capsule(options), options.material), options)
-  }
-
-  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
-    return apply(new Mesh(Geometry.plane(options), options.material), options)
-  }
-
-  /** Wrap a custom Geometry. */
-  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
-    return apply(new Mesh(geometry, options.material), options)
-  }
-}
-
-const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
-
-const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
-  if (o.position) mesh.position = o.position
-  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
-  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
-  if (o.name !== undefined) mesh.name = o.name
-  if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
-  if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
-  if (o.renderPriority !== undefined) mesh.renderPriority = o.renderPriority
-  return mesh
-}
+// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/capsule/plane) and
+// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
+
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import {
+  Geometry,
+  type CapsuleOptions,
+  type CylinderOptions,
+  type PlaneOptions,
+  type SphereOptions,
+} from "./Geometry"
+import { Material } from "./Material"
+import { Node } from "./Node"
+
+/** Common transform/render options every primitive factory accepts. */
+export type MeshOptions = {
+  material?: Material
+  position?: Vec3Like
+  eulerAngles?: Vec3Like
+  scale?: Vec3Like | number
+  name?: string
+  castShadows?: boolean
+  receiveShadows?: boolean
+  /** Coarse draw order, 0 (first) … 7 (last); default 4. See `Mesh.renderPriority`. */
+  renderPriority?: number
+}
+
+export class Mesh extends Node {
+  private _geometry?: Geometry
+
+  constructor(geometry?: Geometry, material?: Material) {
+    super()
+    if (geometry) {
+      const mat = material ?? Material.unlit()
+      this._geometry = geometry
+      this._materials = [ mat ]
+      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
+    }
+  }
+
+  override get geometry(): Geometry | undefined { return this._geometry }
+  /** Replace the geometry in place — the node, its transform and its material stay, the vertex and
+   *  index buffers are rebuilt. What an editor overlay or a debug drawer redraws with. */
+  setGeometry(geometry: Geometry): this {
+    this._geometry = geometry
+    _creator.setMesh(this.id, Material.idOf(this._materials![0]!), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1, geometry.colors)
+    // the host rebuilds the renderable for a new geometry (creator-gl createMesh destroys + builds), which
+    // resets its priority / culling / shadow flags to the defaults — an overlay redrawn every frame lost its
+    // renderPriority 7 after one frame and hid inside the model. What was set on this mesh is set again.
+    if (this._renderPriority !== undefined) this.renderPriority = this._renderPriority
+    if (this._culling !== undefined) this.culling = this._culling
+    if (this._castShadows !== undefined) this.castShadows = this._castShadows
+    if (this._receiveShadows !== undefined) this.receiveShadows = this._receiveShadows
+    return this
+  }
+  private _renderPriority?: number
+  private _culling?: boolean
+  private _castShadows?: boolean
+  private _receiveShadows?: boolean
+
+  /** A Mesh always carries a material (slot 0) — see Node.setMaterial for the slot API. */
+  override get material(): Material { return this._materials![0]! }
+  override set material(m: Material) { this.setMaterial(m, 0) }
+
+  set culling(v: boolean) { this._culling = v; _creator.setCulling(this.id, v) }
+  /** Coarse draw order within the frame: 0 draws first, 7 last, 4 is the default (Filament's
+   *  renderable priority; within one priority opaque draws sort front-to-back, blended back-to-front).
+   *  Something drawn over the scene with `Material.depthTest = false` goes in 7, so nothing drawn
+   *  after it can cover it. Write-only; a host that predates the call ignores it. */
+  set renderPriority(v: number) {
+    this._renderPriority = v
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+    else if (!Mesh._warnedPriority) { Mesh._warnedPriority = true; console.warn("[mesh] this host has no setRenderPriority — renderPriority ignored") }
+  }
+  private static _warnedPriority = false
+  set castShadows(v: boolean) { this._castShadows = v; _creator.setCastShadows(this.id, v) }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; _creator.setReceiveShadows(this.id, v) }
+
+  // --- factories ---
+
+  static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
+    // the size goes into the geometry (not a scale after): the lightmap chart is laid out per face area
+    return apply(new Mesh(Geometry.box(options.size ?? 1), options.material), options)
+  }
+
+  static sphere(options: MeshOptions & SphereOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.sphere(options), options.material), options)
+  }
+
+  static cylinder(options: MeshOptions & CylinderOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.cylinder(options), options.material), options)
+  }
+
+  /** A capsule along Y (`radius`, `length` between the cap centres) — a character's or a collider's shape in one mesh. */
+  static capsule(options: MeshOptions & CapsuleOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.capsule(options), options.material), options)
+  }
+
+  static plane(options: MeshOptions & PlaneOptions = {}): Mesh {
+    return apply(new Mesh(Geometry.plane(options), options.material), options)
+  }
+
+  /** Wrap a custom Geometry. */
+  static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
+    return apply(new Mesh(geometry, options.material), options)
+  }
+}
+
+const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])
+
+const apply = (mesh: Mesh, o: MeshOptions): Mesh => {
+  if (o.position) mesh.position = o.position
+  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles
+  if (o.scale !== undefined) mesh.scale = typeof o.scale === "number" ? [ o.scale, o.scale, o.scale ] : o.scale
+  if (o.name !== undefined) mesh.name = o.name
+  if (o.castShadows !== undefined) mesh.castShadows = o.castShadows
+  if (o.receiveShadows !== undefined) mesh.receiveShadows = o.receiveShadows
+  if (o.renderPriority !== undefined) mesh.renderPriority = o.renderPriority
+  return mesh
+}

package/src/gl/Scatter.ts

@@ -0,0 +1,67 @@
+// A loaded model drawn many times — grass, ground cover, a bush kind — by hardware instancing (2026-10-18, the
+// Forest's grass): `new Scatter(kind, placements)` lays the kind's level-0 meshes out at every placement with the
+// kind's OWN material instances, so a foliage kind keeps its wind, its touch, the ground's baked light and its
+// distance fade, and 1 778 clumps cost ~60 draws instead of 1 778. The engine buckets the placements into cells
+// and splits a cell into chunks of the platform's per-draw cap (64 native); a cell past the kind's fade distance
+// leaves the scene. The chunks are children of this node: add it to a scene, move it, destroy it like any node.
+//
+//   const grass = await Model.load(asset('./kinds/grass.glb'), { foliage: true })   // the KIND: loaded, not added
+//   scene.add(new Scatter(grass, clumps))                                           // clumps: { position, yaw, scale }[]
+//
+// The kind itself need not be in a scene. Placements are fixed at construction — a carpet, not a crowd that moves
+// (InstancedMesh is the one with live transforms). On a host without the engine call the placements become clones
+// of the model under this node, the same picture at the old cost.
+
+import { Node } from "./Node"
+import type { Model } from "./Model"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+
+/** One placement: where the kind's origin stands, its yaw about +Y in degrees, its uniform scale. */
+export type ScatterPlacement = {
+  position: Vec3Like
+  /** Degrees, default 0. */
+  yaw?: number
+  /** Uniform, default 1. */
+  scale?: number
+}
+
+export type ScatterOptions = {
+  /** The cell edge in metres the placements are bucketed by (one draw per 64 placements of a cell). Default 16. */
+  cell?: number
+  /** Whether the copies cast the sun's shadow. Default false: ground cover never does. */
+  castShadows?: boolean
+  name?: string
+}
+
+export class Scatter extends Node {
+  /** Placements given. */
+  readonly count: number
+  /** Renderables the engine made (0 on a host that cloned instead). */
+  readonly draws: number
+
+  constructor(kind: Model, placements: readonly ScatterPlacement[], options: ScatterOptions = {}) {
+    super()
+    this.count = placements.length
+    if (options.name !== undefined) this.name = options.name
+    const data = new Float32Array(placements.length * 5)
+    for (let i = 0; i < placements.length; i++) {
+      const p = placements[i]
+      data[i * 5] = cx(p.position); data[i * 5 + 1] = cy(p.position); data[i * 5 + 2] = cz(p.position)
+      data[i * 5 + 3] = p.yaw ?? 0
+      data[i * 5 + 4] = p.scale ?? 1
+    }
+    const made = placements.length > 0 ? _creator.createGlbScatter?.(this.id, kind.id, data, options.cell ?? 16, options.castShadows ?? false) : 0
+    this.draws = made ?? 0
+    if (made === undefined && placements.length > 0) {
+      // no engine call on this host: the old way, a clone per placement under this node
+      for (const p of placements) {
+        const m = kind.clone()
+        m.position = p.position
+        m.eulerAngles = [ 0, p.yaw ?? 0, 0 ]
+        m.scale = p.scale ?? 1
+        if (!(options.castShadows ?? false)) m.castShadows = false
+        this.add(m)
+      }
+    }
+  }
+}