@jgengine/shell 0.19.0 → 0.21.0

package/dist/weather/DustField.js

@@ -4,6 +4,7 @@ import * as THREE from "three";
 import { useDisposable } from "../render/useDisposable.js";
 import { createWeatherQuadGeometry } from "./weatherGeometry.js";
 import { DEFAULT_DUST_COUNT, DEFAULT_DUST_DENSITY, resolveWeatherInstanceCount } from "./weatherMath.js";
+import { WEATHER_SHELTER_SHADER } from "./weatherShelter.js";
 import { useWeatherUniformSet } from "./weatherUniforms.js";
 const DEFAULT_VOLUME = [70, 22, 70];
 const DEFAULT_ORIGIN = [0, 0, 0];
@@ -16,13 +17,16 @@ const DEFAULT_DUST_COLOR = "#c8a878";
  *
  * @capability weather-dust airborne particulate that turns still air into visible wind
  */
-export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 2.4, size = 0.16, sway = 0.5, opacity = 0.3, color = DEFAULT_DUST_COLOR, groundBias = 0.65, timeScale, seed = 51407, renderOrder = 10, frustumCulled, }) {
+export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 2.4, size = 0.16, sway = 0.5, opacity = 0.3, color = DEFAULT_DUST_COLOR, groundBias = 0.65, timeScale, timeSeconds, seed = 51407, renderOrder = 10, frustumCulled, }) {
     const { camera } = useThree();
-    const shared = useWeatherUniformSet({ wind, timeScale });
+    const shared = useWeatherUniformSet({ wind, timeScale, timeSeconds });
     const geometry = useDisposable(() => createWeatherQuadGeometry(count, seed), [count, seed]);
     const material = useDisposable(() => {
         const uniforms = {
             uTime: shared.time,
+            uShelterCenters: shared.shelterCenters,
+            uShelterShapes: shared.shelterShapes,
+            uShelterCount: shared.shelterCount,
             uWind: shared.wind,
             uAnchor: { value: new THREE.Vector3() },
             uVolume: { value: new THREE.Vector3() },
@@ -39,6 +43,7 @@ export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_D
             depthWrite: false,
             blending: THREE.NormalBlending,
             vertexShader: `
+        ${WEATHER_SHELTER_SHADER}
         uniform float uTime;
         uniform vec3 uWind;
         uniform vec3 uAnchor;
@@ -51,6 +56,7 @@ export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_D
         attribute vec3 aSpawn;
         attribute float aDrift;
 
+        varying float vExposure;
         varying vec2 vUv;
         varying float vDrift;
         varying float vFade;
@@ -76,6 +82,7 @@ export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_D
           vec3 travel = normalize(vec3(uWind.x, 0.0, uWind.z) + vec3(0.0001, 0.0, 0.0)) * carry;
           vec3 local = spawn * uVolume + (uWind + travel) * uTime + bob;
           vec3 worldCenter = mod(local - origin, uVolume) + origin;
+          vExposure = weatherExposure(worldCenter);
 
           // Fade at the top of the volume so recycled motes do not pop into view against the sky.
           float height = (worldCenter.y - origin.y) / max(uVolume.y, 0.001);
@@ -93,6 +100,7 @@ export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_D
         uniform float uOpacity;
         uniform vec3 uColor;
 
+        varying float vExposure;
         varying vec2 vUv;
         varying float vDrift;
         varying float vFade;
@@ -102,6 +110,7 @@ export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_D
           // No hard core: dust is diffuse, and a bright centre reads as snow.
           float puff = smoothstep(1.0, 0.05, distanceFromCenter);
           float alpha = puff * puff * uOpacity * (0.35 + 0.65 * vDrift) * vFade;
+          alpha *= vExposure;
           if (alpha < 0.001) discard;
           gl_FragColor = vec4(uColor, alpha);
         }
@@ -123,7 +132,12 @@ export function DustField({ count = DEFAULT_DUST_COUNT, density = DEFAULT_DUST_D
         uniforms.uOpacity.value = opacity;
         uniforms.uGroundBias.value = groundBias;
         uniforms.uColor.value.set(color);
-        geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
+        geometry.instanceCount = resolveWeatherInstanceCount(count, density * shared.dust.value, budget);
+        const metrics = shared.metrics?.dust;
+        if (metrics !== undefined) {
+            metrics.count = geometry.instanceCount;
+            metrics.capacity = geometry.getAttribute("aSpawn").count;
+        }
     });
     return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
 }

package/dist/weather/FireSpreadLayer.d.ts

@@ -2,7 +2,7 @@ import * as THREE from "three";
 import type { FireGrid } from "@jgengine/core/world/weather";
 export interface FireSpreadLayerProps {
     grid: FireGrid;
-    cellSize: number;
+    cellSize?: number;
     origin?: readonly [number, number];
     /** Sample ground height so flames sit on terrain; defaults to y=0. */
     heightAt?: (x: number, z: number) => number;
@@ -10,5 +10,7 @@ export interface FireSpreadLayerProps {
     flameHeight?: number;
     burningColor?: THREE.ColorRepresentation;
     emberColor?: THREE.ColorRepresentation;
+    /** Absolute authoritative simulation clock; use for pause and snapshot restore. */
+    timeSeconds?: () => number;
 }
-export declare function FireSpreadLayer({ grid, cellSize, origin, heightAt, flameHeight, burningColor, emberColor, }: FireSpreadLayerProps): import("react").JSX.Element;
+export declare function FireSpreadLayer({ grid, cellSize, origin, heightAt, flameHeight, burningColor, emberColor, timeSeconds, }: FireSpreadLayerProps): import("react").JSX.Element;

package/dist/weather/FireSpreadLayer.js

@@ -3,8 +3,7 @@ import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 import { setBillboardQuaternion } from "./fireSpreadPose.js";
-const HIDDEN = new THREE.Matrix4().makeScale(0, 0, 0);
-export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, flameHeight = 1.6, burningColor = "#ff6a1a", emberColor = "#4a1206", }) {
+export function FireSpreadLayer({ grid, cellSize = grid.cellSize, origin = grid.origin, heightAt, flameHeight = 1.6, burningColor = "#ff6a1a", emberColor = "#4a1206", timeSeconds, }) {
     const flames = useRef(null);
     const scorch = useRef(null);
     const capacity = grid.cols * grid.rows;
@@ -33,13 +32,12 @@ export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, fla
         const scorchMesh = scorch.current;
         if (flameMesh === null || scorchMesh === null)
             return;
-        const cells = grid.snapshot();
-        const flicker = 0.85 + 0.15 * Math.sin(state.clock.elapsedTime * 12);
+        const flicker = 0.85 + 0.15 * Math.sin((timeSeconds?.() ?? state.clock.elapsedTime) * 12);
         let flameIndex = 0;
         let scorchIndex = 0;
         for (let row = 0; row < grid.rows; row += 1) {
             for (let col = 0; col < grid.cols; col += 1) {
-                const cell = cells[row * grid.cols + col];
+                const cell = grid.cell(col, row);
                 const x = origin[0] + col * cellSize;
                 const z = origin[1] + row * cellSize;
                 const groundY = heightAt?.(x, z) ?? 0;
@@ -60,12 +58,8 @@ export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, fla
                 }
             }
         }
-        for (let i = flameIndex; i < capacity; i += 1)
-            flameMesh.setMatrixAt(i, HIDDEN);
-        for (let i = scorchIndex; i < capacity; i += 1)
-            scorchMesh.setMatrixAt(i, HIDDEN);
-        flameMesh.count = capacity;
-        scorchMesh.count = capacity;
+        flameMesh.count = flameIndex;
+        scorchMesh.count = scorchIndex;
         flameMesh.instanceMatrix.needsUpdate = true;
         scorchMesh.instanceMatrix.needsUpdate = true;
     });

package/dist/weather/LightningStrike.d.ts

@@ -13,5 +13,8 @@ export interface LightningStrikeProps {
     jaggedness?: number;
     impactLight?: number;
     renderOrder?: number;
+    /** Supply both fields to replay the strike from authoritative simulation state. */
+    timeSeconds?: () => number;
+    startedAt?: number;
 }
-export declare function LightningStrike({ origin, target, strikeKey, seed, visible, duration, color, glow, branches, jaggedness, impactLight, renderOrder, }: LightningStrikeProps): import("react").JSX.Element;
+export declare function LightningStrike({ origin, target, strikeKey, seed, visible, duration, color, glow, branches, jaggedness, impactLight, renderOrder, timeSeconds, startedAt, }: LightningStrikeProps): import("react").JSX.Element;

package/dist/weather/LightningStrike.js

@@ -3,6 +3,7 @@ import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 import { useDisposable } from "../render/useDisposable.js";
+import { lightningStrikeEnvelope } from "./weatherMath.js";
 const DEFAULT_COLOR = "#bdd4ff";
 function createRandom(seed) {
     let state = seed >>> 0;
@@ -47,7 +48,7 @@ function createLightningSegments(origin, target, seed, branches, jaggedness) {
     for (let index = 0; index < points.length - 1; index += 1) {
         segments.push({ from: points[index], to: points[index + 1] });
     }
-    const branchCount = Math.max(0, Math.floor(branches));
+    const branchCount = Math.max(0, Math.min(64, Math.floor(branches)));
     for (let index = 0; index < branchCount; index += 1) {
         const sourceIndex = 2 + Math.floor(random() * Math.max(1, points.length - 5));
         const source = points[sourceIndex];
@@ -78,8 +79,9 @@ function writeLightningGeometry(geometry, segments) {
     geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
     geometry.computeBoundingSphere();
 }
-export function LightningStrike({ origin, target, strikeKey = 0, seed = 451, visible = true, duration = 0.18, color = DEFAULT_COLOR, glow = 2.4, branches = 5, jaggedness = 0.08, impactLight = 26, renderOrder = 20, }) {
-    const lifeRef = useRef(0);
+export function LightningStrike({ origin, target, strikeKey = 0, seed = 451, visible = true, duration = 0.18, color = DEFAULT_COLOR, glow = 2.4, branches = 5, jaggedness = 0.08, impactLight = 26, renderOrder = 20, timeSeconds, startedAt, }) {
+    const localTime = useRef(0);
+    const startRef = useRef(null);
     const lightRef = useRef(null);
     const geometry = useDisposable(() => new THREE.BufferGeometry(), []);
     const material = useDisposable(() => new THREE.LineBasicMaterial({
@@ -97,28 +99,22 @@ export function LightningStrike({ origin, target, strikeKey = 0, seed = 451, vis
     }, [geometry, material, renderOrder]);
     useEffect(() => {
         if (!visible) {
-            lifeRef.current = 0;
+            startRef.current = null;
             material.opacity = 0;
             if (lightRef.current !== null)
                 lightRef.current.intensity = 0;
             return;
         }
         writeLightningGeometry(geometry, createLightningSegments(origin, target, seed ^ hashStrikeKey(strikeKey), branches, jaggedness));
-        lifeRef.current = duration;
-    }, [branches, duration, geometry, jaggedness, material, origin, seed, strikeKey, target, visible]);
+        startRef.current = startedAt ?? timeSeconds?.() ?? localTime.current;
+    }, [branches, duration, geometry, jaggedness, material, origin, seed, strikeKey, target, visible, startedAt, timeSeconds]);
     useFrame((_state, delta) => {
-        if (!visible || lifeRef.current <= 0) {
-            material.opacity = 0;
-            if (lightRef.current !== null)
-                lightRef.current.intensity = 0;
-            return;
-        }
-        lifeRef.current = Math.max(0, lifeRef.current - delta);
-        const amount = duration <= 0 ? 0 : lifeRef.current / duration;
-        const flicker = 0.62 + Math.random() * 0.38;
-        material.opacity = amount * glow * flicker;
+        localTime.current += delta;
+        const now = timeSeconds?.() ?? localTime.current;
+        const amount = visible && startRef.current !== null ? lightningStrikeEnvelope(now, startRef.current, duration, seed ^ hashStrikeKey(strikeKey)) : 0;
+        material.opacity = amount * glow;
         if (lightRef.current !== null)
-            lightRef.current.intensity = amount * impactLight * flicker;
+            lightRef.current.intensity = amount * impactLight;
     });
     return (_jsxs(_Fragment, { children: [_jsx("primitive", { object: line }), _jsx("pointLight", { ref: lightRef, position: [target[0], target[1], target[2]], color: color, intensity: 0, distance: 56, decay: 2 })] }));
 }

package/dist/weather/RainField.d.ts

@@ -15,8 +15,9 @@ export interface RainFieldProps {
     color?: THREE.ColorRepresentation;
     lightning?: number;
     timeScale?: number;
+    timeSeconds?: number | (() => number);
     seed?: number;
     renderOrder?: number;
     frustumCulled?: boolean;
 }
-export declare function RainField({ count, density, budget, volume, wind, origin, followCamera, speed, length, width, opacity, color, lightning, timeScale, seed, renderOrder, frustumCulled, }: RainFieldProps): import("react").JSX.Element;
+export declare function RainField({ count, density, budget, volume, wind, origin, followCamera, speed, length, width, opacity, color, lightning, timeScale, timeSeconds, seed, renderOrder, frustumCulled, }: RainFieldProps): import("react").JSX.Element;

package/dist/weather/RainField.js

@@ -4,17 +4,21 @@ import * as THREE from "three";
 import { useDisposable } from "../render/useDisposable.js";
 import { createWeatherQuadGeometry } from "./weatherGeometry.js";
 import { DEFAULT_RAIN_COUNT, DEFAULT_RAIN_DENSITY, resolveWeatherInstanceCount } from "./weatherMath.js";
+import { WEATHER_SHELTER_SHADER } from "./weatherShelter.js";
 import { useWeatherUniformSet } from "./weatherUniforms.js";
 const DEFAULT_VOLUME = [56, 42, 56];
 const DEFAULT_ORIGIN = [0, 0, 0];
 const DEFAULT_RAIN_COLOR = "#b8c4d8";
-export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 22, length = 1.35, width = 0.018, opacity = 0.48, color = DEFAULT_RAIN_COLOR, lightning, timeScale, seed = 11939, renderOrder = 10, frustumCulled, }) {
+export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 22, length = 1.35, width = 0.018, opacity = 0.48, color = DEFAULT_RAIN_COLOR, lightning, timeScale, timeSeconds, seed = 11939, renderOrder = 10, frustumCulled, }) {
     const { camera } = useThree();
-    const shared = useWeatherUniformSet({ wind, lightning, timeScale });
+    const shared = useWeatherUniformSet({ wind, lightning, timeScale, timeSeconds });
     const geometry = useDisposable(() => createWeatherQuadGeometry(count, seed), [count, seed]);
     const material = useDisposable(() => {
         const uniforms = {
             uTime: shared.time,
+            uShelterCenters: shared.shelterCenters,
+            uShelterShapes: shared.shelterShapes,
+            uShelterCount: shared.shelterCount,
             uWind: shared.wind,
             uLightning: shared.lightning,
             uAnchor: { value: new THREE.Vector3() },
@@ -31,6 +35,7 @@ export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_D
             depthWrite: false,
             blending: THREE.NormalBlending,
             vertexShader: `
+        ${WEATHER_SHELTER_SHADER}
         uniform float uTime;
         uniform vec3 uWind;
         uniform vec3 uAnchor;
@@ -42,6 +47,7 @@ export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_D
         attribute vec3 aSpawn;
         attribute float aDrift;
 
+        varying float vExposure;
         varying vec2 vUv;
         varying float vDrift;
 
@@ -54,6 +60,7 @@ export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_D
           vec3 velocity = vec3(uWind.x, -speed, uWind.z);
           vec3 local = aSpawn * uVolume + velocity * uTime;
           vec3 worldCenter = mod(local - origin, uVolume) + origin;
+          vExposure = weatherExposure(worldCenter);
           vec3 direction = normalize(velocity);
           vec3 cameraRay = normalize(cameraPosition - worldCenter);
           vec3 sideRaw = cross(direction, cameraRay);
@@ -69,6 +76,7 @@ export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_D
         uniform vec3 uColor;
         uniform float uLightning;
 
+        varying float vExposure;
         varying vec2 vUv;
         varying float vDrift;
 
@@ -76,6 +84,7 @@ export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_D
           float across = smoothstep(0.0, 0.45, vUv.x) * smoothstep(1.0, 0.55, vUv.x);
           float along = smoothstep(0.0, 0.28, vUv.y) * smoothstep(1.0, 0.58, vUv.y);
           float alpha = across * along * uOpacity * (0.55 + 0.45 * vDrift);
+          alpha *= vExposure;
           if (alpha < 0.001) discard;
           vec3 litColor = uColor * (1.0 + uLightning * 2.25);
           gl_FragColor = vec4(litColor, alpha);
@@ -97,7 +106,12 @@ export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_D
         uniforms.uWidth.value = width;
         uniforms.uOpacity.value = opacity;
         uniforms.uColor.value.set(color);
-        geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
+        geometry.instanceCount = resolveWeatherInstanceCount(count, density * shared.rain.value, budget);
+        const metrics = shared.metrics?.rain;
+        if (metrics !== undefined) {
+            metrics.count = geometry.instanceCount;
+            metrics.capacity = geometry.getAttribute("aSpawn").count;
+        }
     });
     return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
 }

package/dist/weather/RainImpactField.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from "three";
+/** Bounded ripple pool with terrain height and sky exposure query adapters. */
+export interface RainImpactFieldProps {
+    /** Fixed splash pool, clamped to 256. Default 64. */
+    count?: number;
+    extent?: number;
+    heightAt: (x: number, z: number) => number;
+    /** Sky exposure 0..1; sheltered surfaces produce no splashes. */
+    exposureAt?: (x: number, y: number, z: number) => number;
+    seed?: number;
+    color?: THREE.ColorRepresentation;
+}
+/** Bounded ground ripples sharing precipitation intensity and authoritative animation time.
+ * @capability rain-ground-ripples Render bounded rain impacts on exposed terrain using the shared precipitation clock.
+ */
+export declare function RainImpactField({ count, extent, heightAt, exposureAt, seed, color }: RainImpactFieldProps): import("react").JSX.Element;

package/dist/weather/RainImpactField.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
+import { createWeatherQuadGeometry } from "./weatherGeometry.js";
+import { useWeatherUniformSet } from "./weatherUniforms.js";
+/** Bounded ground ripples sharing precipitation intensity and authoritative animation time.
+ * @capability rain-ground-ripples Render bounded rain impacts on exposed terrain using the shared precipitation clock.
+ */
+export function RainImpactField({ count = 64, extent = 48, heightAt, exposureAt, seed = 11939, color = "#b8c4d8" }) {
+    const capacity = Math.max(0, Math.min(256, Math.floor(Number.isFinite(count) ? count : 64)));
+    const size = Math.max(1, Number.isFinite(extent) ? extent : 48);
+    const shared = useWeatherUniformSet();
+    const geometry = useDisposable(() => {
+        const value = createWeatherQuadGeometry(capacity, seed);
+        value.setAttribute("aGround", new THREE.InstancedBufferAttribute(new Float32Array(capacity), 1));
+        value.setAttribute("aExposure", new THREE.InstancedBufferAttribute(new Float32Array(capacity), 1));
+        value.instanceCount = capacity;
+        return value;
+    }, [capacity, seed]);
+    const material = useDisposable(() => new THREE.ShaderMaterial({
+        transparent: true,
+        side: THREE.DoubleSide,
+        depthWrite: false,
+        uniforms: { uTime: shared.time, uRain: shared.rain, uAnchor: { value: new THREE.Vector2() }, uExtent: { value: size }, uColor: { value: new THREE.Color(color) } },
+        vertexShader: `
+      uniform float uTime;
+      uniform float uExtent;
+      uniform vec2 uAnchor;
+      attribute vec3 aSpawn;
+      attribute float aDrift;
+      attribute float aGround;
+      attribute float aExposure;
+      varying vec2 vUv;
+      varying float vPhase;
+      varying float vExposure;
+      void main() {
+        vUv = uv;
+        vPhase = fract(uTime * (1.6 + aDrift * 0.8) + aDrift);
+        vExposure = aExposure;
+        float radius = 0.08 + vPhase * 0.45;
+        vec2 center = uAnchor + (aSpawn.xz - 0.5) * uExtent;
+        vec3 world = vec3(center.x + position.x * radius, aGround + 0.015, center.y + position.y * radius);
+        gl_Position = projectionMatrix * viewMatrix * vec4(world, 1.0);
+      }
+    `,
+        fragmentShader: `
+      uniform float uRain;
+      uniform vec3 uColor;
+      varying vec2 vUv;
+      varying float vPhase;
+      varying float vExposure;
+      void main() {
+        float radius = length(vUv - 0.5) * 2.0;
+        float ring = smoothstep(0.65, 0.8, radius) * (1.0 - smoothstep(0.84, 1.0, radius));
+        float alpha = ring * (1.0 - vPhase) * min(1.0, uRain) * vExposure * 0.45;
+        if (alpha < 0.001) discard;
+        gl_FragColor = vec4(uColor, alpha);
+      }
+    `,
+    }), [shared, size, color]);
+    useFrame((state) => {
+        const anchorX = Math.round(state.camera.position.x / 8) * 8;
+        const anchorZ = Math.round(state.camera.position.z / 8) * 8;
+        material.uniforms.uAnchor.value.set(anchorX, anchorZ);
+        const spawn = geometry.getAttribute("aSpawn");
+        const ground = geometry.getAttribute("aGround");
+        const exposure = geometry.getAttribute("aExposure");
+        for (let i = 0; i < capacity; i += 1) {
+            const x = anchorX + (spawn.getX(i) - 0.5) * size;
+            const z = anchorZ + (spawn.getZ(i) - 0.5) * size;
+            const y = heightAt(x, z);
+            ground.setX(i, Number.isFinite(y) ? y : 0);
+            const open = exposureAt?.(x, y, z) ?? 1;
+            exposure.setX(i, Math.max(0, Math.min(1, Number.isFinite(open) ? open : 0)));
+        }
+        ground.needsUpdate = true;
+        exposure.needsUpdate = true;
+        const metrics = shared.metrics?.impacts;
+        if (metrics !== undefined) {
+            metrics.count = geometry.instanceCount;
+            metrics.capacity = geometry.getAttribute("aSpawn").count;
+            metrics.heightQueries = capacity;
+            metrics.exposureQueries = exposureAt === undefined ? 0 : capacity;
+            metrics.queryBudget = capacity * (exposureAt === undefined ? 1 : 2);
+        }
+    });
+    return _jsx("mesh", { geometry: geometry, material: material, frustumCulled: false, renderOrder: 9 });
+}

package/dist/weather/SnowField.d.ts

@@ -14,8 +14,9 @@ export interface SnowFieldProps {
     opacity?: number;
     color?: THREE.ColorRepresentation;
     timeScale?: number;
+    timeSeconds?: number | (() => number);
     seed?: number;
     renderOrder?: number;
     frustumCulled?: boolean;
 }
-export declare function SnowField({ count, density, budget, volume, wind, origin, followCamera, speed, size, sway, opacity, color, timeScale, seed, renderOrder, frustumCulled, }: SnowFieldProps): import("react").JSX.Element;
+export declare function SnowField({ count, density, budget, volume, wind, origin, followCamera, speed, size, sway, opacity, color, timeScale, timeSeconds, seed, renderOrder, frustumCulled, }: SnowFieldProps): import("react").JSX.Element;

package/dist/weather/SnowField.js

@@ -4,17 +4,21 @@ import * as THREE from "three";
 import { useDisposable } from "../render/useDisposable.js";
 import { createWeatherQuadGeometry } from "./weatherGeometry.js";
 import { DEFAULT_SNOW_COUNT, DEFAULT_SNOW_DENSITY, resolveWeatherInstanceCount } from "./weatherMath.js";
+import { WEATHER_SHELTER_SHADER } from "./weatherShelter.js";
 import { useWeatherUniformSet } from "./weatherUniforms.js";
 const DEFAULT_VOLUME = [52, 38, 52];
 const DEFAULT_ORIGIN = [0, 0, 0];
 const DEFAULT_SNOW_COLOR = "#ffffff";
-export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 3.2, size = 0.11, sway = 0.62, opacity = 0.86, color = DEFAULT_SNOW_COLOR, timeScale, seed = 72931, renderOrder = 11, frustumCulled, }) {
+export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 3.2, size = 0.11, sway = 0.62, opacity = 0.86, color = DEFAULT_SNOW_COLOR, timeScale, timeSeconds, seed = 72931, renderOrder = 11, frustumCulled, }) {
     const { camera } = useThree();
-    const shared = useWeatherUniformSet({ wind, timeScale });
+    const shared = useWeatherUniformSet({ wind, timeScale, timeSeconds });
     const geometry = useDisposable(() => createWeatherQuadGeometry(count, seed), [count, seed]);
     const material = useDisposable(() => {
         const uniforms = {
             uTime: shared.time,
+            uShelterCenters: shared.shelterCenters,
+            uShelterShapes: shared.shelterShapes,
+            uShelterCount: shared.shelterCount,
             uWind: shared.wind,
             uAnchor: { value: new THREE.Vector3() },
             uVolume: { value: new THREE.Vector3() },
@@ -30,6 +34,7 @@ export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_D
             depthWrite: false,
             blending: THREE.NormalBlending,
             vertexShader: `
+        ${WEATHER_SHELTER_SHADER}
         uniform float uTime;
         uniform vec3 uWind;
         uniform vec3 uAnchor;
@@ -41,6 +46,7 @@ export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_D
         attribute vec3 aSpawn;
         attribute float aDrift;
 
+        varying float vExposure;
         varying vec2 vUv;
         varying float vDrift;
 
@@ -58,6 +64,7 @@ export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_D
           ) * uSway * (0.45 + 0.55 * aDrift);
           vec3 local = aSpawn * uVolume + vec3(uWind.x, -fallSpeed, uWind.z) * uTime + wander;
           vec3 worldCenter = mod(local - origin, uVolume) + origin;
+          vExposure = weatherExposure(worldCenter);
           float flakeSize = uSize * (0.48 + 1.08 * aDrift);
           vec3 right = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
           vec3 up = vec3(viewMatrix[0][1], viewMatrix[1][1], viewMatrix[2][1]);
@@ -70,6 +77,7 @@ export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_D
         uniform float uOpacity;
         uniform vec3 uColor;
 
+        varying float vExposure;
         varying vec2 vUv;
         varying float vDrift;
 
@@ -78,6 +86,7 @@ export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_D
           float disc = smoothstep(1.0, 0.12, distanceFromCenter);
           float core = smoothstep(0.54, 0.0, distanceFromCenter) * 0.42;
           float alpha = (disc + core) * uOpacity * (0.56 + 0.44 * vDrift);
+          alpha *= vExposure;
           if (alpha < 0.001) discard;
           gl_FragColor = vec4(uColor, alpha);
         }
@@ -98,7 +107,12 @@ export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_D
         uniforms.uSway.value = sway;
         uniforms.uOpacity.value = opacity;
         uniforms.uColor.value.set(color);
-        geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
+        geometry.instanceCount = resolveWeatherInstanceCount(count, density * shared.snow.value, budget);
+        const metrics = shared.metrics?.snow;
+        if (metrics !== undefined) {
+            metrics.count = geometry.instanceCount;
+            metrics.capacity = geometry.getAttribute("aSpawn").count;
+        }
     });
     return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
 }

package/dist/weather/WeatherLayer.d.ts

@@ -1,8 +1,11 @@
 import type { ReactNode } from "react";
+import type { EditorVolume } from "@jgengine/core/editor/types";
+import type { AuthoredWeatherSample } from "@jgengine/core/world/authoredWeather";
 import { type DustFieldProps } from "./DustField.js";
 import { type RainFieldProps } from "./RainField.js";
+import { type RainImpactFieldProps } from "./RainImpactField.js";
 import { type SnowFieldProps } from "./SnowField.js";
-import { type WeatherVector } from "./weatherUniforms.js";
+import { type WeatherVector, type WeatherParticleMetrics } from "./weatherUniforms.js";
 /** `"mixed"` runs rain and snow together; `"dust"` is airborne particulate and composes with either via `dust`. */
 export type WeatherLayerMode = "clear" | "rain" | "snow" | "mixed" | "dust";
 export interface WeatherLayerProps {
@@ -11,13 +14,19 @@ export interface WeatherLayerProps {
     wind?: WeatherVector;
     lightning?: number;
     timeScale?: number;
+    timeSeconds?: number | (() => number);
+    /** Read authored conditions at the camera from the authoritative simulation clock. */
+    sample?: (x: number, z: number) => AuthoredWeatherSample;
+    shelters?: readonly EditorVolume[];
+    metrics?: WeatherParticleMetrics;
     rain?: Omit<RainFieldProps, "wind" | "lightning" | "timeScale"> | false;
     snow?: Omit<SnowFieldProps, "wind" | "timeScale"> | false;
     /** Airborne particulate. Drawn in `"dust"` mode, and alongside rain/snow whenever `dustAlways` is set. */
     dust?: Omit<DustFieldProps, "wind" | "timeScale"> | false;
     /** Keep dust in the air in every mode — a world that is dusty whatever else the sky is doing. */
     dustAlways?: boolean;
+    impacts?: RainImpactFieldProps | false;
     enabled?: boolean;
     children?: ReactNode;
 }
-export declare function WeatherLayer({ mode, intensity, wind, lightning, timeScale, rain, snow, dust, dustAlways, enabled, children, }: WeatherLayerProps): import("react").JSX.Element | null;
+export declare function WeatherLayer({ mode, intensity, wind, lightning, timeScale, timeSeconds, sample, shelters, metrics, rain, snow, dust, dustAlways, impacts, enabled, children, }: WeatherLayerProps): import("react").JSX.Element | null;

package/dist/weather/WeatherLayer.js

@@ -1,19 +1,43 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { DustField } from "./DustField.js";
 import { RainField } from "./RainField.js";
+import { RainImpactField } from "./RainImpactField.js";
 import { SnowField } from "./SnowField.js";
 import { WeatherUniformProvider } from "./weatherUniforms.js";
+function clearMetrics(metrics, layer) {
+    metrics[layer].count = 0;
+    metrics[layer].capacity = 0;
+    if (layer === "impacts") {
+        metrics.impacts.heightQueries = 0;
+        metrics.impacts.exposureQueries = 0;
+        metrics.impacts.queryBudget = 0;
+    }
+}
 function resolveLayerDensity(value, fallback, intensity) {
     return (value ?? fallback) * intensity;
 }
-export function WeatherLayer({ mode = "clear", intensity = 1, wind, lightning, timeScale, rain, snow, dust, dustAlways = false, enabled = true, children, }) {
-    if (!enabled)
+export function WeatherLayer({ mode = "clear", intensity = 1, wind, lightning, timeScale, timeSeconds, sample, shelters, metrics, rain, snow, dust, dustAlways = false, impacts, enabled = true, children, }) {
+    if (!enabled) {
+        if (metrics !== undefined)
+            for (const layer of ["rain", "snow", "dust", "impacts"])
+                clearMetrics(metrics, layer);
         return null;
+    }
     const rainProps = rain === false ? null : (rain ?? {});
     const snowProps = snow === false ? null : (snow ?? {});
-    const showRain = rainProps !== null && (mode === "rain" || mode === "mixed");
-    const showSnow = snowProps !== null && (mode === "snow" || mode === "mixed");
+    const showRain = rainProps !== null && (sample !== undefined || mode === "rain" || mode === "mixed");
+    const showSnow = snowProps !== null && (sample !== undefined || mode === "snow" || mode === "mixed");
     const dustProps = dust === false ? null : (dust ?? {});
-    const showDust = dustProps !== null && (mode === "dust" || dustAlways);
-    return (_jsxs(WeatherUniformProvider, { wind: wind, lightning: lightning, timeScale: timeScale, children: [showRain ? (_jsx(RainField, { ...rainProps, density: resolveLayerDensity(rainProps.density, 0.45, intensity) })) : null, showSnow ? (_jsx(SnowField, { ...snowProps, density: resolveLayerDensity(snowProps.density, 0.5, intensity) })) : null, showDust ? (_jsx(DustField, { ...dustProps, density: resolveLayerDensity(dustProps.density, 0.4, intensity) })) : null, children] }));
+    const showDust = dustProps !== null && (sample !== undefined || mode === "dust" || dustAlways);
+    if (metrics !== undefined) {
+        if (!showRain)
+            clearMetrics(metrics, "rain");
+        if (!showSnow)
+            clearMetrics(metrics, "snow");
+        if (!showDust)
+            clearMetrics(metrics, "dust");
+        if (!showRain || impacts === undefined || impacts === false)
+            clearMetrics(metrics, "impacts");
+    }
+    return (_jsxs(WeatherUniformProvider, { wind: wind, lightning: lightning, timeScale: timeScale, timeSeconds: timeSeconds, sample: sample, shelters: shelters, metrics: metrics, children: [showRain ? (_jsx(RainField, { ...rainProps, density: resolveLayerDensity(rainProps.density, 0.45, intensity) })) : null, showSnow ? (_jsx(SnowField, { ...snowProps, density: resolveLayerDensity(snowProps.density, 0.5, intensity) })) : null, showDust ? (_jsx(DustField, { ...dustProps, density: resolveLayerDensity(dustProps.density, 0.4, intensity) })) : null, showRain && impacts !== undefined && impacts !== false ? _jsx(RainImpactField, { ...impacts }) : null, children] }));
 }

package/dist/weather/index.d.ts

@@ -1,4 +1,6 @@
 export { DustField, type DustFieldProps } from "./DustField.js";
+export { AuthoredWeatherLayer, type AuthoredWeatherLayerProps } from "./AuthoredWeatherLayer.js";
+export { RainImpactField, type RainImpactFieldProps } from "./RainImpactField.js";
 export { FireSpreadLayer, type FireSpreadLayerProps } from "./FireSpreadLayer.js";
 export { LightningStrike, type LightningStrikeProps } from "./LightningStrike.js";
 export { RainField, type RainFieldProps } from "./RainField.js";

package/dist/weather/index.js

@@ -1,4 +1,6 @@
 export { DustField } from "./DustField.js";
+export { AuthoredWeatherLayer } from "./AuthoredWeatherLayer.js";
+export { RainImpactField } from "./RainImpactField.js";
 export { FireSpreadLayer } from "./FireSpreadLayer.js";
 export { LightningStrike } from "./LightningStrike.js";
 export { RainField } from "./RainField.js";

package/dist/weather/weatherMath.d.ts

@@ -16,3 +16,5 @@ export interface WeatherSeedAttributes {
 }
 /** @internal */
 export declare function createWeatherSeedAttributes(maxCount: number, seed: number): WeatherSeedAttributes;
+/** @internal */
+export declare function lightningStrikeEnvelope(timeSeconds: number, startedAt: number, duration: number, seed: number): number;

package/dist/weather/weatherMath.js

@@ -40,3 +40,11 @@ export function createWeatherSeedAttributes(maxCount, seed) {
     }
     return { spawn, drift };
 }
+/** @internal */
+export function lightningStrikeEnvelope(timeSeconds, startedAt, duration, seed) {
+    const elapsed = timeSeconds - startedAt;
+    if (elapsed < 0 || duration <= 0 || elapsed >= duration)
+        return 0;
+    const flicker = 0.62 + (Math.sin(elapsed * 97 + seed) * 0.5 + 0.5) * 0.38;
+    return (1 - elapsed / duration) * flicker;
+}

package/dist/weather/weatherShelter.d.ts

@@ -0,0 +1,18 @@
+import * as THREE from "three";
+import type { EditorVolume } from "@jgengine/core/editor/types";
+/** Cosmetic roof clipping is bounded independently of authoritative shelter queries. */
+export declare const WEATHER_SHELTER_BUDGET = 32;
+/** Reusable buffers for the nearest authored shelters submitted to weather shaders. */
+export interface WeatherShelterUniforms {
+    shelterCenters: THREE.IUniform<THREE.Vector4[]>;
+    shelterShapes: THREE.IUniform<THREE.Vector4[]>;
+    shelterCount: THREE.IUniform<number>;
+    shelterIndices: Int32Array;
+    shelterDistances: Float64Array;
+}
+/** @internal */
+export declare function createWeatherShelterUniforms(): WeatherShelterUniforms;
+/** @internal */
+export declare function updateWeatherShelters(uniforms: WeatherShelterUniforms, shelters: readonly EditorVolume[], x: number, y: number, z: number): void;
+/** @internal */
+export declare const WEATHER_SHELTER_SHADER = "\n  uniform vec4 uShelterCenters[32];\n  uniform vec4 uShelterShapes[32];\n  uniform int uShelterCount;\n  float weatherExposure(vec3 point) {\n    float exposure = 1.0;\n    for (int i = 0; i < 32; i++) {\n      if (i >= uShelterCount) break;\n      vec4 center = uShelterCenters[i];\n      vec4 shape = uShelterShapes[i];\n      vec3 delta = abs(point - center.xyz);\n      bool inside = center.w < 0.5 ? all(lessThanEqual(delta, shape.xyz)) : center.w < 1.5 ? length(delta) <= shape.x : length(delta.xz) <= shape.x && delta.y <= shape.y;\n      if (inside) exposure = min(exposure, shape.w);\n    }\n    return exposure;\n  }\n";