@jgengine/shell 0.15.0 → 0.16.0

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

package/dist/weather/weatherMath.d.ts

@@ -2,6 +2,10 @@ export declare const DEFAULT_RAIN_COUNT = 2000;
 export declare const DEFAULT_SNOW_COUNT = 1500;
 export declare const DEFAULT_RAIN_DENSITY = 0.45;
 export declare const DEFAULT_SNOW_DENSITY = 0.5;
+/** Mote budget a {@link DustField} allocates before `density` scales it down. */
+export declare const DEFAULT_DUST_COUNT = 1800;
+/** Share of {@link DEFAULT_DUST_COUNT} drawn at intensity 1 — dust reads thinner than rain or snow. */
+export declare const DEFAULT_DUST_DENSITY = 0.4;
 /** @internal */
 export declare function clampWeatherRatio(value: number): number;
 /** @internal */

package/dist/weather/weatherMath.js

@@ -2,6 +2,10 @@ export const DEFAULT_RAIN_COUNT = 2000;
 export const DEFAULT_SNOW_COUNT = 1500;
 export const DEFAULT_RAIN_DENSITY = 0.45;
 export const DEFAULT_SNOW_DENSITY = 0.5;
+/** Mote budget a {@link DustField} allocates before `density` scales it down. */
+export const DEFAULT_DUST_COUNT = 1800;
+/** Share of {@link DEFAULT_DUST_COUNT} drawn at intensity 1 — dust reads thinner than rain or snow. */
+export const DEFAULT_DUST_DENSITY = 0.4;
 /** @internal */
 export function clampWeatherRatio(value) {
     if (!Number.isFinite(value))

package/dist/world/WorldHud.d.ts

@@ -5,13 +5,15 @@ import { type NameplateSample } from "./worldBarSamples.js";
 export type { NameplateSample, WorldBarSample } from "./worldBarSamples.js";
 export { collectNameplateSamples, collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
 export { telegraphPulseOpacity } from "./telegraphPulse.js";
-export declare function WorldEntityBars({ statId, height, roles, resolveRole, maxDistance, }: {
+export declare function WorldEntityBars({ statId, height, roles, resolveRole, maxDistance, occlude, }: {
     statId: string;
     height?: number;
     roles?: readonly CatalogEntityRole[];
     resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
     /** Hide bars for entities farther than this from the player (world units). Default 60. */
     maxDistance?: number;
+    /** Hide the bar when world geometry stands between the player and the entity. These bars are a screen-space overlay outside the depth buffer, so without this they read through walls. Default false, preserving the always-visible behaviour. */
+    occlude?: boolean;
 }): import("react").JSX.Element;
 /** Props for `WorldNameplates` — entity filter, refresh rate, and headless className/render hooks. */
 export interface WorldNameplatesProps {
@@ -21,6 +23,8 @@ export interface WorldNameplatesProps {
     resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
     /** Hide nameplates for entities farther than this from the player (world units). Default 40. */
     maxDistance?: number;
+    /** Hide the plate when world geometry stands between the player and the entity. Default false. */
+    occlude?: boolean;
     /** Minimum ms between position/health refreshes — trades smoothness for fewer re-renders at scale. Default 120. */
     tickMs?: number;
     /** Draw the built-in HP bar under the name. Set `false` for a name-only plate when the game already draws its own health bar (its own HUD, or `worldHealthBars`). Default true. */
@@ -41,7 +45,7 @@ export interface WorldNameplatesProps {
  *
  * @capability nameplates billboarded name + HP bar over nearby entities
  */
-export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, tickMs, showHealth, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
+export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, occlude, tickMs, showHealth, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
 /** Props for {@link WorldObjectHighlights}. */
 export interface WorldObjectHighlightsProps {
     /** Ring tint. Default a construction-select amber. */

package/dist/world/WorldHud.js

@@ -16,7 +16,7 @@ export { telegraphPulseOpacity } from "./telegraphPulse.js";
 function pinOverlayToViewport(_el, _camera, size) {
     return [size.width / 2, size.height / 2];
 }
-export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxDistance = 60, }) {
+export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxDistance = 60, occlude = false, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
@@ -38,7 +38,7 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxD
             canvas.height = pixelH;
         }
         camera.updateMatrixWorld();
-        collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current, maxDistance);
+        collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current, maxDistance, occlude);
         paintWorldBarSamples(canvas, samplesRef.current, dpr);
     });
     return (_jsx(Html, { fullscreen: true, calculatePosition: pinOverlayToViewport, zIndexRange: [20, 0], style: { pointerEvents: "none" }, children: _jsx("canvas", { ref: canvasRef, style: { width: "100%", height: "100%", display: "block", pointerEvents: "none" } }) }));
@@ -51,7 +51,7 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxD
  *
  * @capability nameplates billboarded name + HP bar over nearby entities
  */
-export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, tickMs = 120, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
+export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, occlude = false, tickMs = 120, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
@@ -65,7 +65,7 @@ export function WorldNameplates({ statId = "health", height = 2.3, roles, resolv
             return;
         lastTickRef.current = nowMs;
         camera.updateMatrixWorld();
-        collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, { width: size.width, height: size.height }, samplesRef.current, projectRef.current, maxDistance);
+        collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, { width: size.width, height: size.height }, samplesRef.current, projectRef.current, maxDistance, occlude);
         setSamples([...samplesRef.current]);
     });
     return (_jsx(Html, { fullscreen: true, calculatePosition: pinOverlayToViewport, zIndexRange: [19, 0], style: { pointerEvents: "none" }, children: _jsx("div", { className: className, "data-nameplates": true, children: samples.map((sample) => renderNameplate !== undefined ? (_jsx("div", { style: { position: "absolute", left: sample.x, top: sample.y }, children: renderNameplate(sample) }, sample.id)) : (_jsxs("div", { className: nameplateClassName, "data-nameplate": sample.id, style: {

package/dist/world/worldBarSamples.d.ts

@@ -16,14 +16,26 @@ export interface Projectable {
     y: number;
     z: number;
 }
-/** @internal */
+/**
+ * True when world geometry stands between the player's eye and `target`. World bars and nameplates
+ * are DOM/canvas overlays projected to screen space, so nothing in the depth buffer can hide them —
+ * without this test an enemy's health bar reads straight through the building it is standing behind.
+ * @internal
+ */
+export declare function worldBarOccluded(ctx: GameContext, from: readonly [number, number, number], target: readonly [number, number, number], eyeHeight: number): boolean;
+/**
+ * Projects every non-local, role/distance-filtered entity carrying `statId` into `into` as a
+ * `WorldBarSample`. Pure data step behind `WorldHealthBars` — call it directly to paint the bars
+ * with your own renderer.
+ * @internal
+ */
 export declare function collectWorldBarSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
     matrixWorldInverse: unknown;
     projectionMatrix: unknown;
 }, viewport: {
     width: number;
     height: number;
-}, into: WorldBarSample[], project: Projectable, maxDistance?: number): number;
+}, into: WorldBarSample[], project: Projectable, maxDistance?: number, occlude?: boolean): number;
 /** One entity's projected nameplate: screen `x`/`y`, display `name`, health `percent` (or `null` when statless), and world `distance` from the player. */
 export interface NameplateSample {
     id: string;
@@ -46,7 +58,7 @@ export declare function collectNameplateSamples(ctx: GameContext, statId: string
 }, viewport: {
     width: number;
     height: number;
-}, into: NameplateSample[], project: Projectable, maxDistance?: number): number;
+}, into: NameplateSample[], project: Projectable, maxDistance?: number, occlude?: boolean): number;
 /** @internal */
 export declare function paintWorldBarSamples(canvas: {
     width: number;