reze-engine 0.56.11 → 0.56.12

package/src/engine.ts

@@ -48,7 +48,7 @@ import { SHADOW_CASCADES, buildShadowVP } from "./shadow-cascades"
 import { REFLECTION_DEBUG_WGSL, buildMirrorCamera, planeFromPointNormal } from "./reflection"
 import { MIRROR_MASK_DOWNSAMPLE_WGSL, MIRROR_MAT_BYTES, mirrorShaderWgsl, mirrorShadowWgsl } from "./shaders/passes/mirror"
 import { packHalf, type HdrImage } from "./hdr"
-import { evalIrradianceSH, projectIrradianceSH } from "./ibl"
+import { evalIrradianceSH, projectIrradianceSH, gradientIrradianceSH } from "./ibl"
 import { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, LYRICS_FLOATS, lyricsApi, packLyrics, type LyricLine, type LyricRect } from "./shaders/lyrics-api"
 import {
   sceneTargets as sceneTargetsFor,
@@ -335,6 +335,16 @@ type WorldOptions = {
   color?: Vec3
   /** Multiplier on world color (Blender: World > Surface > Strength). */
   strength?: number
+  /**
+   * A sky that changes with the direction you look: one colour overhead, one at
+   * the horizon, one below. Game engines light a whole outdoor stage with this
+   * and nothing else, and one flat colour cannot stand in for it — the fill
+   * under a roof and the fill on a wall facing the sky are different light.
+   *
+   * Fitted to the SAME spherical harmonics an HDRI is, so it costs the shader
+   * nothing and an HDRI simply outranks it. Null clears it back to the colour.
+   */
+  gradient?: { sky: Vec3; equator: Vec3; ground: Vec3 } | null
 }
 
 /**
@@ -2301,6 +2311,9 @@ export class Engine {
   private worldEquirectTexture: GPUTexture | null = null
   private worldEquirectView: GPUTextureView | null = null
   private worldStrength = 1
+  /** A three-colour sky's irradiance SH, when the world is a gradient rather
+   *  than a picture. An HDRI outranks it — see writeWorld. */
+  private worldGradientSH: Float32Array | null = null
   /** The installed HDRI's folded irradiance SH (27 floats), or null. */
   private worldSH: Float32Array | null = null
   private fallbackEquirectTexture!: GPUTexture
@@ -3593,9 +3606,12 @@ export class Engine {
     }
   }
 
-  private rebuildCompositeBindGroup(): void {
-    if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView || !this.depthReadView) return
-    if (!this.castBuffer) return
+  /** Returns whether it actually rebuilt: a caller retrying after a resource
+   *  swap has to know, because a bail leaves the previous group — and the
+   *  previous group names the texture the swap replaced. */
+  private rebuildCompositeBindGroup(): boolean {
+    if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView || !this.depthReadView) return false
+    if (!this.castBuffer) return false
     // BEFORE the entries below, not after: they ask fieldPairUsed which effects
     // draw, and that answer includes whether an effect has its field bind group
     // yet. Building the composite first and the field groups second would bind
@@ -3630,6 +3646,7 @@ export class Engine {
         { binding: 21, resource: this.fieldLayerView(this.fieldFgViews[1], 1) },
       ],
     })
+    return true
   }
 
   /**
@@ -4092,7 +4109,13 @@ export class Engine {
    * coefficients, so what lights her is what you see.
    */
   setWorldEquirect(source: HdrImage | null, options?: { strength?: number }): void {
-    this.worldEquirectTexture?.destroy()
+    // RETIRED, NOT DESTROYED. A frame already encoded against the old sky can
+    // still be in flight — the bind groups that name it are rebuilt below, but
+    // the command buffer holding the previous ones is submitted at the end of
+    // the frame this call landed in the middle of. Destroying here is what
+    // produces "Destroyed texture used in a submit"; the next frame's start is
+    // the first moment nothing can be pointing at it.
+    if (this.worldEquirectTexture) this.retiredSkies.push(this.worldEquirectTexture)
     this.worldEquirectTexture = null
     this.worldEquirectView = null
     this.worldStrength = Math.max(options?.strength ?? 1, 0)
@@ -4102,18 +4125,54 @@ export class Engine {
       // Scene-linear radiance in rgba16float. The composite treats it as light
       // rather than wallpaper (mode 3) — a sun in it rolls off like a sun,
       // through the same exposure and view transform as the scene.
+      // MIPPED, and the chain is the prefilter a reflection reads: level n is a
+      // box average of the sky over twice the solid angle of n-1, which is what
+      // lets rzWorldSpecular answer a rough surface without a blur pass per
+      // level. Built on the CPU because the source is already float data in
+      // memory and the alternative is a render pipeline per mip.
+      const levels = Math.floor(Math.log2(Math.max(source.width, source.height))) + 1
       const tex = this.device.createTexture({
         label: "world equirect (HDR)",
         size: [source.width, source.height],
         format: "rgba16float",
+        mipLevelCount: levels,
         usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
       })
-      this.device.queue.writeTexture(
-        { texture: tex },
-        packHalf(source.data),
-        { bytesPerRow: source.width * 8, rowsPerImage: source.height },
-        [source.width, source.height],
-      )
+      let data = source.data
+      let w = source.width
+      let h = source.height
+      for (let level = 0; level < levels; level++) {
+        if (level > 0) {
+          const nw = Math.max(1, w >> 1)
+          const nh = Math.max(1, h >> 1)
+          const down = new Float32Array(nw * nh * 4)
+          for (let y = 0; y < nh; y++) {
+            for (let x = 0; x < nw; x++) {
+              const x0 = Math.min(x * 2, w - 1)
+              const x1 = Math.min(x * 2 + 1, w - 1)
+              const y0 = Math.min(y * 2, h - 1)
+              const y1 = Math.min(y * 2 + 1, h - 1)
+              for (let c = 0; c < 4; c++) {
+                down[(y * nw + x) * 4 + c] =
+                  (data[(y0 * w + x0) * 4 + c] +
+                    data[(y0 * w + x1) * 4 + c] +
+                    data[(y1 * w + x0) * 4 + c] +
+                    data[(y1 * w + x1) * 4 + c]) *
+                  0.25
+              }
+            }
+          }
+          data = down
+          w = nw
+          h = nh
+        }
+        this.device.queue.writeTexture(
+          { texture: tex, mipLevel: level },
+          packHalf(data),
+          { bytesPerRow: w * 8, rowsPerImage: h },
+          [w, h],
+        )
+      }
       this.worldEquirectTexture = tex
       this.worldEquirectView = tex.createView()
       // The sky lights the scene, not only backs it. The sun keeps the toon
@@ -4125,6 +4184,12 @@ export class Engine {
       }
     }
     if (this.worldSH || hadSH) this.writeWorld()
+    // The MATERIAL groups too, not only the composite's: a surface that
+    // reflects the sky samples this very texture, so a world swapped after
+    // init would otherwise keep reflecting the one it replaced. Marked as well,
+    // because either rebuild may bail on resources that are not up yet.
+    this.worldBindingsDirty = true
+    this.rebuildPerFrameBindGroups()
     this.rebuildCompositeBindGroup()
     if (this.device && this.compositeUniformBuffer) this.writeCompositeViewUniforms()
   }
@@ -5147,6 +5212,12 @@ export class Engine {
    * uniform, so nothing recompiles.
    */
   private allocateLightSlots(): void {
+    // BEFORE INIT IS A REAL CALLER. A host sets a scene's lamps from an effect
+    // that runs as soon as its state exists, which on a hot reload is before
+    // the engine has a device — and every public setter here has to survive
+    // that, the way setWorldEquirect does. The buffers are written from the
+    // engine's own state at init, so nothing is lost by returning.
+    if (!this.device) return
     let next = this.docLightCount
     for (const e of this.effects) {
       if (!e.lights) continue
@@ -6743,8 +6814,11 @@ export class Engine {
         // The positional lights. Always bound, empty or not, so every material
         // pipeline shares one layout whether or not the scene has any.
         { binding: 6, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "read-only-storage" } },
-        // The far cascade's shadow map. 8 stays free; 9 is the BRDF LUT.
+        // The far cascade's shadow map, then the world's sky (8) and the BRDF
+        // LUT (9). The sky is always bound — the 1x1 fallback when the scene
+        // has none — so every material pipeline keeps sharing one layout.
         { binding: 7, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "depth" } },
+        { binding: 8, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
         { binding: 9, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
       ],
     })
@@ -6988,6 +7062,19 @@ export class Engine {
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
     })
     this.device.queue.writeBuffer(this.lightsBuffer, 0, this.lightsData)
+    // BEFORE the per-frame groups, which bind it. The composite needs this 1x1
+    // stand-in too, and it used to be created with the composite's own
+    // resources further down — far enough down that a material group built up
+    // here had nothing to put on its sky binding, and every draw went out with
+    // no bind group at index 0.
+    this.fallbackEquirectTexture = this.device.createTexture({
+      label: "equirect fallback",
+      size: [1, 1],
+      format: "rgba8unorm",
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    })
+    this.fallbackEquirectView = this.fallbackEquirectTexture.createView()
+
     // Zero-filled = zero lines, which every accessor answers gracefully.
     this.lyricsBuffer = this.device.createBuffer({
       label: "lyrics",
@@ -7005,39 +7092,7 @@ export class Engine {
     this.lyricsTextureView = this.lyricsTexture.createView()
 
     // Now that shadow resources exist, create the main per-frame bind group
-    this.perFrameBindGroup = this.device.createBindGroup({
-      label: "main per-frame bind group",
-      layout: this.mainPerFrameBindGroupLayout,
-      entries: [
-        { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
-        { binding: 1, resource: { buffer: this.lightUniformBuffer } },
-        { binding: 2, resource: this.materialSampler },
-        { binding: 3, resource: this.shadowMapDepthViews[0] },
-        { binding: 4, resource: this.shadowComparisonSampler },
-        { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
-        { binding: 6, resource: { buffer: this.lightsBuffer } },
-        { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
-        { binding: 9, resource: this.brdfLutView },
-      ],
-    })
-    // The mirror's, identical but for the camera — same lights, same shadow
-    // maps, because a reflection is the same scene lit the same way, seen from
-    // a reflected eye.
-    this.mirrorPerFrameBindGroup = this.device.createBindGroup({
-      label: "mirror per-frame bind group",
-      layout: this.mainPerFrameBindGroupLayout,
-      entries: [
-        { binding: 0, resource: { buffer: this.mirrorCameraBuffer } },
-        { binding: 1, resource: { buffer: this.lightUniformBuffer } },
-        { binding: 2, resource: this.materialSampler },
-        { binding: 3, resource: this.shadowMapDepthViews[0] },
-        { binding: 4, resource: this.shadowComparisonSampler },
-        { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
-        { binding: 6, resource: { buffer: this.lightsBuffer } },
-        { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
-        { binding: 9, resource: this.brdfLutView },
-      ],
-    })
+    this.rebuildPerFrameBindGroups()
 
     this.groundShadowBindGroupLayout = this.device.createBindGroupLayout({
       label: "ground shadow layout",
@@ -7441,14 +7496,6 @@ export class Engine {
         { binding: 21, visibility: GPUShaderStage.FRAGMENT, texture: {} },
       ],
     })
-    this.fallbackEquirectTexture = this.device.createTexture({
-      label: "equirect fallback",
-      size: [1, 1],
-      format: "rgba8unorm",
-      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
-    })
-    this.fallbackEquirectView = this.fallbackEquirectTexture.createView()
-
     this.compositePipelineLayout = this.device.createPipelineLayout({
       bindGroupLayouts: [this.compositeBindGroupLayout],
     })
@@ -9215,6 +9262,103 @@ export class Engine {
     this.writeSun(0)
   }
 
+  /**
+   * The per-frame bind groups, the camera's and the mirror's.
+   *
+   * A METHOD rather than two literals at init, because one of their resources
+   * changes after it: the world's sky texture is swapped whenever an HDRI is
+   * installed or cleared, and a bind group holds the view it was built with.
+   * The mirror's is identical but for the camera — a reflection is the same
+   * scene lit the same way, seen from a reflected eye.
+   */
+  /**
+   * Skies this engine has replaced, kept alive rather than destroyed.
+   *
+   * NOT DESTROYED AT ALL, after three attempts that each deferred it further:
+   * one frame, then three, then "once both bind groups have rebuilt". Every one
+   * still produced "destroyed texture used in a submit" somewhere — a command
+   * buffer encoded before the swap, a rebuild that bailed on half-built
+   * resources, an engine torn down by a hot reload whose last frame is still in
+   * flight. The engine cannot see all of those, and each attempt to enumerate
+   * them found another.
+   *
+   * So the trade is taken explicitly: a replaced sky is a megabyte or two held
+   * until the page goes away, against a validation error every frame. A scene
+   * swaps its world a handful of times in a session, and the GPU frees all of
+   * it when the device does.
+   */
+  private retiredSkies: GPUTexture[] = []
+
+  /** A world was installed or cleared and the bind groups that name its texture
+   *  may not have been rebuilt yet — both rebuilds bail when their own
+   *  resources are half-built, which is exactly the moment a host swaps a sky.
+   *  Retried at the top of a frame until one of them takes. */
+  private worldBindingsDirty = false
+
+  /** Returns whether it actually rebuilt — see rebuildCompositeBindGroup. */
+  private rebuildPerFrameBindGroups(): boolean {
+    // EVERY resource, not just the layout. This runs twice: once at init, where
+    // the order is known, and again whenever a world is installed — which the
+    // host may do before init has finished, and a bind group built around an
+    // undefined buffer is a validation error at creation rather than a missing
+    // picture later.
+    if (
+      !this.device ||
+      !this.mainPerFrameBindGroupLayout ||
+      !this.shadowMapDepthViews?.length ||
+      !this.cameraUniformBuffer ||
+      !this.mirrorCameraBuffer ||
+      !this.lightUniformBuffer ||
+      !this.lightsBuffer ||
+      !this.shadowLightVPBuffer ||
+      !this.materialSampler ||
+      !this.shadowComparisonSampler ||
+      !this.brdfLutView ||
+      !(this.worldEquirectView ?? this.fallbackEquirectView)
+    ) {
+      return false
+    }
+    // BOTH ENTRY LISTS ARE WRITTEN OUT, rather than shared through a helper.
+    // tests/bindings.test.mjs reads this file and checks statically that every
+    // bind group covers exactly its layout — it cannot see through a function,
+    // and a missing binding is a validation error at draw time rather than a
+    // compile error here. The duplication is the price of that check.
+    const env = this.worldEquirectView ?? this.fallbackEquirectView
+    this.perFrameBindGroup = this.device.createBindGroup({
+      label: "main per-frame bind group",
+      layout: this.mainPerFrameBindGroupLayout,
+      entries: [
+        { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+        { binding: 1, resource: { buffer: this.lightUniformBuffer } },
+        { binding: 2, resource: this.materialSampler },
+        { binding: 3, resource: this.shadowMapDepthViews[0] },
+        { binding: 4, resource: this.shadowComparisonSampler },
+        { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
+        { binding: 6, resource: { buffer: this.lightsBuffer } },
+        { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
+        { binding: 8, resource: env },
+        { binding: 9, resource: this.brdfLutView },
+      ],
+    })
+    this.mirrorPerFrameBindGroup = this.device.createBindGroup({
+      label: "mirror per-frame bind group",
+      layout: this.mainPerFrameBindGroupLayout,
+      entries: [
+        { binding: 0, resource: { buffer: this.mirrorCameraBuffer } },
+        { binding: 1, resource: { buffer: this.lightUniformBuffer } },
+        { binding: 2, resource: this.materialSampler },
+        { binding: 3, resource: this.shadowMapDepthViews[0] },
+        { binding: 4, resource: this.shadowComparisonSampler },
+        { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
+        { binding: 6, resource: { buffer: this.lightsBuffer } },
+        { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
+        { binding: 8, resource: env },
+        { binding: 9, resource: this.brdfLutView },
+      ],
+    })
+    return true
+  }
+
   /**
    * Write world ambient. For a uniform-radiance world, hemispherical irradiance
    * is E = π·L and a Lambertian BRDF reflects (albedo/π)·E = albedo·L, so the
@@ -9225,17 +9369,22 @@ export class Engine {
     this.lightData[0] = this.world.color.x * s
     this.lightData[1] = this.world.color.y * s
     this.lightData[2] = this.world.color.z * s
-    this.lightData[3] = 0
+    // The spare in the ambient vec4, which rzWorldSpecular multiplies its sky
+    // sample by: the SH carries strength already, the texture cannot.
+    this.lightData[3] = this.world.strength
     // The sky's irradiance, when an HDRI world is installed — the world
     // STRENGTH dial keeps its meaning by scaling it, and the world COLOUR is
     // simply unread while the flag is up (Blender's own semantics: the image
     // replaces the colour, strength applies to either).
+    // An HDRI outranks a gradient outranks the flat colour, which is the order
+    // of how much each one knows about the sky.
+    const sh = this.worldSH ?? this.worldGradientSH
     for (let i = 0; i < 9; i++) {
       const b = 36 + i * 4
-      if (this.worldSH) {
-        this.lightData[b] = this.worldSH[i * 3] * s
-        this.lightData[b + 1] = this.worldSH[i * 3 + 1] * s
-        this.lightData[b + 2] = this.worldSH[i * 3 + 2] * s
+      if (sh) {
+        this.lightData[b] = sh[i * 3] * s
+        this.lightData[b + 1] = sh[i * 3 + 1] * s
+        this.lightData[b + 2] = sh[i * 3 + 2] * s
       } else {
         this.lightData[b] = 0
         this.lightData[b + 1] = 0
@@ -9243,7 +9392,11 @@ export class Engine {
       }
       this.lightData[b + 3] = 0
     }
-    this.lightData[39] = this.worldSH ? 1 : 0
+    // WHICH KIND of sky, not merely whether there is one: 2 is a picture a
+    // reflection can be sampled from, 1 is a gradient it can only be fitted to,
+    // 0 is a flat colour. rzWorldSpecular reads this to decide whether to touch
+    // the equirect texture at all.
+    this.lightData[39] = this.worldSH ? 2 : this.worldGradientSH ? 1 : 0
     this.updateLightBuffer()
   }
 
@@ -9268,6 +9421,9 @@ export class Engine {
   setWorld(options: WorldOptions): void {
     if (options.color) this.world.color = options.color
     if (options.strength !== undefined) this.world.strength = options.strength
+    if (options.gradient !== undefined) {
+      this.worldGradientSH = options.gradient ? gradientIrradianceSH(options.gradient) : null
+    }
     this.writeWorld()
   }
 
@@ -9451,7 +9607,9 @@ export class Engine {
       this.lightsData[b + 14] = 0
       this.lightsData[b + 15] = 0
     }
-    if (list.length) {
+    // The CPU copy is written either way; only the upload needs a device. A
+    // scene whose lamps arrive before init keeps them, and init uploads them.
+    if (list.length && this.device && this.lightsBuffer) {
       this.device.queue.writeBuffer(
         this.lightsBuffer,
         LIGHT_HEADER * 4,
@@ -11531,6 +11689,38 @@ export class Engine {
     this.cullReadback = null
   }
 
+  /** How far the loaded scene reaches from the origin, in world units — the
+   *  largest any model has ever needed. */
+  private sceneExtent = 0
+
+  /**
+   * Tell the camera how big the scene is, so its far plane can cover it.
+   *
+   * MEASURED ON LOAD, from the model's own vertices, and only ever raised. A
+   * stage is the case that matters: framed from ten units away, a sky dome a
+   * thousand units out sits well beyond a far plane derived from the orbit, and
+   * the part of it past that plane is simply not drawn — which looks like a
+   * polygon of background colour that follows the camera, not like clipping.
+   *
+   * Never lowered when a model leaves: the cost of a far plane that is too
+   * generous is depth precision, and the cost of one that is too near is
+   * geometry that vanishes. One of those is a bug report.
+   */
+  private noteSceneExtent(model: Model): void {
+    const { positions } = model.getGeometry()
+    let most = 0
+    // Every 16th vertex: an extent is a bound, not a measurement, and a stage
+    // has a quarter of a million of them.
+    for (let i = 0; i + 2 < positions.length; i += 48) {
+      const d = positions[i] * positions[i] + positions[i + 1] * positions[i + 1] + positions[i + 2] * positions[i + 2]
+      if (d > most) most = d
+    }
+    const extent = Math.sqrt(most)
+    if (extent <= this.sceneExtent) return
+    this.sceneExtent = extent
+    this.camera?.setSceneExtent(extent)
+  }
+
   /**
    * One record per model: the rigid transform its per-material boxes live under,
    * or the world sphere that bounds it in any pose. Written every frame, because
@@ -12222,6 +12412,7 @@ export class Engine {
     const vertices = model.getVertices()
     const skinning = model.getSkinning()
     const skeleton = model.getSkeleton()
+    this.noteSceneExtent(model)
     const boneCount = skeleton.bones.length
     const matrixSize = boneCount * 16 * 4
 
@@ -14476,6 +14667,17 @@ export class Engine {
   }
 
   private renderWithDelta(deltaTime: number) {
+    // The bind groups first, then the textures they used to name. A retired
+    // texture is freed only once a frame has been rebuilt without it — freeing
+    // it while a group still points at it is what "destroyed texture used in a
+    // submit" means, and it repeats every frame because the stale group stays.
+    if (this.worldBindingsDirty) {
+      // Both have to take: either one bailing leaves a group naming the sky
+      // that was replaced, which is a frame drawn against the wrong one.
+      const perFrame = this.rebuildPerFrameBindGroups()
+      const composite = this.rebuildCompositeBindGroup()
+      this.worldBindingsDirty = !(perFrame && composite)
+    }
     // The scene clock, and the only clock a trail may sample on: renderFrame()
     // drives offline export with an exact per-frame delta, so a path recorded
     // against this is reproducible where one recorded against wall time is not.

package/src/graph/registry.ts

@@ -640,6 +640,27 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     emit: (a) => `layer_weight_facing(${a.blend}, n, v)`,
   },
 
+  /**
+   * The world's radiance from a direction — Blender's Environment Texture, read
+   * off the scene's own sky rather than off an image a material carries.
+   *
+   * ITS DEFAULT VECTOR IS THE REFLECTION, which is the whole point: wire
+   * nothing and it answers what this surface reflects. The roughness input
+   * picks how blurred the answer is; at 0 it is a mirror.
+   *
+   * A scene with no HDRI has no sky to reflect, and this returns the flat world
+   * colour — the same value the ambient already carries, so such a scene looks
+   * exactly as it did.
+   */
+  environment: {
+    inputs: {
+      vector: { type: "vector", contextDefault: "reflect(-v, n)" },
+      roughness: F(0),
+    },
+    outputs: { color: "color" },
+    emit: (a) => `rzWorldSpecular(${a.vector}, ${a.roughness})`,
+  },
+
   // ── Lighting capture ──
   /**
    * Shader → RGB on a white diffuse closure, reduced to a scalar.

package/src/ibl.ts

@@ -113,3 +113,44 @@ export function evalIrradianceSH(sh: Float32Array, n: { x: number; y: number; z:
   }
   return out
 }
+
+/**
+ * A three-colour sky as irradiance SH — the same nine coefficients an HDRI
+ * gives, so nothing downstream has to know which kind of world it is looking at.
+ *
+ * The gradient is Unity's trilight and every other engine's "ambient gradient":
+ * one colour straight up, one at the horizon, one straight down, interpolated
+ * by the direction's height. It is what lights a game stage that has no baked
+ * lighting, and it is not a decoration — the fill on a wall facing the sky and
+ * the fill under a roof differ by the whole span between sky and ground.
+ *
+ * Built by SAMPLING IT INTO A SMALL EQUIRECT and projecting that, rather than by
+ * integrating the basis functions in closed form. The analytic route is a page
+ * of coefficients that has to be rederived if the interpolation ever changes;
+ * this is six lines that reuse the projector the HDRI path is already trusted
+ * to get right, and at 64x32 the fit is exact to well under a percent because
+ * the function has no detail finer than the harmonics can hold anyway.
+ */
+type Rgb = { x: number; y: number; z: number }
+
+export function gradientIrradianceSH(g: { sky: Rgb; equator: Rgb; ground: Rgb }): Float32Array {
+  const w = 64
+  const h = 32
+  const data = new Float32Array(w * h * 4)
+  for (let y = 0; y < h; y++) {
+    // The same parameterisation projectIrradianceSH reads: v runs top to bottom
+    // and the direction's height is cos(pi v).
+    const ny = Math.cos(Math.PI * ((y + 0.5) / h))
+    const t = Math.abs(ny)
+    const a = ny >= 0 ? g.sky : g.ground
+    const c = [g.equator.x + (a.x - g.equator.x) * t, g.equator.y + (a.y - g.equator.y) * t, g.equator.z + (a.z - g.equator.z) * t]
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4
+      data[i] = c[0]
+      data[i + 1] = c[1]
+      data[i + 2] = c[2]
+      data[i + 3] = 1
+    }
+  }
+  return projectIrradianceSH({ width: w, height: h, data }, 1)
+}

package/src/shaders/lights.ts

@@ -44,13 +44,23 @@ export const LIGHT_HEADER = 4
 /** Floats per light — see the layout above. */
 export const LIGHT_STRIDE = 16
 /**
- * The cap. The loop below runs per fragment over the lights a scene has, so
- * this bounds the worst case rather than the ordinary one — and it has to clear
- * a game stage: a Unity rip of one arrives with thirty-odd point lights, which
- * the old ceiling of sixteen cut in half. Past this the extras are dropped.
- * Clustering is what replaces it when a scene wants hundreds.
+ * The cap. The loop below runs per fragment over the lights a scene HAS, so
+ * this bounds the worst case rather than the ordinary one, and the buffer is
+ * storage rather than uniform — 128 records is 8 KiB, which costs nothing to
+ * declare and is paid for only by the scenes that fill it.
+ *
+ * Sized against the work, not against a round number: a Unity stage arrives
+ * with a lamp per fixture. One rip of a resort brought thirty-three, a lit
+ * interior brings a hundred or more, and the ceilings of sixteen and then
+ * forty-eight each cut a real scene in half. Past this the extras are dropped.
+ *
+ * What it does NOT buy: a scene that genuinely lights a fragment from a hundred
+ * lamps pays for a hundred iterations of the loop. The distance test below
+ * rejects most of them in a few instructions, which is what makes a rig of this
+ * size affordable at all; clustering is what replaces the linear walk when a
+ * scene wants every one of them close enough to matter.
  */
-export const MAX_LIGHTS = 48
+export const MAX_LIGHTS = 128
 /** Floats in the whole buffer. */
 export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
 

package/src/shaders/materials/common.ts

@@ -136,6 +136,13 @@ struct LightVP { viewProj: array<mat4x4f, ${SHADOW_CASCADES.length}>, };
 // keeps its shadows when the crisp near volume ends. Binding 7: 6 is the
 // positional lights, 9 the BRDF LUT.
 @group(0) @binding(7) var shadowMapFar: texture_depth_2d;
+// The world's own sky, for a surface that REFLECTS it rather than merely being
+// lit by it. Equirect, in the same layout and the same linear radiance the
+// composite draws the dome from, and mipped — a rough surface reads a coarser
+// level, which is what a prefiltered environment is for. A scene with no HDRI
+// has the 1x1 fallback bound here; rzWorldSpecular checks the SH flag and
+// answers with the flat ambient instead, so nothing samples the placeholder.
+@group(0) @binding(8) var worldEnvTexture: texture_2d<f32>;
 // binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).
 @group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
 @group(2) @binding(0) var diffuseTexture: texture_2d<f32>;

package/src/shaders/materials/nodes.ts

@@ -290,6 +290,47 @@ fn point_world_to_camera(p: vec3f) -> vec3f { return (camera.view * vec4f(p, 1.0
 // One function per slot because WGSL has no texture arrays-of-bindings here; the
 // slot is topology, exactly like a Math node's operation.
 
+/**
+ * The world's radiance arriving from a direction — what a reflection sees.
+ *
+ * The engine's ambient is irradiance: the SH fit of the sky integrated over a
+ * hemisphere, evaluated along the NORMAL. That is the right answer for diffuse
+ * light and the wrong one for a mirror, which needs radiance along the
+ * REFLECTION vector and needs it sharp. A stage ripped from a game asks for
+ * this on nearly every surface — it is what a Unity material's DEFAULT_REFLECTION
+ * keyword means — 
+ * and so does every metal the app has ever drawn.
+ *
+ * ROUGHNESS PICKS A MIP, which is the cheap prefilter: the chain is built by
+ * successive halving at upload, so a level is a box average of the sky over a
+ * widening solid angle. A cosine-lobe convolution would be more correct; the
+ * visible difference is confined to the middle of the roughness range, and the
+ * chain costs one downsample per level instead of a render pass per level.
+ *
+ * Without an HDRI there is nothing to reflect but the flat world colour, which
+ * is what the ambient already is — so the two agree and a scene without a sky
+ * texture sees no change at all.
+ */
+fn rzWorldSpecular(dir: vec3f, roughness: f32) -> vec3f {
+  // A SKY TEXTURE, or the best the scene has. The flag is 2 when an HDRI is
+  // installed, 1 when the world is a gradient fitted to the same harmonics,
+  // and 0 when it is one flat colour — and in the last two cases the ambient
+  // already answers by direction, which is a blurred sky and exactly what a
+  // world without a picture can honestly reflect.
+  if (light.sh[0].w < 1.5) { return rzWorldAmbient(normalize(dir)); }
+  let d = normalize(dir);
+  // The composite's own convention, restated: LH world with +Z forward, which
+  // is what makes a reflection line up with the dome the viewer can see.
+  let u = 0.5 + atan2(d.x, d.z) * 0.15915494309;
+  let v = 0.5 - asin(clamp(d.y, -1.0, 1.0)) * 0.31830988618;
+  let levels = f32(textureNumLevels(worldEnvTexture) - 1u);
+  // sqrt, not linear: mip n covers roughly twice the angle of n-1, so a linear
+  // ramp spends most of its travel in the blurry end and a mirror-to-satin
+  // sweep happens entirely in the first tenth of the dial.
+  let lod = clamp(sqrt(clamp(roughness, 0.0, 1.0)) * levels, 0.0, levels);
+  return textureSampleLevel(worldEnvTexture, diffuseSampler, vec2f(u, v), lod).rgb * light.ambientColor.w;
+}
+
 fn group_tex0(uv: vec2f) -> vec4f { return textureSample(groupTexture0, diffuseSampler, uv); }
 fn group_tex1(uv: vec2f) -> vec4f { return textureSample(groupTexture1, diffuseSampler, uv); }
 fn group_tex2(uv: vec2f) -> vec4f { return textureSample(groupTexture2, diffuseSampler, uv); }