lecodes-sdk 1.1.0 → 1.2.0

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

@@ -1,167 +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 (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)
-    })
-  }
-}
+// 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)
+    })
+  }
+}