@jgengine/shell 0.18.1 → 0.21.0

package/dist/vfx/ParticleField.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
-import { useEffect, useMemo, useRef } from "react";
+import { useEffect, useMemo } from "react";
 import * as THREE from "three";
 const VERTEX_SHADER = /* glsl */ `
   attribute float aSize;
@@ -21,71 +21,189 @@ const FRAGMENT_SHADER = /* glsl */ `
   varying float vAlpha;
   varying vec3 vColor;
   void main() {
-    // Soft round sprite: radial falloff from the point center, discard the corners.
-    vec2 d = gl_PointCoord - vec2(0.5);
-    float r = length(d);
+    float r = length(gl_PointCoord - vec2(0.5));
     if (r > 0.5) discard;
-    float soft = smoothstep(0.5, 0.0, r);
-    gl_FragColor = vec4(vColor, vAlpha * soft);
+    gl_FragColor = vec4(vColor, vAlpha * smoothstep(0.5, 0.0, r));
   }
 `;
+const QUAD_VERTEX = /* glsl */ `
+  attribute vec3 aCenter;
+  attribute vec3 aEnd;
+  attribute vec3 aVelocity;
+  attribute float aId;
+  attribute float aSize;
+  attribute float aAlpha;
+  attribute vec3 aColor;
+  uniform float uShape;
+  uniform float uStretch;
+  varying vec2 vUv;
+  varying float vAlpha;
+  varying vec3 vColor;
+  void main() {
+    vUv = uv;
+    vAlpha = aAlpha;
+    vColor = aColor;
+    vec4 center = modelViewMatrix * vec4(aCenter, 1.0);
+    vec4 view = center;
+    if (uShape == 1.0 || uShape == 5.0) {
+      vec3 end = uShape == 5.0 ? aEnd : aCenter - aVelocity * uStretch;
+      vec4 tail = modelViewMatrix * vec4(end, 1.0);
+      vec2 delta = center.xy - tail.xy;
+      float len = length(delta);
+      vec2 side = len > 0.00001 ? vec2(-delta.y, delta.x) / len : vec2(1.0, 0.0);
+      view = mix(tail, center, uv.y);
+      view.xy += side * position.x * aSize;
+    } else if (uShape == 6.0) {
+      view = modelViewMatrix * vec4(aCenter + vec3(position.x, 0.002, position.y) * aSize * 2.0, 1.0);
+    } else {
+      vec2 corner = position.xy * aSize;
+      if (uShape == 2.0) {
+        float angle = aId * 2.399963;
+        corner = mat2(cos(angle), -sin(angle), sin(angle), cos(angle)) * corner;
+      }
+      if (uShape == 3.0) {
+        corner.y *= 2.7;
+        corner.x += sin(aId * 1.7 + uv.y * 7.0) * aSize * 0.14 * uv.y;
+      }
+      if (uShape == 4.0) corner *= 1.65;
+      view.xy += corner;
+    }
+    gl_Position = projectionMatrix * view;
+  }
+`;
+const QUAD_FRAGMENT = /* glsl */ `
+  uniform float uShape;
+  varying vec2 vUv;
+  varying float vAlpha;
+  varying vec3 vColor;
+  void main() {
+    vec2 d = vUv - 0.5;
+    float alpha;
+    if (uShape == 1.0 || uShape == 5.0) {
+      alpha = smoothstep(0.5, 0.0, abs(d.x)) * smoothstep(0.0, 0.12, vUv.y) * smoothstep(1.0, 0.7, vUv.y);
+    } else if (uShape == 2.0) {
+      float angle = atan(d.y, d.x);
+      float edge = 0.26 + 0.12 * pow(abs(cos(angle * 3.0)), 4.0);
+      alpha = smoothstep(edge, edge * 0.62, length(d));
+    } else if (uShape == 3.0) {
+      float width = (1.0 - vUv.y) * 0.42 + 0.04;
+      alpha = smoothstep(width, 0.0, abs(d.x)) * smoothstep(0.0, 0.18, vUv.y) * smoothstep(1.0, 0.5, vUv.y);
+    } else if (uShape == 6.0) {
+      float r = length(d);
+      alpha = smoothstep(0.07, 0.0, abs(r - 0.38));
+    } else {
+      float r = length(d);
+      alpha = smoothstep(0.5, 0.08, r);
+      if (uShape == 4.0) alpha *= 0.65 + 0.35 * sin(vUv.x * 15.0 + sin(vUv.y * 12.0));
+    }
+    alpha *= vAlpha;
+    if (alpha < 0.001) discard;
+    gl_FragColor = vec4(vColor, alpha);
+  }
+`;
+const SHAPES = { point: 0, streak: 1, flake: 2, flame: 3, smoke: 4, ribbon: 5, ripple: 6 };
 /**
- * Renders a core `ParticleSystem` as a GPU point cloud: one draw call, per-particle
- * size / color / alpha via a soft-round shader, and a `drawRange` clamped to the live
- * count so dead particles cost nothing. The simulation stays engine-side and
- * genre-agnostic; this is purely how it reaches the screen. By default it advances
- * the sim with the frame delta — pass `advance={false}` to drive it from your own
- * fixed loop instead.
- *
- * @capability particle-field render a core particle system as a soft-point GPU cloud with per-particle size, color, and alpha
+ * Render one pooled simulation through a point cloud or instanced quads. Output
+ * selection does not replace spawn, forces, collisions, or deterministic state.
+ * @capability particle-field render a core particle pool as soft points, velocity streaks, connected ribbons, flakes, flames, smoke sprites, or ground ripples
  */
-export function ParticleField({ system, advance = true, blending = "additive", scale = 300, depthWrite = false, }) {
-    const pointsRef = useRef(null);
+export function ParticleField({ system, advance = true, blending = "additive", scale = 300, depthWrite = false, render, metrics }) {
     const dpr = useThree((state) => state.viewport.dpr);
-    const { geometry, material } = useMemo(() => {
-        const initial = system.buffers();
-        const max = initial.positions.length / 3;
-        const geo = new THREE.BufferGeometry();
-        geo.setAttribute("position", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
-        geo.setAttribute("aSize", new THREE.BufferAttribute(new Float32Array(max), 1));
-        geo.setAttribute("aColor", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
-        geo.setAttribute("aAlpha", new THREE.BufferAttribute(new Float32Array(max), 1));
-        geo.setDrawRange(0, 0);
-        const mat = new THREE.ShaderMaterial({
-            vertexShader: VERTEX_SHADER,
-            fragmentShader: FRAGMENT_SHADER,
-            uniforms: { uScale: { value: scale } },
-            transparent: true,
-            depthWrite,
-            blending: blending === "additive" ? THREE.AdditiveBlending : THREE.NormalBlending,
-        });
-        return { geometry: geo, material: mat };
-    }, [system, scale, depthWrite, blending]);
+    const shape = render?.shape ?? "point";
+    const quad = shape !== "point";
+    const { geometry, material, indexById } = useMemo(() => {
+        const max = system.buffers().positions.length / 3;
+        const geo = quad ? new THREE.InstancedBufferGeometry() : new THREE.BufferGeometry();
+        if (quad) {
+            geo.setAttribute("position", new THREE.Float32BufferAttribute([-0.5, -0.5, 0, 0.5, -0.5, 0, 0.5, 0.5, 0, -0.5, 0.5, 0], 3));
+            geo.setAttribute("uv", new THREE.Float32BufferAttribute([0, 0, 1, 0, 1, 1, 0, 1], 2));
+            geo.setIndex([0, 1, 2, 0, 2, 3]);
+            geo.setAttribute("aCenter", new THREE.InstancedBufferAttribute(new Float32Array(max * 3), 3));
+            geo.setAttribute("aEnd", new THREE.InstancedBufferAttribute(new Float32Array(max * 3), 3));
+            geo.setAttribute("aVelocity", new THREE.InstancedBufferAttribute(new Float32Array(max * 3), 3));
+            geo.setAttribute("aId", new THREE.InstancedBufferAttribute(new Float32Array(max), 1));
+            geo.instanceCount = 0;
+        }
+        else {
+            geo.setAttribute("position", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
+            geo.setDrawRange(0, 0);
+        }
+        const attribute = (array, size) => quad ? new THREE.InstancedBufferAttribute(array, size) : new THREE.BufferAttribute(array, size);
+        geo.setAttribute("aSize", attribute(new Float32Array(max), 1));
+        geo.setAttribute("aColor", attribute(new Float32Array(max * 3), 3));
+        geo.setAttribute("aAlpha", attribute(new Float32Array(max), 1));
+        const mat = new THREE.ShaderMaterial({ vertexShader: quad ? QUAD_VERTEX : VERTEX_SHADER, fragmentShader: quad ? QUAD_FRAGMENT : FRAGMENT_SHADER,
+            uniforms: { uScale: { value: scale }, uShape: { value: SHAPES[shape] }, uStretch: { value: render?.stretch ?? 0.08 } },
+            transparent: true, depthWrite, side: THREE.DoubleSide,
+            blending: blending === "additive" ? THREE.AdditiveBlending : THREE.NormalBlending });
+        return { geometry: geo, material: mat, indexById: new Map() };
+    }, [system, quad, shape, scale, depthWrite, blending]);
     useEffect(() => {
+        const bytes = Object.values(geometry.attributes).reduce((total, attribute) => total + attribute.array.byteLength, geometry.index?.array.byteLength ?? 0);
+        if (metrics !== undefined) {
+            metrics.fieldsMounted++;
+            metrics.liveFields++;
+            metrics.attributeBytes += bytes;
+        }
         return () => {
             geometry.dispose();
             material.dispose();
+            if (metrics !== undefined) {
+                metrics.fieldsUnmounted++;
+                metrics.liveFields--;
+                metrics.attributeBytes -= bytes;
+            }
         };
-    }, [geometry, material]);
+    }, [geometry, material, metrics]);
     useFrame((_, delta) => {
+        const started = metrics === undefined ? 0 : performance.now();
         if (advance)
             system.update(Math.min(delta, 0.1));
         const buffers = system.buffers();
         const count = buffers.count;
-        const pos = geometry.getAttribute("position");
-        const size = geometry.getAttribute("aSize");
-        const color = geometry.getAttribute("aColor");
-        const alpha = geometry.getAttribute("aAlpha");
-        pos.array.set(buffers.positions.subarray(0, count * 3));
-        size.array.set(buffers.sizes.subarray(0, count));
-        color.array.set(buffers.colors.subarray(0, count * 3));
-        alpha.array.set(buffers.alphas.subarray(0, count));
-        pos.needsUpdate = true;
-        size.needsUpdate = true;
-        color.needsUpdate = true;
-        alpha.needsUpdate = true;
-        geometry.setDrawRange(0, count);
+        const upload = (name, values, n) => {
+            const attr = geometry.getAttribute(name);
+            attr.array.set(values.subarray(0, n));
+            attr.needsUpdate = true;
+        };
+        upload(quad ? "aCenter" : "position", buffers.positions, count * 3);
+        upload("aSize", buffers.sizes, count);
+        upload("aColor", buffers.colors, count * 3);
+        upload("aAlpha", buffers.alphas, count);
+        if (quad) {
+            upload("aVelocity", buffers.velocities, count * 3);
+            const end = geometry.getAttribute("aEnd");
+            const ids = geometry.getAttribute("aId");
+            if (shape === "ribbon") {
+                for (let i = 0; i < count; i++)
+                    indexById.set(buffers.ids[i], i);
+                for (const id of indexById.keys()) {
+                    const index = indexById.get(id);
+                    if (index >= count || buffers.ids[index] !== id)
+                        indexById.delete(id);
+                }
+            }
+            for (let i = 0; i < count; i++) {
+                ids.setX(i, buffers.ids[i]);
+                const previousIndex = shape === "ribbon" ? indexById.get(buffers.ids[i] - 1) : undefined;
+                const source = previousIndex === undefined ? buffers.previousPositions : buffers.positions;
+                const offset = (previousIndex ?? i) * 3;
+                end.setXYZ(i, source[offset], source[offset + 1], source[offset + 2]);
+            }
+            end.needsUpdate = true;
+            ids.needsUpdate = true;
+            geometry.instanceCount = count;
+        }
+        else
+            geometry.setDrawRange(0, count);
         material.uniforms.uScale.value = scale * dpr;
+        material.uniforms.uStretch.value = render?.stretch ?? 0.08;
+        if (metrics !== undefined) {
+            const elapsed = performance.now() - started;
+            metrics.totalUploadMs += elapsed;
+            metrics.maxUploadMs = Math.max(metrics.maxUploadMs, elapsed);
+            metrics.uploadSamples++;
+        }
     });
-    return _jsx("points", { ref: pointsRef, geometry: geometry, material: material, frustumCulled: false });
+    return quad ? _jsx("mesh", { geometry: geometry, material: material, frustumCulled: false }) : _jsx("points", { geometry: geometry, material: material, frustumCulled: false });
 }

package/dist/visibility/CullingProvider.js

@@ -3,7 +3,7 @@ import { createContext, useContext, useMemo, useRef } from "react";
 import { useThree, useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
-import { createVisibilitySystem } from "@jgengine/core/visibility/visibilitySystem";
+import { buildCullingDriver } from "./cullingDriver.js";
 import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
 const ALWAYS_VISIBLE = () => true;
 const alwaysVisibleRef = { current: ALWAYS_VISIBLE };
@@ -16,66 +16,6 @@ const CullingContext = createContext(null);
 export function useRenderVisibility() {
     return useContext(CullingContext) ?? alwaysVisibleRef;
 }
-const ENTITY_BOUNDS = { kind: "sphere", radius: 2, offset: [0, 1, 0] };
-function objectRadius(scale) {
-    if (scale === undefined)
-        return 1;
-    const s = typeof scale === "number" ? scale : Math.max(scale[0], scale[1], scale[2]);
-    return Math.max(0.75, s);
-}
-function buildSystem(ctx, config) {
-    const versions = new Map();
-    let currentView = null;
-    const scratch = { id: "", position: [0, 0, 0], version: 0 };
-    const objectSpec = { kind: "sphere", radius: 1, offset: [0, 0.5, 0] };
-    function bump(id, position, rot) {
-        const prev = versions.get(id);
-        if (prev !== undefined && prev.x === position[0] && prev.y === position[1] && prev.z === position[2] && prev.rot === rot) {
-            return prev.version;
-        }
-        const version = (prev?.version ?? 0) + 1;
-        versions.set(id, { x: position[0], y: position[1], z: position[2], rot, version });
-        return version;
-    }
-    function* renderables() {
-        const entityOverrides = config?.entities;
-        for (const entity of ctx.scene.entity.list()) {
-            scratch.id = entity.id;
-            scratch.position = entity.position;
-            scratch.version = bump(entity.id, entity.position, entity.rotationY);
-            scratch.bounds = ENTITY_BOUNDS;
-            scratch.overrides = entityOverrides?.[entity.name];
-            scratch.layer = "entity";
-            yield scratch;
-        }
-        const objectOverrides = config?.objects;
-        for (const object of ctx.scene.object.list()) {
-            scratch.id = object.instanceId;
-            scratch.position = object.position;
-            scratch.version = bump(object.instanceId, object.position, object.rotationY);
-            objectSpec.radius = objectRadius(object.visual?.scale);
-            scratch.bounds = objectSpec;
-            scratch.overrides = objectOverrides?.[object.catalogId];
-            scratch.layer = "object";
-            yield scratch;
-        }
-    }
-    const cameras = () => (currentView === null ? EMPTY_CAMERAS : [{ id: "main", view: currentView }]);
-    const options = {
-        renderables,
-        cameras,
-        ...(config?.culling !== undefined ? { settings: config.culling } : {}),
-        ...(config?.scene !== undefined ? { sceneOverrides: config.scene } : {}),
-    };
-    const system = createVisibilitySystem(options);
-    return {
-        system,
-        setView(view) {
-            currentView = view;
-        },
-    };
-}
-const EMPTY_CAMERAS = [];
 const tmpDir = new THREE.Vector3();
 function viewFromCamera(camera) {
     camera.getWorldDirection(tmpDir);
@@ -120,7 +60,7 @@ export function CullingProvider({ config, drawDistance, children }) {
             return config;
         return { ...config, culling: { ...config?.culling, defaultMaxRenderDistance: config?.culling?.defaultMaxRenderDistance ?? drawDistance } };
     }, [config, drawDistance]);
-    const driver = useMemo(() => (enabled ? buildSystem(ctx, resolvedConfig) : null), [ctx, resolvedConfig, enabled]);
+    const driver = useMemo(() => (enabled ? buildCullingDriver(ctx, resolvedConfig) : null), [ctx, resolvedConfig, enabled]);
     useFrame(() => {
         if (driver === null) {
             predicateRef.current = ALWAYS_VISIBLE;

package/dist/visibility/cullingDriver.d.ts

@@ -0,0 +1,9 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { CameraView } from "@jgengine/core/visibility/frustum";
+import type { VisibilityConfig } from "@jgengine/core/visibility/config";
+/** Builds the shell's live scene adapter for headless visibility. @internal */
+export declare function buildCullingDriver(ctx: GameContext, config: VisibilityConfig | undefined): {
+    system: import("@jgengine/core/visibility/visibilitySystem").VisibilitySystem;
+    setView(view: CameraView | null): void;
+    trackedCount(): number;
+};

package/dist/visibility/cullingDriver.js

@@ -0,0 +1,68 @@
+import { createVisibilitySystem } from "@jgengine/core/visibility/visibilitySystem";
+const ENTITY_BOUNDS = { kind: "sphere", radius: 2, offset: [0, 1, 0] };
+const EMPTY_CAMERAS = [];
+function objectRadius(scale) {
+    if (scale === undefined)
+        return 1;
+    const size = typeof scale === "number" ? Math.abs(scale) : Math.max(Math.abs(scale[0]), Math.abs(scale[1]), Math.abs(scale[2]));
+    return Math.max(0.75, size);
+}
+/** Builds the shell's live scene adapter for headless visibility. @internal */
+export function buildCullingDriver(ctx, config) {
+    const entries = new Map();
+    let frame = 0;
+    let currentView = null;
+    function update(id, position, rotation, radius, overrides, layer) {
+        let entry = entries.get(id);
+        if (entry === undefined) {
+            entry = { renderable: { id, position, version: 0 }, bounds: { kind: "sphere", radius, offset: [0, 0.5, 0] }, x: NaN, y: NaN, z: NaN, rotation: NaN, radius: NaN, seen: frame };
+            entries.set(id, entry);
+        }
+        const previous = entry.renderable;
+        const changed = entry.x !== position[0] || entry.y !== position[1] || entry.z !== position[2] || entry.rotation !== rotation || entry.radius !== radius || previous.overrides !== overrides || previous.layer !== layer;
+        if (changed) {
+            // A retained renderable must belong to one row: the core may keep it for always-visible processing.
+            entry.bounds.radius = radius;
+            previous.position = position;
+            previous.version += 1;
+            previous.bounds = layer === "entity" ? ENTITY_BOUNDS : entry.bounds;
+            previous.overrides = overrides;
+            previous.layer = layer;
+            entry.x = position[0];
+            entry.y = position[1];
+            entry.z = position[2];
+            entry.rotation = rotation;
+            entry.radius = radius;
+        }
+        entry.seen = frame;
+        return entry.renderable;
+    }
+    function* renderables() {
+        frame += 1;
+        for (const entity of ctx.scene.entity.list()) {
+            yield update(entity.id, entity.position, entity.rotationY, 2, config?.entities?.[entity.name], "entity");
+        }
+        for (const object of ctx.scene.object.list()) {
+            yield update(object.instanceId, object.position, object.rotationY, objectRadius(object.visual?.scale), config?.objects?.[object.catalogId], "object");
+        }
+        for (const [id, entry] of entries) {
+            if (entry.seen !== frame)
+                entries.delete(id);
+        }
+    }
+    const system = createVisibilitySystem({
+        renderables,
+        cameras: () => currentView === null ? EMPTY_CAMERAS : [{ id: "main", view: currentView }],
+        ...(config?.culling !== undefined ? { settings: config.culling } : {}),
+        ...(config?.scene !== undefined ? { sceneOverrides: config.scene } : {}),
+    });
+    return {
+        system,
+        setView(view) {
+            currentView = view;
+        },
+        trackedCount() {
+            return entries.size;
+        },
+    };
+}

package/dist/weather/AuthoredWeatherLayer.d.ts

@@ -0,0 +1,16 @@
+import type { EditorDocument } from "@jgengine/core/editor/types";
+import { type WeatherLayerProps } from "./WeatherLayer.js";
+/** Authored weather document and optional precipitation appearance and ground sampling. */
+export interface AuthoredWeatherLayerProps {
+    document: EditorDocument;
+    rain?: WeatherLayerProps["rain"];
+    snow?: WeatherLayerProps["snow"];
+    dust?: WeatherLayerProps["dust"];
+    heightAt?: (x: number, z: number) => number;
+    /** Register actual procedural weather pool and impact query counters. */
+    diagnostics?: boolean;
+}
+/** Render pooled precipitation from the same authored document and clock as gameplay.
+ * @capability authored-weather-rendering Render authored weather from shared gameplay samples, simulation time and shelter volumes.
+ */
+export declare function AuthoredWeatherLayer({ document, rain, snow, dust, heightAt, diagnostics }: AuthoredWeatherLayerProps): import("react").JSX.Element | null;

package/dist/weather/AuthoredWeatherLayer.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useGameContext } from "@jgengine/react/provider";
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { warnOnce } from "@jgengine/core/devtools/warnOnce";
+import { WEATHER_SHELTER_BUDGET } from "./weatherShelter.js";
+import { WeatherLayer } from "./WeatherLayer.js";
+/** Render pooled precipitation from the same authored document and clock as gameplay.
+ * @capability authored-weather-rendering Render authored weather from shared gameplay samples, simulation time and shelter volumes.
+ */
+export function AuthoredWeatherLayer({ document, rain, snow, dust, heightAt, diagnostics = false }) {
+    const ctx = useGameContext();
+    const config = document.simulation?.weather;
+    const metrics = useRef({ rain: { count: 0, capacity: 0 }, snow: { count: 0, capacity: 0 }, dust: { count: 0, capacity: 0 }, impacts: { count: 0, capacity: 0, heightQueries: 0, exposureQueries: 0, queryBudget: 0 } });
+    const mounted = config !== undefined;
+    useEffect(() => {
+        if (!diagnostics || !mounted)
+            return;
+        return devtools.probes.register("weatherParticles", () => ({ scope: "procedural-weather", ...structuredClone(metrics.current) }));
+    }, [diagnostics, mounted]);
+    const shelters = useMemo(() => document.volumes.filter((volume) => volume.kind === "shelter"), [document.volumes]);
+    useEffect(() => {
+        if (shelters.length > WEATHER_SHELTER_BUDGET)
+            warnOnce("weather-shelter-budget", `[jgengine] Weather renders the closest ${WEATHER_SHELTER_BUDGET} of ${shelters.length} shelters; gameplay uses all authored shelters.`);
+    }, [shelters.length]);
+    const sample = useCallback((x, z) => ctx.environment.sample(x, z), [ctx.environment]);
+    const exposureAt = useCallback((x, y, z) => ctx.environment.exposureAt(x, y, z), [ctx.environment]);
+    if (config === undefined)
+        return null;
+    return _jsx(WeatherLayer, { sample: sample, metrics: diagnostics ? metrics.current : undefined, shelters: shelters, rain: rain, snow: snow, dust: dust, impacts: heightAt === undefined ? false : { heightAt, exposureAt } });
+}

package/dist/weather/DustField.d.ts

@@ -26,6 +26,7 @@ export interface DustFieldProps {
      */
     groundBias?: number;
     timeScale?: number;
+    timeSeconds?: number | (() => number);
     seed?: number;
     renderOrder?: number;
     frustumCulled?: boolean;
@@ -38,4 +39,4 @@ export interface DustFieldProps {
  *
  * @capability weather-dust airborne particulate that turns still air into visible wind
  */
-export declare function DustField({ count, density, budget, volume, wind, origin, followCamera, speed, size, sway, opacity, color, groundBias, timeScale, seed, renderOrder, frustumCulled, }: DustFieldProps): import("react").JSX.Element;
+export declare function DustField({ count, density, budget, volume, wind, origin, followCamera, speed, size, sway, opacity, color, groundBias, timeScale, timeSeconds, seed, renderOrder, frustumCulled, }: DustFieldProps): import("react").JSX.Element;

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;