@jgengine/shell 0.19.0 → 0.22.0

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";

package/dist/weather/weatherShelter.js

@@ -0,0 +1,75 @@
+import * as THREE from "three";
+/** Cosmetic roof clipping is bounded independently of authoritative shelter queries. */
+export const WEATHER_SHELTER_BUDGET = 32;
+/** @internal */
+export function createWeatherShelterUniforms() {
+    return {
+        shelterCenters: { value: Array.from({ length: WEATHER_SHELTER_BUDGET }, () => new THREE.Vector4()) },
+        shelterShapes: { value: Array.from({ length: WEATHER_SHELTER_BUDGET }, () => new THREE.Vector4()) },
+        shelterCount: { value: 0 },
+        shelterIndices: new Int32Array(WEATHER_SHELTER_BUDGET),
+        shelterDistances: new Float64Array(WEATHER_SHELTER_BUDGET),
+    };
+}
+/** @internal */
+export function updateWeatherShelters(uniforms, shelters, x, y, z) {
+    const indices = uniforms.shelterIndices;
+    const distances = uniforms.shelterDistances;
+    distances.fill(Infinity);
+    indices.fill(-1);
+    for (let index = 0; index < shelters.length; index += 1) {
+        const shelter = shelters[index];
+        if (shelter.kind !== "shelter")
+            continue;
+        const hx = shelter.shape === "box" ? shelter.halfExtents?.x ?? 0 : shelter.radius ?? 0;
+        const hy = shelter.shape === "box" ? shelter.halfExtents?.y ?? 0 : shelter.shape === "sphere" ? shelter.radius ?? 0 : (shelter.height ?? 0) * 0.5;
+        const hz = shelter.shape === "box" ? shelter.halfExtents?.z ?? 0 : shelter.radius ?? 0;
+        const dx = Math.max(0, Math.abs(x - shelter.center.x) - hx);
+        const dy = Math.max(0, Math.abs(y - shelter.center.y) - hy);
+        const dz = Math.max(0, Math.abs(z - shelter.center.z) - hz);
+        const distance = dx * dx + dy * dy + dz * dz;
+        for (let slot = 0; slot < WEATHER_SHELTER_BUDGET; slot += 1) {
+            if (distance >= distances[slot])
+                continue;
+            for (let move = WEATHER_SHELTER_BUDGET - 1; move > slot; move -= 1) {
+                distances[move] = distances[move - 1];
+                indices[move] = indices[move - 1];
+            }
+            distances[slot] = distance;
+            indices[slot] = index;
+            break;
+        }
+    }
+    let count = 0;
+    for (let slot = 0; slot < WEATHER_SHELTER_BUDGET; slot += 1) {
+        const index = indices[slot];
+        if (index < 0)
+            break;
+        const shelter = shelters[index];
+        const center = shelter.center;
+        uniforms.shelterCenters.value[slot].set(center.x, center.y, center.z, shelter.shape === "box" ? 0 : shelter.shape === "sphere" ? 1 : 2);
+        const exposure = typeof shelter.meta?.exposure === "number" ? Math.max(0, Math.min(1, shelter.meta.exposure)) : 0;
+        const extents = shelter.halfExtents;
+        uniforms.shelterShapes.value[slot].set(shelter.shape === "box" ? extents?.x ?? 0 : shelter.radius ?? 0, shelter.shape === "box" ? extents?.y ?? 0 : (shelter.height ?? 0) * 0.5, shelter.shape === "box" ? extents?.z ?? 0 : 0, exposure);
+        count += 1;
+    }
+    uniforms.shelterCount.value = count;
+}
+/** @internal */
+export const WEATHER_SHELTER_SHADER = `
+  uniform vec4 uShelterCenters[32];
+  uniform vec4 uShelterShapes[32];
+  uniform int uShelterCount;
+  float weatherExposure(vec3 point) {
+    float exposure = 1.0;
+    for (int i = 0; i < 32; i++) {
+      if (i >= uShelterCount) break;
+      vec4 center = uShelterCenters[i];
+      vec4 shape = uShelterShapes[i];
+      vec3 delta = abs(point - center.xyz);
+      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;
+      if (inside) exposure = min(exposure, shape.w);
+    }
+    return exposure;
+  }
+`;

package/dist/weather/weatherUniforms.d.ts

@@ -1,19 +1,58 @@
 import { type ReactNode } from "react";
 import * as THREE from "three";
+import type { EditorVolume } from "@jgengine/core/editor/types";
+import { type WeatherShelterUniforms } from "./weatherShelter.js";
+import type { AuthoredWeatherSample } from "@jgengine/core/world/authoredWeather";
 export type WeatherVector = readonly [number, number, number];
-export interface WeatherUniformSet {
+/** Actual procedural weather submissions and per-frame impact query work. */
+export interface WeatherParticleMetrics {
+    rain: {
+        count: number;
+        capacity: number;
+    };
+    snow: {
+        count: number;
+        capacity: number;
+    };
+    dust: {
+        count: number;
+        capacity: number;
+    };
+    impacts: {
+        count: number;
+        capacity: number;
+        heightQueries: number;
+        exposureQueries: number;
+        queryBudget: number;
+    };
+}
+export interface WeatherUniformSet extends WeatherShelterUniforms {
     time: THREE.IUniform<number>;
     wind: THREE.IUniform<THREE.Vector3>;
     lightning: THREE.IUniform<number>;
+    rain: THREE.IUniform<number>;
+    snow: THREE.IUniform<number>;
+    dust: THREE.IUniform<number>;
+    controlsWind: boolean;
+    metrics?: WeatherParticleMetrics;
 }
 export interface WeatherUniformOptions {
     wind?: WeatherVector;
     lightning?: number;
     timeScale?: number;
+    /** Absolute authoritative simulation seconds; no render delta is accumulated when supplied. */
+    timeSeconds?: number | (() => number);
+    sample?: (x: number, z: number) => AuthoredWeatherSample;
+    /** The closest 32 authored shelter volumes clip cosmetic particles. */
+    shelters?: readonly EditorVolume[];
+    /** Opt-in counters read from submitted geometry and actual query calls. */
+    metrics?: WeatherParticleMetrics;
 }
 /** @internal */
 export declare function createWeatherUniformSet(options?: WeatherUniformOptions): WeatherUniformSet;
 /** @internal */
+export declare function updateWeatherUniformSet(uniforms: WeatherUniformSet, options: WeatherUniformOptions, delta: number, x?: number, z?: number, y?: number): void;
+/** @internal */
 export declare function WeatherUniformProvider({ children, ...options }: WeatherUniformOptions & {
     children: ReactNode;
 }): import("react").JSX.Element;

package/dist/weather/weatherUniforms.js

@@ -2,25 +2,44 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useMemo } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
+import { createWeatherShelterUniforms, updateWeatherShelters } from "./weatherShelter.js";
 const WeatherUniformContext = createContext(null);
 /** @internal */
 export function createWeatherUniformSet(options = {}) {
     const wind = options.wind ?? [0, 0, 0];
     return {
-        time: { value: 0 },
+        ...createWeatherShelterUniforms(),
+        time: { value: typeof options.timeSeconds === "function" ? options.timeSeconds() : options.timeSeconds ?? 0 },
         wind: { value: new THREE.Vector3(wind[0], wind[1], wind[2]) },
         lightning: { value: options.lightning ?? 0 },
+        rain: { value: options.sample === undefined ? 1 : 0 },
+        snow: { value: options.sample === undefined ? 1 : 0 },
+        dust: { value: options.sample === undefined ? 1 : 0 },
+        controlsWind: options.wind !== undefined || options.sample !== undefined,
+        metrics: options.metrics,
     };
 }
+/** @internal */
+export function updateWeatherUniformSet(uniforms, options, delta, x = 0, z = 0, y = 0) {
+    const sample = options.sample?.(x, z);
+    const explicitTime = sample?.timeSeconds ?? (typeof options.timeSeconds === "function" ? options.timeSeconds() : options.timeSeconds);
+    uniforms.time.value = explicitTime ?? uniforms.time.value + delta * (options.timeScale ?? 1);
+    const wind = sample === undefined ? options.wind ?? [0, 0, 0] : [sample.wind[0], 0, sample.wind[1]];
+    uniforms.wind.value.set(wind[0], wind[1], wind[2]);
+    uniforms.lightning.value = sample?.lightning ?? options.lightning ?? 0;
+    uniforms.rain.value = sample?.rain ?? 1;
+    uniforms.snow.value = sample?.snow ?? 1;
+    uniforms.dust.value = sample?.dust ?? 1;
+    uniforms.controlsWind = options.wind !== undefined || options.sample !== undefined;
+    uniforms.metrics = options.metrics;
+    updateWeatherShelters(uniforms, options.shelters ?? [], x, y, z);
+}
 function useUniformTicker(uniforms, options, enabled = true) {
-    useFrame((_state, delta) => {
+    useFrame((state, delta) => {
         if (!enabled)
             return;
-        const wind = options.wind ?? [0, 0, 0];
-        uniforms.time.value += delta * (options.timeScale ?? 1);
-        uniforms.wind.value.set(wind[0], wind[1], wind[2]);
-        uniforms.lightning.value = options.lightning ?? 0;
-    });
+        updateWeatherUniformSet(uniforms, options, delta, state.camera.position.x, state.camera.position.z, state.camera.position.y);
+    }, -1);
 }
 /** @internal */
 export function WeatherUniformProvider({ children, ...options }) {
@@ -32,6 +51,7 @@ export function WeatherUniformProvider({ children, ...options }) {
 export function useWeatherUniformSet(options = {}) {
     const shared = useContext(WeatherUniformContext);
     const local = useMemo(() => createWeatherUniformSet(options), []);
-    useUniformTicker(local, options, shared === null);
-    return shared ?? local;
+    useUniformTicker(local, options, shared === null || (!shared.controlsWind && options.wind !== undefined));
+    const inherited = useMemo(() => shared === null ? local : { ...shared, wind: local.wind }, [shared, local]);
+    return shared === null ? local : !shared.controlsWind && options.wind !== undefined ? inherited : shared;
 }

package/dist/world/AuthoredFlocks.d.ts

@@ -0,0 +1,22 @@
+import { type ReactElement } from "react";
+import * as THREE from "three";
+import type { FlockStepAgent } from "@jgengine/core/ai/flock";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+/** Caller-owned species models for authored habitat agents. */
+export interface AuthoredFlocksProps {
+    models: Record<string, string | ModelConfig>;
+    assets?: AssetCatalog;
+    /** Model nose axis. Default -Z. */
+    forward?: readonly [number, number, number];
+    maxInstances?: number;
+}
+/** @internal Orient habitat agents from their full authoritative velocity. */
+export declare function applyFlockPose(group: THREE.Group, agent: FlockStepAgent, forward: THREE.Vector3, direction: THREE.Vector3): void;
+/**
+ * Render bounded authored habitat agents with game-selected species models. The
+ * environment owns movement and lifetime; existing model owners load, animate,
+ * and dispose the native GLB. Unmapped species have no substitute geometry.
+ * @capability authored-flocks render authored habitat agents through caller-selected animated species models with velocity orientation and bounded model lifetime
+ */
+export declare function AuthoredFlocks({ models, assets, forward, maxInstances }: AuthoredFlocksProps): ReactElement;

package/dist/world/AuthoredFlocks.js

@@ -0,0 +1,87 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useMemo, useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { IsolatedEntityModel } from "../render/SceneModels.js";
+import { resolveModel } from "../render/resolveModel.js";
+/** @internal Orient habitat agents from their full authoritative velocity. */
+export function applyFlockPose(group, agent, forward, direction) {
+    group.position.set(...agent.position);
+    direction.set(...agent.velocity);
+    if (direction.lengthSq() > 1e-12)
+        group.quaternion.setFromUnitVectors(forward, direction.normalize());
+}
+/**
+ * Render bounded authored habitat agents with game-selected species models. The
+ * environment owns movement and lifetime; existing model owners load, animate,
+ * and dispose the native GLB. Unmapped species have no substitute geometry.
+ * @capability authored-flocks render authored habitat agents through caller-selected animated species models with velocity orientation and bounded model lifetime
+ */
+export function AuthoredFlocks({ models, assets, forward = [0, 0, -1], maxInstances = 256 }) {
+    const ctx = useGameContext();
+    const speciesModels = useMemo(() => {
+        const resolved = new Map();
+        for (const [species, value] of Object.entries(models)) {
+            if (typeof value === "string" && assets === undefined)
+                throw new Error(`[jgengine] flock species ${species} requires an asset catalog to resolve ${value}`);
+            const model = typeof value === "string" ? resolveModel(value, assets) : value;
+            resolved.set(species, model.animation === undefined ? { ...model, animation: "auto" } : model);
+        }
+        return resolved;
+    }, [models, assets]);
+    const entries = useRef(new Map());
+    const seen = useRef(new Set());
+    const direction = useRef(new THREE.Vector3());
+    const nose = useRef(new THREE.Vector3());
+    const [, setGeneration] = useState(0);
+    nose.current.set(...forward).normalize();
+    if (nose.current.lengthSq() === 0)
+        nose.current.set(0, 0, -1);
+    const limit = Number.isFinite(maxInstances) ? Math.max(0, Math.min(1024, Math.floor(maxInstances))) : 256;
+    useFrame(() => {
+        let changed = false;
+        let count = 0;
+        seen.current.clear();
+        for (const flock of ctx.environment.flocks()) {
+            if (flock.role !== "cosmetic")
+                continue;
+            const model = speciesModels.get(flock.species);
+            if (model === undefined)
+                continue;
+            for (let i = 0; i < flock.agents.length && count < limit; i++, count++) {
+                const key = `${flock.id}:${i}`;
+                const agent = flock.agents[i];
+                seen.current.add(key);
+                const current = entries.current.get(key);
+                if (current === undefined) {
+                    entries.current.set(key, { agent, model, group: null });
+                    changed = true;
+                }
+                else {
+                    current.agent = agent;
+                    if (current.model !== model) {
+                        current.model = model;
+                        changed = true;
+                    }
+                    if (current.group !== null)
+                        applyFlockPose(current.group, agent, nose.current, direction.current);
+                }
+            }
+            if (count >= limit)
+                break;
+        }
+        for (const key of entries.current.keys())
+            if (!seen.current.has(key)) {
+                entries.current.delete(key);
+                changed = true;
+            }
+        if (changed)
+            setGeneration((n) => n + 1);
+    });
+    return _jsx(_Fragment, { children: Array.from(entries.current, ([key, entry]) => _jsx("group", { ref: (group) => {
+                entry.group = group;
+                if (group !== null)
+                    applyFlockPose(group, entry.agent, nose.current, direction.current);
+            }, children: _jsx(IsolatedEntityModel, { model: entry.model }) }, key)) });
+}

package/dist/world/StaticObjectModels.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from "react";
+import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import { type StaticObjectBatch } from "./staticObjectBatches.js";
+/** Render compatible authored props as shared model draws, preserving unsupported models. @internal */
+export declare function StaticObjectModels({ batch, single }: {
+    batch: StaticObjectBatch;
+    single: (object: SceneObject) => ReactNode;
+}): import("react").JSX.Element;

package/dist/world/StaticObjectModels.js

@@ -0,0 +1,75 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame, useLoader } from "@react-three/fiber";
+import { useEffect, useMemo, useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { sharedGltfLoader } from "../render/modelLoad.js";
+import { IsolatedModelPart } from "../render/SceneModels.js";
+import { measureLocalBounds, reportMeasuredBounds } from "../render/measureBounds.js";
+import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "../render/measureCollisionMesh.js";
+import { buildScatterModelSources, disposeScatterModelSources } from "../scatter/scatterModels.js";
+import { useRenderVisibility } from "../visibility/CullingProvider.js";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
+import { canInstanceStaticScene, incompatibleStaticObjectIds, isCompatibleStaticObject, syncStaticObjectSource } from "./staticObjectBatches.js";
+function ObjectSource({ source, objects, batch }) {
+    const ctx = useGameContext();
+    const visibility = useRenderVisibility();
+    const ref = useRef(null);
+    const scratch = useMemo(() => new THREE.Object3D(), []);
+    useEffect(() => {
+        const mesh = ref.current;
+        return () => { mesh?.dispose(); };
+    }, [objects.length, source]);
+    useFrame(() => {
+        if (ref.current !== null)
+            syncStaticObjectSource(ref.current, source, objects, (id) => {
+                const object = ctx.scene.object.get(id);
+                return object !== null && object.catalogId === batch.objects[0].catalogId &&
+                    isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
+            }, visibility.current, scratch);
+    }, CAMERA_POST_FRAME_PRIORITY + 0.1);
+    return _jsx("instancedMesh", { ref: ref, args: [source.geometry, source.material, objects.length], castShadow: source.castShadow, receiveShadow: source.receiveShadow, dispose: null });
+}
+function LoadedStaticObjects({ batch, single }) {
+    const ctx = useGameContext();
+    const [excluded, setExcluded] = useState([]);
+    const fallbackObjects = useRef(new Map());
+    useFrame(() => {
+        const next = incompatibleStaticObjectIds(batch, ctx.scene.object.get, ctx.scene.object.catalog, excluded, fallbackObjects.current);
+        if (next !== excluded)
+            setExcluded(next);
+    });
+    const objects = useMemo(() => batch.objects.filter((object) => !excluded.includes(object.instanceId)), [batch, excluded]);
+    const gltf = useLoader(sharedGltfLoader, batch.model.url);
+    const supported = useMemo(() => canInstanceStaticScene(gltf.scene, gltf.animations), [gltf]);
+    const harvested = useMemo(() => supported ? buildScatterModelSources(gltf.scene, batch.model) : null, [supported, gltf, batch.model]);
+    useEffect(() => () => { if (harvested !== null)
+        disposeScatterModelSources(harvested.root); }, [harvested]);
+    useEffect(() => {
+        if (harvested === null)
+            return;
+        const root = new THREE.Group();
+        for (const source of harvested.sources) {
+            const mesh = new THREE.Mesh(source.geometry, source.material);
+            mesh.matrixAutoUpdate = false;
+            mesh.matrix.copy(source.localMatrix);
+            root.add(mesh);
+        }
+        const key = batch.objects[0].catalogId;
+        if (batch.model.dims?.maxY === undefined) {
+            const bounds = measureLocalBounds(root);
+            if (bounds !== null)
+                reportMeasuredBounds(ctx, "object", key, bounds);
+        }
+        const triangles = measureLocalCollisionTriangles(root);
+        if (triangles !== null)
+            reportMeasuredCollisionMesh(ctx, "object", key, triangles);
+    }, [ctx, harvested, batch]);
+    if (harvested === null)
+        return _jsx(_Fragment, { children: batch.objects.map(single) });
+    return _jsxs(_Fragment, { children: [harvested.sources.map((source, index) => objects.length === 0 ? null : _jsx(ObjectSource, { source: source, objects: objects, batch: batch }, index)), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
+}
+/** Render compatible authored props as shared model draws, preserving unsupported models. @internal */
+export function StaticObjectModels({ batch, single }) {
+    return _jsx(IsolatedModelPart, { model: batch.model, seam: "object", children: _jsx(LoadedStaticObjects, { batch: batch, single: single }) });
+}