lecodes-sdk 1.0.0 → 1.2.0

package/src/gl/Light.ts

@@ -3,7 +3,15 @@
 
 import { Color, type ColorInput } from "../core/color"
 import type { Vec3Like } from "../math/vec"
-import { Node } from "./Node"
+import { Node, type NodeTweenProps } from "./Node"
+import { DOM_GL_LIGHT, colorValue, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import type { Animation } from "../animate/tween/Animation"
+
+/** Animatable light props on top of the node transform. */
+export type LightTweenProps = NodeTweenProps & {
+  intensity?: number | number[],
+  color?: ColorInput | ColorInput[],
+}
 
 export type SunOptions = {
   /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
@@ -19,6 +27,9 @@ export type SunOptions = {
    *   3 - 2048 map, contact-hardening soft edges (PCSS: sharp where the caster touches, softer
    *       away; discrete-GPU territory, ~+60 % of a frame on an iGPU)
    * A lightmapped level already carries every static shadow, so 0 is a legitimate choice there.
+   * On a level with a baked light grid the variance / PCSS filters cannot be used (they need every
+   * receiver in the shadow map, and the baked statics are kept out of it): 3 renders as PCSS on the
+   * depth map - the same contact-hardening look - and 2 renders as 1.
    */
   shadowsQuality?: 0 | 1 | 2 | 3
   /**
@@ -46,26 +57,42 @@ export type PointOptions = {
   /** Point-light shadows are a cubemap render per light; off by default. */
   castShadows?: boolean
   /**
-   * Whether `lecodes lightmap bake` bakes this light into the level's lightmap (docs/lightmap-plan.md).
-   * A baked light is switched OFF at runtime once the bake applies — statics read it from the atlas,
-   * movers from the light volume — so it costs nothing per frame; a light that must stay live (a
-   * flicker, a lamp the player can shoot out) says `baked: false` and is kept out of the bake.
-   * Lights created after the level loads (a muzzle flash) are never in a bake. Default true.
+   * Whether `lecodes lightmap bake` bakes this light into the level's lightmap. A baked lamp lights the statics
+   * from the atlas and the MOVERS from the level's light grid, and is held dark in real time while that grid is
+   * loaded (without a grid it keeps lighting the movers live); a light
+   * that must reach the statics live too — a flicker, a lamp the player can shoot out, a muzzle flash —
+   * says `baked: false`: it is kept out of the bake and put on the statics' light channel. Default true.
    */
   baked?: boolean
+  /**
+   * THE BAKE'S SHAPE of this lamp: `[width, height]` in metres = an AREA light - a rectangle in the light's local XZ
+   * plane, emitting along its local -Y (down, for an unrotated node) with the same lumens: a ceiling panel. The bake
+   * lights from the whole rectangle (soft shadows, light from where the panel is and not from a point inside the
+   * fixture). Real time it is still the point light above. Ignored with `baked: false`.
+   */
+  bakeArea?: readonly [number, number]
 }
 
 export class Light extends Node {
   private _intensity = 0
+
+  /** Tween `intensity` / `color` (a flash, a sunrise) and the transform — see {@link Node.animateTo}. */
+  override animateTo(props: LightTweenProps & TweenMeta): Animation { return super.animateTo(props) }
+  override animateFrom(props: LightTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
+  /** @internal */
+  override _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    if (prop === "intensity") return { domain: DOM_GL_LIGHT, id, value: floatValue, commit: (v) => { this._intensity = v as number } }
+    if (prop === "color") return { domain: DOM_GL_LIGHT, id, value: (v) => colorValue(v, Color.toRgba01) }
+    return super._tweenChannel(prop)
+  }
   /** @internal PointOptions.baked — a candidate for the lightmap bake (default true). */
   _baked = true
-  /** @internal the bake carries this light: the real-time one is held dark (Lightmap.load). */
-  _bakedOff = false
   /** @internal every live point light, for the bake / the switch-off; a destroyed one leaves. */
   static _points = new Set<Light>()
-  /** @internal sun direction as created (the engine keeps it; Lightmap.load reads it back). */
+  /** @internal sun direction as created (the engine keeps it). */
   _direction: [number, number, number] = [ 0, -1, 0 ]
-  /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
+  /** The most recently created sun. */
   static lastSun: Light | null = null
   /** @internal the colour as created / last set (a settings menu recreates a sun from these). */
   _color: ColorInput = 0xffffff
@@ -113,6 +140,9 @@ export class Light extends Node {
       options.range ?? 10,
       options.castShadows ?? false,
     )
+    if (options.bakeArea && light._baked) _creator.setLightBakeArea?.(light.id, options.bakeArea[0], options.bakeArea[1])
+    // an unbaked lamp lights the baked statics live: Filament channel 1 (see Lightmap)
+    if (!light._baked) _creator.setLightChannel?.(light.id, 1, true)
     return light
   }
 
@@ -123,14 +153,17 @@ export class Light extends Node {
   get intensity(): number { return this._intensity }
   set intensity(value: number) {
     this._intensity = value
-    _creator.setLightIntensity?.(this.id, this._bakedOff ? 0 : value)
+    if (!this._heldDark) _creator.setLightIntensity?.(this.id, value)
   }
 
-  /** @internal Hold a baked point light dark (the atlas / volume carries it) or hand it back to the real-time path. */
-  _setBakedOff(off: boolean): void {
-    if (this._bakedOff === off) return
-    this._bakedOff = off
-    _creator.setLightIntensity?.(this.id, off ? 0 : this._intensity)
+  /** @internal A BAKED lamp is held dark while the level's LIGHT GRID is loaded (Lightmap): the statics have it in the
+   *  atlas and the movers in the grid's ambient cubes - left burning it lit every mover and unbaked prop a second time,
+   *  without a shadow (through walls), and put a hot spot on its own fixture. `intensity` keeps the authored value. */
+  _heldDark = false
+  _holdDark(dark: boolean): void {
+    if (this._heldDark === dark) return
+    this._heldDark = dark
+    _creator.setLightIntensity?.(this.id, dark ? 0 : this._intensity)
   }
 
   destroy(): void {