@jgengine/shell 0.9.0 → 0.11.0

package/dist/drivers/FrameDriver.d.ts

@@ -0,0 +1,37 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { PointerService } from "../pointer/pointerService.js";
+import type { ShellMultiplayer } from "../multiplayer.js";
+import type { PlayableGame } from "../registry.js";
+export declare const POSTER_SETTLE_SECONDS = 1.6;
+export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }: {
+    ctx: GameContext;
+    playable: PlayableGame;
+    tracker: ActionStateTracker<string>;
+    yawRef: {
+        current: number;
+    };
+    pitchRef: {
+        current: number;
+    };
+    primaryClickRef: {
+        current: boolean;
+    };
+    pointerAxisRef: {
+        current: PointerAxisState | null;
+    };
+    gateRef: {
+        current: boolean;
+    };
+    onRuntimeError: (error: unknown, phase: string) => void;
+    multiplayer: ShellMultiplayer | null;
+    serverIdRef: {
+        current: string | null;
+    };
+    pointerService: PointerService;
+    pointerAim: boolean;
+    pingCommand: string | undefined;
+    poster: boolean;
+    onPosterSettled: () => void;
+}): null;

package/dist/drivers/FrameDriver.js

@@ -0,0 +1,232 @@
+import { useFrame } from "@react-three/fiber";
+import { useMemo, useRef } from "react";
+import { RESERVED_INPUT_ACTIONS, dispatchBoundAction, heldActionsFor, shouldFireBoundAction } from "../boundActionDispatch.js";
+import { executeHotbarSlot, findHotbarSlotActions, hotbarIdFor } from "../hotbarActions.js";
+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 { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { resolveCommandSink } from "../commandSink.js";
+import { inputFramesEqual, resolveInputSink } from "../inputSink.js";
+import { advanceBehaviors } from "@jgengine/core/scene/behaviorRuntime";
+import { resolveActivePrompt } from "@jgengine/core/interaction/proximityPrompt";
+import { DEFAULT_PICKUP_RADIUS } from "@jgengine/core/game/worldItem";
+import { playControlsActive } from "@jgengine/core/game/controlGate";
+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";
+const TURN_SPEED = 2.4;
+export const POSTER_SETTLE_SECONDS = 1.6;
+export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }) {
+    const posterElapsedRef = useRef(0);
+    const posterDoneRef = useRef(false);
+    const hasReportedTickError = useRef(false);
+    const repeatFiredAtRef = useRef(new Map());
+    const slotActions = useMemo(() => findHotbarSlotActions(playable.game.input), [playable]);
+    const hotbarId = useMemo(() => hotbarIdFor(playable), [playable]);
+    const movementTuning = useMemo(() => resolvePlayerMovementTuning({
+        collision: playable.collision,
+        movement: playable.movement,
+        physics: playable.game.physics,
+        world: playable.game.world,
+    }), [playable]);
+    const autoPickupRadius = useMemo(() => {
+        const cfg = playable.worldItem?.autoPickup;
+        if (cfg === undefined || cfg === false)
+            return null;
+        const fallback = playable.worldItem?.pickupRadius ?? DEFAULT_PICKUP_RADIUS;
+        return cfg === true ? fallback : cfg.radius ?? fallback;
+    }, [playable]);
+    const drivesPose = useMemo(() => shellDrivesPlayerPose(playable.game.input), [playable]);
+    const serverAuthoritative = useMemo(() => isServerAuthoritative(playable.game.multiplayer) && multiplayer !== null, [playable, multiplayer]);
+    const commandSink = useMemo(() => ({
+        run: (name, input) => resolveCommandSink(ctx, {
+            serverAuthoritative,
+            backend: multiplayer?.backend ?? null,
+            serverId: serverIdRef.current,
+        }).run(name, input),
+    }), [ctx, multiplayer, serverAuthoritative, serverIdRef]);
+    const inputSink = useMemo(() => ({
+        send: (frame) => resolveInputSink({
+            serverAuthoritative,
+            backend: multiplayer?.backend ?? null,
+            serverId: serverIdRef.current,
+        }).send(frame),
+    }), [multiplayer, serverAuthoritative, serverIdRef]);
+    const lastSentInputRef = useRef(null);
+    const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
+    useFrame((_state, rawDt) => {
+        if (poster) {
+            if (posterDoneRef.current)
+                return;
+            posterElapsedRef.current += Math.min(rawDt, 0.05);
+            if (posterElapsedRef.current >= POSTER_SETTLE_SECONDS) {
+                posterDoneRef.current = true;
+                onPosterSettled();
+                return;
+            }
+        }
+        const sendInput = () => {
+            if (!serverAuthoritative)
+                return;
+            const frame = { held: ctx.input.held(), pointer: ctx.input.pointer() };
+            const last = lastSentInputRef.current;
+            if (last !== null && inputFramesEqual(last, frame))
+                return;
+            lastSentInputRef.current = frame;
+            inputSink.send(frame);
+        };
+        if (gateRef.current || !playControlsActive(ctx)) {
+            ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS));
+            sendInput();
+            return;
+        }
+        const simStart = performance.now();
+        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.publishPointer(pointerAxisRef.current);
+            sendInput();
+            const turnInput = (tracker.isDown("turnRight") ? 1 : 0) - (tracker.isDown("turnLeft") ? 1 : 0);
+            if (turnInput !== 0)
+                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() }, 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);
+                }
+                endPhase();
+            }
+            if (!serverAuthoritative) {
+                devtools.profile.measure("onTick", () => {
+                    playable.loop.onTick(ctx, gameDt);
+                });
+                advanceBehaviors(ctx, gameDt);
+            }
+            endPhase = devtools.profile.begin("actions");
+            if (tracker.wasPressed("tabTarget")) {
+                if (ctx.game.commands.has("target.cycle"))
+                    ctx.game.commands.run("target.cycle", {});
+                else
+                    ctx.scene.entity.cycleTarget(playerId, { filter: "hostile" });
+            }
+            if (tracker.wasPressed("clearTarget")) {
+                if (ctx.game.commands.has("target.clear"))
+                    ctx.game.commands.run("target.clear", {});
+                else
+                    ctx.scene.entity.setTarget(playerId, null);
+            }
+            if (pingCommand !== undefined && tracker.wasPressed("ping")) {
+                const hit = pointerService.worldHit();
+                if (hit !== null && ctx.game.commands.has(pingCommand)) {
+                    commandSink.run(pingCommand, {
+                        point: hit.point,
+                        entity: hit.entity,
+                        object: hit.object,
+                        normal: hit.normal,
+                    });
+                }
+            }
+            const aimOverride = pointerAim ? pointerAimFor(ctx, pointerService) : undefined;
+            const commandAim = aimOverride ?? { yaw: yawRef.current, pitch: pitchRef.current };
+            if (collisionDebug.getState().layers.aimLaser) {
+                const aimFrom = ctx.player.possession.active(playerId) ?? playerId;
+                collisionDebug.setAimProbe({
+                    from: aimFrom,
+                    aim: commandAim,
+                    originPolicy: { kind: "converge" },
+                    maxDistance: 100,
+                });
+            }
+            else if (collisionDebug.getAimProbe() !== null) {
+                collisionDebug.setAimProbe(null);
+            }
+            const nowMs = performance.now();
+            for (const action of Object.keys(playable.game.input ?? {})) {
+                const pressed = tracker.wasPressed(action);
+                if (action === "ping" && pingCommand !== undefined)
+                    continue;
+                if (action === "interact") {
+                    if (!pressed)
+                        continue;
+                    const prompts = playable.prompts?.(ctx);
+                    const focus = prompts === undefined ? null : ctx.scene.entity.get(playerId);
+                    if (prompts !== undefined && focus !== null) {
+                        const active = resolveActivePrompt({ x: focus.position[0], z: focus.position[2] }, prompts);
+                        if (active !== null && active.prompt.invoke !== null) {
+                            commandSink.run(active.prompt.invoke.name, active.prompt.invoke.input);
+                        }
+                    }
+                    continue;
+                }
+                if (!shouldFireBoundAction(tracker, action, playable.game.input, repeatFiredAtRef.current, nowMs))
+                    continue;
+                repeatFiredAtRef.current.set(action, nowMs);
+                dispatchBoundAction(ctx, action, yawRef.current, pitchRef.current, commandAim, RESERVED_INPUT_ACTIONS, commandSink);
+            }
+            if (hotbarId !== null) {
+                for (const { action, slot } of slotActions) {
+                    if (!tracker.wasPressed(action))
+                        continue;
+                    const result = executeHotbarSlot(ctx, playerId, hotbarId, slot, yawRef.current, pitchRef.current, aimOverride);
+                    if (!result.ok)
+                        console.warn(`[jgengine:item-use] ${result.error}`);
+                }
+                const usePrimary = tracker.wasPressed("useAbility") || (primaryClickRef.current && hotbarId !== null);
+                if (usePrimary) {
+                    primaryClickRef.current = false;
+                    const slots = ctx.player.inventory.state(hotbarId).slots;
+                    const preferred = playable.hotbarSelection?.() ?? -1;
+                    const slot = preferred >= 0 && slots[preferred] !== null && slots[preferred] !== undefined
+                        ? preferred
+                        : slots.findIndex((stack) => stack !== null);
+                    if (slot >= 0) {
+                        const result = executeHotbarSlot(ctx, playerId, hotbarId, slot, yawRef.current, pitchRef.current, aimOverride);
+                        if (!result.ok)
+                            console.warn(`[jgengine:item-use] ${result.error}`);
+                    }
+                }
+            }
+            tracker.endFrame();
+            endPhase();
+            const serverId = serverIdRef.current;
+            if (multiplayer !== null && serverId !== null) {
+                endPhase = devtools.profile.begin("presence");
+                const focus = ctx.scene.entity.get(playerId);
+                if (focus !== null) {
+                    multiplayer.backend.presenceSync.syncPose(serverId, {
+                        x: focus.position[0],
+                        y: focus.position[1],
+                        z: focus.position[2],
+                        rotationY: focus.rotationY,
+                        rotationPitch: pitchRef.current,
+                    });
+                }
+                endPhase();
+            }
+        }
+        catch (error) {
+            if (!hasReportedTickError.current) {
+                hasReportedTickError.current = true;
+                onRuntimeError(error, "tick");
+            }
+        }
+        devtools.frame.record({ frameMs: rawDt * 1000, simMs: performance.now() - simStart });
+    }, GAME_SIM_FRAME_PRIORITY);
+    return null;
+}

package/dist/drivers/HudOnlyDriver.d.ts

@@ -0,0 +1,16 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { PlayableGame } from "../registry.js";
+export declare function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }: {
+    ctx: GameContext;
+    playable: PlayableGame;
+    tracker: ActionStateTracker<string>;
+    pointerAxisRef: {
+        current: PointerAxisState | null;
+    };
+    gateRef: {
+        current: boolean;
+    };
+    onRuntimeError: (error: unknown, phase: string) => void;
+}): null;

package/dist/drivers/HudOnlyDriver.js

@@ -0,0 +1,60 @@
+import { useEffect, useMemo, useRef } from "react";
+import { dispatchBoundAction, heldActionsFor, shouldFireBoundAction } from "../boundActionDispatch.js";
+import { advanceBehaviors } from "@jgengine/core/scene/behaviorRuntime";
+import { playControlsActive } from "@jgengine/core/game/controlGate";
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { EMPTY_RESERVED, NO_ACTIONS } from "../shellConstants.js";
+export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }) {
+    const hasReportedTickError = useRef(false);
+    const repeatFiredAtRef = useRef(new Map());
+    const lastFrameRef = useRef(null);
+    const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
+    useEffect(() => {
+        let frameId;
+        const tick = (now) => {
+            frameId = requestAnimationFrame(tick);
+            const last = lastFrameRef.current;
+            lastFrameRef.current = now;
+            if (last === null)
+                return;
+            if (gateRef.current || !playControlsActive(ctx)) {
+                ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS));
+                return;
+            }
+            const rawDt = (now - last) / 1000;
+            const simStart = performance.now();
+            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.publishPointer(pointerAxisRef.current);
+                endPhase();
+                devtools.profile.measure("onTick", () => {
+                    playable.loop.onTick(ctx, gameDt);
+                });
+                advanceBehaviors(ctx, gameDt);
+                endPhase = devtools.profile.begin("actions");
+                const nowMs = performance.now();
+                for (const action of inputActions) {
+                    if (!shouldFireBoundAction(tracker, action, playable.game.input, repeatFiredAtRef.current, nowMs))
+                        continue;
+                    repeatFiredAtRef.current.set(action, nowMs);
+                    dispatchBoundAction(ctx, action, 0, 0, { yaw: 0, pitch: 0 }, EMPTY_RESERVED);
+                }
+                tracker.endFrame();
+                endPhase();
+            }
+            catch (error) {
+                if (!hasReportedTickError.current) {
+                    hasReportedTickError.current = true;
+                    onRuntimeError(error, "tick");
+                }
+            }
+            devtools.frame.record({ frameMs: rawDt * 1000, simMs: performance.now() - simStart });
+        };
+        frameId = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frameId);
+    }, [ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, inputActions]);
+    return null;
+}

package/dist/environment/Daylight.d.ts

@@ -1,16 +1,28 @@
 import { type MutableRefObject } from "react";
 import * as THREE from "three";
-import type { SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+import type { BiomeBand, SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+import { type VolumetricCloudsConfig } from "@jgengine/core/world/volumetricClouds";
 export interface SkyDomeProps {
     topColor?: string;
     horizonColor?: string;
     radius?: number;
     offset?: number;
     exponent?: number;
+    /** Direction toward the sun; a bright HDR sun disc + warm glow is drawn there (blooms through the post chain). Omit to skip the sun. */
+    sunDirection?: readonly [number, number, number];
+    /** Sun disc/glow colour. Default warm white. */
+    sunColor?: string;
+    /** Sun disc/glow intensity multiplier. Default 1. */
+    sunIntensity?: number;
+    /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
+    hazeStrength?: number;
+    /** Sun-glow brightness multiplier around the sun disc. Default 1. */
+    sunGlowStrength?: number;
     /** 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>;
 }
-export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
+/** @internal */
+export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, hazeStrength, sunGlowStrength, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
 export interface DaylightProps {
     sky?: SkyDomeProps | false;
     fog?: {
@@ -30,14 +42,21 @@ export interface DaylightProps {
     };
     /** When false, only the sky dome and fog mount — use with authored `PlayableGame.lighting`. Default true. */
     lights?: boolean;
+    /** Raymarched volumetric cloud layer over the sky dome. Omit for no clouds — off by default. */
+    clouds?: VolumetricCloudsConfig;
 }
-export declare function Daylight({ sky, fog, sun, ambient, lights }?: DaylightProps): import("react").JSX.Element;
+/** @internal */
+export declare function Daylight({ sky, fog, sun, ambient, lights, clouds }?: DaylightProps): import("react").JSX.Element;
 export interface SkyDaylightProps {
     sky: SkyEnvironmentDescriptor;
     lights?: boolean;
+    /** Terrain `biomeBands`; when any carries `fog`/`sky`, fog and dome cross-fade per camera z. */
+    bands?: readonly BiomeBand[];
 }
-/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
-export declare function SkyDaylight({ sky, lights }: SkyDaylightProps): import("react").JSX.Element;
+/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates.
+ * @internal
+ */
+export declare function SkyDaylight({ sky, lights, bands }: SkyDaylightProps): import("react").JSX.Element;
 export interface TimeOfDayDaylightProps {
     sky: SkyEnvironmentDescriptor;
     /** The world's `SimClock` (or a stub exposing `calendar().dayFraction`). Absent means static rendering. */
@@ -47,10 +66,13 @@ export interface TimeOfDayDaylightProps {
         };
     };
     lights?: boolean;
+    /** Terrain `biomeBands`; when any carries `fog`/`sky`, fog and dome cross-fade per camera z. */
+    bands?: readonly BiomeBand[];
 }
 /**
  * Drives sky/fog (and optional default lights) from the world clock when `sky.timeOfDay` and `clock`
  * are both present. Authored `PlayableGame.lighting` is never rewritten — pass `lights={false}` so
  * only dome colors and fog track the day fraction.
- */
-export declare function TimeOfDayDaylight({ sky, clock, lights }: TimeOfDayDaylightProps): import("react").JSX.Element;
+  * @internal
+  */
+export declare function TimeOfDayDaylight({ sky, clock, lights, bands }: TimeOfDayDaylightProps): import("react").JSX.Element;

package/dist/environment/Daylight.js

@@ -2,14 +2,42 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useFrame } from "@react-three/fiber";
 import { useEffect, 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 { daylightStateAt, SKY_PRESET_DAY_FRACTION } from "./daylightCycle.js";
+import { VolumetricClouds } from "./VolumetricClouds.js";
+function normalizeVec3(v) {
+    const out = new THREE.Vector3(v[0], v[1], v[2]);
+    return out.lengthSq() === 0 ? new THREE.Vector3(0, 1, 0) : out.normalize();
+}
 const SKY_TOP = "#3fa4f2";
 const SKY_HORIZON = "#e3f4ff";
 const FOG_COLOR = "#e9f6ff";
 const SUN_COLOR = "#fff1c9";
 const HEMI_SKY = "#bfe3ff";
 const HEMI_GROUND = "#4c6b34";
-export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, materialRef, } = {}) {
+/**
+ * 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.
+ */
+function ShadowCastingSun({ position, intensity, color, }) {
+    const ref = useRef(null);
+    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);
+        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 }));
+}
+/** @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, materialRef, } = {}) {
+    const meshRef = useRef(null);
     const material = useMemo(() => {
         return new THREE.ShaderMaterial({
             uniforms: {
@@ -17,6 +45,11 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                 bottomColor: { value: new THREE.Color(horizonColor) },
                 offset: { value: offset },
                 exponent: { value: exponent },
+                uSunColor: { value: new THREE.Color(sunColor) },
+                uSunDirection: { value: sunDirection === undefined ? new THREE.Vector3(0, 1, 0) : normalizeVec3(sunDirection) },
+                uSunIntensity: { value: sunDirection === undefined ? 0 : sunIntensity },
+                uHazeStrength: { value: hazeStrength },
+                uSunGlow: { value: sunGlowStrength },
             },
             vertexShader: `
         varying vec3 vWorldPosition;
@@ -29,19 +62,42 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
             fragmentShader: `
         uniform vec3 topColor;
         uniform vec3 bottomColor;
+        uniform vec3 uSunColor;
+        uniform vec3 uSunDirection;
+        uniform float uSunIntensity;
+        uniform float uHazeStrength;
+        uniform float uSunGlow;
         uniform float offset;
         uniform float exponent;
         varying vec3 vWorldPosition;
+        float sHash(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+        float sNoise(vec2 p){
+          vec2 i = floor(p); vec2 f = fract(p); vec2 u = f * f * (3.0 - 2.0 * f);
+          return mix(mix(sHash(i), sHash(i + vec2(1.0, 0.0)), u.x),
+                     mix(sHash(i + vec2(0.0, 1.0)), sHash(i + vec2(1.0, 1.0)), u.x), u.y);
+        }
+        float sFbm(vec2 p){ float v = 0.0; float a = 0.5; for (int i = 0; i < 5; i++){ v += a * sNoise(p); p *= 2.0; a *= 0.5; } return v; }
         void main() {
-          float h = normalize(vWorldPosition + vec3(0.0, offset, 0.0)).y;
-          gl_FragColor = vec4(mix(bottomColor, topColor, max(pow(max(h, 0.0), exponent), 0.0)), 1.0);
+          vec3 dir = normalize(vWorldPosition + vec3(0.0, offset, 0.0));
+          float h = max(dir.y, 0.0);
+          vec3 col = mix(bottomColor, topColor, pow(h, exponent));
+          col = mix(col, bottomColor * 1.12, pow(1.0 - h, 6.0) * uHazeStrength);
+          vec3 vd = normalize(vWorldPosition);
+          vec2 cuv = vd.xz / (max(vd.y, 0.06) + 0.15) * 1.2;
+          float clouds = smoothstep(0.52, 0.82, sFbm(cuv));
+          float band = smoothstep(0.08, 0.35, dir.y) * smoothstep(1.0, 0.35, dir.y);
+          col = mix(col, mix(topColor, vec3(1.0), 0.6), clouds * band * 0.35);
+          float sd = max(dot(vd, normalize(uSunDirection)), 0.0);
+          float glow = pow(sd, 8.0) * 0.35 + pow(sd, 128.0) * 2.6;
+          col += uSunColor * glow * uSunIntensity * uSunGlow;
+          gl_FragColor = vec4(col, 1.0);
         }
       `,
             side: THREE.BackSide,
             depthWrite: false,
             fog: false,
         });
-    }, [topColor, horizonColor, offset, exponent]);
+    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity, hazeStrength, sunGlowStrength]);
     useEffect(() => {
         if (materialRef !== undefined)
             materialRef.current = material;
@@ -51,27 +107,111 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                 materialRef.current = null;
         };
     }, [material, materialRef]);
-    return (_jsx("mesh", { material: material, renderOrder: -1, children: _jsx("sphereGeometry", { args: [radius, 32, 16] }) }));
+    useFrame((state) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        mesh.position.x = state.camera.position.x;
+        mesh.position.z = state.camera.position.z;
+    });
+    return (_jsx("mesh", { ref: meshRef, material: material, renderOrder: -1, frustumCulled: false, children: _jsx("sphereGeometry", { args: [radius, 32, 16] }) }));
 }
-export function Daylight({ sky, fog, sun, ambient, lights = true } = {}) {
+/** @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 ?? {}) }), 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("directionalLight", { position: [sunPosition[0], sunPosition[1], sunPosition[2]], intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR, castShadow: true })] })) : 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("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] }));
+}
+/** True when at least one band overrides fog or sky — the trigger for the per-frame biome driver. */
+function bandsDriveSkyOrFog(bands) {
+    return bands !== undefined && bands.some((band) => band.fog !== undefined || band.sky !== undefined);
 }
-/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
-export function SkyDaylight({ sky, lights = true }) {
+/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates.
+ * @internal
+ */
+export function SkyDaylight({ sky, lights = true, bands }) {
+    if (bandsDriveSkyOrFog(bands))
+        return _jsx(BiomeDaylight, { sky: sky, bands: bands, lights: lights });
+    return _jsx(StaticSkyDaylight, { sky: sky, lights: lights });
+}
+/** Dome-shape overrides (radius, haze, sun-glow) carried by the sky descriptor, spread onto `SkyDome`; unset fields keep the dome defaults. */
+function skyDomeShape(sky) {
+    return {
+        ...(sky.radius === undefined ? {} : { radius: sky.radius }),
+        ...(sky.hazeStrength === undefined ? {} : { hazeStrength: sky.hazeStrength }),
+        ...(sky.sunGlowStrength === undefined ? {} : { sunGlowStrength: sky.sunGlowStrength }),
+    };
+}
+function StaticSkyDaylight({ sky, lights }) {
     const state = useMemo(() => daylightStateAt(SKY_PRESET_DAY_FRACTION[sky.preset], sky), [sky]);
-    return (_jsx(Daylight, { sky: { topColor: state.skyTop, horizonColor: state.skyBottom }, fog: { color: sky.fog?.color ?? state.background, near: sky.fog?.near, far: sky.fog?.far }, sun: { position: state.sunPosition, intensity: state.sunIntensity }, ambient: { intensity: state.ambientIntensity }, lights: lights }));
+    return (_jsx(Daylight, { sky: { topColor: state.skyTop, horizonColor: state.skyBottom, ...skyDomeShape(sky) }, fog: { color: sky.fog?.color ?? state.background, near: sky.fog?.near, far: sky.fog?.far }, sun: { position: state.sunPosition, intensity: state.sunIntensity }, ambient: { intensity: state.ambientIntensity }, lights: lights, clouds: sky.volumetricClouds }));
 }
 /**
  * Drives sky/fog (and optional default lights) from the world clock when `sky.timeOfDay` and `clock`
  * are both present. Authored `PlayableGame.lighting` is never rewritten — pass `lights={false}` so
  * only dome colors and fog track the day fraction.
- */
-export function TimeOfDayDaylight({ sky, clock, lights = true }) {
+  * @internal
+  */
+export function TimeOfDayDaylight({ sky, clock, lights = true, bands }) {
+    if (bandsDriveSkyOrFog(bands))
+        return _jsx(BiomeDaylight, { sky: sky, bands: bands, clock: clock, lights: lights });
     if (!sky.timeOfDay || clock === undefined)
         return _jsx(SkyDaylight, { sky: sky, lights: lights });
     return _jsx(DrivenDaylight, { sky: sky, clock: clock, lights: lights });
 }
+/**
+ * Per-frame biome fog/sky driver: cross-fades fog color/range, dome colors, and sun/ambient intensity
+ * along the camera's z through the terrain's `biomeBands`. Base look is the sky preset (or, when
+ * `sky.timeOfDay` and a `clock` are present, the live day fraction); bands ride on top.
+ */
+function BiomeDaylight({ sky, bands, clock, lights, }) {
+    const timeOfDay = sky.timeOfDay && clock !== undefined;
+    const baseFraction = timeOfDay ? clock.calendar().dayFraction : SKY_PRESET_DAY_FRACTION[sky.preset];
+    const initial = useMemo(() => daylightStateAt(baseFraction, sky), [sky, baseFraction]);
+    const sunRef = useRef(null);
+    const hemiRef = useRef(null);
+    const fogRef = useRef(null);
+    const skyMaterialRef = useRef(null);
+    const fogFallback = useMemo(() => ({
+        color: sky.fog?.color ?? initial.background,
+        near: sky.fog?.near ?? 70,
+        far: sky.fog?.far ?? 260,
+        density: 0,
+    }), [sky.fog?.color, sky.fog?.near, sky.fog?.far, initial.background]);
+    const skyFallback = useMemo(() => ({
+        horizonColor: initial.skyBottom,
+        zenithColor: initial.skyTop,
+        sunIntensity: initial.sunIntensity,
+        ambientIntensity: initial.ambientIntensity,
+    }), [initial.skyBottom, initial.skyTop, initial.sunIntensity, initial.ambientIntensity]);
+    const fogSampler = useMemo(() => createBiomeFogSampler(bands, fogFallback), [bands, fogFallback]);
+    const skySampler = useMemo(() => createBiomeSkySampler(bands, skyFallback), [bands, skyFallback]);
+    useFrame((state) => {
+        const base = timeOfDay ? daylightStateAt(clock.calendar().dayFraction, sky) : initial;
+        const z = state.camera.position.z;
+        const fog = fogSampler(z);
+        const skyValue = skySampler(z);
+        const fogNode = fogRef.current;
+        if (fogNode !== null) {
+            fogNode.color.set(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);
+        }
+        const sun = sunRef.current;
+        if (sun !== null) {
+            sun.position.set(base.sunPosition[0], base.sunPosition[1], base.sunPosition[2]);
+            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] }));
+}
 function DrivenDaylight({ sky, clock, lights, }) {
     const initial = useMemo(() => daylightStateAt(clock.calendar().dayFraction, sky), [clock, sky]);
     const sunRef = useRef(null);
@@ -97,5 +237,5 @@ function DrivenDaylight({ sky, clock, lights, }) {
             skyMaterial.uniforms.bottomColor.value.set(state.skyBottom);
         }
     });
-    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, materialRef: skyMaterialRef }), _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, 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] }));
 }