@jgengine/shell 0.18.0 → 0.19.0

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";
@@ -17,9 +19,10 @@ import { devtools } from "@jgengine/core/devtools/devtools";
 import { collisionDebug } from "../devtools/collisionDebug.js";
 import { GAME_SIM_FRAME_PRIORITY } from "../camera/index.js";
 import { NO_ACTIONS } from "../shellConstants.js";
+import { createPredictionBuffer } from "@jgengine/core/runtime/prediction";
 const TURN_SPEED = 2.4;
 export const POSTER_SETTLE_SECONDS = 1.6;
-export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }) {
+export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, authoritativeFrameRef, }) {
     const posterElapsedRef = useRef(0);
     const posterDoneRef = useRef(false);
     const hasReportedTickError = useRef(false);
@@ -56,7 +59,26 @@ 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,
+        step: (state) => state,
+        snapThreshold: 0.1,
+    }));
+    const predictionHandler = useMemo(() => (_revision) => {
+        const playerId = ctx.player.possession.active(ctx.player.userId);
+        const player = ctx.scene.entity.get(playerId);
+        if (player === null)
+            return;
+        const prediction = predictionRef.current;
+        const current = player.position;
+        const snapshot = prediction.snapshot();
+        const tick = snapshot.records.at(-1)?.tick ?? snapshot.confirmedTick;
+        const result = prediction.reconcile(tick, current);
+        if (result.snapped)
+            ctx.scene.entity.setPose(playerId, { position: current });
+    }, [ctx]);
+    authoritativeFrameRef.current = serverAuthoritative ? predictionHandler : null;
     useFrame((_state, rawDt) => {
         if (poster) {
             if (posterDoneRef.current)
@@ -71,7 +93,12 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
         const sendInput = () => {
             if (!serverAuthoritative)
                 return;
-            const frame = { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() };
+            const frame = {
+                held: ctx.input.held(),
+                pointer: ctx.input.pointer(),
+                analog: ctx.input.analog(),
+                tick: ctx.sim.tick(),
+            };
             const last = lastSentInputRef.current;
             if (last !== null && inputFramesEqual(last, frame))
                 return;
@@ -88,8 +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);
-            const gameDt = ctx.time.advance(dt);
-            ctx.input.publish(heldActionsFor(tracker, inputActions));
+            ctx.input.publish(heldActionsFor(tracker, tracker.actions()));
             ctx.input.publishPointer(pointerAxisRef.current);
             ctx.input.publishAnalog(analogRef.current);
             sendInput();
@@ -98,28 +124,50 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
                 yawRef.current = steerYaw(yawRef.current, turnInput, TURN_SPEED, dt);
             endPhase();
             const playerId = ctx.player.possession.active(ctx.player.userId);
-            const player = ctx.scene.entity.get(playerId);
-            if (player !== null && drivesPose && !serverAuthoritative) {
-                endPhase = devtools.profile.begin("pose");
-                stepPlayerMovement(ctx, ctx.player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() }, rawDt, movementTuning, yawRef.current);
-                endPhase();
-            }
-            if (autoPickupRadius !== null && !serverAuthoritative) {
-                endPhase = devtools.profile.begin("pickup");
-                const self = ctx.scene.entity.get(playerId);
-                if (self !== null) {
-                    const nearest = ctx.scene.worldItem.nearestInRadius(self.position, autoPickupRadius);
-                    if (nearest !== null)
-                        ctx.scene.worldItem.pickup(nearest, ctx.player.userId);
+            ctx.sim.advance(dt, (stepDt) => {
+                const gameDt = ctx.time.advance(stepDt);
+                ctx.sim.runStages("beforeMovement", stepDt);
+                const player = ctx.scene.entity.get(playerId);
+                // Server-authoritative sessions still run the deterministic local step as a prediction; the
+                // replicated pose is the confirmation that the transport reconciles on the next world diff.
+                if (player !== null && drivesPose) {
+                    const endPose = devtools.profile.begin("pose");
+                    stepPlayerMovement(ctx, ctx.player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() }, stepDt, movementTuning, yawRef.current, pitchRef.current);
+                    const predicted = ctx.scene.entity.get(playerId);
+                    if (predicted !== null) {
+                        predictionRef.current.record({ held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog(), tick: ctx.sim.tick() }, stepDt, predicted.position);
+                    }
+                    endPose();
                 }
-                endPhase();
-            }
-            if (!serverAuthoritative) {
-                devtools.profile.measure("onTick", () => {
-                    playable.loop.onTick(ctx, gameDt);
-                });
-                advanceBehaviors(ctx, gameDt);
-            }
+                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");
+                    const self = ctx.scene.entity.get(playerId);
+                    if (self !== null) {
+                        const nearest = ctx.scene.worldItem.nearestInRadius(self.position, autoPickupRadius);
+                        if (nearest !== null)
+                            ctx.scene.worldItem.pickup(nearest, ctx.player.userId);
+                    }
+                    endPickup();
+                }
+                if (!serverAuthoritative) {
+                    devtools.profile.measure("onTick", () => {
+                        playable.loop.onTick(ctx, gameDt);
+                    });
+                    advanceBehaviors(ctx, gameDt);
+                }
+                ctx.sim.runStages("afterTick", stepDt);
+            });
             endPhase = devtools.profile.begin("actions");
             if (tracker.wasPressed("tabTarget")) {
                 if (ctx.game.commands.has("target.cycle"))

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,14 +26,19 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
             try {
                 let endPhase = devtools.profile.begin("time+input");
                 const dt = Math.min(rawDt, 0.05);
-                const gameDt = ctx.time.advance(dt);
-                ctx.input.publish(heldActionsFor(tracker, inputActions));
+                ctx.input.publish(heldActionsFor(tracker, tracker.actions()));
                 ctx.input.publishPointer(pointerAxisRef.current);
                 endPhase();
-                devtools.profile.measure("onTick", () => {
-                    playable.loop.onTick(ctx, gameDt);
+                ctx.sim.advance(dt, (stepDt) => {
+                    const gameDt = ctx.time.advance(stepDt);
+                    ctx.sim.runStages("beforeMovement", stepDt);
+                    ctx.sim.runStages("afterMovement", stepDt);
+                    devtools.profile.measure("onTick", () => {
+                        playable.loop.onTick(ctx, gameDt);
+                    });
+                    advanceBehaviors(ctx, gameDt);
+                    ctx.sim.runStages("afterTick", stepDt);
                 });
-                advanceBehaviors(ctx, gameDt);
                 endPhase = devtools.profile.begin("actions");
                 const nowMs = performance.now();
                 for (const action of inputActions) {

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/EnvironmentScene.js

@@ -85,7 +85,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, 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 (_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 }) }));
 }
 /** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
 function vegetationGroundColor(terrain, field, grass) {

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