lecodes-sdk 1.0.0 → 1.2.0

package/src/gl/Material.ts

@@ -161,8 +161,6 @@ export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
   metallic?: number
 }
 
-/** `Material.lightmapShading` tiers — see the setter. */
-export type LightmapShading = "full" | "baked" | "baked-lite"
 
 export class Material {
   /** @internal native material-instance handle. */
@@ -328,54 +326,50 @@ 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). */
+  /** The lightmap material (packages/creator-bake): a lit PBR material whose whole DIFFUSE light is the
+   *  baked irradiance atlas on UV1 (`lightmapLight`, lux) — the real-time sun, lamps and diffuse IBL do not
+   *  touch it; the specular IBL stays, occluded by the baked sky visibility. Models take it through
+   *  `Model.load(…, { lightmap: true })`; a static Mesh gets one from here. Parameters use gltfio's names
+   *  (`baseColorFactor`, `baseColorMap`, `roughnessFactor`, `metallicFactor`) plus `lightmapLight`, `lightmapAux`,
+   *  `lightmapST`, `lightScale` (the level-wide value `Lightmap.load` sets) and the debug view knobs. */
   static lightmap(): Material {
-    // Inline literals: the compiler's preload header captures the shader names from them.
-    const id = Material.lightmapShading === "baked"
-      ? _creatorUtils.fetchLocal("lightmap-baked.filamat")
-      : Material.lightmapShading === "baked-lite"
-        ? _creatorUtils.fetchLocal("lightmap-baked-lite.filamat")
-        : _creatorUtils.fetchLocal("lightmap.filamat")
-    const m = new Material({ _id: id } as any)
-    m.set("baseColorFactor", "#ffffffff").set("roughnessFactor", 1).set("metallicFactor", 0)
-    m.set("lightmapST", [ 1, 1, 0, 0 ]).set("ambientScale", 1).set("sunStrength", 1).set("hasNormalMap", 0)
-    // lightScale 0 = no baked point lights until Lightmap.load binds a light atlas / volume
-    m.set("bakedAo", 1).set("lightScale", 0)
-    m.set("probeMin", [ 0, 0, 0, 0 ]).set("probeInvSize", [ 0, 0, 0, 0 ])
+    // Inline literal: the compiler's preload header captures the shader name from it.
+    const m = new Material({ _id: _creatorUtils.fetchLocal("lightmap.filamat") } as any)
+    Material._lightmapDefaults(m)
     return m
   }
 
   /** `Material.lightmap()`'s masked twin (`blending: masked`, same shader and parameters): what the engine
    *  gives a lightmapped model's alpha-MASK materials. The cutoff comes from the glTF material. */
   static lightmapMasked(): Material {
-    const id = Material.lightmapShading === "baked"
-      ? _creatorUtils.fetchLocal("lightmap-baked-masked.filamat")
-      : Material.lightmapShading === "baked-lite"
-        ? _creatorUtils.fetchLocal("lightmap-baked-lite-masked.filamat")
-        : _creatorUtils.fetchLocal("lightmap-masked.filamat")
-    const m = new Material({ _id: id } 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)
-    m.set("bakedAo", 1).set("lightScale", 0)
-    m.set("probeMin", [ 0, 0, 0, 0 ]).set("probeInvSize", [ 0, 0, 0, 0 ])
+    const m = new Material({ _id: _creatorUtils.fetchLocal("lightmap-masked.filamat") } as any)
+    Material._lightmapDefaults(m)
     return m
   }
 
   /** The terrain splat material (docs/terrain-plan.md §1.5): four albedo (+ normal-map) layers blended by
    *  a control map on the terrain's own grid, per-layer `tiling` (metres per repeat) / `roughness` /
-   *  `normalScale` / `triplanar`, lightmap-aware (the same `lightmap` / `lightmapST` block as
-   *  `Material.lightmap`). `Terrain` builds and owns one per terrain; the uniforms are primed here so an
-   *  unset layer is white and an unbaked terrain is fully lit. */
+   *  `normalScale` / `triplanar`. `Terrain` builds and owns one per terrain; the uniforms are primed here so an
+   *  unset layer is white. Lit real-time; a BAKED terrain takes `Material.terrainLightmap()`. */
   static terrain(): Material {
     // Inline literal: the compiler's preload header captures the shader name from it.
     const m = new Material({ _id: _creatorUtils.fetchLocal("terrain.filamat") } as any)
     m.set("tiling", [ 8, 8, 8, 8 ]).set("roughness", [ 1, 1, 1, 1 ]).set("normalScale", [ 0, 0, 0, 0 ]).set("triplanar", [ 0, 0, 0, 0 ])
     m.set("gridSize", [ 2, 2 ]).set("cellSize", 1).set("tint", "#ffffff")
-    m.set("lightmapST", [ 1, 1, 0, 0 ]).set("ambientScale", 1).set("sunStrength", 1).set("bakedAo", 1).set("lightScale", 0)
+    return m
+  }
+
+  /** `Material.terrain()` for a BAKED terrain (terrain-lightmap.mat): the same layers and uniforms, shaded like
+   *  `Material.lightmap()` — the whole diffuse light is the baked atlas on the terrain's UV1 (one rect), which
+   *  `Lightmap.load` binds. A scene file's `terrain:` node that is a lightmap static is built with it; without a
+   *  bound bake it draws black, like any lightmapped static. No reflection probes (the sampler budget): it reflects the
+   *  sky through the baked sky visibility. */
+  static terrainLightmap(): Material {
+    // Inline literal: the compiler's preload header captures the shader name from it.
+    const m = new Material({ _id: _creatorUtils.fetchLocal("terrain-lightmap.filamat") } as any)
+    m.set("tiling", [ 8, 8, 8, 8 ]).set("roughness", [ 1, 1, 1, 1 ]).set("normalScale", [ 0, 0, 0, 0 ]).set("triplanar", [ 0, 0, 0, 0 ])
+    m.set("gridSize", [ 2, 2 ]).set("cellSize", 1).set("tint", "#ffffff")
+    m.set("lightmapST", [ 1, 1, 0, 0 ]).set("lightScale", 1).set("debugMode", 0).set("debugParams", [ 0.001, 0, 5, 0 ])
     return m
   }
 
@@ -387,23 +381,41 @@ 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. */
+  static foliage(): Material {
+    const m = new Material({ _id: _creatorUtils.fetchLocal("foliage.filamat") } as any)
+    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 = new Material({ _id: _creatorUtils.fetchLocal("foliage-masked.filamat") } as any)
+    Material._glbDefaults(m)
+    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)
+  }
 
-  static _lightmapShading: LightmapShading = "full"
-  /** Which shader lightmapped models take — a graphics-quality tier, engine-wide. `"full"` is filament's
-   *  lit path over the baked atlas (IBL specular, real-time point lights such as a muzzle flash, sun
-   *  shadows on dynamic objects). `"baked"` keeps the baked light and an approximated ambient but drops
-   *  the lit path: ~40 % cheaper per pixel on a fill-bound GPU. `"baked-lite"` is that minus the normal,
-   *  metallic/roughness and occlusion map reads (the factors stand in, the atlas keeps the baked AO;
-   *  emissive still glows): +20 % more at 1080p on the same GPU. Read when a lightmapped model LOADS, so set
-   *  it before the level (a settings menu applies it on the next level load), like `Texture.maxSize`. */
-  static get lightmapShading(): LightmapShading { return Material._lightmapShading }
-  static set lightmapShading(mode: LightmapShading) {
-    if (mode === Material._lightmapShading) return
-    Material._lightmapShading = mode
-    Material._lmTemplate = undefined   // the next load builds a template on the new shader
-    Material._lmMaskedTemplate = undefined
+  private static _lightmapDefaults(m: Material): void {
+    Material._glbDefaults(m)
+    m.set("lightmapST", [ 1, 1, 0, 0 ]).set("lightScale", 1).set("debugMode", 0).set("debugParams", [ 0.001, 0, 5, 0 ])
   }
 
+  /** @internal the foliage template pair, like the lightmap one (a host that lacks the tier returns id 0 from
+   *  fetchLocal — `Model.load` then falls back to the lightmap tier). */
+  static _foliageTemplate(): Material { return (Material._folTemplate ??= Material.foliage()) }
+  private static _folTemplate: Material | undefined
+  static _foliageMaskedTemplate(): Material { return (Material._folMaskedTemplate ??= Material.foliageMasked()) }
+  private static _folMaskedTemplate: 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/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/Model.ts

@@ -34,11 +34,10 @@ 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. */
+  /** @internal loaded through the lightmap material (a baked static); clones inherit it. */
   _lightmapped = false
-  /** @internal what `load` does without an explicit `lightmap` option: `'dynamic'` while a scene file with
-   *  `env.lightmap.volume` runs (Lightmap sets it), so weapons, spawns and make() subtrees read the volume. */
-  static _lightmapDefault: false | "dynamic" = false
+  /** @internal loaded through the foliage tier (`Foliage`); clones inherit it. */
+  _foliage = false
   /** @internal the shadow pair, mirrored here because the bridge writes both at once. */
   _castShadows = true
   /** @internal */
@@ -107,6 +106,7 @@ export class Model extends Node {
     const id = _creator.cloneEntity(this.id)
     const m = new Model(id)
     m._lightmapped = this._lightmapped
+    m._foliage = this._foliage
     if (!this._culling) { m._culling = false; _creator.setGlbCulling(id, false) }   // the engine default is on
     if (this._lodMesh >= 0) { m._lodMesh = this._lodMesh; _pushLod(m) }
     // the clone is a FRESH gltfio instance — it comes back with the asset's own shadow flags,
@@ -124,12 +124,14 @@ export class Model extends Node {
       /** Frustum culling — see `culling` (default: on where the host refits skinned bounds, else off). */
       culling?: boolean
       onProgress?: (p: { loaded: number, total?: number }) => void
-      /** Baked lighting (docs/lightmap-plan.md). `true` = a STATIC: loads through the lightmap material so
+      /** Baked lighting (packages/creator-bake). `true` = a STATIC: loads through the lightmap material so
        *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
-       *  --lightmap-uv`). `'dynamic'` = a mover: the same material, lit by the level's light VOLUME instead
-       *  (no UV1 needed). Omitted: `'dynamic'` while a scene file with `env.lightmap.volume` is running,
-       *  else off. `false` = the standard shader. Hosts without lightmap support ignore it. */
-      lightmap?: boolean | "dynamic"
+       *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
+       *  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
     } = {},
   ): Promise<Model> {
     if (typeof source === "string") {
@@ -139,14 +141,23 @@ export class Model extends Node {
       })
     }
     return new Promise<Model>((resolve, reject) => {
-      const mode = options.lightmap ?? Model._lightmapDefault
-      const lightmapped = !!mode && !!_creator.setNextGlbLightmapped
-      // the tier + its masked twin (alpha-MASK materials — foliage — take the lightmap shader too, 2026-09-11)
+      // the provider path: a foliage model takes the vegetation tier's pair when the host ships it (fetchLocal
+      // id 0 = it does not), a static the lightmap material + its masked twin; anything else the ubershader
+      const foliageWanted = !!options.foliage && !!_creator.setNextGlbLightmapped
+      let foliage = false
+      if (foliageWanted) {
+        const fol = Material.idOf(Material._foliageTemplate())
+        const folMasked = fol ? Material.idOf(Material._foliageMaskedTemplate()) : 0
+        foliage = fol > 0 && folMasked > 0
+        if (foliage) _creator.setNextGlbLightmapped!(fol, folMasked)
+      }
+      const lightmapped = !foliage && !!options.lightmap && !!_creator.setNextGlbLightmapped
       if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()), Material.idOf(Material._lightmapMaskedTemplate()))
       _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
+        model._foliage = foliage
         const culling = options.culling ?? Model._cullingDefault()
         if (!culling) { model._culling = false; _creator.setGlbCulling(entityId, false) }
         resolve(model)

package/src/gl/Node.ts

@@ -16,6 +16,19 @@ import { ensurePhysicsEvents } from "./physics/physicsEvents"
 import { Material } from "./Material"
 import type { CompAxis, CompWriter } from "../core/compWrite"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
+import type { Animation } from "../animate/tween/Animation"
+import { CLOCK_GAME, DOM_GL_NODE, eulerValue, quatValue, vec3Value, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import { tweenBag } from "../animate/tween/Timeline"
+
+/** Animatable transform props of a 3D node: a value tweens from the current one, an ARRAY OF
+ *  VALUES is a keyframe list (`position: [[0,0,0], [0,2,0]]`). */
+export type NodeTweenProps = {
+  position?: Vec3Like | Vec3Like[],
+  scale?: number | Vec3Like | (number | Vec3Like)[],
+  quaternion?: QuatLike | QuatLike[],
+  /** Degrees, YXZ; interpolated per axis without shortest-arc, so `[0, 720, 0]` spins twice. */
+  eulerAngles?: Vec3Like | Vec3Like[],
+}
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
 export const nodeRegistry = new Registry<Node>()
@@ -197,6 +210,32 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
     if (this._xf) this._setOwnedRotation()
   }
 
+  // --- keyframe animation (docs/timeline-plan.md) ---
+  /** Tween the transform to the given values — `node.animateTo({ position: [0, 2, 0], duration: 800,
+   *  easing: 'inOutCubic' })`; arrays of values are keyframes. Runs on the game clock (pauses with
+   *  the game) unless `clock: 'ui'`. Returns the {@link Animation} handle. Phase 1: plain nodes —
+   *  a physics-owned node (a body / character) is not routed through its engine object yet. */
+  animateTo(props: NodeTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, true)
+  }
+  /** Tween FROM the given values to the node's current transform (an entrance). */
+  animateFrom(props: NodeTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, false)
+  }
+  /** @internal keyframe-core target protocol */
+  readonly _tweenClock: number = CLOCK_GAME
+  /** @internal */
+  _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    switch (prop) {
+      case "position": return { domain: DOM_GL_NODE, id, value: vec3Value }
+      case "scale": return { domain: DOM_GL_NODE, id, value: vec3Value }
+      case "quaternion": return { domain: DOM_GL_NODE, id, value: quatValue }
+      case "eulerAngles": return { domain: DOM_GL_NODE, id, value: eulerValue }
+      default: return null
+    }
+  }
+
   get eulerAngles(): Vec3 { return new Mat4(this._sync()).eulerAngles }
   // order 1 = YXZ — the SDK's euler convention (math/quat.ts); the getter also extracts YXZ, so
   // the pair round-trips. (Historically this passed 0/XYZ AND the engine stored the euler matrix