lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/gl/Material.ts

@@ -58,6 +58,12 @@ export type ParticlesMaterialOptions = {
   blend?: "alpha" | "add"
   /** Soft radial falloff toward the sprite edge. Defaults to true without a map, false with one. */
   soft?: boolean
+  /** Soft particles: fade each sprite out over this many metres as it cuts into the scene geometry
+   *  behind it (Unity's "Soft Particles Factor"), so smoke and dust no longer slice through the
+   *  ground and walls with a hard edge. 0 = off (default). Reads the scene's depth buffer, which the
+   *  engine keeps bound while any soft system is on screen — the extra depth pass is only paid then.
+   *  Filament hosts (desktop / web / Android / Apple); web-lite draws such sprites unfaded. */
+  depthFade?: number
   /** How each particle is drawn: `'point'` (default — GPU point sprites, cheapest), `'quad'`
    *  (real camera-facing quads — no driver size cap, geometric rotation), or `'stretch'`
    *  (quads stretched along velocity — sparks, rain, speed streaks). `'ribbon'` is what `Trail`
@@ -169,6 +175,7 @@ export class Material {
     m.uniforms.emissive = options.emissive ?? 0
     m.uniforms.additive = options.blend === "add" ? 1 : 0
     m.uniforms.softness = (options.soft ?? !options.map) ? 1 : 0
+    m.uniforms.depthFade = options.depthFade ?? 0
     if (quad) {
       m.uniforms.mode = options.render === "ribbon" ? 2 : options.render === "stretch" ? 1 : 0
       m.uniforms.stretch = options.stretch ?? (options.render === "stretch" ? 0.05 : 0)
@@ -188,6 +195,24 @@ 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). */
+  static lightmap(): Material {
+    // Inline literal: the compiler's preload header captures the shader name from it.
+    const m = new Material({ _id: _creatorUtils.fetchLocal("lightmap.filamat") } 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)
+    return m
+  }
+
+  /** @internal the shared template instance `Model.load({ lightmap })` hands the engine (its MATERIAL is what
+   *  the GLB provider instantiates; the template itself never draws). */
+  static _lightmapTemplate(): Material { return (Material._lmTemplate ??= Material.lightmap()) }
+  private static _lmTemplate: 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)
@@ -198,6 +223,17 @@ export class Material {
 
   /** Load a custom compiled shader (.mat URL) as a material. */
   static load(url: string): Promise<Material> {
+    // "id:<n>" — the artifact is a LOCAL file the host already resolved through fetchLocal (a
+    // compile with no asset server: the desktop host reads it from next to the bundle). There is
+    // nothing to fetch, so the material is ready synchronously; -1 means the host found no such
+    // file, which would otherwise reach createMaterial as a bad handle.
+    if (url.startsWith("id:")) {
+      const id = Number(url.slice(3))
+      if (!(id >= 0)) {
+        return Promise.reject(new Error(`Shader not found next to the app (${url}). Compile it with \`lecodes shaders compile\`.`))
+      }
+      return Promise.resolve(new Material({ _id: id } as any))
+    }
     return fetch(url, { useOnce: true }).then((resp) => {
       if (resp.status >= 400) return Promise.reject(new Error(`Failed to fetch shader from ${url}. HTTP ${resp.status}`))
       return new Material(resp)

package/runtime/sdk/gl/Mesh.ts

@@ -24,7 +24,6 @@ export type MeshOptions = {
 
 export class Mesh extends Node {
   private _geometry?: Geometry
-  private _materials: Material[] = []
 
   constructor(geometry?: Geometry, material?: Material) {
     super()
@@ -32,29 +31,15 @@ export class Mesh extends Node {
       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)
+      _creator.setMesh(this.id, Material.idOf(mat), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, geometry._meshKind, geometry.uv1)
     }
   }
 
   override get geometry(): Geometry | undefined { return this._geometry }
 
-  get material(): Material { return this._materials[0] }
-  set material(m: Material) { this.setMaterial(m, 0) }
-
-  setMaterial(material: Material, index = 0): this {
-    this._materials[index] = material
-    _creator.setMaterial(this.id, Material.idOf(material), index)
-    return this
-  }
-  getMaterial(index = 0): Material | null {
-    const existing = this._materials[index]
-    if (existing) return existing
-    const id = _creator.getMaterial(this.id, index)
-    if (id === 0) return null
-    const mat = new Material(id)
-    this._materials[index] = mat
-    return mat
-  }
+  /** 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) }
   set castShadows(v: boolean) { _creator.setCastShadows(this.id, v) }
@@ -63,10 +48,8 @@ export class Mesh extends Node {
   // --- factories ---
 
   static box(options: MeshOptions & { size?: Vec3Like | number } = {}): Mesh {
-    const geo = Geometry.box()
-    const [ sx, sy, sz ] = sizeToVec(options.size ?? 1)
-    if (sx !== 1 || sy !== 1 || sz !== 1) geo.scale(sx, sy, sz)
-    return apply(new Mesh(geo, options.material), options)
+    // 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 {

package/runtime/sdk/gl/Model.ts

@@ -1,20 +1,24 @@
 // 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:
+// 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')
+//   hero.anim.play('Run', { loop: true })
 
 import { fetch, type FetchResponse } from "../runtime/fetch"
 import { Node } from "./Node"
-import { ModelAnimation } from "./ModelAnimation"
+import { Animator } from "./animation/Animator"
+import { Material } from "./Material"
 
 export class Model extends Node {
-  /** GLB skeletal animation — always present on a Model. */
-  declare readonly anim: ModelAnimation
+  /** 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
 
   constructor(internalId: number) {
     super(internalId)
-    this.aspect(ModelAnimation)
+    this.aspect(Animator)
   }
 
   /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
@@ -23,13 +27,21 @@ export class Model extends Node {
   clone(): Model {
     const id = _creator.cloneEntity(this.id)
     _creator.setGlbCulling(id, false)
-    return new Model(id)
+    const m = new Model(id)
+    m._lightmapped = this._lightmapped
+    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: { culling?: boolean, onProgress?: (p: { loaded: number, total?: number }) => void } = {},
+    options: {
+      culling?: boolean
+      onProgress?: (p: { loaded: number, total?: number }) => void
+      /** Load through the lightmap material so `Lightmap.load` can bind a baked atlas (the GLB needs
+       *  TEXCOORD_1 — `lecodes assets doctor --lightmap-uv`). Hosts without lightmap support ignore it. */
+      lightmap?: boolean
+    } = {},
   ): Promise<Model> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
@@ -38,9 +50,12 @@ export class Model extends Node {
       })
     }
     return new Promise<Model>((resolve, reject) => {
+      const lightmapped = !!options.lightmap && !!_creator.setNextGlbLightmapped
+      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()))
       _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
         if (options.culling !== true) _creator.setGlbCulling(entityId, false)
         resolve(model)
       }, reject)