@jgengine/shell 0.25.0 → 0.27.0

package/dist/postfx/PostProcessing.js

@@ -7,6 +7,8 @@ import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
 import { DEFAULT_AO } from "@jgengine/core/render/postProcessing";
+import { adaptExposure, DEFAULT_AUTO_EXPOSURE, exposureForKey, keyLuminanceFromSamples } from "@jgengine/core/render/colorPipeline";
+import { ExposureMeterPass } from "./autoExposure.js";
 import { createGradePass } from "./gradeShader.js";
 import { StylizePass } from "./stylizePass.js";
 import { renderShadowlessPrepass } from "./shadowPrepass.js";
@@ -38,6 +40,14 @@ const TONE_MAPPING = {
     linear: THREE.LinearToneMapping,
     none: THREE.NoToneMapping,
 };
+/**
+ * Rounds an adapted exposure to 1/32 of a stop. Without it the sky's display-colour cache (which keys
+ * off the renderer's exposure) re-solves its swatches every frame the meter nudges.
+ * @internal
+ */
+export function quantizeExposure(value) {
+    return Math.round(value * 32) / 32;
+}
 /** Release each pass and the composer's owned targets. @internal */
 export function disposeGraph(built) {
     for (const pass of built.composer.passes)
@@ -58,7 +68,7 @@ export function resolveAoStage(ao, tierAllowsAo) {
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
- * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Stylize → Grade. Rendered only
+ * post chain: RenderPass → GTAO → UnrealBloom → SMAA → exposure meter → OutputPass → Stylize → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
  * `stages` (resolved from the player's graphics profile) controls expensive passes
@@ -113,6 +123,22 @@ export function PostProcessing({ config, quality = "high", stages }) {
         if (resolvedStages.smaa && aa === "smaa") {
             composer.addPass(new SMAAPass());
         }
+        // Clamped auto-exposure meters the pre-tone-map buffer, so the meter sits before OutputPass and
+        // hands the adaptation to the renderer's exposure — the one value the sky swatches also read.
+        const autoExposure = config.autoExposure === false ? null : { ...DEFAULT_AUTO_EXPOSURE, ...(config.autoExposure ?? {}) };
+        const authoredExposure = config.exposure ?? 1;
+        if (autoExposure !== null) {
+            let current = authoredExposure;
+            let sampled = false;
+            composer.addPass(new ExposureMeterPass((samples, seconds) => {
+                const target = authoredExposure * exposureForKey(keyLuminanceFromSamples(samples), autoExposure);
+                // The first sample lands on its own target; fading in from the authored exposure would
+                // open every load on a visible exposure slideshow.
+                current = sampled ? adaptExposure(current, target, seconds, autoExposure.adaptationSeconds) : target;
+                sampled = true;
+                gl.toneMappingExposure = quantizeExposure(current);
+            }));
+        }
         composer.addPass(new OutputPass());
         if (config.stylize !== undefined && config.stylize !== false) {
             composer.addPass(new StylizePass(scene, camera, config.stylize));
@@ -133,7 +159,7 @@ export function PostProcessing({ config, quality = "high", stages }) {
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;
-        gl.toneMapping = TONE_MAPPING[config.toneMapping ?? "aces"];
+        gl.toneMapping = TONE_MAPPING[config.toneMapping ?? "agx"];
         gl.toneMappingExposure = config.exposure ?? 1;
         return () => {
             gl.toneMapping = prevTone;

package/dist/postfx/autoExposure.d.ts

@@ -0,0 +1,49 @@
+import * as THREE from "three";
+import { Pass } from "three-stdlib";
+/** Linear luminance encoded in one byte by {@link ExposureMeterPass}. @internal */
+export declare function decodeMeterByte(value: number, target: Float32Array, targetIndex: number): void;
+/**
+ * Meters the pre-tone-map beauty buffer for auto-exposure. Every `sampleInterval` frames it reduces
+ * the frame to a 16×16 grid of log-luminance (GPU) and reads that back (1 KB), then hands the decoded
+ * samples to `onSample` with the wall time since the previous sample. The pass itself is a pass-through,
+ * so it can sit anywhere before the tone-mapping output pass without changing the picture.
+ * @internal
+ */
+export declare class ExposureMeterPass extends Pass {
+    private readonly onSample;
+    /** Frames between readbacks once warmed up. Reading the GPU back stalls the pipeline, so this is
+     * as rare as exposure adaptation tolerates. */
+    private readonly sampleInterval;
+    readonly meterTarget: THREE.WebGLRenderTarget;
+    readonly reduceUniforms: {
+        tDiffuse: {
+            value: THREE.Texture | null;
+        };
+    };
+    private readonly copyUniforms;
+    private readonly reduceQuad;
+    private readonly copyQuad;
+    private readonly pixels;
+    private readonly samples;
+    private frames;
+    private taken;
+    private elapsed;
+    private pendingSeconds;
+    private gl;
+    private pbo;
+    private fence;
+    constructor(onSample: (samples: Float32Array, seconds: number) => void, 
+    /** Frames between readbacks once warmed up. Reading the GPU back stalls the pipeline, so this is
+     * as rare as exposure adaptation tolerates. */
+    sampleInterval?: number);
+    render(renderer: THREE.WebGLRenderer, writeBuffer: THREE.WebGLRenderTarget, readBuffer: THREE.WebGLRenderTarget, deltaTime: number): void;
+    /**
+     * Queues a readback through a pixel-pack buffer and a fence, so the CPU never waits on the GPU: the
+     * samples arrive a frame or two later through {@link collectPendingSample}. A renderer without WebGL2
+     * buffers falls back to the synchronous read, which costs one stall per sample.
+     */
+    private queueReadback;
+    private collectPendingSample;
+    private emit;
+    dispose(): void;
+}

package/dist/postfx/autoExposure.js

@@ -0,0 +1,189 @@
+import * as THREE from "three";
+import { FullScreenQuad, Pass } from "three-stdlib";
+/**
+ * Grid the beauty buffer is averaged down to before readback, per axis. 16×16 cells × 4×4 taps
+ * covers 4096 samples of the frame — enough for a stable key luminance, small enough to read back
+ * (1 KB of encoded log-luminance) without a measurable stall.
+ */
+const METER_SIZE = 16;
+const TAPS_PER_AXIS = 4;
+/** Encoded range of the log-luminance bytes: 2^-16 .. 2^8. */
+const LOG_MIN = -16;
+const LOG_MAX = 8;
+const LOG_RANGE = LOG_MAX - LOG_MIN;
+const reduceShader = {
+    uniforms: { tDiffuse: { value: null } },
+    vertexShader: /* glsl */ `
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }
+  `,
+    fragmentShader: /* glsl */ `
+    uniform sampler2D tDiffuse;
+    varying vec2 vUv;
+
+    void main() {
+      vec2 cell = vec2(${METER_SIZE.toFixed(1)});
+      vec2 texel = 1.0 / cell;
+      vec2 origin = floor(vUv * cell) * texel;
+      float logSum = 0.0;
+      for (int y = 0; y < ${TAPS_PER_AXIS}; y++) {
+        for (int x = 0; x < ${TAPS_PER_AXIS}; x++) {
+          vec2 jitter = (vec2(float(x), float(y)) + 0.5) / ${TAPS_PER_AXIS.toFixed(1)};
+          vec3 color = texture2D(tDiffuse, origin + jitter * texel).rgb;
+          float luma = dot(color, vec3(0.2126, 0.7152, 0.0722));
+          // Log-encoded so one bright window cannot outweigh the room around it.
+          logSum += clamp(log2(max(luma, 1e-6)), ${LOG_MIN.toFixed(1)}, ${LOG_MAX.toFixed(1)});
+        }
+      }
+      float encoded = (logSum / ${(TAPS_PER_AXIS * TAPS_PER_AXIS).toFixed(1)} - ${LOG_MIN.toFixed(1)}) / ${LOG_RANGE.toFixed(1)};
+      gl_FragColor = vec4(encoded, encoded, encoded, 1.0);
+    }
+  `,
+};
+const copyShader = {
+    uniforms: { tDiffuse: { value: null } },
+    vertexShader: reduceShader.vertexShader,
+    fragmentShader: /* glsl */ `
+    uniform sampler2D tDiffuse;
+    varying vec2 vUv;
+    void main() { gl_FragColor = texture2D(tDiffuse, vUv); }
+  `,
+};
+/** Linear luminance encoded in one byte by {@link ExposureMeterPass}. @internal */
+export function decodeMeterByte(value, target, targetIndex) {
+    target[targetIndex] = Math.pow(2, (value / 255) * LOG_RANGE + LOG_MIN);
+}
+/**
+ * Meters the pre-tone-map beauty buffer for auto-exposure. Every `sampleInterval` frames it reduces
+ * the frame to a 16×16 grid of log-luminance (GPU) and reads that back (1 KB), then hands the decoded
+ * samples to `onSample` with the wall time since the previous sample. The pass itself is a pass-through,
+ * so it can sit anywhere before the tone-mapping output pass without changing the picture.
+ * @internal
+ */
+export class ExposureMeterPass extends Pass {
+    onSample;
+    sampleInterval;
+    meterTarget;
+    reduceUniforms = reduceShader.uniforms;
+    copyUniforms = copyShader.uniforms;
+    reduceQuad;
+    copyQuad;
+    pixels = new Uint8Array(METER_SIZE * METER_SIZE * 4);
+    samples = new Float32Array(METER_SIZE * METER_SIZE);
+    frames = 0;
+    taken = 0;
+    elapsed = 0;
+    pendingSeconds = 0;
+    gl = null;
+    pbo = null;
+    fence = null;
+    constructor(onSample, 
+    /** Frames between readbacks once warmed up. Reading the GPU back stalls the pipeline, so this is
+     * as rare as exposure adaptation tolerates. */
+    sampleInterval = 32) {
+        super();
+        this.onSample = onSample;
+        this.sampleInterval = sampleInterval;
+        this.meterTarget = new THREE.WebGLRenderTarget(METER_SIZE, METER_SIZE, {
+            type: THREE.UnsignedByteType,
+            depthBuffer: false,
+            stencilBuffer: false,
+        });
+        this.meterTarget.texture.minFilter = THREE.NearestFilter;
+        this.meterTarget.texture.magFilter = THREE.NearestFilter;
+        this.meterTarget.texture.generateMipmaps = false;
+        this.reduceQuad = new FullScreenQuad(new THREE.ShaderMaterial(reduceShader));
+        this.copyQuad = new FullScreenQuad(new THREE.ShaderMaterial(copyShader));
+    }
+    render(renderer, writeBuffer, readBuffer, deltaTime) {
+        const previous = renderer.getRenderTarget();
+        this.reduceUniforms.tDiffuse.value = readBuffer.texture;
+        renderer.setRenderTarget(this.meterTarget);
+        this.reduceQuad.render(renderer);
+        this.frames += 1;
+        this.elapsed += deltaTime;
+        this.collectPendingSample();
+        // The first few frames sample every frame so a load starts at its metered exposure, not at the
+        // authored one; after that a readback is queued on a schedule.
+        if (this.fence === null && (this.taken < 4 || this.frames % this.sampleInterval === 0)) {
+            this.queueReadback(renderer);
+        }
+        this.copyUniforms.tDiffuse.value = readBuffer.texture;
+        if (this.renderToScreen) {
+            renderer.setRenderTarget(null);
+        }
+        else {
+            renderer.setRenderTarget(writeBuffer);
+            if (this.clear)
+                renderer.clear();
+        }
+        this.copyQuad.render(renderer);
+        renderer.setRenderTarget(previous);
+    }
+    /**
+     * Queues a readback through a pixel-pack buffer and a fence, so the CPU never waits on the GPU: the
+     * samples arrive a frame or two later through {@link collectPendingSample}. A renderer without WebGL2
+     * buffers falls back to the synchronous read, which costs one stall per sample.
+     */
+    queueReadback(renderer) {
+        this.pendingSeconds = this.elapsed;
+        this.elapsed = 0;
+        this.gl ??= renderer.getContext?.() ?? null;
+        const gl = this.gl;
+        if (gl === null || typeof gl.fenceSync !== "function") {
+            renderer.readRenderTargetPixels(this.meterTarget, 0, 0, METER_SIZE, METER_SIZE, this.pixels);
+            this.emit();
+            return;
+        }
+        this.pbo ??= gl.createBuffer();
+        renderer.setRenderTarget(this.meterTarget);
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+        gl.readPixels(0, 0, METER_SIZE, METER_SIZE, gl.RGBA, gl.UNSIGNED_BYTE, 0);
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+        this.fence = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+    }
+    collectPendingSample() {
+        const gl = this.gl;
+        if (gl === null || this.fence === null || this.pbo === null)
+            return;
+        const status = gl.clientWaitSync(this.fence, 0, 0);
+        if (status === gl.TIMEOUT_EXPIRED)
+            return;
+        if (status === gl.WAIT_FAILED) {
+            gl.deleteSync(this.fence);
+            this.fence = null;
+            return;
+        }
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+        gl.getBufferSubData(gl.PIXEL_PACK_BUFFER, 0, this.pixels);
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+        gl.deleteSync(this.fence);
+        this.fence = null;
+        this.emit();
+    }
+    emit() {
+        for (let index = 0; index < this.samples.length; index += 1) {
+            decodeMeterByte(this.pixels[index * 4] ?? 0, this.samples, index);
+        }
+        this.taken += 1;
+        this.onSample(this.samples, this.pendingSeconds);
+    }
+    dispose() {
+        if (this.gl !== null) {
+            if (this.fence !== null)
+                this.gl.deleteSync(this.fence);
+            if (this.pbo !== null)
+                this.gl.deleteBuffer(this.pbo);
+            this.fence = null;
+            this.pbo = null;
+        }
+        this.meterTarget.dispose();
+        this.reduceQuad.material.dispose();
+        this.reduceQuad.dispose();
+        this.copyQuad.material.dispose();
+        this.copyQuad.dispose();
+    }
+}

package/dist/postfx/gradeShader.js

@@ -27,10 +27,15 @@ const fragmentShader = /* glsl */ `
 
   vec3 sampleLut(vec3 color) {
     float size = max(uLutSize, 2.0);
-    vec3 c = clamp(color, 0.0, 1.0) * (size - 1.0);
-    float blue = floor(c.b);
-    vec2 uv = vec2((blue * size + c.r + 0.5) / (size * size), (c.g + 0.5) / size);
-    return texture2D(uLut, uv).rgb;
+    float levels = size - 1.0;
+    vec3 c = clamp(color, 0.0, 1.0) * levels;
+    // One tile per blue slice, sampled at texel centres so linear filtering never reads across
+    // into the neighbouring slice, and the two nearest slices blend the blue axis by hand.
+    float slice = floor(c.b);
+    float next = min(slice + 1.0, levels);
+    vec2 uvA = vec2((slice * size + 0.5 + c.r) / (size * size), (0.5 + c.g) / size);
+    vec2 uvB = vec2((next * size + 0.5 + c.r) / (size * size), (0.5 + c.g) / size);
+    return mix(texture2D(uLut, uvA).rgb, texture2D(uLut, uvB).rgb, c.b - slice);
   }
 
   void main() {
@@ -61,6 +66,34 @@ const vertexShader = /* glsl */ `
     gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
   }
 `;
+/** Packs a baked cube into the strip layout the sampler expects: `size` tiles side by side per blue slice. */
+function lutStripTexture(cube) {
+    const size = cube.size;
+    const data = new Uint8Array(size * size * size * 4);
+    for (let slice = 0; slice < size; slice += 1) {
+        for (let green = 0; green < size; green += 1) {
+            for (let red = 0; red < size; red += 1) {
+                const from = (slice * size * size + green * size + red) * 3;
+                const to = (green * size * size + slice * size + red) * 4;
+                data[to] = cube.data[from] ?? 0;
+                data[to + 1] = cube.data[from + 1] ?? 0;
+                data[to + 2] = cube.data[from + 2] ?? 0;
+                data[to + 3] = 255;
+            }
+        }
+    }
+    const texture = new THREE.DataTexture(data, size * size, size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    // Display-space values sampled raw in the shader, so no colour-space decode on the way in.
+    texture.colorSpace = THREE.NoColorSpace;
+    texture.minFilter = THREE.LinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.generateMipmaps = false;
+    texture.flipY = false;
+    texture.needsUpdate = true;
+    return texture;
+}
 /** Build the display-space colour-grade pass and load its optional LUT. Dispose the pass to release its LUT; advance `uniforms.uTime.value` each frame to animate grain. */
 export function createGradePass(config = {}) {
     const lift = config.lift ?? DEFAULT_LIFT;
@@ -95,6 +128,12 @@ export function createGradePass(config = {}) {
     };
     if (config.lut !== undefined) {
         const lut = config.lut;
+        if ("cube" in lut) {
+            lutTexture = lutStripTexture(lut.cube);
+            pass.uniforms.uLut.value = lutTexture;
+            pass.uniforms.uLutSize.value = lut.cube.size;
+            return pass;
+        }
         void new THREE.TextureLoader().loadAsync(lut.url).then((texture) => {
             if (disposed) {
                 texture.dispose();

package/dist/presentationRecovery3d.js

@@ -2,6 +2,7 @@ import { addAfterEffect, useThree } from "@react-three/fiber";
 import { useTexture } from "@react-three/drei";
 import { useLayoutEffect } from "react";
 import { usePresentationRetryScope } from "./presentationRecovery.js";
+import { useStableTextureSet } from "./render/stableTextureSet.js";
 /** Registers exact loader inputs and their cache clear before a load can suspend. @internal */
 export function useRecoverableTexture(input) {
     const scope = usePresentationRetryScope();
@@ -9,7 +10,7 @@ export function useRecoverableTexture(input) {
     const loaded = scope?.registry.register(inputs, useTexture.clear);
     const textures = useTexture(input);
     loaded?.();
-    return textures;
+    return useStableTextureSet(textures);
 }
 /** Observes the owning renderer after the restored material subtree commits and draws. @internal */
 export function PresentationRecoveredDraw() {

package/dist/render/CascadedShadows.d.ts

@@ -1,6 +1,7 @@
 import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.js";
 import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
+import type { DaylightModulation } from "./SceneLighting.js";
 /** @internal Default PCF penumbra in shadow-map texels for configured directional lights. */
 export declare const DEFAULT_SHADOW_RADIUS = 1.25;
 /**
@@ -12,8 +13,9 @@ export declare const DEFAULT_SHADOW_RADIUS = 1.25;
  *
  * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
  */
-export declare function CascadedShadows({ entry }: {
+export declare function CascadedShadows({ entry, modulation }: {
     entry: DirectionalLightingConfig;
+    modulation?: DaylightModulation;
 }): null;
 /** Structural slice of CSM so the patcher is testable without a renderer. */
 export interface CsmMaterialSetup {

package/dist/render/CascadedShadows.js

@@ -16,10 +16,11 @@ function isStandardMaterial(mat) {
  *
  * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
  */
-export function CascadedShadows({ entry }) {
+export function CascadedShadows({ entry, modulation }) {
     const camera = useThree((s) => s.camera);
     const scene = useThree((s) => s.scene);
     const csmRef = useRef(null);
+    const baseIntensity = entry.intensity ?? 1.3;
     useEffect(() => {
         const cascades = Math.max(2, Math.min(4, Math.floor(entry.cascades ?? 3)));
         const lightDirection = new THREE.Vector3(-entry.position[0], -entry.position[1], -entry.position[2]);
@@ -71,6 +72,13 @@ export function CascadedShadows({ entry }) {
         const csm = csmRef.current;
         if (csm === null)
             return;
+        if (modulation !== undefined) {
+            // Mutated in place: changing `entry.intensity` would rebuild every cascade's shadow map.
+            for (const light of csm.lights) {
+                light.intensity = baseIntensity * modulation.sunFactor;
+                light.color.set(modulation.sunColor);
+            }
+        }
         csm.camera = camera;
         csm.update();
     });

package/dist/render/EnvironmentLighting.d.ts

@@ -19,6 +19,15 @@ export interface EnvironmentLightingProps {
     sunDirection?: readonly [number, number, number];
     /** Sun disc tint. Default warm white. */
     sunColor?: string;
+    /**
+     * Day-cycle scaling for the probe's brightness. Rebuilding a PMREM every frame is not free, so a
+     * cycle dims the applied environment instead of re-baking it; without this the sky turns black at
+     * night while the IBL keeps lighting the world like noon.
+     */
+    daylight?: {
+        sunFactor: number;
+        ambientFactor: number;
+    };
 }
 /**
  * Image-based lighting from a procedural sky/horizon/ground probe with an HDR sun (not three's stock
@@ -29,7 +38,7 @@ export interface EnvironmentLightingProps {
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, horizonTint, sunDirection, sunColor, }: EnvironmentLightingProps): null;
+export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, horizonTint, sunDirection, sunColor, daylight, }: EnvironmentLightingProps): null;
 /** @internal Default IBL strength for the procedural probe: enough sky fill and sun lobe to model forms. */
 export declare const DEFAULT_IBL_INTENSITY = 0.45;
 /** @internal Fallback probe sun when no directional light is authored: high and off to one side. */

package/dist/render/EnvironmentLighting.js

@@ -1,5 +1,5 @@
 import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
-import { useThree } from "@react-three/fiber";
+import { useThree, useFrame } from "@react-three/fiber";
 import { useEffect } from "react";
 import * as THREE from "three";
 import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
@@ -13,7 +13,7 @@ import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY, skyColor = "#87b5e0", groundColor = "#3d4a38", horizonTint = "#ffffff", sunDirection, sunColor = "#fff2d6", }) {
+export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY, skyColor = "#87b5e0", groundColor = "#3d4a38", horizonTint = "#ffffff", sunDirection, sunColor = "#fff2d6", daylight, }) {
     const gl = useThree((state) => state.gl);
     const scene = useThree((state) => state.scene);
     useEffect(() => {
@@ -32,8 +32,10 @@ export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY,
             if (cancelled)
                 return;
             cancelled = true;
-            if (target !== undefined && scene.environment === target.texture)
+            if (target !== undefined && scene.environment === target.texture) {
                 scene.environment = previous;
+                scene.environmentIntensity = previousIntensity;
+            }
             if (appliedRotation !== undefined && scene.environmentRotation === appliedRotation && appliedRotation.equals(appliedRotationValue))
                 scene.environmentRotation = previousRotation;
             if (scene.environmentIntensity === appliedIntensity)
@@ -106,6 +108,12 @@ export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY,
         }
         return release;
     }, [gl, scene, source, intensity, skyColor, groundColor, horizonTint, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
+    useFrame(() => {
+        if (daylight === undefined || scene.environment === null)
+            return;
+        // Ambient fill and the probe's sun lobe fade together; the probe's colours stay authored.
+        scene.environmentIntensity = (source?.intensity ?? intensity) * (daylight.ambientFactor * 0.6 + daylight.sunFactor * 0.4);
+    });
     return null;
 }
 /** @internal Default IBL strength for the procedural probe: enough sky fill and sun lobe to model forms. */

package/dist/render/IrradianceVolumeLighting.d.ts

@@ -0,0 +1,18 @@
+import { type IrradianceVolume } from "@jgengine/core/render/lightProbes";
+/** @internal Props for shell {@link IrradianceVolumeLighting}. */
+export interface IrradianceVolumeLightingProps {
+    /** Baked volumes authored on the scene document; the one covering the camera wins. */
+    volumes: readonly IrradianceVolume[];
+}
+/**
+ * Ambient light from an authored irradiance volume: each frame it samples the volume that covers the
+ * camera and writes the nine SH coefficients into three's scene light probe. This is what makes an
+ * interior read as its own space — a room gets the fill from its own lamps and bounce instead of the
+ * sky's hemisphere, and the ambient varies as you walk through it.
+ *
+ * One light probe serves the whole scene, so a world with several volumes is sampled by camera
+ * position; that is exact while the camera is inside a room and approximate at the doorways between
+ * them.
+ * @internal shell-internal lighting; games author the volume on the scene document.
+ */
+export declare function IrradianceVolumeLighting({ volumes }: IrradianceVolumeLightingProps): import("react").JSX.Element;

package/dist/render/IrradianceVolumeLighting.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useMemo, useRef } from "react";
+import * as THREE from "three";
+import { PROBE_STRIDE, sampleIrradianceVolume, selectIrradianceVolume, SH_COEFFICIENTS, } from "@jgengine/core/render/lightProbes";
+/**
+ * Ambient light from an authored irradiance volume: each frame it samples the volume that covers the
+ * camera and writes the nine SH coefficients into three's scene light probe. This is what makes an
+ * interior read as its own space — a room gets the fill from its own lamps and bounce instead of the
+ * sky's hemisphere, and the ambient varies as you walk through it.
+ *
+ * One light probe serves the whole scene, so a world with several volumes is sampled by camera
+ * position; that is exact while the camera is inside a room and approximate at the doorways between
+ * them.
+ * @internal shell-internal lighting; games author the volume on the scene document.
+ */
+export function IrradianceVolumeLighting({ volumes }) {
+    const probeRef = useRef(null);
+    const sampled = useMemo(() => new Float32Array(PROBE_STRIDE), []);
+    useFrame((state) => {
+        const probe = probeRef.current;
+        if (probe === null)
+            return;
+        const position = state.camera.position;
+        const volume = selectIrradianceVolume(volumes, [position.x, position.y, position.z]);
+        if (volume === undefined)
+            return;
+        if (!sampleIrradianceVolume(volume, [position.x, position.y, position.z], sampled))
+            return;
+        for (let band = 0; band < SH_COEFFICIENTS; band += 1) {
+            probe.sh.coefficients[band].set(sampled[band * 3], sampled[band * 3 + 1], sampled[band * 3 + 2]);
+        }
+    });
+    return _jsx("lightProbe", { ref: probeRef });
+}

package/dist/render/SceneLighting.d.ts

@@ -3,6 +3,17 @@ import type { BackdropConfig, LightingConfig, PointLightingConfig } from "@jgeng
 import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
 /** Default cap for combined dynamic point and spot lights. */
 export declare const POINT_LIGHT_BUDGET = 8;
+/**
+ * Per-frame scaling a day cycle applies to a game's authored sun and ambient fill, so an authored
+ * sun sets and a moon rises instead of the world staying lit like noon after dark. `sunFactor` and
+ * `ambientFactor` are 1 at the authored noon peak; colors come from the atmosphere.
+ * @internal
+ */
+export interface DaylightModulation {
+    sunFactor: number;
+    sunColor: string;
+    ambientFactor: number;
+}
 /** @internal Clamp point lights for the runtime budget. */
 export declare function resolvePointLightBudget(entries: readonly PointLightingConfig[] | undefined): readonly PointLightingConfig[];
 /**
@@ -12,9 +23,11 @@ export declare function resolvePointLightBudget(entries: readonly PointLightingC
  * and `shadowCameraSize` is silently inert.
  */
 export declare function syncShadowProjection(light: DirectionalLight): void;
-export declare function ConfiguredLighting({ lighting, profile }: {
+export declare function ConfiguredLighting({ lighting, profile, modulation, }: {
     lighting: LightingConfig;
     profile?: GraphicsProfile;
+    /** Day-cycle scaling for the first directional (the sun) and the ambient fill. */
+    modulation?: DaylightModulation;
 }): import("react").JSX.Element;
 export declare function BackdropFog({ fog }: {
     fog: BackdropConfig["fog"];