lecodes-sdk 0.20.2 → 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,38 +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 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
   }
 
@@ -367,22 +377,45 @@ export class Material {
    *  the GLB provider instantiates; the template itself never draws). */
   static _lightmapTemplate(): Material { return (Material._lmTemplate ??= Material.lightmap()) }
   private static _lmTemplate: Material | undefined
+  /** @internal The tier's MASKED twin, handed to the engine next to the template: a model's glTF MASK
+   *  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
+  }
 
-  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.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)
+  }
+
+  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,102 +1,120 @@
-// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/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 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)
-    return this
-  }
-
-  /** 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) { _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) {
-    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) { _creator.setCastShadows(this.id, v) }
-  set receiveShadows(v: boolean) { _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)
-  }
-
-  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
+}