@jgengine/shell 0.25.0 → 0.27.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/EnvironmentScene.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
 import { PresentationAssetBoundary } from "../presentationRecovery.js";
 import { PresentationRecoveredDraw, useRecoverableTexture } from "../presentationRecovery3d.js";
@@ -18,14 +18,16 @@ import { buildAuthoredRoadNetwork, RoadRibbons } from "./RoadRibbons.js";
 import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
+import { GrassCover } from "../terrain/GrassCover.js";
 import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
 import { createTerrainDetailMaterial } from "../terrain/terrainDetailMaterial.js";
+import { MAX_TERRAIN_LAYER_MAPS } from "../terrain/terrainDetailMaterial.js";
 import { useTerrainQuality } from "../terrain/terrainQuality.js";
 import { createTerrainPaintTextures, packTerrainPaintWeights } from "../terrain/terrainSurfaces.js";
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
-function TexturedTerrainGround({ detail, layout, }) {
+function TexturedTerrainGround({ detail, layout, layerMaps, }) {
     const maps = detail.material.maps;
     const textures = useRecoverableTexture({
         color: maps.color,
@@ -42,9 +44,44 @@ function TexturedTerrainGround({ detail, layout, }) {
         }
     }, [textures]);
     const quality = useTerrainQuality();
-    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures, { paint: layout.paint, quality }).material, [detail, textures, layout.paint, quality]);
+    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures, { paint: layout.paint, quality, ...(layerMaps === undefined ? {} : { layerMaps }) }).material, [detail, textures, layout.paint, quality, layerMaps]);
     return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
 }
+/** 1×1 white PNG: binds a valid sampler for a painted layer that has no scanned map. */
+const NO_LAYER_MAP = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+/**
+ * Scanned color maps for up to {@link MAX_TERRAIN_LAYER_MAPS} painted terrain layers, loaded through
+ * the shared recoverable texture path and tiled at each layer's own authored metres. The URL is
+ * authored data (`TerrainMaterialLayer.materialUrl`), resolved by the editor from a library name, so
+ * the renderer never reaches into the asset pipeline.
+ */
+function useTerrainLayerMaps(paint) {
+    const urls = useMemo(() => Array.from({ length: MAX_TERRAIN_LAYER_MAPS }, (_, index) => {
+        const url = paint?.slots[index + 1]?.materialUrl;
+        return url === undefined || url.length === 0 ? NO_LAYER_MAP : url;
+    }), [paint]);
+    const textures = useRecoverableTexture({ layer1: urls[0], layer2: urls[1], layer3: urls[2], layer4: urls[3] });
+    useEffect(() => {
+        for (const texture of Object.values(textures)) {
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.needsUpdate = true;
+        }
+    }, [textures]);
+    const slots = paint?.slots;
+    return useMemo(() => {
+        if (slots === undefined)
+            return undefined;
+        return Array.from({ length: MAX_TERRAIN_LAYER_MAPS }, (_, index) => {
+            const slot = slots[index + 1];
+            if (slot?.materialUrl === undefined)
+                return undefined;
+            const texture = textures[`layer${index + 1}`];
+            return texture === undefined ? undefined : { color: texture, tileMetres: slot.tileMetres };
+        });
+    }, [slots, textures]);
+}
 function TerrainGround({ terrain, field, center, sculpt, }) {
     const detailEnabled = terrain.detail !== false;
     const paint = useMemo(() => {
@@ -79,12 +116,13 @@ function TerrainGround({ terrain, field, center, sculpt, }) {
     }, [terrain.baseHeight, terrain.height]);
     const resolvedDetail = useMemo(() => (terrain.detail === false ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
     const quality = useTerrainQuality();
+    const layerMaps = useTerrainLayerMaps(paint);
     const proceduralMaterial = useMemo(() => resolvedDetail === undefined || resolvedDetail.material !== undefined
         ? undefined
-        : createTerrainDetailMaterial(resolvedDetail, undefined, { paint, quality }).material, [resolvedDetail, paint, quality]);
+        : createTerrainDetailMaterial(resolvedDetail, undefined, { paint, quality, ...(layerMaps === undefined ? {} : { layerMaps }) }).material, [resolvedDetail, paint, quality, layerMaps]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center } }) }));
+        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center }, ...(layerMaps === undefined ? {} : { layerMaps }) }) }));
     }
     return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, paintColorAt: paintColorAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
@@ -100,7 +138,7 @@ function Vegetation({ grass, field, groundColor, }) {
     const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
     const colorBase = grass.colors[0];
     const colorTip = grass.colors[grass.colors.length - 1];
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
+    return (_jsxs("group", { position: [cx, 0, cz], children: [_jsx(GrassCover, { area: area, seed: typeof grass.seed === "number" ? grass.seed : 1, colorBase: colorBase ?? "#3f7d2d", colorTip: colorTip ?? "#66a83f", strength: grass.groundCover ?? 0.9, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), heightAt: heightAt, coverageAt: () => 1 }), _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true })] }));
 }
 /** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
 function vegetationGroundColor(terrain, field, grass, sculpt) {
@@ -142,19 +180,24 @@ function DynamicWater({ ocean }) {
     const groupRef = useRef(null);
     const [x, z] = ocean.position ?? [0, 0];
     const config = useOceanConfig(ocean);
+    const depthAt = useCallback((lx, lz) => ocean.levelAt(ctx.time.now()) - ctx.world.ground.sampleHeight(x + lx, z + lz), [ctx.time.now, ctx.world.ground, ocean.levelAt, x, z]);
     useFrame(() => {
         if (groupRef.current !== null)
             groupRef.current.position.y = ocean.levelAt(ctx.time.now());
     });
-    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config }) }));
+    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config, depthAt: depthAt }) }));
 }
 function Water({ ocean }) {
+    const ctx = useGameContext();
     const [x, z] = ocean.position ?? [0, 0];
     const config = useOceanConfig(ocean);
+    // The ocean descriptor has no depth field: sample the live ground so the sheet shades
+    // shallow→deep and the shoreline foam band lands where the bed meets the surface.
+    const depthAt = useCallback((lx, lz) => ocean.level - ctx.world.ground.sampleHeight(x + lx, z + lz), [ctx.world.ground, ocean.level, x, z]);
     if (ocean.levelAt !== undefined) {
         return _jsx(DynamicWater, { ocean: ocean });
     }
-    return _jsx(Ocean, { position: [x, ocean.level, z], config: config });
+    return _jsx(Ocean, { position: [x, ocean.level, z], config: config, depthAt: depthAt });
 }
 function Structures({ structures, field }) {
     const placements = useMemo(() => resolveStructureBuildings(structures).map((building) => ({

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