lecodes-sdk 1.1.0 → 1.2.0

package/src/gl/Particles.ts

@@ -42,6 +42,7 @@ const TAG_VELOCITY_LIFE = 19
 const TAG_ORDER = 20
 const TAG_SMOOTH_PATH = 21
 const TAG_RIBBON_ORIENT = 22
+const TAG_LIT = 23
 /** `TrailOptions.orient` → the native axis code (0 = the camera-facing default). */
 const RIBBON_AXIS: Record<"camera" | "x" | "y" | "z", number> = { camera: 0, x: 1, y: 2, z: 3 }
 
@@ -54,6 +55,7 @@ export const _particleTags = {
   RENDER_MODE: TAG_RENDER_MODE, MESH_GEOMETRY: TAG_MESH_GEOMETRY,
   ANGULAR_VELOCITY: TAG_ANGULAR_VELOCITY, GROUND: TAG_GROUND, VELOCITY_LIFE: TAG_VELOCITY_LIFE,
   ORDER: TAG_ORDER, SMOOTH_PATH: TAG_SMOOTH_PATH, RIBBON_ORIENT: TAG_RIBBON_ORIENT,
+  LIT: TAG_LIT,
 }
 
 // --- curve builders -----------------------------------------------------------------------------
@@ -304,6 +306,15 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
    *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
    *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
   order?: number
+  /** Sprites take the light of the PLACE each one is in — the level's baked light grid (`env.lightmap.volume`).
+   *  A sprite is unlit: its colour is the picture, which is right for fire and wrong for dust — a puff kicked up
+   *  under an awning glows as if it stood in the sun. With `lit` every particle's colour is multiplied by the light
+   *  where it is, relative to the level's OPEN ground: exactly the authored colour out in the sun, the ambient's
+   *  share of it (tinted the way the shade is) under a roof — per particle, so a trail of puffs laid from the sun
+   *  into the shade is lit along its length. Author the colour for the open; nothing else to tune. Without a grid
+   *  — a level with no bake, a host that has none — the colours are drawn as authored. Points, quads, stretch and
+   *  `Trail`; mesh particles are lit by their material. Default false. */
+  lit?: boolean
   /** Coarse draw order among ALL blended draws, 0 (first) … 7 (last) — see `Mesh.renderPriority`.
    *  Default 5: meshes sit at 4 and decals at 3, so smoke covers a car's glass and its skid marks
    *  whatever the camera does (the engine's depth sort compares object centres, and an emitter's
@@ -492,6 +503,7 @@ export class Particles extends Node {
     if (options.rateOverDistance !== undefined) out.push(TAG_RATE_DISTANCE, 1, options.rateOverDistance)
     if (options.smooth !== undefined) out.push(TAG_SMOOTH_PATH, 1, options.smooth ? 1 : 0)
     if (options.order !== undefined) out.push(TAG_ORDER, 1, options.order)
+    if (options.lit !== undefined) out.push(TAG_LIT, 1, options.lit ? 1 : 0)
     if (options.rate !== undefined) out.push(TAG_RATE, 1, options.rate)
     if (options.shape !== undefined) pushShape(out, options.shape)
     if (options.velocityOverLife !== undefined) pushVelocityLife(out, options.velocityOverLife)
@@ -547,6 +559,8 @@ export class Particles extends Node {
   /** Lay a frame's spawns along a curve through the emitter's path, not the straight chord. */
   set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
   set order(val: number) { this._send([ TAG_ORDER, 1, val ]) }
+  /** Colours × the baked light where each particle is — see `ParticlesOptions.lit`. */
+  set lit(val: boolean) { this._send([ TAG_LIT, 1, val ? 1 : 0 ]) }
   /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
   set renderPriority(v: number) {
     if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
@@ -644,6 +658,9 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
    *  frame rate, since a longer frame bows further off its own chord. Default false; see
    *  `ParticlesOptions.smooth`. */
   smooth?: boolean
+  /** The strip takes the baked light of the place each of its points is at — `ParticlesOptions.lit`. Smoke and
+   *  dust trails; leave it off for a glowing one. Default false. */
+  lit?: boolean
   /** Which way the strip's WIDTH points.
    *
    *  `'camera'` (default) rolls the strip about its own length to stay flat to the viewer — it can
@@ -689,6 +706,7 @@ export class Trail extends Node {
       TAG_LIFETIME, 2, time, time,
     ]
     if (options.smooth) out.push(TAG_SMOOTH_PATH, 1, 1)
+    if (options.lit) out.push(TAG_LIT, 1, 1)
     if (options.orient !== undefined || options.faceCamera !== undefined) {
       this._orient = RIBBON_AXIS[options.orient ?? "camera"]
       if (options.faceCamera !== undefined) this._faceCamera = options.faceCamera
@@ -732,6 +750,7 @@ export class Trail extends Node {
 
   /** Follow a curve through the emitter's path instead of the straight chord between frames. */
   set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
+  set lit(val: boolean) { this._send([ TAG_LIT, 1, val ? 1 : 0 ]) }
 
   /** Which way the strip's width points — see `TrailOptions.orient`. Keeps the current `faceCamera`. */
   set orient(val: "camera" | "x" | "y" | "z") {