@jgengine/shell 0.24.0 → 0.26.0

package/dist/environment/Daylight.js

@@ -1,6 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
-import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import * as THREE from "three";
 import { createBiomeFogSampler, createBiomeSkySampler } from "@jgengine/core/world/terrain";
 import { resolveVolumetricClouds } from "@jgengine/core/world/volumetricClouds";
@@ -17,15 +17,23 @@ const SKY_TOP = "#3fa4f2";
 const SKY_HORIZON = "#e3f4ff";
 const FOG_COLOR = "#e9f6ff";
 const SUN_COLOR = "#fff1c9";
+const MOON_COLOR = "#cfdcf2";
 const HEMI_SKY = "#bfe3ff";
 const HEMI_GROUND = "#4c6b34";
+/** Aim the dome's moon disc and dial its brightness; called per frame by the time-of-day drivers. @internal */
+export function setSkyMoon(material, direction, color, intensity, starOpacity) {
+    material.uniforms.uMoonDirection.value.set(direction[0], direction[1], direction[2]).normalize();
+    material.uniforms.uMoonColor.value.set(color);
+    material.uniforms.uMoonIntensity.value = intensity;
+    material.uniforms.uStars.value = starOpacity;
+}
 /**
  * Shadow-casting sun whose shadow box leads the camera each frame ({@link sunShadowFocus}), so
  * grounded shadows stay crisp and soft-edged under the player anywhere in a large world. Time-of-day
  * drivers aim it through `directionRef` and retint it through `lightRef`.
  * @internal
  */
-export function SunLight({ direction, directionRef, lightRef, intensity, color, }) {
+export function SunLight({ direction, directionRef, lightRef, intensity, color, castShadow = true, }) {
     const ownRef = useRef(null);
     const ref = lightRef ?? ownRef;
     const scratch = useMemo(() => ({ forward: new THREE.Vector3(), focus: { x: 0, z: 0 }, position: [0, 0, 0] }), []);
@@ -41,7 +49,15 @@ export function SunLight({ direction, directionRef, lightRef, intensity, color,
         light.target.updateMatrixWorld();
     });
     const initial = sunLightPosition({ x: 0, z: 0 }, direction);
-    return (_jsx("directionalLight", { ref: ref, position: initial, intensity: intensity, color: color, castShadow: true, "shadow-mapSize-width": SUN_SHADOW.mapSize, "shadow-mapSize-height": SUN_SHADOW.mapSize, "shadow-camera-left": -SUN_SHADOW.halfExtent, "shadow-camera-right": SUN_SHADOW.halfExtent, "shadow-camera-top": SUN_SHADOW.halfExtent, "shadow-camera-bottom": -SUN_SHADOW.halfExtent, "shadow-camera-near": SUN_SHADOW.near, "shadow-camera-far": SUN_SHADOW.far, "shadow-bias": SUN_SHADOW.bias, "shadow-normalBias": SUN_SHADOW.normalBias, "shadow-radius": SUN_SHADOW.radius }));
+    return (_jsx("directionalLight", { ref: ref, position: initial, intensity: intensity, color: color, castShadow: castShadow, "shadow-mapSize-width": SUN_SHADOW.mapSize, "shadow-mapSize-height": SUN_SHADOW.mapSize, "shadow-camera-left": -SUN_SHADOW.halfExtent, "shadow-camera-right": SUN_SHADOW.halfExtent, "shadow-camera-top": SUN_SHADOW.halfExtent, "shadow-camera-bottom": -SUN_SHADOW.halfExtent, "shadow-camera-near": SUN_SHADOW.near, "shadow-camera-far": SUN_SHADOW.far, "shadow-bias": SUN_SHADOW.bias, "shadow-normalBias": SUN_SHADOW.normalBias, "shadow-radius": SUN_SHADOW.radius }));
+}
+/**
+ * The moon as a dim, shadowless key light opposite the sun, so a night scene keeps a lit and a
+ * shaded side instead of collapsing into flat ambient. Same camera-following aim as the sun.
+ * @internal
+ */
+export function MoonLight({ direction, directionRef, lightRef, intensity, color }) {
+    return _jsx(SunLight, { direction: direction, directionRef: directionRef, lightRef: lightRef, intensity: intensity, color: color, castShadow: false });
 }
 /**
  * Sets the zenith and horizon colors a sky dome should show on screen. The dome converts them each
@@ -87,7 +103,7 @@ export function setSkyFogColor(fog, color) {
 }
 const fogDisplayColors = new WeakMap();
 /** @internal */
-export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, sunDirection, sunColor = "#fff4d6", sunIntensity = 1, hazeStrength = 0.5, sunGlowStrength = 1, cloudiness = 0.35, materialRef, } = {}) {
+export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, sunDirection, sunColor = "#fff4d6", sunIntensity = 1, moonDirection, moonColor = MOON_COLOR, moonIntensity = 0, starOpacity = 0, hazeStrength = 0.5, sunGlowStrength = 1, cloudiness = 0.35, materialRef, } = {}) {
     const meshRef = useRef(null);
     const material = useMemo(() => {
         const dome = new THREE.ShaderMaterial({
@@ -99,6 +115,10 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                 uSunColor: { value: new THREE.Color(sunColor) },
                 uSunDirection: { value: sunDirection === undefined ? new THREE.Vector3(0, 1, 0) : normalizeVec3(sunDirection) },
                 uSunIntensity: { value: sunDirection === undefined ? 0 : sunIntensity },
+                uMoonColor: { value: new THREE.Color(moonColor) },
+                uMoonDirection: { value: moonDirection === undefined ? new THREE.Vector3(0, -1, 0) : normalizeVec3(moonDirection) },
+                uMoonIntensity: { value: moonDirection === undefined ? 0 : moonIntensity },
+                uStars: { value: starOpacity },
                 uHazeStrength: { value: hazeStrength },
                 uSunGlow: { value: sunGlowStrength },
                 uCloudiness: { value: cloudiness },
@@ -117,6 +137,10 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
         uniform vec3 uSunColor;
         uniform vec3 uSunDirection;
         uniform float uSunIntensity;
+        uniform vec3 uMoonColor;
+        uniform vec3 uMoonDirection;
+        uniform float uMoonIntensity;
+        uniform float uStars;
         uniform float uHazeStrength;
         uniform float uSunGlow;
         uniform float uCloudiness;
@@ -130,6 +154,16 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                      mix(sHash(i + vec2(0.0, 1.0)), sHash(i + vec2(1.0, 1.0)), u.x), u.y);
         }
         float sFbm(vec2 p){ float v = 0.0; float a = 0.5; for (int i = 0; i < 5; i++){ v += a * sNoise(p); p *= 2.0; a *= 0.5; } return v; }
+        float h3(vec3 p){ return fract(sin(dot(p, vec3(12.9898, 78.233, 37.719))) * 43758.5453); }
+        float starField(vec3 dir){
+          vec3 q = dir * 170.0;
+          vec3 cell = floor(q);
+          float seed = h3(cell);
+          if (seed < 0.984) return 0.0;
+          vec3 jitter = fract(vec3(seed * 137.0, seed * 311.0, seed * 531.0)) - 0.5;
+          float d = length(fract(q) - 0.5 - jitter * 0.7);
+          return smoothstep(0.18, 0.0, d) * smoothstep(0.984, 0.999, seed);
+        }
         void main() {
           vec3 dir = normalize(vWorldPosition + vec3(0.0, offset, 0.0));
           float h = max(dir.y, 0.0);
@@ -143,6 +177,16 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
           float sd = max(dot(vd, normalize(uSunDirection)), 0.0);
           float glow = pow(sd, 8.0) * 0.35 + pow(sd, 128.0) * 2.6;
           col += uSunColor * glow * uSunIntensity * uSunGlow;
+          if (uStars > 0.001) {
+            float stars = starField(vd) * smoothstep(0.02, 0.22, vd.y) * smoothstep(0.35, 0.9, uStars);
+            col += vec3(0.86, 0.9, 1.0) * stars * uStars * 1.6;
+          }
+          if (uMoonIntensity > 0.001) {
+            float md = max(dot(vd, normalize(uMoonDirection)), 0.0);
+            float disc = smoothstep(0.99955, 0.99985, md);
+            float halo = pow(md, 512.0) * 0.5 + pow(md, 24.0) * 0.05;
+            col += uMoonColor * (disc * 2.2 + halo) * uMoonIntensity;
+          }
           gl_FragColor = vec4(col, 1.0);
           #include <tonemapping_fragment>
           #include <colorspace_fragment>
@@ -154,7 +198,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
         });
         setSkyDomeColors(dome, topColor, horizonColor);
         return dome;
-    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity, hazeStrength, sunGlowStrength, cloudiness]);
+    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity, moonDirection, moonColor, moonIntensity, starOpacity, hazeStrength, sunGlowStrength, cloudiness]);
     useEffect(() => {
         if (materialRef !== undefined)
             materialRef.current = material;
@@ -189,21 +233,46 @@ function aimSkySun(material, position) {
     material.uniforms.uSunDirection.value.set(position[0], position[1], position[2]).normalize();
 }
 /** @internal */
-export function Daylight({ sky, fog, sun, ambient, lights = true, clouds } = {}) {
+export function Daylight({ sky, fog, sun, ambient, moon, lights = true, clouds } = {}) {
     const sunPosition = sun?.position ?? [120, 160, 70];
-    return (_jsxs(_Fragment, { children: [sky === false ? null : (_jsx(SkyDome, { ...(sky ?? {}), sunDirection: sunPosition, sunColor: sun?.color ?? SUN_COLOR, sunIntensity: sun?.intensity ?? 1 })), clouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(clouds), sunDirection: sunPosition })), fog === false ? null : (_jsx(SkyFog, { color: fog?.color ?? FOG_COLOR, near: fog?.near ?? 70, far: fog?.far ?? 260 })), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx(SunLight, { direction: sunPosition, intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR })] })) : null] }));
+    const moonIntensity = moon?.intensity ?? 0;
+    return (_jsxs(_Fragment, { children: [sky === false ? null : (_jsx(SkyDome, { ...(sky ?? {}), sunDirection: sunPosition, sunColor: sun?.color ?? SUN_COLOR, sunIntensity: sun?.intensity ?? 1, ...(moon?.position === undefined ? {} : { moonDirection: moon.position }), ...(moon?.color === undefined ? {} : { moonColor: moon.color }), moonIntensity: moonIntensity, starOpacity: moon?.stars ?? 0 })), clouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(clouds), sunDirection: sunPosition })), fog === false ? null : (_jsx(SkyFog, { color: fog?.color ?? FOG_COLOR, near: fog?.near ?? 70, far: fog?.far ?? 260 })), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx(SunLight, { direction: sunPosition, intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR }), moonIntensity > 0 && moon?.position !== undefined ? (_jsx(MoonLight, { direction: moon.position, intensity: moonIntensity, color: moon.color ?? MOON_COLOR })) : null] })) : null] }));
 }
 /** True when at least one band overrides fog or sky — the trigger for the per-frame biome driver. */
 function bandsDriveSkyOrFog(bands) {
     return bands !== undefined && bands.some((band) => band.fog !== undefined || band.sky !== undefined);
 }
+/**
+ * Mount state for the moon: it re-renders only when the moon crosses the horizon. A zero-intensity
+ * directional light still costs a per-fragment loop in every lit material, so a day sky must not
+ * carry it.
+ * @internal
+ */
+export function useMoonAboveHorizon(initialUp) {
+    const [up, setUp] = useState(initialUp);
+    const upRef = useRef(up);
+    return [
+        up,
+        (intensity) => {
+            const next = intensity > 0;
+            if (next === upRef.current)
+                return;
+            upRef.current = next;
+            setUp(next);
+        },
+    ];
+}
+/** Fog range: the sky's own fields win, then the authored backdrop, then the caller's default. */
+function skyFogRange(sky, fogRange, fallback) {
+    return { near: sky.fog?.near ?? fogRange?.near ?? fallback.near, far: sky.fog?.far ?? fogRange?.far ?? fallback.far };
+}
 /** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates.
  * @internal
  */
-export function SkyDaylight({ sky, lights = true, bands }) {
+export function SkyDaylight({ sky, lights = true, bands, fogRange }) {
     if (bandsDriveSkyOrFog(bands))
-        return _jsx(BiomeDaylight, { sky: sky, bands: bands, lights: lights });
-    return _jsx(StaticSkyDaylight, { sky: sky, lights: lights });
+        return _jsx(BiomeDaylight, { sky: sky, bands: bands, lights: lights, fogRange: fogRange });
+    return _jsx(StaticSkyDaylight, { sky: sky, lights: lights, fogRange: fogRange });
 }
 /** Dome-shape overrides (radius, haze, sun-glow) carried by the sky descriptor, spread onto `SkyDome`; unset fields keep the dome defaults. */
 function skyDomeShape(sky) {
@@ -215,43 +284,48 @@ function skyDomeShape(sky) {
         ...(sky.cloudiness === undefined ? {} : { cloudiness: sky.cloudiness }),
     };
 }
-function StaticSkyDaylight({ sky, lights }) {
+function StaticSkyDaylight({ sky, lights, fogRange, }) {
     const state = useMemo(() => daylightStateAt(SKY_PRESET_DAY_FRACTION[sky.preset], sky), [sky]);
-    return (_jsx(Daylight, { sky: { topColor: state.skyTop, horizonColor: state.skyBottom, ...skyDomeShape(sky) }, fog: { color: sky.fog?.color ?? state.background, near: sky.fog?.near, far: sky.fog?.far }, sun: { position: state.sunPosition, intensity: state.sunIntensity }, ambient: { intensity: state.ambientIntensity }, lights: lights, clouds: sky.volumetricClouds }));
+    const range = skyFogRange(sky, fogRange, { near: 70, far: 260 });
+    return (_jsx(Daylight, { sky: { topColor: state.skyTop, horizonColor: state.skyBottom, ...skyDomeShape(sky) }, fog: { color: sky.fog?.color ?? state.fogColor, ...range }, sun: { position: state.sunPosition, intensity: state.sunIntensity, color: state.sunColor }, moon: { position: state.moonPosition, intensity: state.moonIntensity, color: state.moonColor, stars: state.starOpacity }, ambient: { intensity: state.ambientIntensity }, lights: lights, clouds: sky.volumetricClouds }));
 }
 /**
  * Drives sky/fog (and optional default lights) from the world clock when `sky.timeOfDay` and `clock`
  * are both present. Authored `PlayableGame.lighting` is never rewritten — pass `lights={false}` so
- * only dome colors and fog track the day fraction.
+ * only dome colors and fog track the day fraction; `AuthoredDaylight` scales those authored lights
+ * from the same state.
   * @internal
   */
-export function TimeOfDayDaylight({ sky, clock, lights = true, bands }) {
+export function TimeOfDayDaylight({ sky, clock, lights = true, bands, fogRange }) {
     if (bandsDriveSkyOrFog(bands))
-        return _jsx(BiomeDaylight, { sky: sky, bands: bands, clock: clock, lights: lights });
+        return _jsx(BiomeDaylight, { sky: sky, bands: bands, clock: clock, lights: lights, fogRange: fogRange });
     if (!sky.timeOfDay || clock === undefined)
-        return _jsx(SkyDaylight, { sky: sky, lights: lights });
-    return _jsx(DrivenDaylight, { sky: sky, clock: clock, lights: lights });
+        return _jsx(SkyDaylight, { sky: sky, lights: lights, bands: bands, fogRange: fogRange });
+    return _jsx(DrivenDaylight, { sky: sky, clock: clock, lights: lights, fogRange: fogRange });
 }
 /**
  * Per-frame biome fog/sky driver: cross-fades fog color/range, dome colors, and sun/ambient intensity
  * along the camera's z through the terrain's `biomeBands`. Base look is the sky preset (or, when
  * `sky.timeOfDay` and a `clock` are present, the live day fraction); bands ride on top.
  */
-function BiomeDaylight({ sky, bands, clock, lights, }) {
+function BiomeDaylight({ sky, bands, clock, lights, fogRange, }) {
     const timeOfDay = sky.timeOfDay && clock !== undefined;
     const baseFraction = timeOfDay ? clock.calendar().dayFraction : SKY_PRESET_DAY_FRACTION[sky.preset];
     const initial = useMemo(() => daylightStateAt(baseFraction, sky), [sky, baseFraction]);
     const sunRef = useRef(null);
     const sunDirectionRef = useRef(initial.sunPosition);
+    const moonRef = useRef(null);
+    const moonDirectionRef = useRef(initial.moonPosition);
     const hemiRef = useRef(null);
     const fogRef = useRef(null);
     const skyMaterialRef = useRef(null);
+    const range = skyFogRange(sky, fogRange, { near: 70, far: 260 });
     const fogFallback = useMemo(() => ({
-        color: sky.fog?.color ?? initial.background,
-        near: sky.fog?.near ?? 70,
-        far: sky.fog?.far ?? 260,
+        color: sky.fog?.color ?? initial.fogColor,
+        near: range.near,
+        far: range.far,
         density: 0,
-    }), [sky.fog?.color, sky.fog?.near, sky.fog?.far, initial.background]);
+    }), [sky.fog?.color, range.near, range.far, initial.fogColor]);
     const skyFallback = useMemo(() => ({
         horizonColor: initial.skyBottom,
         zenithColor: initial.skyTop,
@@ -260,14 +334,18 @@ function BiomeDaylight({ sky, bands, clock, lights, }) {
     }), [initial.skyBottom, initial.skyTop, initial.sunIntensity, initial.ambientIntensity]);
     const fogSampler = useMemo(() => createBiomeFogSampler(bands, fogFallback), [bands, fogFallback]);
     const skySampler = useMemo(() => createBiomeSkySampler(bands, skyFallback), [bands, skyFallback]);
+    const [moonUp, syncMoon] = useMoonAboveHorizon(initial.moonIntensity > 0);
     useFrame((state) => {
         const base = timeOfDay ? daylightStateAt(clock.calendar().dayFraction, sky) : initial;
+        syncMoon(base.moonIntensity);
         const z = state.camera.position.z;
         const fog = fogSampler(z);
         const skyValue = skySampler(z);
         const fogNode = fogRef.current;
         if (fogNode !== null) {
-            setSkyFogColor(fogNode, fog.color);
+            // Under a day cycle the sky owns the fog color (bands still own its range): a fixed noon
+            // tint would leave bright haze hanging in a black night sky.
+            setSkyFogColor(fogNode, sky.fog?.color ?? (timeOfDay ? base.fogColor : fog.color));
             fogNode.near = fog.near;
             fogNode.far = fog.far;
         }
@@ -275,41 +353,60 @@ function BiomeDaylight({ sky, bands, clock, lights, }) {
         if (skyMaterial !== null) {
             setSkyDomeColors(skyMaterial, skyValue.zenithColor, skyValue.horizonColor);
             aimSkySun(skyMaterial, base.sunPosition);
+            setSkyMoon(skyMaterial, base.moonPosition, base.moonColor, base.moonIntensity, base.starOpacity);
         }
         sunDirectionRef.current = base.sunPosition;
+        moonDirectionRef.current = base.moonPosition;
+        const moon = moonRef.current;
+        if (moon !== null)
+            moon.intensity = base.moonIntensity;
         const sun = sunRef.current;
-        if (sun !== null)
+        if (sun !== null) {
             sun.intensity = skyValue.sunIntensity;
+            sun.color.set(base.sunColor);
+        }
         const hemi = hemiRef.current;
         if (hemi !== null)
             hemi.intensity = skyValue.ambientIntensity;
     });
-    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, sunDirection: initial.sunPosition, sunColor: SUN_COLOR, materialRef: skyMaterialRef, ...skyDomeShape(sky) }), sky.volumetricClouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(sky.volumetricClouds), sunDirection: initial.sunPosition })), _jsx(SkyFog, { fogRef: fogRef, color: fogFallback.color, near: fogFallback.near, far: fogFallback.far }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx(SunLight, { direction: initial.sunPosition, directionRef: sunDirectionRef, lightRef: sunRef, intensity: initial.sunIntensity, color: SUN_COLOR })] })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, sunDirection: initial.sunPosition, sunColor: initial.sunColor, materialRef: skyMaterialRef, moonDirection: initial.moonPosition, moonColor: initial.moonColor, moonIntensity: initial.moonIntensity, starOpacity: initial.starOpacity, ...skyDomeShape(sky) }), sky.volumetricClouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(sky.volumetricClouds), sunDirection: initial.sunPosition })), _jsx(SkyFog, { fogRef: fogRef, color: fogFallback.color, near: fogFallback.near, far: fogFallback.far }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx(SunLight, { direction: initial.sunPosition, directionRef: sunDirectionRef, lightRef: sunRef, intensity: initial.sunIntensity, color: initial.sunColor }), moonUp ? (_jsx(MoonLight, { direction: initial.moonPosition, directionRef: moonDirectionRef, lightRef: moonRef, intensity: initial.moonIntensity, color: initial.moonColor })) : null] })) : null] }));
 }
-function DrivenDaylight({ sky, clock, lights, }) {
+function DrivenDaylight({ sky, clock, lights, fogRange, }) {
     const initial = useMemo(() => daylightStateAt(clock.calendar().dayFraction, sky), [clock, sky]);
     const sunRef = useRef(null);
     const sunDirectionRef = useRef(initial.sunPosition);
+    const moonRef = useRef(null);
+    const moonDirectionRef = useRef(initial.moonPosition);
     const hemiRef = useRef(null);
     const fogRef = useRef(null);
     const skyMaterialRef = useRef(null);
+    const range = skyFogRange(sky, fogRange, { near: 70, far: 260 });
+    const [moonUp, syncMoon] = useMoonAboveHorizon(initial.moonIntensity > 0);
     useFrame(() => {
         const state = daylightStateAt(clock.calendar().dayFraction, sky);
         sunDirectionRef.current = state.sunPosition;
+        moonDirectionRef.current = state.moonPosition;
+        syncMoon(state.moonIntensity);
         const sun = sunRef.current;
-        if (sun !== null)
+        if (sun !== null) {
             sun.intensity = state.sunIntensity;
+            sun.color.set(state.sunColor);
+        }
+        const moon = moonRef.current;
+        if (moon !== null)
+            moon.intensity = state.moonIntensity;
         const hemi = hemiRef.current;
         if (hemi !== null)
             hemi.intensity = state.ambientIntensity;
         const fog = fogRef.current;
         if (fog !== null)
-            setSkyFogColor(fog, sky.fog?.color ?? state.background);
+            setSkyFogColor(fog, sky.fog?.color ?? state.fogColor);
         const skyMaterial = skyMaterialRef.current;
         if (skyMaterial !== null) {
             setSkyDomeColors(skyMaterial, state.skyTop, state.skyBottom);
             aimSkySun(skyMaterial, state.sunPosition);
+            setSkyMoon(skyMaterial, state.moonPosition, state.moonColor, state.moonIntensity, state.starOpacity);
         }
     });
-    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, sunDirection: initial.sunPosition, sunColor: SUN_COLOR, materialRef: skyMaterialRef, ...skyDomeShape(sky) }), sky.volumetricClouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(sky.volumetricClouds), sunDirection: initial.sunPosition })), _jsx(SkyFog, { fogRef: fogRef, color: sky.fog?.color ?? initial.background, near: sky.fog?.near ?? 70, far: sky.fog?.far ?? 260 }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx(SunLight, { direction: initial.sunPosition, directionRef: sunDirectionRef, lightRef: sunRef, intensity: initial.sunIntensity, color: SUN_COLOR })] })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, sunDirection: initial.sunPosition, sunColor: initial.sunColor, materialRef: skyMaterialRef, moonDirection: initial.moonPosition, moonColor: initial.moonColor, moonIntensity: initial.moonIntensity, starOpacity: initial.starOpacity, ...skyDomeShape(sky) }), sky.volumetricClouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(sky.volumetricClouds), sunDirection: initial.sunPosition })), _jsx(SkyFog, { fogRef: fogRef, color: sky.fog?.color ?? initial.fogColor, near: range.near, far: range.far }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx(SunLight, { direction: initial.sunPosition, directionRef: sunDirectionRef, lightRef: sunRef, intensity: initial.sunIntensity, color: initial.sunColor }), moonUp ? (_jsx(MoonLight, { direction: initial.moonPosition, directionRef: moonDirectionRef, lightRef: moonRef, intensity: initial.moonIntensity, color: initial.moonColor })) : null] })) : null] }));
 }

package/dist/environment/daylightCycle.d.ts

@@ -6,19 +6,40 @@ export interface DaylightCycleConfig {
     ambientIntensity?: number;
     /** Fixed sun placement, or the noon placement the day arc swings around. Unset keeps the engine arc. */
     sun?: SkySunConfig;
+    /** Authored noon sun colour, reddened toward the horizon by the atmosphere. Default warm white. */
+    sunColor?: string;
+    /** Authored noon fog colour; dawn, dusk and night cross-fade to their own haze. Default the noon horizon. */
+    fogColor?: string;
+    /** Peak moonlight as a fraction of `sunIntensity`. Default `MOONLIGHT_PEAK`. */
+    moonIntensity?: number;
+    /** Moonlight colour. Default `MOONLIGHT_COLOR`. */
+    moonColor?: string;
 }
 export interface DaylightState {
     sunPosition: [number, number, number];
     sunIntensity: number;
+    /** The sun's colour at this hour: authored tint high up, atmosphere-reddened near the horizon. */
+    sunColor: string;
     ambientIntensity: number;
     skyTop: string;
     skyBottom: string;
     background: string;
+    /** Scene fog colour matched to the sky at this hour, so fogged ground meets the horizon. */
+    fogColor: string;
+    /** The moon's direction — the sun's arc half a day away, so it is up whenever the sun is down. */
+    moonPosition: [number, number, number];
+    /** Moonlight intensity, already scaled by the authored noon sun intensity. */
+    moonIntensity: number;
+    moonColor: string;
+    /** Star visibility, 0 in daylight and 1 with the sun well under the horizon. */
+    starOpacity: number;
 }
 export declare const DEFAULT_DAY_SUN_INTENSITY = 1;
 export declare const DEFAULT_DAY_AMBIENT_INTENSITY = 0.6;
 export declare const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
 export declare const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
+/** Warm-white noon sun used when the game authored no sun tint (the shell's `SUN_COLOR`). */
+export declare const DEFAULT_SUN_COLOR = "#fff1c9";
 /** The engine arc's noon height: `atan(1 / SUN_DEPTH_RATIO)`, ~68 degrees. */
 export declare const DEFAULT_SUN_ELEVATION_DEG: number;
 /**
@@ -41,8 +62,9 @@ export declare const SKY_PRESET_DAY_FRACTION: Record<"day" | "dusk" | "night", n
 export declare function lerpHexColor(a: string, b: string, t: number): string;
 /**
  * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
- * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
- * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
-  * @internal
-  */
+ * lerping sun position/intensity, ambient intensity, sky and fog colors through a dawn/day/dusk/night
+ * keyframe table, and deriving sun tint, moonlight and star visibility from the sun's elevation.
+ * `config` overrides the noon (peak-day) colors and intensities only.
+ * @internal
+ */
 export declare function daylightStateAt(dayFraction: number, config?: DaylightCycleConfig): DaylightState;

package/dist/environment/daylightCycle.js

@@ -1,3 +1,4 @@
+import { elevationOf, MOONLIGHT_COLOR, moonIllumination, NIGHT_FOG_COLOR, starOpacity, sunlightColor, } from "@jgengine/core/render/physicalSky";
 const NIGHT_SUN_INTENSITY = 0.02;
 const NIGHT_AMBIENT_INTENSITY = 0.08;
 const NIGHT_SKY_TOP = "#02030a";
@@ -14,6 +15,8 @@ export const DEFAULT_DAY_SUN_INTENSITY = 1;
 export const DEFAULT_DAY_AMBIENT_INTENSITY = 0.6;
 export const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
 export const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
+/** Warm-white noon sun used when the game authored no sun tint (the shell's `SUN_COLOR`). */
+export const DEFAULT_SUN_COLOR = "#fff1c9";
 const SUN_DISTANCE = 200;
 const SUN_DEPTH_RATIO = 0.4;
 const DEG = Math.PI / 180;
@@ -79,6 +82,7 @@ function buildKeyframes(config) {
         ambientIntensity: NIGHT_AMBIENT_INTENSITY,
         skyTop: NIGHT_SKY_TOP,
         skyBottom: NIGHT_SKY_BOTTOM,
+        fog: NIGHT_FOG_COLOR,
     };
     const dawn = {
         t: 0.25,
@@ -86,6 +90,7 @@ function buildKeyframes(config) {
         ambientIntensity: DAWN_AMBIENT_INTENSITY,
         skyTop: DAWN_SKY_TOP,
         skyBottom: DAWN_SKY_BOTTOM,
+        fog: DAWN_SKY_BOTTOM,
     };
     const day = {
         t: 0.5,
@@ -93,6 +98,7 @@ function buildKeyframes(config) {
         ambientIntensity: config.ambientIntensity ?? DEFAULT_DAY_AMBIENT_INTENSITY,
         skyTop: config.zenithColor ?? DEFAULT_DAY_SKY_TOP,
         skyBottom: config.horizonColor ?? DEFAULT_DAY_SKY_BOTTOM,
+        fog: config.fogColor ?? config.horizonColor ?? DEFAULT_DAY_SKY_BOTTOM,
     };
     const dusk = {
         t: 0.75,
@@ -100,6 +106,7 @@ function buildKeyframes(config) {
         ambientIntensity: DUSK_AMBIENT_INTENSITY,
         skyTop: DUSK_SKY_TOP,
         skyBottom: DUSK_SKY_BOTTOM,
+        fog: DUSK_SKY_BOTTOM,
     };
     const midnight = { ...night, t: 1 };
     return [night, dawn, day, dusk, midnight];
@@ -122,10 +129,11 @@ function segmentAt(wrapped, keyframes) {
 }
 /**
  * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
- * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
- * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
-  * @internal
-  */
+ * lerping sun position/intensity, ambient intensity, sky and fog colors through a dawn/day/dusk/night
+ * keyframe table, and deriving sun tint, moonlight and star visibility from the sun's elevation.
+ * `config` overrides the noon (peak-day) colors and intensities only.
+ * @internal
+ */
 export function daylightStateAt(dayFraction, config = {}) {
     const wrapped = wrapFraction(dayFraction);
     const keyframes = buildKeyframes(config);
@@ -134,8 +142,31 @@ export function daylightStateAt(dayFraction, config = {}) {
     const ambientIntensity = lerp(from.ambientIntensity, to.ambientIntensity, localT);
     const skyTop = lerpHexColor(from.skyTop, to.skyTop, localT);
     const skyBottom = lerpHexColor(from.skyBottom, to.skyBottom, localT);
+    const fogColor = lerpHexColor(from.fog, to.fog, localT);
     const sunPosition = sunPositionAt(wrapped, config.sun);
-    return { sunPosition, sunIntensity, ambientIntensity, skyTop, skyBottom, background: skyBottom };
+    const moonPosition = sunPositionAt(wrapped + 0.5, config.sun);
+    const sunColor = mixHex(config.sunColor ?? DEFAULT_SUN_COLOR, sunlightColor(elevationOf(sunPosition)), lowSunWeight(wrapped));
+    return {
+        sunPosition,
+        sunIntensity,
+        sunColor,
+        ambientIntensity,
+        skyTop,
+        skyBottom,
+        background: skyBottom,
+        fogColor,
+        moonPosition,
+        moonIntensity: moonIllumination(elevationOf(moonPosition), config.moonIntensity) * (config.sunIntensity ?? DEFAULT_DAY_SUN_INTENSITY),
+        moonColor: config.moonColor ?? MOONLIGHT_COLOR,
+        starOpacity: starOpacity(elevationOf(sunPosition)),
+    };
+}
+function mixHex(from, to, t) {
+    return t <= 0 ? from : t >= 1 ? to : lerpHexColor(from, to, t);
+}
+/** How much of the sun's colour comes from the atmosphere rather than the authored tint: 0 with the sun high, 1 once it is on the horizon. */
+function lowSunWeight(wrapped) {
+    return Math.min(1, Math.abs(wrapped - 0.5) / 0.25);
 }
 /**
  * Sun position for a wrapped day fraction. Without `sun`, the legacy arc: east at dawn, ~68 degrees

package/dist/postfx/PostProcessing.d.ts

@@ -5,6 +5,12 @@ interface BuiltGraph {
     composer: EffectComposer;
     grade: ShaderPass | null;
 }
+/**
+ * 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 declare function quantizeExposure(value: number): number;
 /** Release each pass and the composer's owned targets. @internal */
 export declare function disposeGraph(built: BuiltGraph): void;
 /** Resize the composer and its passes at the renderer's pixel ratio. @internal */
@@ -14,7 +20,7 @@ export declare function resolveAoStage(ao: PostProcessingConfig["ao"], tierAllow
 /**
  * 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

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;
+}