lecodes-sdk 1.0.0 → 1.1.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/Model.ts

@@ -1,156 +1,167 @@
-// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
-// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
-// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
-//   const hero = await Model.load(asset('./hero.glb'))
-//   hero.anim.play('Run', { loop: true })
-
-import { fetch, type FetchResponse } from "../runtime/fetch"
-import { Node } from "./Node"
-import { Animator, _pushLod, type LodMode } from "./animation/Animator"
-import { Material } from "./Material"
-
-/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
- *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
- *  `world` its skinned position this frame. */
-export interface TrianglePick {
-  /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
-  entity: number
-  node: number
-  nodeName: string
-  mesh: string
-  primitive: number
-  material: string
-  /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
-  triangle: number
-  backface: boolean
-  distance: number
-  point: [number, number, number]
-  bary: [number, number, number]
-  skin: string
-  vertices: { index: number, bind: [number, number, number], world: [number, number, number], bones: { name: string, weight: number }[] }[]
-}
-
-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
-  /** @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 the shadow pair, mirrored here because the bridge writes both at once. */
-  _castShadows = true
-  /** @internal */
-  _receiveShadows = true
-  /** @internal */
-  _culling = true
-  /** @internal -1 = auto (see `lod`) */
-  _lodMesh = -1
-
-  constructor(internalId: number) {
-    super(internalId)
-    this.aspect(Animator)
-  }
-
-  /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
-   *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
-   *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
-   *  is never wanted. */
-  get castShadows(): boolean { return this._castShadows }
-  set castShadows(v: boolean) { this._castShadows = v; this._applyShadows() }
-
-  /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
-  get receiveShadows(): boolean { return this._receiveShadows }
-  set receiveShadows(v: boolean) { this._receiveShadows = v; this._applyShadows() }
-
-  /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
-   *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
-   *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
-   *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
-   *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
-   *  mesh, a debugging aid); `true` forces it on regardless of the host. */
-  get culling(): boolean { return this._culling }
-  set culling(v: boolean) { this._culling = v; _creator.setGlbCulling(this.id, v) }
-  /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
-   *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
-   *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
-   *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
-   *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
-  get lod(): LodMode { return this._lodMesh < 0 ? "auto" : (this._lodMesh as 0 | 1 | 2 | 3) }
-  set lod(v: LodMode) { this._lodMesh = v === "auto" ? -1 : Math.max(0, Math.min(3, Math.round(v))); _pushLod(this) }
-
-  /** @internal the default for a fresh instance (load / clone), decided once per host. */
-  static _cullingDefault(): boolean {
-    if (Model._cullDefault === undefined) Model._cullDefault = !!_creator.skinnedCullingSupported?.()
-    return Model._cullDefault
-  }
-  private static _cullDefault: boolean | undefined
-
-  /** @internal both flags travel together — the bridge walks the instance once. */
-  _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
-
-  /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
-   *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
-   *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
-   *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
-   *  only. null = miss, or a host without the pick (desktop today). */
-  pickTriangle(screenX: number, screenY: number): TrianglePick | null {
-    const json = _creator.pickTriangle?.(this.id, screenX, screenY)
-    return json ? JSON.parse(json) as TrianglePick : null
-  }
-
-  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
-   *  the same parent and scene and sharing this model's current transform. The clone has its own
-   *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
-  clone(): Model {
-    const id = _creator.cloneEntity(this.id)
-    const m = new Model(id)
-    m._lightmapped = this._lightmapped
-    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,
-    // not this model's, so a cleared flag has to be re-applied
-    m._castShadows = this._castShadows
-    m._receiveShadows = this._receiveShadows
-    if (!this._castShadows || !this._receiveShadows) m._applyShadows()
-    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: {
-      /** 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
-       *  `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"
-    } = {},
-  ): Promise<Model> {
-    if (typeof source === "string") {
-      return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
-        if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`))
-        return Model.load(resp, options)
-      })
-    }
-    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)
-      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
-        const culling = options.culling ?? Model._cullingDefault()
-        if (!culling) { model._culling = false; _creator.setGlbCulling(entityId, false) }
-        resolve(model)
-      }, reject)
-    })
-  }
-}
+// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
+// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
+// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
+//   const hero = await Model.load(asset('./hero.glb'))
+//   hero.anim.play('Run', { loop: true })
+
+import { fetch, type FetchResponse } from "../runtime/fetch"
+import { Node } from "./Node"
+import { Animator, _pushLod, type LodMode } from "./animation/Animator"
+import { Material } from "./Material"
+
+/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
+ *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
+ *  `world` its skinned position this frame. */
+export interface TrianglePick {
+  /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
+  entity: number
+  node: number
+  nodeName: string
+  mesh: string
+  primitive: number
+  material: string
+  /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
+  triangle: number
+  backface: boolean
+  distance: number
+  point: [number, number, number]
+  bary: [number, number, number]
+  skin: string
+  vertices: { index: number, bind: [number, number, number], world: [number, number, number], bones: { name: string, weight: number }[] }[]
+}
+
+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 (a baked static); clones inherit it. */
+  _lightmapped = 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 */
+  _receiveShadows = true
+  /** @internal */
+  _culling = true
+  /** @internal -1 = auto (see `lod`) */
+  _lodMesh = -1
+
+  constructor(internalId: number) {
+    super(internalId)
+    this.aspect(Animator)
+  }
+
+  /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
+   *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
+   *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
+   *  is never wanted. */
+  get castShadows(): boolean { return this._castShadows }
+  set castShadows(v: boolean) { this._castShadows = v; this._applyShadows() }
+
+  /** Is this model lit by other casters' shadows? Same instance-wide reach as castShadows. */
+  get receiveShadows(): boolean { return this._receiveShadows }
+  set receiveShadows(v: boolean) { this._receiveShadows = v; this._applyShadows() }
+
+  /** Frustum culling for the whole instance: a model the camera cannot see skips the draw and the
+   *  shadow pass. ON by default where the host keeps a skinned mesh's bounds honest — the engine refits
+   *  them to the joints every frame, so a walking, kneeling or ragdolled body is never culled while on
+   *  screen (`_creator.skinnedCullingSupported`); OFF (always draw) on hosts without that, where
+   *  Filament would cull an animated body by its bind-pose box. `false` = always draw (a skybox-sized
+   *  mesh, a debugging aid); `true` forces it on regardless of the host. */
+  get culling(): boolean { return this._culling }
+  set culling(v: boolean) { this._culling = v; _creator.setGlbCulling(this.id, v) }
+  /** Level of detail (docs/lod-plan.md). `'auto'` (default): the engine shows the `_LOD<n>` mesh level
+   *  that fits the model's size on screen (`lecodes assets doctor --lod` makes them) and scales the
+   *  animation rate with it; a number 0–3 pins that level for both — `0` = always full detail (a hero,
+   *  a showcase), `2`/`3` = always cheap (a crowd filler). `model.anim.lod = 'full'` keeps the animation
+   *  exact while the mesh still switches. No-op on hosts without the LOD pass. */
+  get lod(): LodMode { return this._lodMesh < 0 ? "auto" : (this._lodMesh as 0 | 1 | 2 | 3) }
+  set lod(v: LodMode) { this._lodMesh = v === "auto" ? -1 : Math.max(0, Math.min(3, Math.round(v))); _pushLod(this) }
+
+  /** @internal the default for a fresh instance (load / clone), decided once per host. */
+  static _cullingDefault(): boolean {
+    if (Model._cullDefault === undefined) Model._cullDefault = !!_creator.skinnedCullingSupported?.()
+    return Model._cullDefault
+  }
+  private static _cullDefault: boolean | undefined
+
+  /** @internal both flags travel together — the bridge walks the instance once. */
+  _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
+
+  /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
+   *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
+   *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
+   *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
+   *  only. null = miss, or a host without the pick (desktop today). */
+  pickTriangle(screenX: number, screenY: number): TrianglePick | null {
+    const json = _creator.pickTriangle?.(this.id, screenX, screenY)
+    return json ? JSON.parse(json) as TrianglePick : null
+  }
+
+  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
+   *  the same parent and scene and sharing this model's current transform. The clone has its own
+   *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
+  clone(): Model {
+    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,
+    // not this model's, so a cleared flag has to be re-applied
+    m._castShadows = this._castShadows
+    m._receiveShadows = this._receiveShadows
+    if (!this._castShadows || !this._receiveShadows) m._applyShadows()
+    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: {
+      /** 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 (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`) 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") {
+      return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
+        if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`))
+        return Model.load(resp, options)
+      })
+    }
+    return new Promise<Model>((resolve, reject) => {
+      // 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)
+      }, reject)
+    })
+  }
+}

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