@jgengine/shell 0.10.0 → 0.12.0

package/dist/environment/Daylight.js

@@ -2,7 +2,10 @@ 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();
@@ -32,7 +35,9 @@ function ShadowCastingSun({ position, intensity, color, }) {
     });
     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 }));
 }
-export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, sunDirection, sunColor = "#fff4d6", sunIntensity = 1, materialRef, } = {}) {
+/** @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: {
@@ -43,6 +48,8 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                 uSunColor: { value: new THREE.Color(sunColor) },
                 uSunDirection: { value: sunDirection === undefined ? new THREE.Vector3(0, 1, 0) : normalizeVec3(sunDirection) },
                 uSunIntensity: { value: sunDirection === undefined ? 0 : sunIntensity },
+                uHazeStrength: { value: hazeStrength },
+                uSunGlow: { value: sunGlowStrength },
             },
             vertexShader: `
         varying vec3 vWorldPosition;
@@ -58,6 +65,8 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
         uniform vec3 uSunColor;
         uniform vec3 uSunDirection;
         uniform float uSunIntensity;
+        uniform float uHazeStrength;
+        uniform float uSunGlow;
         uniform float offset;
         uniform float exponent;
         varying vec3 vWorldPosition;
@@ -72,7 +81,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
           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) * 0.5);
+          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));
@@ -80,7 +89,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
           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;
+          col += uSunColor * glow * uSunIntensity * uSunGlow;
           gl_FragColor = vec4(col, 1.0);
         }
       `,
@@ -88,7 +97,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
             depthWrite: false,
             fog: false,
         });
-    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity]);
+    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity, hazeStrength, sunGlowStrength]);
     useEffect(() => {
         if (materialRef !== undefined)
             materialRef.current = material;
@@ -98,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 ?? {}), sunDirection: sunPosition, sunColor: sun?.color ?? SUN_COLOR, sunIntensity: sun?.intensity ?? 1 })), 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("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.
+ * @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 }),
+    };
 }
-/** 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 }) {
+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);
@@ -144,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] }));
 }

package/dist/environment/EnvironmentScene.js

@@ -1,12 +1,15 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
+import { useTexture } from "@react-three/drei";
+import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
 import { resolveStructureBuildings } from "@jgengine/core/world/environmentSummary";
 import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { GroundPad } from "./GroundPad.js";
 import { RoadRibbons } from "./RoadRibbons.js";
+import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
 import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
@@ -15,6 +18,26 @@ import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
 import { WeatherUniformProvider } from "../weather/weatherUniforms.js";
+function TexturedTerrainGround({ detail, layout, }) {
+    const maps = detail.material.maps;
+    const textures = useTexture({
+        color: maps.color,
+        normal: maps.normal,
+        roughness: maps.roughness,
+        ao: maps.ao,
+    });
+    useEffect(() => {
+        textures.color.colorSpace = THREE.SRGBColorSpace;
+        for (const texture of Object.values(textures)) {
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.needsUpdate = true;
+        }
+    }, [textures]);
+    const material = useMemo(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
+    useEffect(() => () => material.dispose(), [material]);
+    return (_jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material }));
+}
 function TerrainGround({ terrain, field, center, }) {
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
     const paletteAt = useMemo(() => {
@@ -38,16 +61,20 @@ function TerrainGround({ terrain, field, center, }) {
         const swing = terrain.height * 1.2;
         return [base - swing, base + swing];
     }, [terrain.baseHeight, terrain.height]);
-    const detailMaterial = useMemo(() => terrain.detail === undefined
+    const resolvedDetail = useMemo(() => (terrain.detail === undefined ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
+    const proceduralMaterial = useMemo(() => resolvedDetail === undefined || resolvedDetail.material !== undefined
         ? undefined
-        : createTerrainDetailMaterial(resolveTerrainDetail(terrain.detail, terrain.waterLevel)).material, [terrain.detail, terrain.waterLevel]);
-    useEffect(() => () => detailMaterial?.dispose(), [detailMaterial]);
-    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: detailMaterial }));
+        : createTerrainDetailMaterial(resolvedDetail).material, [resolvedDetail]);
+    useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
+    if (resolvedDetail?.material !== undefined) {
+        return (_jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, center } }));
+    }
+    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
 function areaCenter(area) {
     return area.position ?? [0, 0];
 }
-function Vegetation({ grass, field }) {
+function Vegetation({ grass, field, groundColor, }) {
     const [cx, cz] = areaCenter(grass.area);
     const heightAt = useMemo(() => cx === 0 && cz === 0
         ? field.sampleHeight
@@ -56,7 +83,15 @@ function Vegetation({ grass, field }) {
     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, density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, wind: wind, 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, 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) {
+    const sampler = terrainGroundColorSampler(terrain, field);
+    if (sampler === undefined)
+        return undefined;
+    const [cx, cz] = areaCenter(grass.area);
+    return sampler(cx, cz);
 }
 function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
@@ -64,9 +99,9 @@ function weatherVolume(area) {
 function Precipitation({ weather }) {
     const [cx, cz] = areaCenter(weather.area);
     if (weather.kind === "rain") {
-        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, width: weather.width, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
     }
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
 }
 function Weather({ weather }) {
     return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
@@ -119,5 +154,5 @@ export function EnvironmentScene({ feature }) {
     const pads = feature.pads ?? [];
     const islands = feature.islands ?? [];
     const roads = feature.roads ?? [];
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field }, `road-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field }, `road-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/VolumetricClouds.d.ts

@@ -0,0 +1,17 @@
+import type { VolumetricCloudsRules } from "@jgengine/core/world/volumetricClouds";
+/** Props for {@link VolumetricClouds} — fully-resolved cloud rules plus the shared sun direction. */
+export interface VolumetricCloudsProps {
+    rules: VolumetricCloudsRules;
+    /** Direction toward the sun (same vector `SkyDome`/`Daylight` use for the sun disc). */
+    sunDirection: readonly [number, number, number];
+}
+/**
+ * A raymarched volumetric cloud slab: a large horizontal box straddling `[height, height+thickness]`,
+ * following the camera in XZ (like `SkyDome`), whose fragment shader raymarches 3D FBM noise inside
+ * the slab and accumulates density-weighted color with a sun-facing forward-scatter term. Mounted
+ * from `Daylight`/`SkyDaylight`/`TimeOfDayDaylight` whenever a sky descriptor carries
+ * `volumetricClouds`; off by default (the component itself is simply not rendered). A game never
+ * mounts this directly — author clouds via `sky({ volumetricClouds })`.
+ * @internal
+ */
+export declare function VolumetricClouds({ rules, sunDirection }: VolumetricCloudsProps): import("react").JSX.Element;

package/dist/environment/VolumetricClouds.js

@@ -0,0 +1,202 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+/**
+ * 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.
+ */
+const INSIDE_FRUSTUM_DOME_RADIUS = 240;
+function hashSeed(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) % 100000;
+}
+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 CLOUD_VERTEX_SHADER = /* glsl */ `
+varying vec3 vJgCloudWorldPos;
+void main() {
+  vJgCloudWorldPos = (modelMatrix * vec4(position, 1.0)).xyz;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+const CLOUD_FRAGMENT_SHADER = /* glsl */ `
+uniform vec3 uCameraPos;
+uniform vec3 uColor;
+uniform vec3 uSunColor;
+uniform vec3 uSunDirection;
+uniform float uSunScatter;
+uniform float uCoverage;
+uniform float uDensity;
+uniform float uBaseHeight;
+uniform float uThickness;
+uniform float uScale;
+uniform float uSpeed;
+uniform float uTime;
+uniform float uSeedOffset;
+varying vec3 vJgCloudWorldPos;
+
+float jgCloudHash13(vec3 p){
+  p = fract(p * 0.1031 + uSeedOffset * 0.0007);
+  p += dot(p, p.yzx + 33.33);
+  return fract((p.x + p.y) * p.z);
+}
+
+float jgCloudNoise(vec3 p){
+  vec3 i = floor(p);
+  vec3 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  float n000 = jgCloudHash13(i + vec3(0.0, 0.0, 0.0));
+  float n100 = jgCloudHash13(i + vec3(1.0, 0.0, 0.0));
+  float n010 = jgCloudHash13(i + vec3(0.0, 1.0, 0.0));
+  float n110 = jgCloudHash13(i + vec3(1.0, 1.0, 0.0));
+  float n001 = jgCloudHash13(i + vec3(0.0, 0.0, 1.0));
+  float n101 = jgCloudHash13(i + vec3(1.0, 0.0, 1.0));
+  float n011 = jgCloudHash13(i + vec3(0.0, 1.0, 1.0));
+  float n111 = jgCloudHash13(i + vec3(1.0, 1.0, 1.0));
+  return mix(
+    mix(mix(n000, n100, f.x), mix(n010, n110, f.x), f.y),
+    mix(mix(n001, n101, f.x), mix(n011, n111, f.x), f.y),
+    f.z
+  );
+}
+
+float jgCloudFbm(vec3 p){
+  float v = 0.0;
+  float a = 0.5;
+  for (int i = 0; i < 5; i++) {
+    v += a * jgCloudNoise(p);
+    p = p * 2.03 + vec3(11.3, 7.1, 5.7);
+    a *= 0.5;
+  }
+  return v;
+}
+
+// Density of the cloud slab at a world point: a 3D-FBM puff field carved by a coverage threshold and
+// shaped by a cumulus vertical profile (rounded base, eroded anvil top). 0 outside the slab.
+float jgCloudDensity(vec3 pos){
+  float heightFrac = (pos.y - uBaseHeight) / uThickness;
+  if (heightFrac < 0.0 || heightFrac > 1.0) return 0.0;
+  float profile = smoothstep(0.0, 0.2, heightFrac) * smoothstep(1.0, 0.5, heightFrac);
+  vec3 wind = vec3(uTime * uSpeed, 0.0, uTime * uSpeed * 0.6);
+  vec3 sp = (pos + wind) / uScale;
+  float shape = jgCloudFbm(sp);
+  float threshold = mix(0.62, 0.2, uCoverage);
+  float d = smoothstep(threshold, threshold + 0.3, shape * profile + profile * 0.12);
+  return d * profile * uDensity;
+}
+
+// March a few steps toward the sun and turn the accumulated density into transmittance (Beer's law) —
+// the self-shadowing that gives the clouds volume instead of a flat wash.
+float jgCloudLight(vec3 pos){
+  vec3 ldir = normalize(uSunDirection);
+  float stepL = uThickness * 0.2;
+  float dens = 0.0;
+  vec3 p = pos;
+  for (int i = 0; i < 4; i++) {
+    p += ldir * stepL;
+    dens += jgCloudDensity(p);
+  }
+  return exp(-dens * stepL * 1.6);
+}
+
+void main() {
+  vec3 rayOrigin = uCameraPos;
+  vec3 rayDir = normalize(vJgCloudWorldPos - uCameraPos);
+  if (rayDir.y < 0.015) discard;
+
+  float tBottom = (uBaseHeight - rayOrigin.y) / rayDir.y;
+  float tTop = (uBaseHeight + uThickness - rayOrigin.y) / rayDir.y;
+  float tNear = max(min(tBottom, tTop), 0.0);
+  float tFar = max(tBottom, tTop);
+  if (tFar <= tNear) discard;
+  tFar = min(tFar, tNear + uThickness * 6.0);
+
+  const int STEPS = 32;
+  float stepLen = (tFar - tNear) / float(STEPS);
+  float t = tNear + stepLen * 0.5;
+  float transmittance = 1.0;
+  vec3 color = vec3(0.0);
+  float sunDot = max(dot(rayDir, normalize(uSunDirection)), 0.0);
+  float silver = pow(sunDot, 5.0) * uSunScatter;
+
+  for (int i = 0; i < STEPS; i++) {
+    vec3 pos = rayOrigin + rayDir * t;
+    float dens = jgCloudDensity(pos);
+    if (dens > 0.002) {
+      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;
+      float dt = dens * stepLen * 1.3;
+      float a = 1.0 - exp(-dt);
+      color += transmittance * a * lit;
+      transmittance *= 1.0 - a;
+      if (transmittance < 0.02) break;
+    }
+    t += stepLen;
+  }
+
+  float alpha = (1.0 - transmittance) * smoothstep(0.015, 0.22, rayDir.y);
+  if (alpha < 0.01) discard;
+  gl_FragColor = vec4(color, alpha);
+}
+`;
+/**
+ * A raymarched volumetric cloud slab: a large horizontal box straddling `[height, height+thickness]`,
+ * following the camera in XZ (like `SkyDome`), whose fragment shader raymarches 3D FBM noise inside
+ * the slab and accumulates density-weighted color with a sun-facing forward-scatter term. Mounted
+ * from `Daylight`/`SkyDaylight`/`TimeOfDayDaylight` whenever a sky descriptor carries
+ * `volumetricClouds`; off by default (the component itself is simply not rendered). A game never
+ * mounts this directly — author clouds via `sky({ volumetricClouds })`.
+ * @internal
+ */
+export function VolumetricClouds({ rules, sunDirection }) {
+    const meshRef = useRef(null);
+    const timeRef = useRef(0);
+    const material = useMemo(() => {
+        return new THREE.ShaderMaterial({
+            uniforms: {
+                uCameraPos: { value: new THREE.Vector3() },
+                uColor: { value: new THREE.Color(rules.color) },
+                uSunColor: { value: new THREE.Color(rules.sunColor) },
+                uSunDirection: { value: normalizeVec3(sunDirection) },
+                uSunScatter: { value: rules.sunScatter },
+                uCoverage: { value: rules.coverage },
+                uDensity: { value: rules.density },
+                uBaseHeight: { value: rules.height },
+                uThickness: { value: rules.thickness },
+                uScale: { value: rules.scale },
+                uSpeed: { value: rules.speed },
+                uTime: { value: 0 },
+                uSeedOffset: { value: hashSeed(rules.seed) },
+            },
+            vertexShader: CLOUD_VERTEX_SHADER,
+            fragmentShader: CLOUD_FRAGMENT_SHADER,
+            transparent: true,
+            depthWrite: false,
+            side: THREE.BackSide,
+            fog: false,
+        });
+    }, [rules, sunDirection]);
+    useEffect(() => () => material.dispose(), [material]);
+    useFrame((state, delta) => {
+        timeRef.current += delta;
+        const mesh = meshRef.current;
+        if (mesh !== null) {
+            mesh.position.x = state.camera.position.x;
+            mesh.position.z = state.camera.position.z;
+        }
+        const uniforms = material.uniforms;
+        uniforms.uCameraPos.value.copy(state.camera.position);
+        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

@@ -17,10 +17,12 @@ 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";
 export declare const SKY_PRESET_DAY_FRACTION: Record<"day" | "dusk" | "night", number>;
+/** @internal */
 export declare function lerpHexColor(a: string, b: string, t: number): string;
 /**
  * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
  * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
  * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
- */
+  * @internal
+  */
 export declare function daylightStateAt(dayFraction: number, config?: DaylightCycleConfig): DaylightState;

package/dist/environment/daylightCycle.js

@@ -38,6 +38,7 @@ function clampByte(value) {
 function rgbToHex(rgb) {
     return `#${rgb.map((channel) => clampByte(channel).toString(16).padStart(2, "0")).join("")}`;
 }
+/** @internal */
 export function lerpHexColor(a, b, t) {
     const [ar, ag, ab] = hexToRgb(a);
     const [br, bg, bb] = hexToRgb(b);
@@ -95,7 +96,8 @@ function segmentAt(wrapped, keyframes) {
  * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
  * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
  * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
- */
+  * @internal
+  */
 export function daylightStateAt(dayFraction, config = {}) {
     const wrapped = wrapFraction(dayFraction);
     const keyframes = buildKeyframes(config);

package/dist/environment/groundPadMath.d.ts

@@ -8,6 +8,9 @@ export type PadShape = {
     width: number;
     depth: number;
 };
+/** @internal */
 export declare function resolvePadShape(size: PadSize): PadShape;
+/** @internal */
 export declare function resolvePadSurfaceY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height" | "elevation">): number;
+/** @internal */
 export declare function resolvePadMeshY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height" | "elevation">): number;

package/dist/environment/groundPadMath.js

@@ -1,10 +1,13 @@
 export const PAD_THICKNESS = 0.1;
+/** @internal */
 export function resolvePadShape(size) {
     return "radius" in size ? { circular: true, radius: size.radius } : { circular: false, width: size[0], depth: size[1] };
 }
+/** @internal */
 export function resolvePadSurfaceY(groundHeight, pad) {
     return pad.elevation ?? groundHeight + pad.height;
 }
+/** @internal */
 export function resolvePadMeshY(groundHeight, pad) {
     return resolvePadSurfaceY(groundHeight, pad) - PAD_THICKNESS / 2;
 }

package/dist/environment/index.d.ts

@@ -1,4 +1,5 @@
 export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDaylightProps, type SkyDomeProps, type TimeOfDayDaylightProps, } from "./Daylight.js";
 export { EnvironmentScene, type EnvironmentSceneProps } from "./EnvironmentScene.js";
+export { VolumetricClouds, type VolumetricCloudsProps } from "./VolumetricClouds.js";
 export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, type DaylightCycleConfig, type DaylightState, } from "./daylightCycle.js";
 export { resolveSkyLightOwnership, skyEmitsLights, type SkyLightOwnership, } from "./skyLightingPolicy.js";

package/dist/environment/index.js

@@ -1,4 +1,5 @@
 export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, } from "./Daylight.js";
 export { EnvironmentScene } from "./EnvironmentScene.js";
+export { VolumetricClouds } from "./VolumetricClouds.js";
 export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, } from "./daylightCycle.js";
 export { resolveSkyLightOwnership, skyEmitsLights, } from "./skyLightingPolicy.js";

package/dist/environment/skyLightingPolicy.d.ts

@@ -6,5 +6,7 @@
  * sky-owned lights when the game did not author lighting).
  */
 export type SkyLightOwnership = "authored" | "sky-default";
+/** @internal */
 export declare function resolveSkyLightOwnership(hasAuthoredLighting: boolean): SkyLightOwnership;
+/** @internal */
 export declare function skyEmitsLights(ownership: SkyLightOwnership): boolean;

package/dist/environment/skyLightingPolicy.js

@@ -1,6 +1,8 @@
+/** @internal */
 export function resolveSkyLightOwnership(hasAuthoredLighting) {
     return hasAuthoredLighting ? "authored" : "sky-default";
 }
+/** @internal */
 export function skyEmitsLights(ownership) {
     return ownership === "sky-default";
 }

package/dist/environment/terrainGroundColor.d.ts

@@ -0,0 +1,9 @@
+import type { TerrainEnvironmentDescriptor } from "@jgengine/core/world/features";
+import { type TerrainField } from "@jgengine/core/world/terrain";
+/**
+ * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
+ * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
+ * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * @internal
+ */
+export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField): ((x: number, z: number) => string) | undefined;

package/dist/environment/terrainGroundColor.js

@@ -0,0 +1,22 @@
+import * as THREE from "three";
+import { resolveTerrainPalette } from "@jgengine/core/world/terrain";
+/**
+ * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
+ * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
+ * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * @internal
+ */
+export function terrainGroundColorSampler(terrain, field) {
+    if (terrain === undefined)
+        return undefined;
+    const palette = resolveTerrainPalette(terrain);
+    const low = new THREE.Color(palette.low);
+    const high = new THREE.Color(palette.high);
+    const base = terrain.baseHeight ?? 0;
+    const swing = terrain.height * 1.2;
+    const scratch = new THREE.Color();
+    return (x, z) => {
+        const t = swing <= 0 ? 0.5 : THREE.MathUtils.clamp((field.sampleHeight(x, z) - (base - swing)) / (swing * 2), 0, 1);
+        return `#${scratch.copy(low).lerp(high, t).getHexString()}`;
+    };
+}