reze-engine 0.56.10 → 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
 }
 
 /**
@@ -1594,6 +1604,23 @@ interface EffectInstance {
   trails: EffectTrails | null
 }
 
+/**
+ * A light the DOCUMENT places, as setLights takes it.
+ *
+ * `aim` is what separates the two kinds: with one the light is a spot pointing
+ * that way, without one it is a point light. Angles are the whole cone in
+ * degrees, the way a fixture and every DCC states them.
+ */
+export type SceneLight = {
+  position: XYZ
+  color: XYZ
+  intensity?: number
+  radius?: number
+  aim?: XYZ
+  angle?: number
+  innerAngle?: number
+}
+
 export class Engine {
   private static instance: Engine | null = null
 
@@ -1612,7 +1639,7 @@ export class Engine {
   // `!` field here is genuinely absent until init() — this one no longer is.
   private camera: Camera
   private cameraUniformBuffer!: GPUBuffer
-  private cameraMatrixData = new Float32Array(36)
+  private cameraMatrixData = new Float32Array(40)
   // Blender-style scene config groups (resolved from EngineOptions)
   private world!: { color: Vec3; strength: number }
   private sun!: { color: Vec3; strength: number; direction: Vec3 }
@@ -2284,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
@@ -3576,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
@@ -3613,6 +3646,7 @@ export class Engine {
         { binding: 21, resource: this.fieldLayerView(this.fieldFgViews[1], 1) },
       ],
     })
+    return true
   }
 
   /**
@@ -4075,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)
@@ -4085,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
@@ -4108,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()
   }
@@ -5130,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
@@ -6726,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" } },
       ],
     })
@@ -6971,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",
@@ -6988,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",
@@ -7424,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],
     })
@@ -9198,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
@@ -9208,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
@@ -9226,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()
   }
 
@@ -9251,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()
   }
 
@@ -9377,12 +9550,17 @@ export class Engine {
    * keep the meaning the caller gave them, which is the same rule the anchor
    * table follows. Passing none (or an empty list) turns the layer off and the
    * scene renders exactly as it did before lights existed.
+   *
+   * A light with an `aim` is a SPOT: it reaches only inside `angle`, full
+   * inside `innerAngle`, and the two are degrees from the axis the way every
+   * tool states a cone. Without one it is a point light, which the shading
+   * spells as a cone that covers everything rather than as a second case.
    */
   setLights(
     /** Structural {x,y,z} rather than the Vec3 class, the same choice effect
      *  params make: a scene document's JSON passes straight in, and so does a
      *  literal typed into a console. Vec3 satisfies it either way. */
-    lights: { position: XYZ; color: XYZ; intensity?: number; radius?: number }[] | null,
+    lights: SceneLight[] | null,
   ): void {
     const list = (lights ?? []).slice(0, MAX_LIGHTS)
     this.docLightCount = list.length
@@ -9409,9 +9587,29 @@ export class Engine {
       this.lightsData[b + 4] = Math.max(l.color.x * k, 0)
       this.lightsData[b + 5] = Math.max(l.color.y * k, 0)
       this.lightsData[b + 6] = Math.max(l.color.z * k, 0)
-      // [b + 7] is `type`, reserved: every light is a point light today.
-    }
-    if (list.length) {
+      // A spot only where an aim was given AND it points somewhere: a zero
+      // vector cannot be normalised, and a cone around nothing would light
+      // nothing at all — a light that vanishes because its aim was left at the
+      // default is worse than one that shines everywhere.
+      const len = l.aim ? Math.hypot(l.aim.x, l.aim.y, l.aim.z) : 0
+      this.lightsData[b + 7] = len > 0 ? 1 : 0
+      this.lightsData[b + 8] = len > 0 ? l.aim!.x / len : 0
+      this.lightsData[b + 9] = len > 0 ? l.aim!.y / len : 0
+      this.lightsData[b + 10] = len > 0 ? l.aim!.z / len : 0
+      // Half-angles in degrees, as cosines. Ordered so the outer edge is never
+      // inside the inner one — a cone written the other way round would divide
+      // by a negative span and light its own rim instead of its middle.
+      const outer = len > 0 ? Math.cos((Math.min(Math.max(l.angle ?? 45, 0), 179) / 2) * (Math.PI / 180)) : -1
+      const inner = len > 0 ? Math.cos((Math.min(Math.max(l.innerAngle ?? (l.angle ?? 45) * 0.8, 0), 179) / 2) * (Math.PI / 180)) : -1
+      this.lightsData[b + 11] = outer
+      this.lightsData[b + 12] = Math.max(inner, outer)
+      this.lightsData[b + 13] = 0
+      this.lightsData[b + 14] = 0
+      this.lightsData[b + 15] = 0
+    }
+    // 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,
@@ -11491,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
@@ -12182,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
 
@@ -14436,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.
@@ -15865,6 +16107,11 @@ export class Engine {
     // shader derives the full viewport (width via projection aspect) for its
     // babylon-mmd constant-pixel edge extrusion.
     this.cameraMatrixData[35] = this.canvas.height
+    // The SCENE clock, which is what a material may animate on: it pauses with
+    // the transport and an export steps it exactly, so a ripple is in the same
+    // place in the file as it was on screen. Wall time would drift between the
+    // two. The buffer was already allocated at 40 floats; this is one of them.
+    this.cameraMatrixData[36] = this.sceneClock
     this.device.queue.writeBuffer(this.cameraUniformBuffer, 0, this.cameraMatrixData)
 
     // 360 backdrop: the composite reconstructs each pixel's view ray from the

package/src/graph/registry.ts

@@ -132,6 +132,16 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     outputs: { color: "color", alpha: "float" },
     contextOutputs: { color: "tex_color", alpha: "tex_s.a" },
   },
+  // The scene clock, in seconds. A material is otherwise a function of position
+  // alone — this is what lets one SCROLL: ripples on water, a conveyor, a sign.
+  // It is the same clock the effects read, so a paused scene holds still and an
+  // export steps it frame by frame.
+  time: {
+    inputs: {},
+    outputs: { value: "float" },
+    contextOutputs: { value: "camera.time" },
+  },
+
   geometry: {
     inputs: {},
     outputs: {
@@ -630,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/index.ts

@@ -14,6 +14,7 @@ export {
   type MaterialPreset,
   type MaterialPresetMap,
   type ModelTransform,
+  type SceneLight,
   type ModelAttachment,
   type GizmoDragEvent,
   type GizmoDragCallback,

package/src/reflection.ts

@@ -156,5 +156,8 @@ export function buildMirrorCamera(
   out[33] = camera[33] - t * ny
   out[34] = camera[34] - t * nz
   out[35] = camera[35]
+  // The clock, unfolded: a mirrored draw of an animated material must be at the
+  // same instant as the one it reflects, or the ripples disagree across the pane.
+  out[36] = camera[36]
   return out
 }