@jgengine/shell 0.18.1 → 0.21.0

package/dist/environment/Daylight.d.ts

@@ -1,4 +1,4 @@
-import { type MutableRefObject } from "react";
+import { type MutableRefObject, type RefObject } from "react";
 import * as THREE from "three";
 import type { BiomeBand, SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
 import { type VolumetricCloudsConfig } from "@jgengine/core/world/volumetricClouds";
@@ -23,6 +23,40 @@ export interface SkyDomeProps {
     /** Exposes the created shader material so a time-of-day driver can mutate its uniforms per frame without recreating it. */
     materialRef?: MutableRefObject<THREE.ShaderMaterial | null>;
 }
+/**
+ * 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 declare function SunLight({ direction, directionRef, lightRef, intensity, color, }: {
+    direction: readonly [number, number, number];
+    directionRef?: MutableRefObject<readonly [number, number, number]>;
+    lightRef?: RefObject<THREE.DirectionalLight | null>;
+    intensity: number;
+    color: string;
+}): import("react").JSX.Element;
+/**
+ * Sets the zenith and horizon colors a sky dome should show on screen. The dome converts them each
+ * frame through the renderer's tone mapping ({@link DisplayColorWriter}), so a picked swatch renders
+ * as picked instead of greyed by the output curve.
+ * @internal
+ */
+export declare function setSkyDomeColors(material: THREE.ShaderMaterial, top: THREE.ColorRepresentation, bottom: THREE.ColorRepresentation): void;
+/**
+ * Scene fog whose color is a display color, converted through the renderer's tone mapping like the
+ * dome's horizon so fogged ground meets the sky without a seam. Drivers retint it with
+ * {@link setSkyFogColor}.
+ * @internal
+ */
+export declare function SkyFog({ color, near, far, fogRef }: {
+    color: string;
+    near: number;
+    far: number;
+    fogRef?: RefObject<THREE.Fog | null>;
+}): import("react").JSX.Element;
+/** Sets the display color a {@link SkyFog} converts each frame. @internal */
+export declare function setSkyFogColor(fog: THREE.Fog, color: THREE.ColorRepresentation): void;
 /** @internal */
 export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, hazeStrength, sunGlowStrength, cloudiness, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
 export interface DaylightProps {

package/dist/environment/Daylight.js

@@ -1,10 +1,13 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useFrame } from "@react-three/fiber";
-import { useEffect, useMemo, useRef } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { createBiomeFogSampler, createBiomeSkySampler } from "@jgengine/core/world/terrain";
 import { resolveVolumetricClouds } from "@jgengine/core/world/volumetricClouds";
+import { warnOnce } from "@jgengine/core/devtools/warnOnce";
+import { DisplayColorWriter } from "../render/displayColor.js";
 import { daylightStateAt, SKY_PRESET_DAY_FRACTION } from "./daylightCycle.js";
+import { SUN_SHADOW, sunLightPosition, sunShadowFocus } from "./sunShadowMath.js";
 import { VolumetricClouds } from "./VolumetricClouds.js";
 function normalizeVec3(v) {
     const out = new THREE.Vector3(v[0], v[1], v[2]);
@@ -17,29 +20,77 @@ const SUN_COLOR = "#fff1c9";
 const HEMI_SKY = "#bfe3ff";
 const HEMI_GROUND = "#4c6b34";
 /**
- * Sun directional light whose high-resolution shadow camera follows the view each
- * frame, so grounded shadows stay crisp under the player anywhere in a large world
- * instead of only near the origin.
+ * 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
  */
-function ShadowCastingSun({ position, intensity, color, }) {
-    const ref = useRef(null);
+export function SunLight({ direction, directionRef, lightRef, intensity, color, }) {
+    const ownRef = useRef(null);
+    const ref = lightRef ?? ownRef;
+    const scratch = useMemo(() => ({ forward: new THREE.Vector3(), focus: { x: 0, z: 0 }, position: [0, 0, 0] }), []);
     useFrame((state) => {
         const light = ref.current;
         if (light === null)
             return;
-        const cx = state.camera.position.x;
-        const cz = state.camera.position.z;
-        light.position.set(cx + position[0], position[1], cz + position[2]);
-        light.target.position.set(cx, 0, cz);
+        state.camera.getWorldDirection(scratch.forward);
+        const focus = sunShadowFocus(state.camera.position, scratch.forward, scratch.focus);
+        const [x, y, z] = sunLightPosition(focus, directionRef?.current ?? direction, scratch.position);
+        light.position.set(x, y, z);
+        light.target.position.set(focus.x, 0, focus.z);
         light.target.updateMatrixWorld();
     });
-    return (_jsx("directionalLight", { ref: ref, position: [position[0], position[1], position[2]], intensity: intensity, color: color, castShadow: true, "shadow-mapSize-width": 2048, "shadow-mapSize-height": 2048, "shadow-camera-left": -90, "shadow-camera-right": 90, "shadow-camera-top": 90, "shadow-camera-bottom": -90, "shadow-camera-near": 10, "shadow-camera-far": 520, "shadow-bias": -0.0004, "shadow-normalBias": 0.02 }));
+    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 }));
+}
+/**
+ * Sets the zenith and horizon colors a sky dome should show on screen. The dome converts them each
+ * frame through the renderer's tone mapping ({@link DisplayColorWriter}), so a picked swatch renders
+ * as picked instead of greyed by the output curve.
+ * @internal
+ */
+export function setSkyDomeColors(material, top, bottom) {
+    const display = material.userData;
+    (display.top ??= new THREE.Color()).set(top);
+    (display.bottom ??= new THREE.Color()).set(bottom);
+}
+/**
+ * Scene fog whose color is a display color, converted through the renderer's tone mapping like the
+ * dome's horizon so fogged ground meets the sky without a seam. Drivers retint it with
+ * {@link setSkyFogColor}.
+ * @internal
+ */
+export function SkyFog({ color, near, far, fogRef }) {
+    const ownRef = useRef(null);
+    const ref = fogRef ?? ownRef;
+    const writer = useMemo(() => new DisplayColorWriter(), []);
+    useLayoutEffect(() => {
+        if (ref.current !== null)
+            setSkyFogColor(ref.current, color);
+    }, [ref, color]);
+    useFrame((state) => {
+        const fog = ref.current;
+        const display = fog === null ? undefined : fogDisplayColors.get(fog);
+        if (fog === null || display === undefined)
+            return;
+        writer.write(fog.color, display, state.gl);
+    });
+    return _jsx("fog", { attach: "fog", ref: ref, args: [color, near, far] });
 }
+/** Sets the display color a {@link SkyFog} converts each frame. @internal */
+export function setSkyFogColor(fog, color) {
+    const display = fogDisplayColors.get(fog);
+    if (display === undefined)
+        fogDisplayColors.set(fog, new THREE.Color(color));
+    else
+        display.set(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, } = {}) {
     const meshRef = useRef(null);
     const material = useMemo(() => {
-        return new THREE.ShaderMaterial({
+        const dome = new THREE.ShaderMaterial({
             uniforms: {
                 topColor: { value: new THREE.Color(topColor) },
                 bottomColor: { value: new THREE.Color(horizonColor) },
@@ -93,12 +144,16 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
           float glow = pow(sd, 8.0) * 0.35 + pow(sd, 128.0) * 2.6;
           col += uSunColor * glow * uSunIntensity * uSunGlow;
           gl_FragColor = vec4(col, 1.0);
+          #include <tonemapping_fragment>
+          #include <colorspace_fragment>
         }
       `,
             side: THREE.BackSide,
             depthWrite: false,
             fog: false,
         });
+        setSkyDomeColors(dome, topColor, horizonColor);
+        return dome;
     }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity, hazeStrength, sunGlowStrength, cloudiness]);
     useEffect(() => {
         if (materialRef !== undefined)
@@ -109,7 +164,18 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                 materialRef.current = null;
         };
     }, [material, materialRef]);
+    const camera = useThree((state) => state.camera);
+    const writers = useMemo(() => ({ top: new DisplayColorWriter(), bottom: new DisplayColorWriter() }), []);
+    useEffect(() => {
+        const far = camera.far;
+        if (typeof far !== "number" || radius < far)
+            return;
+        warnOnce("sky-dome-radius", `[jgengine] sky radius ${radius} is at or beyond the camera far plane ${far}; the dome depth-clips to black. Lower sky.radius or raise camera.frustum.far.`);
+    }, [camera, radius]);
     useFrame((state) => {
+        const display = material.userData;
+        writers.top.write(material.uniforms.topColor.value, display.top, state.gl);
+        writers.bottom.write(material.uniforms.bottomColor.value, display.bottom, state.gl);
         const mesh = meshRef.current;
         if (mesh === null)
             return;
@@ -118,10 +184,14 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
     });
     return (_jsx("mesh", { ref: meshRef, material: material, renderOrder: -1, frustumCulled: false, children: _jsx("sphereGeometry", { args: [radius, 32, 16] }) }));
 }
+/** Points the dome's sun glow at `position` and keeps the disc lit; called per frame by the time-of-day drivers. */
+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 } = {}) {
     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("fog", { attach: "fog", args: [fog?.color ?? FOG_COLOR, fog?.near ?? 70, fog?.far ?? 260] })), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx(ShadowCastingSun, { position: sunPosition, intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR })] })) : null] }));
+    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] }));
 }
 /** True when at least one band overrides fog or sky — the trigger for the per-frame biome driver. */
 function bandsDriveSkyOrFog(bands) {
@@ -172,6 +242,7 @@ function BiomeDaylight({ sky, bands, clock, lights, }) {
     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 hemiRef = useRef(null);
     const fogRef = useRef(null);
     const skyMaterialRef = useRef(null);
@@ -196,50 +267,49 @@ function BiomeDaylight({ sky, bands, clock, lights, }) {
         const skyValue = skySampler(z);
         const fogNode = fogRef.current;
         if (fogNode !== null) {
-            fogNode.color.set(fog.color);
+            setSkyFogColor(fogNode, fog.color);
             fogNode.near = fog.near;
             fogNode.far = fog.far;
         }
         const skyMaterial = skyMaterialRef.current;
         if (skyMaterial !== null) {
-            skyMaterial.uniforms.topColor.value.set(skyValue.zenithColor);
-            skyMaterial.uniforms.bottomColor.value.set(skyValue.horizonColor);
+            setSkyDomeColors(skyMaterial, skyValue.zenithColor, skyValue.horizonColor);
+            aimSkySun(skyMaterial, base.sunPosition);
         }
+        sunDirectionRef.current = base.sunPosition;
         const sun = sunRef.current;
-        if (sun !== null) {
-            sun.position.set(base.sunPosition[0], base.sunPosition[1], base.sunPosition[2]);
+        if (sun !== null)
             sun.intensity = skyValue.sunIntensity;
-        }
         const hemi = hemiRef.current;
         if (hemi !== null)
             hemi.intensity = skyValue.ambientIntensity;
     });
-    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, materialRef: skyMaterialRef, ...skyDomeShape(sky) }), sky.volumetricClouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(sky.volumetricClouds), sunDirection: initial.sunPosition })), _jsx("fog", { attach: "fog", ref: fogRef, args: [fogFallback.color, fogFallback.near, fogFallback.far] }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx("directionalLight", { ref: sunRef, position: initial.sunPosition, intensity: initial.sunIntensity, color: SUN_COLOR, castShadow: true })] })) : null] }));
+    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] }));
 }
 function DrivenDaylight({ sky, clock, lights, }) {
     const initial = useMemo(() => daylightStateAt(clock.calendar().dayFraction, sky), [clock, sky]);
     const sunRef = useRef(null);
+    const sunDirectionRef = useRef(initial.sunPosition);
     const hemiRef = useRef(null);
     const fogRef = useRef(null);
     const skyMaterialRef = useRef(null);
     useFrame(() => {
         const state = daylightStateAt(clock.calendar().dayFraction, sky);
+        sunDirectionRef.current = state.sunPosition;
         const sun = sunRef.current;
-        if (sun !== null) {
-            sun.position.set(state.sunPosition[0], state.sunPosition[1], state.sunPosition[2]);
+        if (sun !== null)
             sun.intensity = state.sunIntensity;
-        }
         const hemi = hemiRef.current;
         if (hemi !== null)
             hemi.intensity = state.ambientIntensity;
         const fog = fogRef.current;
         if (fog !== null)
-            fog.color.set(sky.fog?.color ?? state.background);
+            setSkyFogColor(fog, sky.fog?.color ?? state.background);
         const skyMaterial = skyMaterialRef.current;
         if (skyMaterial !== null) {
-            skyMaterial.uniforms.topColor.value.set(state.skyTop);
-            skyMaterial.uniforms.bottomColor.value.set(state.skyBottom);
+            setSkyDomeColors(skyMaterial, state.skyTop, state.skyBottom);
+            aimSkySun(skyMaterial, state.sunPosition);
         }
     });
-    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, materialRef: skyMaterialRef, ...skyDomeShape(sky) }), sky.volumetricClouds === undefined ? null : (_jsx(VolumetricClouds, { rules: resolveVolumetricClouds(sky.volumetricClouds), sunDirection: initial.sunPosition })), _jsx("fog", { attach: "fog", ref: fogRef, args: [sky.fog?.color ?? initial.background, sky.fog?.near ?? 70, sky.fog?.far ?? 260] }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx("directionalLight", { ref: sunRef, position: initial.sunPosition, intensity: initial.sunIntensity, color: SUN_COLOR, castShadow: true })] })) : null] }));
+    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] }));
 }

package/dist/environment/EnvironmentScene.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
-import { useTexture } from "@react-three/drei";
+import { PresentationAssetBoundary } from "../presentationRecovery.js";
+import { PresentationRecoveredDraw, useRecoverableTexture } from "../presentationRecovery3d.js";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
@@ -20,14 +21,13 @@ import { createTerrainDetailMaterial } from "../terrain/terrainDetailMaterial.js
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
-import { WeatherUniformProvider } from "../weather/weatherUniforms.js";
 function TexturedTerrainGround({ detail, layout, }) {
     const maps = detail.material.maps;
-    const textures = useTexture({
+    const textures = useRecoverableTexture({
         color: maps.color,
         normal: maps.normal,
-        roughness: maps.roughness,
-        ao: maps.ao,
+        ...(maps.roughness !== undefined ? { roughness: maps.roughness } : {}),
+        ...(maps.ao !== undefined ? { ao: maps.ao } : {}),
     });
     useEffect(() => {
         textures.color.colorSpace = THREE.SRGBColorSpace;
@@ -38,7 +38,7 @@ function TexturedTerrainGround({ detail, layout, }) {
         }
     }, [textures]);
     const material = useDisposable(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
-    return (_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 }));
+    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 })] }));
 }
 function TerrainGround({ terrain, field, center, }) {
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
@@ -69,7 +69,7 @@ function TerrainGround({ terrain, field, center, }) {
         : createTerrainDetailMaterial(resolvedDetail).material, [resolvedDetail]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, center } }));
+        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, center } }) }));
     }
     return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
@@ -99,14 +99,15 @@ function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
 }
 function Precipitation({ weather }) {
+    const ctx = useGameContext();
     const [cx, cz] = areaCenter(weather.area);
     if (weather.kind === "rain") {
-        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, width: weather.width, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { timeSeconds: ctx.time.now, density: weather.density, speed: weather.speed, length: weather.dropLength, width: weather.width, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
     }
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { timeSeconds: ctx.time.now, density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
 }
 function Weather({ weather }) {
-    return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
+    return (_jsx(_Fragment, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
 }
 function oceanConfig(ocean) {
     return {

package/dist/environment/VolumetricClouds.js

@@ -7,7 +7,8 @@ import { useDisposable } from "../render/useDisposable.js";
  * Camera-centered proxy dome radius. Must sit inside the default camera far plane
  * (`CAMERA_FRUSTUM_DEFAULTS.far` = 300) — a bigger sphere is clipped whole and renders nothing. The
  * raymarch works in world space against the absolute cloud slab, so this size only has to cover the
- * screen (camera is always at the dome center), never bound the clouds.
+ * screen (camera is always at the dome center), never bound the clouds; each fragment writes its own
+ * depth at the first cloud hit, so the dome's radius never decides what occludes the clouds.
  */
 const INSIDE_FRUSTUM_DOME_RADIUS = 240;
 function hashSeed(text) {
@@ -43,8 +44,18 @@ uniform float uScale;
 uniform float uSpeed;
 uniform float uTime;
 uniform float uSeedOffset;
+uniform mat4 uProjection;
+uniform mat4 uView;
 varying vec3 vJgCloudWorldPos;
 
+// Depth-buffer value of a world point, so the proxy dome tests against the scene at the cloud's
+// own distance instead of the dome's: a tower in front of the slab entry then occludes the cloud.
+float jgCloudDepthAt(vec3 worldPos){
+  vec4 clip = uProjection * uView * vec4(worldPos, 1.0);
+  float ndc = clip.z / max(clip.w, 1e-5);
+  return clamp(ndc * 0.5 + 0.5, 0.0, 0.999999);
+}
+
 float jgCloudHash13(vec3 p){
   p = fract(p * 0.1031 + uSeedOffset * 0.0007);
   p += dot(p, p.yzx + 33.33);
@@ -128,11 +139,13 @@ void main() {
   vec3 color = vec3(0.0);
   float sunDot = max(dot(rayDir, normalize(uSunDirection)), 0.0);
   float silver = pow(sunDot, 5.0) * uSunScatter;
+  float tHit = -1.0;
 
   for (int i = 0; i < STEPS; i++) {
     vec3 pos = rayOrigin + rayDir * t;
     float dens = jgCloudDensity(pos);
     if (dens > 0.002) {
+      if (tHit < 0.0) tHit = t;
       float light = jgCloudLight(pos);
       float powder = 1.0 - exp(-dens * 3.0);
       vec3 lit = mix(uColor, uSunColor, light) * (0.55 + 0.45 * powder) + uSunColor * silver * 0.5;
@@ -146,7 +159,8 @@ void main() {
   }
 
   float alpha = (1.0 - transmittance) * smoothstep(0.015, 0.22, rayDir.y);
-  if (alpha < 0.01) discard;
+  if (alpha < 0.01 || tHit < 0.0) discard;
+  gl_FragDepthEXT = jgCloudDepthAt(rayOrigin + rayDir * tHit);
   gl_FragColor = vec4(color, alpha);
 }
 `;
@@ -178,6 +192,8 @@ export function VolumetricClouds({ rules, sunDirection }) {
                 uSpeed: { value: rules.speed },
                 uTime: { value: 0 },
                 uSeedOffset: { value: hashSeed(rules.seed) },
+                uProjection: { value: new THREE.Matrix4() },
+                uView: { value: new THREE.Matrix4() },
             },
             vertexShader: CLOUD_VERTEX_SHADER,
             fragmentShader: CLOUD_FRAGMENT_SHADER,
@@ -196,6 +212,8 @@ export function VolumetricClouds({ rules, sunDirection }) {
         }
         const uniforms = material.uniforms;
         uniforms.uCameraPos.value.copy(state.camera.position);
+        uniforms.uProjection.value.copy(state.camera.projectionMatrix);
+        uniforms.uView.value.copy(state.camera.matrixWorldInverse);
         uniforms.uTime.value = timeRef.current;
     });
     return (_jsx("mesh", { ref: meshRef, material: material, renderOrder: -0.5, frustumCulled: false, children: _jsx("sphereGeometry", { args: [INSIDE_FRUSTUM_DOME_RADIUS, 32, 16] }) }));

package/dist/environment/daylightCycle.d.ts

@@ -1,8 +1,11 @@
+import type { SkySunConfig } from "@jgengine/core/world/features";
 export interface DaylightCycleConfig {
     horizonColor?: string;
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
+    /** Fixed sun placement, or the noon placement the day arc swings around. Unset keeps the engine arc. */
+    sun?: SkySunConfig;
 }
 export interface DaylightState {
     sunPosition: [number, number, number];
@@ -16,6 +19,23 @@ 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";
+/** The engine arc's noon height: `atan(1 / SUN_DEPTH_RATIO)`, ~68 degrees. */
+export declare const DEFAULT_SUN_ELEVATION_DEG: number;
+/**
+ * Unit direction toward a sun at compass `azimuth` (0 = -Z, 90 = +X) and `elevation` above the
+ * horizon, both in degrees. Shared by the dome glow, the sky-owned sun light, and the editor.
+ * @internal
+ */
+export declare function sunDirectionFromBearing(azimuth: number, elevation: number): [number, number, number];
+/**
+ * Inverse of {@link sunDirectionFromBearing}: the bearing/elevation (degrees) of a world-space
+ * direction such as an authored directional light's position. A zero vector reads as overhead.
+ * @internal
+ */
+export declare function bearingFromDirection(direction: readonly [number, number, number]): {
+    azimuth: number;
+    elevation: number;
+};
 export declare const SKY_PRESET_DAY_FRACTION: Record<"day" | "dusk" | "night", number>;
 /** @internal */
 export declare function lerpHexColor(a: string, b: string, t: number): string;

package/dist/environment/daylightCycle.js

@@ -16,6 +16,34 @@ export const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
 export const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
 const SUN_DISTANCE = 200;
 const SUN_DEPTH_RATIO = 0.4;
+const DEG = Math.PI / 180;
+/** The engine arc's noon height: `atan(1 / SUN_DEPTH_RATIO)`, ~68 degrees. */
+export const DEFAULT_SUN_ELEVATION_DEG = Math.atan2(1, SUN_DEPTH_RATIO) / DEG;
+/**
+ * Unit direction toward a sun at compass `azimuth` (0 = -Z, 90 = +X) and `elevation` above the
+ * horizon, both in degrees. Shared by the dome glow, the sky-owned sun light, and the editor.
+ * @internal
+ */
+export function sunDirectionFromBearing(azimuth, elevation) {
+    const az = azimuth * DEG;
+    const el = elevation * DEG;
+    const flat = Math.cos(el);
+    return [Math.sin(az) * flat, Math.sin(el), -Math.cos(az) * flat];
+}
+/**
+ * Inverse of {@link sunDirectionFromBearing}: the bearing/elevation (degrees) of a world-space
+ * direction such as an authored directional light's position. A zero vector reads as overhead.
+ * @internal
+ */
+export function bearingFromDirection(direction) {
+    const [x, y, z] = direction;
+    const length = Math.hypot(x, y, z);
+    if (length === 0)
+        return { azimuth: 0, elevation: 90 };
+    const azimuth = ((Math.atan2(x, -z) / DEG) + 360) % 360;
+    const elevation = Math.asin(Math.max(-1, Math.min(1, y / length))) / DEG;
+    return { azimuth, elevation };
+}
 export const SKY_PRESET_DAY_FRACTION = {
     night: 0,
     day: 0.5,
@@ -106,13 +134,37 @@ 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 sunPosition = sunPositionAt(wrapped, config.sun);
+    return { sunPosition, sunIntensity, ambientIntensity, skyTop, skyBottom, background: skyBottom };
+}
+/**
+ * Sun position for a wrapped day fraction. Without `sun`, the legacy arc: east at dawn, ~68 degrees
+ * up at noon, west at dusk, tilted 0.4 toward +Z. With `sun`, the arc is rotated so noon lands
+ * exactly on the authored bearing and elevation and the sun still rises 90 degrees before it and
+ * sets 90 degrees after it, so a fixed preset (noon, dusk, night fractions) samples the same arc.
+ */
+function sunPositionAt(wrapped, sun) {
     const angle = (wrapped - 0.25) * 2 * Math.PI;
-    const elevation = Math.sin(angle);
-    const azimuth = Math.cos(angle);
-    const sunPosition = [
-        azimuth * SUN_DISTANCE,
-        elevation * SUN_DISTANCE,
-        SUN_DISTANCE * SUN_DEPTH_RATIO,
+    const along = Math.cos(angle);
+    const up = Math.sin(angle);
+    if (sun === undefined) {
+        return [along * SUN_DISTANCE, up * SUN_DISTANCE, SUN_DISTANCE * SUN_DEPTH_RATIO];
+    }
+    const noon = sunDirectionFromBearing(sun.azimuth ?? 0, sun.elevation ?? DEFAULT_SUN_ELEVATION_DEG);
+    const horizon = normalize([noon[0], 0, noon[2]], [0, 0, -1]);
+    const east = [-horizon[2], 0, horizon[0]];
+    const zenith = normalize(cross(east, noon), [0, 1, 0]);
+    const rise = normalize(cross(noon, zenith), east);
+    return [
+        (rise[0] * along + noon[0] * up) * SUN_DISTANCE,
+        (rise[1] * along + noon[1] * up) * SUN_DISTANCE,
+        (rise[2] * along + noon[2] * up) * SUN_DISTANCE,
     ];
-    return { sunPosition, sunIntensity, ambientIntensity, skyTop, skyBottom, background: skyBottom };
+}
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function normalize(v, fallback) {
+    const length = Math.hypot(v[0], v[1], v[2]);
+    return length < 1e-6 ? [fallback[0], fallback[1], fallback[2]] : [v[0] / length, v[1] / length, v[2] / length];
 }

package/dist/environment/sunShadowMath.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One shadow map for an outdoor sun: 2048 texels over a 70 m box that leads the camera, so the
+ * ground the player looks at gets ~3.4 cm texels and a PCF radius wide enough to hide the
+ * stair-step. A 180 m box centered on the camera wasted half its texels behind the view.
+ * @internal
+ */
+export declare const SUN_SHADOW: {
+    readonly mapSize: 2048;
+    readonly halfExtent: 35;
+    readonly lead: 22;
+    readonly radius: 6;
+    readonly distance: 220;
+    readonly near: 10;
+    readonly far: 520;
+    readonly bias: -0.0004;
+    readonly normalBias: 0.02;
+};
+/**
+ * Where the sun's shadow box centers this frame: `lead` meters ahead of the camera along its
+ * horizontal view, snapped to whole shadow texels so edges hold still while the camera moves.
+ * Looking straight down (no horizontal view) centers on the camera.
+ * @internal
+ */
+export declare function sunShadowFocus(camera: {
+    x: number;
+    z: number;
+}, forward: {
+    x: number;
+    z: number;
+}, out?: {
+    x: number;
+    z: number;
+}): {
+    x: number;
+    z: number;
+};
+/**
+ * The sun light's world position for a focus point: `distance` meters back along the sun
+ * direction, so near/far cover the box whatever magnitude the sky's sun vector carries.
+ * @internal
+ */
+export declare function sunLightPosition(focus: {
+    x: number;
+    z: number;
+}, sun: readonly [number, number, number], out?: [number, number, number]): [number, number, number];

package/dist/environment/sunShadowMath.js

@@ -0,0 +1,50 @@
+/**
+ * One shadow map for an outdoor sun: 2048 texels over a 70 m box that leads the camera, so the
+ * ground the player looks at gets ~3.4 cm texels and a PCF radius wide enough to hide the
+ * stair-step. A 180 m box centered on the camera wasted half its texels behind the view.
+ * @internal
+ */
+export const SUN_SHADOW = {
+    mapSize: 2048,
+    halfExtent: 35,
+    lead: 22,
+    radius: 6,
+    distance: 220,
+    near: 10,
+    far: 520,
+    bias: -0.0004,
+    normalBias: 0.02,
+};
+/**
+ * Where the sun's shadow box centers this frame: `lead` meters ahead of the camera along its
+ * horizontal view, snapped to whole shadow texels so edges hold still while the camera moves.
+ * Looking straight down (no horizontal view) centers on the camera.
+ * @internal
+ */
+export function sunShadowFocus(camera, forward, out = { x: 0, z: 0 }) {
+    const length = Math.hypot(forward.x, forward.z);
+    const lead = length < 1e-6 ? 0 : SUN_SHADOW.lead / length;
+    const texel = (SUN_SHADOW.halfExtent * 2) / SUN_SHADOW.mapSize;
+    out.x = Math.round((camera.x + forward.x * lead) / texel) * texel;
+    out.z = Math.round((camera.z + forward.z * lead) / texel) * texel;
+    return out;
+}
+/**
+ * The sun light's world position for a focus point: `distance` meters back along the sun
+ * direction, so near/far cover the box whatever magnitude the sky's sun vector carries.
+ * @internal
+ */
+export function sunLightPosition(focus, sun, out = [0, 0, 0]) {
+    const length = Math.hypot(sun[0], sun[1], sun[2]);
+    if (length < 1e-6) {
+        out[0] = focus.x;
+        out[1] = SUN_SHADOW.distance;
+        out[2] = focus.z;
+        return out;
+    }
+    const scale = SUN_SHADOW.distance / length;
+    out[0] = focus.x + sun[0] * scale;
+    out[1] = sun[1] * scale;
+    out[2] = focus.z + sun[2] * scale;
+    return out;
+}