@jgengine/shell 0.18.1 → 0.19.0

package/dist/diagnostics/FpsCounter.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+/** Counts rendered frames. Mount inside the Canvas. @internal */
+export function FpsProbe({ tally }) {
+    useFrame(() => {
+        tally.frames += 1;
+    });
+    return null;
+}
+/**
+ * Player-facing frames-per-second readout, sampled twice a second from rendered frames (not
+ * display refreshes), so it reflects the frame-rate limit and GPU load.
+ * @internal shell-internal; shown by the `graphics.showFps` setting.
+ */
+export function FpsCounter({ tally }) {
+    const label = useRef(null);
+    useEffect(() => {
+        let last = performance.now();
+        tally.frames = 0;
+        const timer = setInterval(() => {
+            const now = performance.now();
+            const fps = (tally.frames * 1000) / Math.max(1, now - last);
+            tally.frames = 0;
+            last = now;
+            if (label.current !== null)
+                label.current.textContent = `${fps < 10 ? fps.toFixed(1) : Math.round(fps)} FPS`;
+        }, 500);
+        return () => clearInterval(timer);
+    }, [tally]);
+    return (_jsx("div", { className: "pointer-events-none absolute bottom-1 right-1 z-50 rounded bg-black/60 px-2 py-0.5 font-mono text-xs tabular-nums text-emerald-300", children: _jsx("span", { ref: label, children: "-- FPS" }) }));
+}

package/dist/drivers/FrameDriver.js

@@ -6,6 +6,8 @@ import { pointerAimFor } from "../shellPointer.js";
 import { shellDrivesPlayerPose } from "../shellMovement.js";
 import { steerYaw } from "@jgengine/core/movement/steering";
 import { stepPlayerMovement, resolvePlayerMovementTuning } from "@jgengine/core/movement/playerMovement";
+import { localPlayers } from "@jgengine/core/runtime/localPlayers";
+import { seatCameraYaw } from "../camera/Viewports.js";
 import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
 import { resolveCommandSink } from "../commandSink.js";
 import { inputFramesEqual, resolveInputSink } from "../inputSink.js";
@@ -57,7 +59,6 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
         }).send(frame),
     }), [multiplayer, serverAuthoritative, serverIdRef]);
     const lastSentInputRef = useRef(null);
-    const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
     const predictionRef = useRef(createPredictionBuffer({
         initial: [0, 0, 0],
         maxTicks: 120,
@@ -114,7 +115,7 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
         try {
             let endPhase = devtools.profile.begin("time+input");
             const dt = Math.min(rawDt, 0.05);
-            ctx.input.publish(heldActionsFor(tracker, inputActions));
+            ctx.input.publish(heldActionsFor(tracker, tracker.actions()));
             ctx.input.publishPointer(pointerAxisRef.current);
             ctx.input.publishAnalog(analogRef.current);
             sendInput();
@@ -138,6 +139,16 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
                     }
                     endPose();
                 }
+                if (drivesPose && !serverAuthoritative) {
+                    const table = localPlayers(ctx);
+                    const seats = table.slots();
+                    for (let index = 1; index < seats.length; index += 1) {
+                        const seat = table.local(seats[index].slotId);
+                        if (seat === null)
+                            continue;
+                        stepPlayerMovement(ctx, seat.userId, { held: seat.input.held(), pointer: null, analog: seat.input.analog() }, stepDt, movementTuning, seatCameraYaw(ctx, seat.userId));
+                    }
+                }
                 ctx.sim.runStages("afterMovement", stepDt);
                 if (autoPickupRadius !== null && !serverAuthoritative) {
                     const endPickup = devtools.profile.begin("pickup");

package/dist/drivers/FrameRateLimiter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Drives the Canvas at a capped frame rate. Mount only with `frameloop="never"`: it runs its
+ * own requestAnimationFrame loop and advances R3F on the refreshes `paceFrame` admits, so
+ * simulation, useFrame and rendering all run at the cap with correct deltas.
+ * @internal shell-internal; driven by the player's frame-rate limit setting.
+ */
+export declare function FrameRateLimiter({ fps }: {
+    fps: number;
+}): null;

package/dist/drivers/FrameRateLimiter.js

@@ -0,0 +1,39 @@
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+import { paceFrame } from "@jgengine/core/settings/frameRateLimit";
+/**
+ * Drives the Canvas at a capped frame rate. Mount only with `frameloop="never"`: it runs its
+ * own requestAnimationFrame loop and advances R3F on the refreshes `paceFrame` admits, so
+ * simulation, useFrame and rendering all run at the cap with correct deltas.
+ * @internal shell-internal; driven by the player's frame-rate limit setting.
+ */
+export function FrameRateLimiter({ fps }) {
+    const advance = useThree((state) => state.advance);
+    const get = useThree((state) => state.get);
+    useEffect(() => {
+        if (fps <= 0)
+            return;
+        // R3F's "never" mode reads the timestamp as seconds on its own clock; continue that clock.
+        const base = get().clock.elapsedTime;
+        let start = null;
+        let anchor = 0;
+        let frame = requestAnimationFrame(function tick(now) {
+            frame = requestAnimationFrame(tick);
+            if (start === null) {
+                start = now;
+                anchor = now;
+            }
+            const next = paceFrame(now, anchor, fps);
+            if (next === null)
+                return;
+            anchor = next;
+            advance(base + (now - start) / 1000, true);
+        });
+        return () => {
+            cancelAnimationFrame(frame);
+            // Hand the clock back to R3F's own loop in milliseconds so its next delta is one frame.
+            get().clock.oldTime = performance.now();
+        };
+    }, [fps, advance, get]);
+    return null;
+}

package/dist/drivers/HudOnlyDriver.js

@@ -26,7 +26,7 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
             try {
                 let endPhase = devtools.profile.begin("time+input");
                 const dt = Math.min(rawDt, 0.05);
-                ctx.input.publish(heldActionsFor(tracker, inputActions));
+                ctx.input.publish(heldActionsFor(tracker, tracker.actions()));
                 ctx.input.publishPointer(pointerAxisRef.current);
                 endPhase();
                 ctx.sim.advance(dt, (stepDt) => {

package/dist/environment/DayNightSky.js

@@ -2,7 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useFrame } from "@react-three/fiber";
 import { useMemo, useRef } from "react";
 import * as THREE from "three";
-import { SkyDome } from "./Daylight.js";
+import { setSkyDomeColors, SkyDome, SunLight } from "./Daylight.js";
 import { daylightStateAt } from "./daylightCycle.js";
 const HEMI_GROUND = "#4c6b34";
 /**
@@ -22,22 +22,22 @@ export function DayNightSky({ cycle, radius, hazeStrength, sunGlowStrength, ligh
     const hemiRef = useRef(null);
     const initial = useMemo(() => cycle.sample(), [cycle]);
     const initialSun = useMemo(() => daylightStateAt(initial.dayFraction).sunPosition, [initial.dayFraction]);
+    const sunDirectionRef = useRef(initialSun);
     useFrame(() => {
         const sample = cycle.sample();
         const geometry = daylightStateAt(sample.dayFraction);
         const material = skyMaterialRef.current;
         if (material !== null) {
-            material.uniforms.topColor.value.set(sample.lightColor);
-            material.uniforms.bottomColor.value.set(sample.color);
+            setSkyDomeColors(material, sample.lightColor, sample.color);
             material.uniforms.uSunColor.value.set(sample.lightColor);
             material.uniforms.uSunDirection.value
                 .set(geometry.sunPosition[0], geometry.sunPosition[1], geometry.sunPosition[2])
                 .normalize();
             material.uniforms.uSunIntensity.value = sample.intensity;
         }
+        sunDirectionRef.current = geometry.sunPosition;
         const sun = sunRef.current;
         if (sun !== null) {
-            sun.position.set(geometry.sunPosition[0], geometry.sunPosition[1], geometry.sunPosition[2]);
             sun.intensity = sample.intensity * keyLightIntensity;
             sun.color.set(sample.lightColor);
         }
@@ -47,5 +47,5 @@ export function DayNightSky({ cycle, radius, hazeStrength, sunGlowStrength, ligh
             hemi.color.set(sample.lightColor);
         }
     });
-    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.lightColor, horizonColor: initial.color, sunDirection: initialSun, sunColor: initial.lightColor, sunIntensity: initial.intensity, materialRef: skyMaterialRef, ...(radius === undefined ? {} : { radius }), ...(hazeStrength === undefined ? {} : { hazeStrength }), ...(sunGlowStrength === undefined ? {} : { sunGlowStrength }) }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [initial.lightColor, HEMI_GROUND, initial.intensity * ambientIntensity] }), _jsx("directionalLight", { ref: sunRef, position: initialSun, intensity: initial.intensity * keyLightIntensity, color: initial.lightColor, 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 })] })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.lightColor, horizonColor: initial.color, sunDirection: initialSun, sunColor: initial.lightColor, sunIntensity: initial.intensity, materialRef: skyMaterialRef, ...(radius === undefined ? {} : { radius }), ...(hazeStrength === undefined ? {} : { hazeStrength }), ...(sunGlowStrength === undefined ? {} : { sunGlowStrength }) }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [initial.lightColor, HEMI_GROUND, initial.intensity * ambientIntensity] }), _jsx(SunLight, { direction: initialSun, directionRef: sunDirectionRef, lightRef: sunRef, intensity: initial.intensity * keyLightIntensity, color: initial.lightColor })] })) : null] }));
 }

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/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];
 }