lecodes-sdk 2.4.9 → 2.5.0

package/src/gl/Lightmap.ts

@@ -77,7 +77,7 @@ export type LightmapOptions = {
    *  what is under it by the solid angle it fills, with no picture. Dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
   transmit?: Record<string, LightmapTransmit>
   /** FOR THE BAKE: CUBES BY NAME — regular expressions (ECMAScript, case-sensitive) searched in every record's key
-   *  (`<node key>@<ordinal>`: `"SM_pipe"` takes every pipe node, `"@1$"` the second mesh of each): a record that matches
+   *  (`<node key>@<ordinal>`: `"SM_pipe"` takes every pipe node, `"@1$"` the second node primitive of each): a record that matches
    *  leaves the atlas like a small or thin one — an occluder lit by ambient cubes baked where it stands — whatever its size
    *  or charts. Added to the CLI's `--cube` patterns (both apply). */
   cube?: string[]
@@ -121,6 +121,9 @@ export type LightmapFiles = {
   /** THE PACKED LIGHTMAP UV1 (`<stem>-uv1.bin`): the bake packs every mesh's lightmap charts into a square of their own
    *  and its rects map that uv1 — the engine swaps it into the models' TEXCOORD_1 before the rects go on. */
   uv1?: string
+  /** THE STATIC LEVEL CACHE (`<stem>.static`, gl/Statics.ts): the snapshot `lecodes static` wrote beside the bake; the macro
+   *  stages it when it exists, and `load()` rebuilds the level's statics from it when its digest still matches. */
+  statics?: string
 }
 
 /** What `bake('<path>.bake', options)` compiles to — the files of the bake and the level's options in one literal:
@@ -142,6 +145,7 @@ export type LightmapDebugParams = {
 
 /** What `Lightmap.probe` answers: the baked texel under a screen point. */
 export type LightmapProbe = {
+  /** the bake's record (`<key>@<ordinal>`) whose rect holds the texel; "" when none does */
   key: string
   entity: number
   node: string
@@ -239,9 +243,9 @@ type BakeConfig = {
  *  from `from` to `to` along it) — one for a small one, round(length / objectSlab) for a long one — and per slab per side
  *  of its box (+x -x +y -y +z -z) the irradiance rgb in lux + the sky visibility; probes = a, b, a's weight (-1 = none,
  *  -2 = the sky) */
-type BakeObjectLight = { at: number[], axis: number, from: number, to: number, cubes: number[][][], probes: number[] }
+export type BakeObjectLight = { at: number[], axis: number, from: number, to: number, cubes: number[][][], probes: number[] }
 /** a RECORD of the .bake: a registered node's key, or `<key>@<ordinal>` for one mesh of a model (creator-bake atlas.h) */
-type BakeInstance = { key: string, receiver: boolean, small?: boolean, light?: BakeObjectLight, page?: number, rect?: number[], st?: number[] }
+export type BakeInstance = { key: string, receiver: boolean, small?: boolean, light?: BakeObjectLight, page?: number, rect?: number[], st?: number[] }
 type BakeProbes = {
   file: string, size: number, levels: number, count: number, oct: number, tile: number[], perRow: number, atlas: number[],
   spacing: number, layout: "rooms" | "grid",
@@ -251,8 +255,8 @@ type BakeProbes = {
   /** per probe: its open share of the sphere (0 = a room, over 0.15 = under the sky) */
   sky: number[],
 }
-type BakeData = {
-  version: number, size: number, pages: number, texel: number, lightScale: number,
+export type BakeData = {
+  version: number, size: number, pages: number, texel: number, lightScale: number, texels?: number,
   light: string[], aux: string[], direct?: string[], indirect?: string[],
   probes?: BakeProbes | null,
   /** the light grid (creator-bake volume.h): its file and lattice */
@@ -263,6 +267,8 @@ type BakeData = {
   instances: BakeInstance[],
 }
 type PageKind = "light" | "direct" | "indirect"
+/** What `Lightmap.prepare` hands `apply`: the bake read and its pages loaded. */
+export type LightmapPrepared = { def: LightmapDef, data: BakeData, n: number, light: Texture[], aux: Texture[], probes: number, probeAtlas?: Texture, t: number[] }
 type Bound = {
   data: BakeData, rects: Map<string, BakeInstance>, byEntity: Map<number, Entry>, files: LightmapFiles, pages: number,
   aux: Texture[], light: Texture[], direct?: Texture[], indirect?: Texture[],
@@ -434,9 +440,21 @@ export class Lightmap {
    *  to (a scene file's `env.lightmap`). Resolves to null when nothing was applied (no bake yet, a host without the
    *  feature, bake mode). */
   private static scene: Scene | null = null
-  static async load(scene: Scene, def: LightmapDef): Promise<LightmapInfo | null> {
+  /** `load` in two halves (the static level cache binds records as it clones, so the pages must be in BEFORE the
+   *  statics build): `prepare` reads the bake, swaps the uv1 in, loads the pages / probes and sets the level-wide
+   *  options; `apply` binds the rects of the statics the SDK registered, then the light grid. */
+  static async prepare(scene: Scene, def: LightmapDef): Promise<LightmapPrepared | null> {
     Lightmap.scene = scene
     const bake = bakeConfig()
+    // a def built by hand the old way — `{ data, light: asset('…-light.ktx2'), aux }`: the pages are LISTS and `path` the
+    // bake's target (only the bake needs it), both of them bake()'s; without this a string page fails as "not a function"
+    // on its .map, a missing path on its .lastIndexOf
+    if (!Array.isArray(def.light) || !Array.isArray(def.aux) || (bake && typeof def.path !== "string")) {
+      const msg = `${String(def.path ?? def.data)} is not what bake() compiles to — pass \`bake('<path>.bake')\`: it reads every page off the manifest`
+      if (bake) console.error(`[lightmap] error: ${msg}`)
+      else console.warn(`Lightmap: ${msg}; rendering without the bake`)
+      return null
+    }
     if (bake) { Lightmap.bake(bake, def); return null }
     if (!_creator.lightmapApply) {
       if (!Lightmap.warned) { Lightmap.warned = true; console.warn("Lightmap: this host has no lightmap support — rendering without the bake") }
@@ -444,6 +462,7 @@ export class Lightmap {
     }
     if (def.data === null) { console.warn(`Lightmap: no bake at ${def.path} yet — run \`lecodes lightmap bake\``); return null }
     let data: BakeData
+    const tJson = Date.now()
     try {
       const resp = await fetch(def.data, { useOnce: true })
       if (resp.status >= 400) { console.warn(`Lightmap: no bake at ${def.path} (HTTP ${resp.status}) — run \`lecodes lightmap bake\``); return null }
@@ -456,7 +475,9 @@ export class Lightmap {
       console.warn(`Lightmap: ${def.path} is not a creator-bake file (version ${String(data.version)}) — rebake with \`lecodes lightmap bake\``)
       return null
     }
+    const tUv1 = Date.now()
     if (!(await Lightmap.loadUv1(data, def))) return null   // the rects map the packed uv1: it goes in first
+    const tPages = Date.now()
     // the pages the manifest names, in order (bake() listed them off it); both atlases are DATA and exempt from
     // Texture.maxSize (a capped atlas blurs every shadow edge)
     const n = Math.min(data.pages, def.light.length, def.aux.length)
@@ -485,6 +506,24 @@ export class Lightmap {
       }
     }
     console.log(`[lightmap] bound ${n} page(s) of ${data.size} at ${(data.texel * 100).toFixed(2)} cm (${data.mips ?? 1} level(s), sun map ${data.sunMapLevels ?? (data.sunMap ? 1 : 0)}), lightScale ${lightScale}${(def.lightScale ?? 1) !== 1 ? ` (bake ${data.lightScale} x ${def.lightScale})` : ""}${probes > 0 ? `, ${probes} reflection probe(s)` : ""}`)
+    return { def, data, n, light, aux, probes, probeAtlas, t: [ tJson, tUv1, tPages, Date.now() ] }
+  }
+
+  /** The bake's page texture ids, light / aux interleaved per page — what the static level cache binds with. */
+  static pageIds(p: LightmapPrepared): Uint32Array {
+    const out = new Uint32Array(p.n * 2)
+    for (let i = 0; i < p.n; i++) { out[i * 2] = p.light[i]._h.id; out[i * 2 + 1] = p.aux[i]._h.id }
+    return out
+  }
+
+  /** @internal The bake the level is bound to (after `apply`), for the static level cache's snapshot. */
+  static _bakeData(): BakeData | null { return Lightmap.bound?.data ?? null }
+
+  static async apply(p: LightmapPrepared): Promise<LightmapInfo | null> {
+    if (!_creator.lightmapApply) return null   // prepare checked; the narrowing is per function
+    const { def, data, n, light, aux, probes, probeAtlas } = p
+    const [ tJson, tUv1, tPages, tPagesDone ] = p.t
+    const tApply = Date.now()
     const rects = new Map<string, BakeInstance>()
     for (const inst of data.instances) if (inst.receiver && inst.st && inst.page !== undefined) rects.set(inst.key, inst)
     // the ones the bake left out for their size: occluders there, movers here — not a rect gone missing
@@ -499,8 +538,9 @@ export class Lightmap {
     // a bake from before the slabs (`light.cube`, one cube): not read — its small statics stay unlit until it is rebaked
     const lit = (l?: BakeObjectLight): l is BakeObjectLight => !!l && Array.isArray(l.cubes)
     if (data.instances.some((i) => i.small && i.light && !lit(i.light))) console.warn(`Lightmap: ${def.path} has small statics without \`light.cubes\` (baked before the slabbed object light) — they stay unlit; rebake with \`lecodes lightmap bake\``)
-    // THE BAKE'S UNIT IS THE MESH: a model's primitives are records of their own, `<key>@<ordinal>` (ordinal = the primitive's
-    // index over the file's meshes) - a rect, or a small static's light, each; the host binds record k to that primitive
+    // THE BAKE'S UNIT IS THE NODE'S MESH: a model's node primitives are records of their own, `<key>@<ordinal>` (ordinal = the
+    // primitive's index over the file's walked nodes) - a rect, or a small static's light, each; the host binds record k to
+    // that node's primitive (and its LOD twins')
     const parts = Lightmap.recordsOf(data.instances)
     let smallLit = 0
     const byEntity = new Map<number, Entry>()
@@ -547,10 +587,18 @@ export class Lightmap {
     if (small.size) console.log(`[lightmap] ${small.size} small, thin or cube-marked record(s) are not in the atlas (the bake's minTexels / thinTexels / cube): ${smallLit} lit by the light baked where they stand`)
     if (missing.length) console.warn(`Lightmap: ${missing.length} static(s) or mesh record(s) have no rect in the bake (${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "…" : ""}) — rebake`)
     Lightmap.bound = { data, rects, byEntity, files: def, pages: n, aux, light, probes, probeAtlas, showing: "light" }
+    const tVolume = Date.now()
     await Lightmap.loadVolume(data, def)
+    console.log(`[lightmap] load: json ${tUv1 - tJson}, uv1 ${tPages - tUv1}, pages ${tPagesDone - tPages}, apply ${tVolume - tApply} (${applied + smallLit} of ${Lightmap.entries.length} statics, ${data.instances.length} records), volume ${Date.now() - tVolume} ms`)
     return { size: data.size, texel: data.texel, pages: n, applied, total: rects.size, missing }
   }
 
+  /** Bind a bake to the level: the statics registered so far take their rects, the movers the light grid. */
+  static async load(scene: Scene, def: LightmapDef): Promise<LightmapInfo | null> {
+    const p = await Lightmap.prepare(scene, def)
+    return p ? Lightmap.apply(p) : null
+  }
+
   /** The bake's `<key>@k` records by their node key: a model's meshes (k = the primitive's ordinal in its file). */
   private static recordsOf(instances: BakeInstance[]): Map<string, Map<number, BakeInstance>> {
     const out = new Map<string, Map<number, BakeInstance>>()
@@ -636,31 +684,36 @@ export class Lightmap {
   /** The view names in `lightmapDebug`'s order — for a knob that cycles them. */
   static get debugModes(): readonly LightmapDebugMode[] { return DEBUG_MODES }
 
-  /** The baked texel under a screen point (logical px): its instance key, page and texel column / row,
+  /** The baked texel under a screen point (logical px): its record key, page and texel column / row,
    *  so the value can be looked up in the bake's debug layers (`lecodes lightmap inspect`). null when
    *  nothing baked is under the point or the host has no triangle pick. */
   static probe(screenX: number, screenY: number): LightmapProbe | null {
     const b = Lightmap.bound
     if (!b || !_creator.pickTriangle) return null
-    type Hit = { entity: number, nodeName: string, material: string, point: number[], distance: number, uv1?: [number, number], lightmapOrdinal?: number }
-    // the nearest hit over the registered statics: one pick per entry (the all-instances pick, entity 0, walks
-    // every GLB instance including the off-scene templates and is what a scene file's clones confuse)
-    let hit: Hit | null = null
-    for (const id of b.byEntity.keys()) {
-      const h: Hit | null = _creator.pickTriangle(id, screenX, screenY)
-      if (h && (!hit || h.distance < hit.distance)) hit = h
-    }
-    if (!hit) { console.log(`[probe] nothing baked under ${screenX.toFixed(0)},${screenY.toFixed(0)}`); return null }
-    const entry = b.byEntity.get(hit.entity)
-    if (!entry) { console.log(`[probe] hit entity ${hit.entity} node "${hit.nodeName}" at ${hit.point.map((c) => c.toFixed(2)).join(",")} is not a registered static`); return null }
-    const hitKey = hit.lightmapOrdinal !== undefined && b.rects.has(`${entry.key}@${hit.lightmapOrdinal}`) ? `${entry.key}@${hit.lightmapOrdinal}` : entry.key
-    const inst = b.rects.get(hitKey)
-    if (!inst || !inst.st) { console.log(`[probe] ${hitKey}: no rect in the bake`); return null }
-    if (!hit.uv1) { console.log(`[probe] ${entry.key}: the hit primitive carries no TEXCOORD_1`); return null }
-    const st = inst.st
+    // ONE PICK OVER THE SCENE (entity 0: the engine skips what is out of the scene or not drawn - a template, a LOD level
+    // not shown) and THE RECT FROM THE ENGINE: under the static level cache the statics have no JS node and no registry
+    // entry, the host bound their rects itself, so the hit's own material answers (lightmapTexture + lightmapST) and the
+    // record is the receiver whose rect on that page holds the point (rects never overlap: atlas.h)
+    const hit = _creator.pickTriangle(0, screenX, screenY)
+    if (!hit) { console.log(`[probe] nothing under ${screenX.toFixed(0)},${screenY.toFixed(0)}`); return null }
+    const where = `node "${hit.nodeName}" at ${hit.point.map((c) => c.toFixed(2)).join(",")}`
+    if (!hit.uv1) { console.log(`[probe] ${where}: the hit primitive carries no TEXCOORD_1`); return null }
+    if (!hit.lightmapST || !hit.lightmapTexture) { console.log(`[probe] ${where}: draws with no rect of the bake (a mover, or a static the bake left out)`); return null }
+    const sets: Texture[][] = [ b.light, b.direct ?? [], b.indirect ?? [] ]
+    let page = -1
+    for (const set of sets) { page = set.findIndex((t) => t._h.id === hit.lightmapTexture); if (page >= 0) break }
+    if (page < 0) { console.log(`[probe] ${where}: its light page (texture ${hit.lightmapTexture}) is not of the bound bake`); return null }
+    const st = hit.lightmapST
     const u = hit.uv1[0] * st[0] + st[2], v = hit.uv1[1] * st[1] + st[3]
+    let key = ""
+    for (const inst of b.data.instances) {
+      const r = inst.st
+      if (!inst.receiver || inst.page !== page || !r) continue
+      if (u >= r[2] && u <= r[2] + r[0] && v >= r[3] && v <= r[3] + r[1]) { key = inst.key; break }
+    }
+    if (key === "") console.log(`[probe] ${where}: no record of the bake holds page ${page} texel ${Math.floor(u * b.data.size)},${Math.floor(v * b.data.size)} (a rebind?)`)
     return {
-      key: hitKey, entity: hit.entity, node: hit.nodeName, material: hit.material, page: inst.page ?? 0,
+      key, entity: hit.entity, node: hit.nodeName, material: hit.material, page,
       texel: [ Math.floor(u * b.data.size), Math.floor(v * b.data.size) ],
       uv1: [ hit.uv1[0], hit.uv1[1] ], world: [ hit.point[0], hit.point[1], hit.point[2] ], distance: hit.distance,
     }

package/src/gl/Material.ts

@@ -450,24 +450,48 @@ export class Material {
    *  materials (foliage cards) take it instead of falling back to the ubershader's full lit path. */
   static _lightmapMaskedTemplate(): Material { return (Material._lmMaskedTemplate ??= Material.lightmapMasked()) }
   private static _lmMaskedTemplate: Material | undefined
-  /** The FOLIAGE tier (`Model.load(…, { foliage: true })`, see `Foliage`): an unlit shader with its own cheap
-   *  lighting plus a vertex shader that sways in the wind, bends away from benders and thins out with distance,
-   *  and a per-copy tint. glTF parameters like `Material.lightmap()` plus `wind` / `sway` / `fade` / `benders`,
-   *  which the engine writes itself. Not baked by the rewritten bake yet. */
+  /** The FOLIAGE tier's BARK (`Model.load(…, { foliage })`, see `Foliage`): the opaque material a vegetation model's
+   *  trunks, limbs and stems take — lit by the sky and the real-time sun, swaying in the wind, bending away from
+   *  benders, thinning out with distance, with a per-copy tint. glTF parameters like `Material.lightmap()` plus
+   *  `wind` / `sway` / `fade` / `benders`, which the engine writes itself. */
   static foliage(): Material {
     const m = Material._builtin(_creator.builtinMaterial("foliage"), "foliage")
     Material._glbDefaults(m)
     return m
   }
 
-  /** `Material.foliage()`'s masked twin (`blending: masked`): what the engine gives a foliage model's alpha-MASK
-   *  materials — the cards. */
-  static foliageMasked(): Material {
-    const m = Material._builtin(_creator.builtinMaterial("foliage-masked"), "foliage-masked")
+  /** The CARDS of a crown (`Model.load(…, { foliage: 'tree' })`): what a vegetation model's alpha-MASK materials take
+   *  — leaves and needles lit per vertex on the crown's hull normal by the sky and the real-time sun, with the
+   *  sun's shadow per pixel. Ground cover takes `Material.grass()` instead. */
+  static foliageCards(): Material {
+    const m = Material._builtin(_creator.builtinMaterial("foliage-cards"), "foliage-cards")
     Material._glbDefaults(m)
     return m
   }
 
+  /** GROUND COVER (`Model.load(…, { foliage: 'grass' })`): the cards of grass, ferns, heath — the plant that IS the
+   *  ground's surface. The same wind as `Material.foliage()`, lit by the terrain it stands on: the ground's baked
+   *  ambient and sun share under it, the soil's colour at its base. A crown (`'tree'`) reads nothing from the ground. */
+  static grass(): Material {
+    const m = Material._builtin(_creator.builtinMaterial("grass"), "grass")
+    Material._glbDefaults(m)
+    return m
+  }
+
+  /** A tree's far IMPOSTOR (`Model.load(…, { foliage: 'tree' })`): the material of the camera-facing quad
+   *  lecodes-assets bakes into a tree's GLB as its last LOD level — an atlas of views of the tree (a grid of azimuths ×
+   *  elevation rows, or a hemi-octahedron; albedo, normal, baked sky visibility) lit per pixel like the crown's cards.
+   *  The engine picks it for the material whose extras carry `lecodes.impostor` and writes `impostorGrid` /
+   *  `impostor` from them. */
+  static foliageImpostor(): Material {
+    const m = Material._builtin(_creator.builtinMaterial("foliage-impostor"), "foliage-impostor")
+    Material._glbDefaults(m)
+    // the quad shadows itself from its own atlas (the frame nearest the sun); matc has no parameter defaults, and the
+    // GLB path (glb.cpp impostorFromExtras) writes the same 1 — 0 turns the term off
+    m.set("impostorSelfShadow", 1)
+    return m
+  }
+
   /** the glTF-side identity values every provider-handed material starts from */
   private static _glbDefaults(m: Material): void {
     m.set("baseColorFactor", "#ffffffff").set("roughnessFactor", 1).set("metallicFactor", 0).set("hasNormalMap", 0)
@@ -485,20 +509,26 @@ 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) {
-      const lean = Material.foliageCards === "lean" ? _creator.builtinMaterial("foliage-cards") : null
-      Material._folMaskedTemplate = Material._glbTemplate(lean ?? _creator.builtinMaterial("foliage-masked"))
-    }
-    return Material._folMaskedTemplate
+  /** @internal a crown's cards (foliage-cards.mat), the masked twin handed with the bark */
+  static _foliageCardsTemplate(): Material | null {
+    if (Material._folCardsTemplate === undefined) Material._folCardsTemplate = Material._glbTemplate(_creator.builtinMaterial("foliage-cards"))
+    return Material._folCardsTemplate
+  }
+  private static _folCardsTemplate: Material | null | undefined
+  /** @internal the ground cover's masked twin (grass.mat); null where the host carries no grass material — the
+   *  crown's cards then (an older host) */
+  static _grassTemplate(): Material | null {
+    if (Material._grassTpl === undefined) Material._grassTpl = Material._glbTemplate(_creator.builtinMaterial("grass")) ?? Material._foliageCardsTemplate()
+    return Material._grassTpl
+  }
+  private static _grassTpl: Material | null | undefined
+  /** @internal a tree's far impostor (foliage-impostor.mat), handed with the bark and the cards; null where the host
+   *  carries no such material — `Model.load` then arms the pair alone */
+  static _foliageImpostorTemplate(): Material | null {
+    if (Material._folImpostorTpl === undefined) Material._folImpostorTpl = Material._glbTemplate(_creator.builtinMaterial("foliage-impostor"))
+    return Material._folImpostorTpl
   }
-  private static _folMaskedTemplate: Material | null | undefined
+  private static _folImpostorTpl: Material | null | undefined
   private static _glbTemplate(h: Handle | null): Material | null {
     if (!h) return null
     const m = new Material(h)

package/src/gl/Model.ts

@@ -20,7 +20,7 @@ export interface TrianglePick {
   mesh: string
   primitive: number
   material: string
-  /** the primitive's index over its file's meshes: the lightmap bake's record `<key>@<ordinal>` */
+  /** the primitive's index over its file's walked nodes' primitives: the lightmap bake's record `<key>@<ordinal>` */
   lightmapOrdinal: number
   /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
   triangle: number
@@ -34,6 +34,12 @@ export interface TrianglePick {
   vertices: { index: number, bind: [number, number, number], world: [number, number, number], bones: { name: string, weight: number }[] }[]
 }
 
+/** What a vegetation model is lit as (`Model.load`'s `foliage`): a CROWN or GROUND COVER; false = not foliage. */
+export type FoliageKind = false | "tree" | "grass"
+/** @internal a scene node's `foliage` field as the kind `Model.load` takes (`true` = a crown) */
+export const foliageKindOf = (f: boolean | "tree" | "grass" | { kind?: "tree" | "grass" } | undefined): FoliageKind =>
+  (!f ? false : typeof f === "object" ? f.kind ?? "tree" : f === "grass" ? "grass" : "tree")
+
 export class Model extends Node {
   /** The model's Animator — always present, its clip table = the GLB's embedded clips. Add to it
    *  with `model.anim.addClip(name, clip)` (external clips), `model.anim.addLayer()`; set its fields
@@ -135,8 +141,11 @@ export class Model extends Node {
        *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */
       lightmap?: boolean
       /** Vegetation: load through the FOLIAGE tier (see `Foliage`) — wind, touch bending, distance fade,
-       *  per-copy tint. Hosts without the tier fall back to the standard shader. */
-      foliage?: boolean
+       *  per-copy tint. `'tree'` (= `true`): a CROWN — a volume in the air, lit by the sky and the real-time sun
+       *  through the shadow map. `'grass'`: GROUND COVER — grass, ferns, heath: the plant that is the ground's
+       *  surface, lit by the terrain's baked light under it and tinted by its soil at the base. Hosts without the
+       *  tier fall back to the standard shader. */
+      foliage?: boolean | "tree" | "grass"
     } = {},
   ): Promise<Model> {
     if (typeof source === "string") {
@@ -152,9 +161,14 @@ export class Model extends Node {
       let foliage = false
       if (foliageWanted) {
         const fol = Material._foliageTemplate()
-        const folMasked = fol && Material._foliageMaskedTemplate()
+        const folMasked = fol && (options.foliage === "grass" ? Material._grassTemplate() : Material._foliageCardsTemplate())
         foliage = !!fol && !!folMasked
-        if (fol && folMasked) _creator.setNextGlbLightmapped!(Material.idOf(fol), Material.idOf(folMasked))
+        // a tree also arms its far impostor (the `_LOD<k>` quad lecodes-assets bakes), when the host carries the material
+        const impostor = fol && folMasked && options.foliage !== "grass" ? Material._foliageImpostorTemplate() : null
+        if (fol && folMasked) {
+          if (impostor) _creator.setNextGlbLightmapped!(Material.idOf(fol), Material.idOf(folMasked), Material.idOf(impostor))
+          else _creator.setNextGlbLightmapped!(Material.idOf(fol), Material.idOf(folMasked))
+        }
       }
       const lightmapped = !foliage && !!options.lightmap && !!_creator.setNextGlbLightmapped
       if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()), Material.idOf(Material._lightmapMaskedTemplate()))