@jgengine/shell 0.15.0 → 0.17.0

package/dist/structures/GeneratedBuilding.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useLayoutEffect, useMemo, useRef } from "react";
+import { Suspense, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { useDisposable } from "../render/useDisposable.js";
+import { BuildingKitBatch } from "./BuildingKitBatch.js";
+import { bucketBuildingParts, normalFor, outwardOffset } from "./buildingKitFit.js";
 const DEFAULT_PALETTE = {
     wall: "#83766a",
     window: "#8ecae6",
@@ -19,26 +21,6 @@ const DEFAULT_PALETTE = {
 function colorFor(kind, palette) {
     return palette?.[kind] ?? DEFAULT_PALETTE[kind];
 }
-function normalFor(facade) {
-    if (facade === "front")
-        return [0, 1];
-    if (facade === "back")
-        return [0, -1];
-    if (facade === "left")
-        return [-1, 0];
-    if (facade === "right")
-        return [1, 0];
-    return [0, 0];
-}
-function outwardOffset(part) {
-    if (part.kind === "wall" || part.kind === "roof" || part.kind === "corner")
-        return 0;
-    if (part.kind === "window" || part.kind === "shutter" || part.kind === "storefront")
-        return 0.025;
-    if (part.kind === "awning" || part.kind === "storeSign")
-        return 0.09;
-    return 0.12;
-}
 function materialFor(part, palette) {
     const color = colorFor(part.kind, palette);
     if (part.kind === "window" || part.kind === "storefront") {
@@ -65,56 +47,6 @@ function batchMaterialFor(kind, palette) {
     }
     return new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
 }
-const CLOTHESLINE_ROW_OFFSETS = [-0.09, 0.09];
-function bucketPartMatrices(buildings, visible) {
-    const dummy = new THREE.Object3D();
-    const buckets = new Map();
-    for (const placement of buildings) {
-        const [ox, oy, oz] = placement.position ?? [0, 0, 0];
-        // Building yaw turns the whole massing about its center. Engine Y-rotation convention (matches
-        // dummy.rotation.y below): a local vector (x, z) maps to (x·cos + z·sin, −x·sin + z·cos).
-        const yaw = placement.rotationY ?? 0;
-        const [px0, pz0] = placement.pivot ?? [0, 0];
-        const cos = Math.cos(yaw);
-        const sin = Math.sin(yaw);
-        for (const part of placement.building.parts) {
-            if (visible !== null && !visible.has(part.kind))
-                continue;
-            const [nx, nz] = normalFor(part.facade);
-            const offset = outwardOffset(part);
-            // Local offset from the pivot (part position + facade-normal nudge), then rotated by the yaw.
-            const lx = part.position[0] - px0 + nx * offset;
-            const lz = part.position[2] - pz0 + nz * offset;
-            const px = ox + px0 + lx * cos + lz * sin;
-            const py = oy + part.position[1];
-            const pz = oz + pz0 - lx * sin + lz * cos;
-            const partYaw = part.rotationY + yaw;
-            let bucket = buckets.get(part.kind);
-            if (bucket === undefined) {
-                bucket = [];
-                buckets.set(part.kind, bucket);
-            }
-            if (part.kind === "clothesline") {
-                const rowSin = Math.sin(partYaw);
-                const rowCos = Math.cos(partYaw);
-                for (const row of CLOTHESLINE_ROW_OFFSETS) {
-                    dummy.position.set(px + row * rowSin, py, pz + row * rowCos);
-                    dummy.rotation.set(0, partYaw, 0);
-                    dummy.scale.set(part.scale[0], Math.max(part.scale[1], 0.025), 0.025);
-                    dummy.updateMatrix();
-                    bucket.push(dummy.matrix.clone());
-                }
-                continue;
-            }
-            dummy.position.set(px, py, pz);
-            dummy.rotation.set(0, partYaw, 0);
-            dummy.scale.set(part.scale[0], part.scale[1], part.scale[2]);
-            dummy.updateMatrix();
-            bucket.push(dummy.matrix.clone());
-        }
-    }
-    return buckets;
-}
 function BuildingKindBatch({ kind, matrices, palette, geometry, }) {
     const meshRef = useRef(null);
     const material = useDisposable(() => batchMaterialFor(kind, palette), [kind, palette]);
@@ -128,15 +60,15 @@ function BuildingKindBatch({ kind, matrices, palette, geometry, }) {
     }, [matrices, material]);
     return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
 }
-export function InstancedBuildings({ buildings, palette, visibleKinds }) {
+export function InstancedBuildings({ buildings, palette, kit, resolveModelUrl, visibleKinds, }) {
     const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);
-    const buckets = useMemo(() => {
+    const { boxes, models } = useMemo(() => {
         const visible = visibleKinds === undefined ? null : new Set(visibleKinds);
-        return bucketPartMatrices(buildings, visible);
-    }, [buildings, visibleKinds]);
-    if (buckets.size === 0)
+        return bucketBuildingParts(buildings, visible, kit, resolveModelUrl);
+    }, [buildings, visibleKinds, kit, resolveModelUrl]);
+    if (boxes.size === 0 && models.size === 0)
         return null;
-    return (_jsx("group", { children: [...buckets.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))) }));
+    return (_jsxs("group", { children: [[...boxes.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))), [...models.entries()].map(([url, instances]) => (_jsx(Suspense, { fallback: null, children: _jsx(BuildingKitBatch, { url: url, instances: instances }) }, url)))] }));
 }
 function BlockMesh({ part, palette }) {
     const [nx, nz] = normalFor(part.facade);
@@ -161,7 +93,7 @@ export function BuildingBlock({ part, palette }) {
     }
     return _jsx(BlockMesh, { part: part, palette: palette });
 }
-export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
+export function GeneratedBuilding({ building, palette, partRenderer, kit, resolveModelUrl, visibleKinds, }) {
     const { kitParts, batched } = useMemo(() => {
         const visible = visibleKinds === undefined ? null : new Set(visibleKinds);
         const kitRendered = [];
@@ -169,7 +101,7 @@ export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
         for (const part of building.parts) {
             if (visible !== null && !visible.has(part.kind))
                 continue;
-            const rendered = kit?.renderPart?.(part);
+            const rendered = partRenderer?.renderPart?.(part);
             if (rendered !== undefined) {
                 kitRendered.push({ id: part.id, node: rendered });
                 continue;
@@ -178,6 +110,6 @@ export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
         }
         const placements = batchedParts.length === 0 ? [] : [{ building: { id: building.id, parts: batchedParts } }];
         return { kitParts: kitRendered, batched: placements };
-    }, [building, kit, visibleKinds]);
-    return (_jsxs("group", { name: building.id, children: [kitParts.map((entry) => (_jsx("group", { children: entry.node }, entry.id))), _jsx(InstancedBuildings, { buildings: batched, palette: palette })] }));
+    }, [building, partRenderer, visibleKinds]);
+    return (_jsxs("group", { name: building.id, children: [kitParts.map((entry) => (_jsx("group", { children: entry.node }, entry.id))), _jsx(InstancedBuildings, { buildings: batched, palette: palette, kit: kit, resolveModelUrl: resolveModelUrl })] }));
 }

package/dist/structures/buildingKitFit.d.ts

@@ -0,0 +1,59 @@
+import * as THREE from "three";
+import type { BuildingKit, BuildingKitFit, BuildingKitPart } from "@jgengine/core/world/buildingKit";
+import type { BuildingFacade, BuildingPartKind, BuildingPartPlacement, InstancedBuildingPlacement } from "./GeneratedBuilding.js";
+/**
+ * One kit-bound part resolved to the world slot the fallback box would have filled, carrying the
+ * binding that replaces it. `slotScale` is the slot box in world units; `yaw` already includes the
+ * whole-building rotation.
+ * @internal
+ */
+export interface BuildingKitInstance {
+    position: readonly [number, number, number];
+    yaw: number;
+    slotScale: readonly [number, number, number];
+    part: BuildingKitPart;
+    fit: BuildingKitFit;
+}
+/** A kit model's native extents, measured once per URL from the harvested root. @internal */
+export interface BuildingKitModelBounds {
+    size: readonly [number, number, number];
+    center: readonly [number, number, number];
+}
+/** Box-path matrices per part kind plus kit-bound instances per resolved model URL. @internal */
+export interface BuildingPartBuckets {
+    boxes: Map<BuildingPartKind, THREE.Matrix4[]>;
+    models: Map<string, BuildingKitInstance[]>;
+}
+/** Outward XZ normal of a facade; `roof` has none. @internal */
+export declare function normalFor(facade: BuildingFacade): readonly [number, number];
+/** How far a part sits proud of its facade, so decor never z-fights the wall behind it. @internal */
+export declare function outwardOffset(part: BuildingPartPlacement): number;
+/**
+ * Splits every placed part into the two render paths: parts a kit binds to a model land in a bucket
+ * keyed by their resolved URL, everything else keeps today's per-kind box matrices. With no kit every
+ * part resolves to `box`, so the box path is untouched.
+ * @internal
+ */
+export declare function bucketBuildingParts(buildings: readonly InstancedBuildingPlacement[], visible: ReadonlySet<BuildingPartKind> | null, kit?: BuildingKit, resolveModelUrl?: (model: string) => string): BuildingPartBuckets;
+/**
+ * Whether a model needs a quarter-turn about Y to run along its slot. Modular kits disagree on which
+ * horizontal axis a panel is authored along — within one pack a wall may run along Z while a door
+ * runs along X — so compare which horizontal axis is longer on each and turn when they disagree.
+ * @internal
+ */
+export declare function buildingKitQuarterTurn(fit: BuildingKitFit, slotScale: readonly [number, number, number], nativeSize: readonly [number, number, number], autoOrient?: boolean): boolean;
+/**
+ * Maps a model's native extents onto the slot box per {@link BuildingKitFit}. Degenerate or
+ * non-finite native extents fall back to a ratio of 1 on that axis rather than blowing the model up.
+ * @internal
+ */
+export declare function buildingKitFitScale(fit: BuildingKitFit, slotScale: readonly [number, number, number], nativeSize: readonly [number, number, number]): [number, number, number];
+/** Measures the harvested model root once so every instance of that URL shares one fit basis. @internal */
+export declare function measureBuildingKitModel(root: THREE.Object3D): BuildingKitModelBounds;
+/**
+ * Composes one kit instance's world matrix: fit scale times the binding's `scale`, the binding's
+ * Euler XYZ rotation on top of the slot's facade yaw, the binding's slot-local `offset` rotated into
+ * world space by that total yaw, and a recentre so the model's bounds center lands on the slot center.
+ * @internal
+ */
+export declare function composeBuildingKitMatrix(instance: BuildingKitInstance, bounds: BuildingKitModelBounds, target?: THREE.Matrix4): THREE.Matrix4;

package/dist/structures/buildingKitFit.js

@@ -0,0 +1,188 @@
+import * as THREE from "three";
+import { resolveBuildingKitPart } from "@jgengine/core/world/buildingKit";
+const CLOTHESLINE_ROW_OFFSETS = [-0.09, 0.09];
+/** Outward XZ normal of a facade; `roof` has none. @internal */
+export function normalFor(facade) {
+    if (facade === "front")
+        return [0, 1];
+    if (facade === "back")
+        return [0, -1];
+    if (facade === "left")
+        return [-1, 0];
+    if (facade === "right")
+        return [1, 0];
+    return [0, 0];
+}
+/** How far a part sits proud of its facade, so decor never z-fights the wall behind it. @internal */
+export function outwardOffset(part) {
+    if (part.kind === "wall" || part.kind === "roof" || part.kind === "corner")
+        return 0;
+    if (part.kind === "window" || part.kind === "shutter" || part.kind === "storefront")
+        return 0.025;
+    if (part.kind === "awning" || part.kind === "storeSign")
+        return 0.09;
+    return 0.12;
+}
+/**
+ * Splits every placed part into the two render paths: parts a kit binds to a model land in a bucket
+ * keyed by their resolved URL, everything else keeps today's per-kind box matrices. With no kit every
+ * part resolves to `box`, so the box path is untouched.
+ * @internal
+ */
+export function bucketBuildingParts(buildings, visible, kit, resolveModelUrl) {
+    const dummy = new THREE.Object3D();
+    const boxes = new Map();
+    const models = new Map();
+    for (const placement of buildings) {
+        const [ox, oy, oz] = placement.position ?? [0, 0, 0];
+        // Building yaw turns the whole massing about its center. Engine Y-rotation convention (matches
+        // dummy.rotation.y below): a local vector (x, z) maps to (x·cos + z·sin, −x·sin + z·cos).
+        const yaw = placement.rotationY ?? 0;
+        const [px0, pz0] = placement.pivot ?? [0, 0];
+        const cos = Math.cos(yaw);
+        const sin = Math.sin(yaw);
+        for (const part of placement.building.parts) {
+            if (visible !== null && !visible.has(part.kind))
+                continue;
+            const binding = resolveBuildingKitPart(kit, part.kind, part.kit);
+            if (binding.type === "omit")
+                continue;
+            const [nx, nz] = normalFor(part.facade);
+            const offset = outwardOffset(part);
+            // Local offset from the pivot (part position + facade-normal nudge), then rotated by the yaw.
+            const lx = part.position[0] - px0 + nx * offset;
+            const lz = part.position[2] - pz0 + nz * offset;
+            const px = ox + px0 + lx * cos + lz * sin;
+            const py = oy + part.position[1];
+            const pz = oz + pz0 - lx * sin + lz * cos;
+            const partYaw = part.rotationY + yaw;
+            if (binding.type === "model") {
+                const url = resolveModelUrl?.(binding.part.model) ?? binding.part.model;
+                const instance = {
+                    position: [px, py, pz],
+                    yaw: partYaw,
+                    slotScale: part.scale,
+                    part: binding.part,
+                    fit: binding.fit,
+                };
+                const bucket = models.get(url);
+                if (bucket === undefined)
+                    models.set(url, [instance]);
+                else
+                    bucket.push(instance);
+                continue;
+            }
+            let bucket = boxes.get(part.kind);
+            if (bucket === undefined) {
+                bucket = [];
+                boxes.set(part.kind, bucket);
+            }
+            if (part.kind === "clothesline") {
+                const rowSin = Math.sin(partYaw);
+                const rowCos = Math.cos(partYaw);
+                for (const row of CLOTHESLINE_ROW_OFFSETS) {
+                    dummy.position.set(px + row * rowSin, py, pz + row * rowCos);
+                    dummy.rotation.set(0, partYaw, 0);
+                    dummy.scale.set(part.scale[0], Math.max(part.scale[1], 0.025), 0.025);
+                    dummy.updateMatrix();
+                    bucket.push(dummy.matrix.clone());
+                }
+                continue;
+            }
+            dummy.position.set(px, py, pz);
+            dummy.rotation.set(0, partYaw, 0);
+            dummy.scale.set(part.scale[0], part.scale[1], part.scale[2]);
+            dummy.updateMatrix();
+            bucket.push(dummy.matrix.clone());
+        }
+    }
+    return { boxes, models };
+}
+function ratio(slot, native) {
+    if (!Number.isFinite(slot) || !Number.isFinite(native) || Math.abs(native) < 1e-6)
+        return 1;
+    return slot / native;
+}
+/**
+ * Whether a model needs a quarter-turn about Y to run along its slot. Modular kits disagree on which
+ * horizontal axis a panel is authored along — within one pack a wall may run along Z while a door
+ * runs along X — so compare which horizontal axis is longer on each and turn when they disagree.
+ * @internal
+ */
+export function buildingKitQuarterTurn(fit, slotScale, nativeSize, autoOrient = true) {
+    if (!autoOrient || fit === "native")
+        return false;
+    const [sx, , sz] = slotScale;
+    const [nx, , nz] = nativeSize;
+    if (![sx, sz, nx, nz].every((value) => Number.isFinite(value)))
+        return false;
+    if (Math.abs(nx - nz) < 1e-6 || Math.abs(sx - sz) < 1e-6)
+        return false;
+    return sx >= sz !== nx >= nz;
+}
+/**
+ * Maps a model's native extents onto the slot box per {@link BuildingKitFit}. Degenerate or
+ * non-finite native extents fall back to a ratio of 1 on that axis rather than blowing the model up.
+ * @internal
+ */
+export function buildingKitFitScale(fit, slotScale, nativeSize) {
+    if (fit === "native")
+        return [1, 1, 1];
+    const rx = ratio(slotScale[0], nativeSize[0]);
+    const ry = ratio(slotScale[1], nativeSize[1]);
+    const rz = ratio(slotScale[2], nativeSize[2]);
+    if (fit === "stretch")
+        return [rx, ry, rz];
+    const uniform = fit === "cover" ? Math.max(rx, ry, rz) : Math.min(rx, ry, rz);
+    return [uniform, uniform, uniform];
+}
+/** Measures the harvested model root once so every instance of that URL shares one fit basis. @internal */
+export function measureBuildingKitModel(root) {
+    const box = new THREE.Box3().setFromObject(root);
+    if (box.isEmpty())
+        return { size: [0, 0, 0], center: [0, 0, 0] };
+    return {
+        size: [box.max.x - box.min.x, box.max.y - box.min.y, box.max.z - box.min.z],
+        center: [(box.min.x + box.max.x) / 2, (box.min.y + box.max.y) / 2, (box.min.z + box.max.z) / 2],
+    };
+}
+const UP = new THREE.Vector3(0, 1, 0);
+const scratchScale = new THREE.Vector3();
+const scratchPosition = new THREE.Vector3();
+const scratchCenter = new THREE.Vector3();
+const scratchQuat = new THREE.Quaternion();
+const scratchYaw = new THREE.Quaternion();
+const scratchEuler = new THREE.Euler();
+/**
+ * Composes one kit instance's world matrix: fit scale times the binding's `scale`, the binding's
+ * Euler XYZ rotation on top of the slot's facade yaw, the binding's slot-local `offset` rotated into
+ * world space by that total yaw, and a recentre so the model's bounds center lands on the slot center.
+ * @internal
+ */
+export function composeBuildingKitMatrix(instance, bounds, target = new THREE.Matrix4()) {
+    const turn = buildingKitQuarterTurn(instance.fit, instance.slotScale, bounds.size, instance.part.autoOrient);
+    // The turn swaps which native axis faces the slot's width, so fit against the swapped extents.
+    const native = turn
+        ? [bounds.size[2], bounds.size[1], bounds.size[0]]
+        : bounds.size;
+    const fit = buildingKitFitScale(instance.fit, instance.slotScale, native);
+    const mul = instance.part.scale ?? [1, 1, 1];
+    const fitted = turn
+        ? [fit[2] * mul[0], fit[1] * mul[1], fit[0] * mul[2]]
+        : [fit[0] * mul[0], fit[1] * mul[1], fit[2] * mul[2]];
+    scratchScale.set(fitted[0], fitted[1], fitted[2]);
+    const rotation = instance.part.rotation;
+    const turnYaw = turn ? Math.PI / 2 : 0;
+    scratchEuler.set(rotation?.[0] ?? 0, (rotation?.[1] ?? 0) + turnYaw, rotation?.[2] ?? 0, "XYZ");
+    scratchQuat.setFromEuler(scratchEuler);
+    scratchQuat.premultiply(scratchYaw.setFromAxisAngle(UP, instance.yaw));
+    const offset = instance.part.offset ?? [0, 0, 0];
+    const totalYaw = instance.yaw + (rotation?.[1] ?? 0) + turnYaw;
+    const cos = Math.cos(totalYaw);
+    const sin = Math.sin(totalYaw);
+    scratchCenter
+        .set(bounds.center[0] * scratchScale.x, bounds.center[1] * scratchScale.y, bounds.center[2] * scratchScale.z)
+        .applyQuaternion(scratchQuat);
+    scratchPosition.set(instance.position[0] + offset[0] * cos + offset[2] * sin - scratchCenter.x, instance.position[1] + offset[1] - scratchCenter.y, instance.position[2] - offset[0] * sin + offset[2] * cos - scratchCenter.z);
+    return target.compose(scratchPosition, scratchQuat, scratchScale);
+}

package/dist/structures/buildingKitRegistry.d.ts

@@ -0,0 +1,9 @@
+import type { BuildingKit } from "@jgengine/core/world/buildingKit";
+/** Registers a kit under its own `id`, replacing any kit already registered under that name. */
+export declare function registerBuildingKit(kit: BuildingKit): void;
+/** The kit registered under `id`, or `undefined` for an unset or unknown name (renders blocks). */
+export declare function getBuildingKit(id: string | undefined): BuildingKit | undefined;
+/** Every registered kit id — the editor's kit picker and diagnostics read this. */
+export declare function listBuildingKits(): string[];
+/** Drops every registration. For tests and hot-reload teardown. */
+export declare function clearBuildingKits(): void;

package/dist/structures/buildingKitRegistry.js

@@ -0,0 +1,26 @@
+/**
+ * Kits a game has bound, keyed by `BuildingKit.id`.
+ *
+ * Scene documents name a kit rather than embedding it, so an authored city stays portable and free
+ * of model paths while the game keeps ownership of its art. Registration is the game's job — the
+ * engine ships no kits.
+ */
+const kits = new Map();
+/** Registers a kit under its own `id`, replacing any kit already registered under that name. */
+export function registerBuildingKit(kit) {
+    kits.set(kit.id, kit);
+}
+/** The kit registered under `id`, or `undefined` for an unset or unknown name (renders blocks). */
+export function getBuildingKit(id) {
+    if (id === undefined || id === "")
+        return undefined;
+    return kits.get(id);
+}
+/** Every registered kit id — the editor's kit picker and diagnostics read this. */
+export function listBuildingKits() {
+    return [...kits.keys()].sort();
+}
+/** Drops every registration. For tests and hot-reload teardown. */
+export function clearBuildingKits() {
+    kits.clear();
+}

package/dist/weather/DustField.d.ts

@@ -0,0 +1,41 @@
+import * as THREE from "three";
+import { type WeatherVector } from "./weatherUniforms.js";
+/**
+ * Wind-borne particulate: dust, sand, ash, pollen, spores. Unlike rain and snow this is not falling
+ * — motion is dominated by horizontal wind with a slow vertical bob, and density thins with height
+ * so the air near the ground carries the most grit. Any arid, volcanic, or blown-out world needs it.
+ */
+export interface DustFieldProps {
+    count?: number;
+    density?: number;
+    budget?: number;
+    volume?: WeatherVector;
+    wind?: WeatherVector;
+    origin?: WeatherVector;
+    followCamera?: boolean;
+    /** Horizontal drift added to `wind`, in world units per second. */
+    speed?: number;
+    size?: number;
+    /** Amplitude of the slow vertical bob that keeps motes from travelling on rails. */
+    sway?: number;
+    opacity?: number;
+    color?: THREE.ColorRepresentation;
+    /**
+     * How fast density falls off with height across the volume, 0..1. At 0 the volume is filled
+     * evenly; at 1 nearly everything hugs the ground. Default 0.65.
+     */
+    groundBias?: number;
+    timeScale?: number;
+    seed?: number;
+    renderOrder?: number;
+    frustumCulled?: boolean;
+}
+/**
+ * Renders wind-borne particulate as camera-facing motes. Reach for it whenever the air itself
+ * should read as weather — a desert gale, ash off a volcano, pollen in a meadow, grain dust in a
+ * silo. Compose it through {@link WeatherLayer}'s `"dust"` mode (or `dustAlways` alongside rain and
+ * snow) rather than mounting it directly, so it shares one wind and time source with the other layers.
+ *
+ * @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;

package/dist/weather/DustField.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useThree } from "@react-three/fiber";
+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 { useWeatherUniformSet } from "./weatherUniforms.js";
+const DEFAULT_VOLUME = [70, 22, 70];
+const DEFAULT_ORIGIN = [0, 0, 0];
+const DEFAULT_DUST_COLOR = "#c8a878";
+/**
+ * Renders wind-borne particulate as camera-facing motes. Reach for it whenever the air itself
+ * should read as weather — a desert gale, ash off a volcano, pollen in a meadow, grain dust in a
+ * silo. Compose it through {@link WeatherLayer}'s `"dust"` mode (or `dustAlways` alongside rain and
+ * snow) rather than mounting it directly, so it shares one wind and time source with the other layers.
+ *
+ * @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, }) {
+    const { camera } = useThree();
+    const shared = useWeatherUniformSet({ wind, timeScale });
+    const geometry = useDisposable(() => createWeatherQuadGeometry(count, seed), [count, seed]);
+    const material = useDisposable(() => {
+        const uniforms = {
+            uTime: shared.time,
+            uWind: shared.wind,
+            uAnchor: { value: new THREE.Vector3() },
+            uVolume: { value: new THREE.Vector3() },
+            uSpeed: { value: speed },
+            uSize: { value: size },
+            uSway: { value: sway },
+            uOpacity: { value: opacity },
+            uColor: { value: new THREE.Color(color) },
+            uGroundBias: { value: groundBias },
+        };
+        return new THREE.ShaderMaterial({
+            uniforms,
+            transparent: true,
+            depthWrite: false,
+            blending: THREE.NormalBlending,
+            vertexShader: `
+        uniform float uTime;
+        uniform vec3 uWind;
+        uniform vec3 uAnchor;
+        uniform vec3 uVolume;
+        uniform float uSpeed;
+        uniform float uSize;
+        uniform float uSway;
+        uniform float uGroundBias;
+
+        attribute vec3 aSpawn;
+        attribute float aDrift;
+
+        varying vec2 vUv;
+        varying float vDrift;
+        varying float vFade;
+
+        void main() {
+          vUv = uv;
+          vDrift = aDrift;
+
+          // Bias the spawn height toward the ground: pow() on a uniform [0,1) packs samples low
+          // without needing a second attribute or a reseed.
+          vec3 spawn = aSpawn;
+          spawn.y = pow(spawn.y, 1.0 + uGroundBias * 4.0);
+
+          vec3 origin = uAnchor - vec3(uVolume.x * 0.5, uVolume.y * 0.12, uVolume.z * 0.5);
+          float phase = aDrift * 6.28318530718;
+          // Faster motes ride higher in the gust, the way real airborne grit sorts itself.
+          float carry = uSpeed * (0.55 + 0.9 * aDrift);
+          vec3 bob = vec3(
+            sin(uTime * 0.43 + phase) * 0.35,
+            sin(uTime * 0.67 + phase * 1.9) + sin(uTime * 0.31 + phase) * 0.4,
+            cos(uTime * 0.39 + phase * 1.3) * 0.35
+          ) * uSway * (0.4 + 0.6 * aDrift);
+          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;
+
+          // 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);
+          vFade = 1.0 - smoothstep(0.55, 1.0, height);
+
+          float moteSize = uSize * (0.4 + 1.3 * 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]);
+          vec3 world = worldCenter + right * position.x * moteSize + up * position.y * moteSize;
+
+          gl_Position = projectionMatrix * viewMatrix * vec4(world, 1.0);
+        }
+      `,
+            fragmentShader: `
+        uniform float uOpacity;
+        uniform vec3 uColor;
+
+        varying vec2 vUv;
+        varying float vDrift;
+        varying float vFade;
+
+        void main() {
+          float distanceFromCenter = length(vUv - 0.5) * 2.0;
+          // 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;
+          if (alpha < 0.001) discard;
+          gl_FragColor = vec4(uColor, alpha);
+        }
+      `,
+        });
+    }, [color, groundBias, opacity, shared, size, speed, sway]);
+    useFrame(() => {
+        const anchor = followCamera ? camera.position : null;
+        const uniforms = material.uniforms;
+        const target = uniforms.uAnchor.value;
+        if (anchor !== null)
+            target.copy(anchor);
+        else
+            target.set(origin[0], origin[1], origin[2]);
+        uniforms.uVolume.value.set(volume[0], volume[1], volume[2]);
+        uniforms.uSpeed.value = speed;
+        uniforms.uSize.value = size;
+        uniforms.uSway.value = sway;
+        uniforms.uOpacity.value = opacity;
+        uniforms.uGroundBias.value = groundBias;
+        uniforms.uColor.value.set(color);
+        geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
+    });
+    return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
+}

package/dist/weather/WeatherLayer.d.ts

@@ -1,8 +1,10 @@
 import type { ReactNode } from "react";
+import { type DustFieldProps } from "./DustField.js";
 import { type RainFieldProps } from "./RainField.js";
 import { type SnowFieldProps } from "./SnowField.js";
 import { type WeatherVector } from "./weatherUniforms.js";
-export type WeatherLayerMode = "clear" | "rain" | "snow" | "mixed";
+/** `"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 {
     mode?: WeatherLayerMode;
     intensity?: number;
@@ -11,7 +13,11 @@ export interface WeatherLayerProps {
     timeScale?: number;
     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;
     enabled?: boolean;
     children?: ReactNode;
 }
-export declare function WeatherLayer({ mode, intensity, wind, lightning, timeScale, rain, snow, enabled, children, }: WeatherLayerProps): import("react").JSX.Element | null;
+export declare function WeatherLayer({ mode, intensity, wind, lightning, timeScale, rain, snow, dust, dustAlways, enabled, children, }: WeatherLayerProps): import("react").JSX.Element | null;

package/dist/weather/WeatherLayer.js

@@ -1,16 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DustField } from "./DustField.js";
 import { RainField } from "./RainField.js";
 import { SnowField } from "./SnowField.js";
 import { WeatherUniformProvider } from "./weatherUniforms.js";
 function resolveLayerDensity(value, fallback, intensity) {
     return (value ?? fallback) * intensity;
 }
-export function WeatherLayer({ mode = "clear", intensity = 1, wind, lightning, timeScale, rain, snow, enabled = true, children, }) {
+export function WeatherLayer({ mode = "clear", intensity = 1, wind, lightning, timeScale, rain, snow, dust, dustAlways = false, enabled = true, children, }) {
     if (!enabled)
         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");
-    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, children] }));
+    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] }));
 }

package/dist/weather/index.d.ts

@@ -1,3 +1,4 @@
+export { DustField, type DustFieldProps } from "./DustField.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,3 +1,4 @@
+export { DustField } from "./DustField.js";
 export { FireSpreadLayer } from "./FireSpreadLayer.js";
 export { LightningStrike } from "./LightningStrike.js";
 export { RainField } from "./RainField.js";