@jgengine/shell 0.19.0 → 0.21.0

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 }) });
+}

package/dist/world/WorldHud.d.ts

@@ -5,15 +5,19 @@ 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, occlude, }: {
+export declare function WorldEntityBars({ statId, height, roles, resolveRole, maxDistance, occlude, tickMs, maxSamples, }: {
     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. */
+    /** Hide bars beyond this camera distance in 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. */
+    /** Hide bars behind blocking geometry from the render camera. Default true; false explicitly reveals through walls. */
     occlude?: boolean;
+    /** Minimum visibility/health refresh interval in ms; anchors reproject every frame. Default 80. */
+    tickMs?: number;
+    /** Maximum overlays and occlusion rays per refresh. Default 64, capped at 256. */
+    maxSamples?: number;
 }): import("react").JSX.Element;
 /** Props for `WorldNameplates` — entity filter, refresh rate, and headless className/render hooks. */
 export interface WorldNameplatesProps {
@@ -21,12 +25,16 @@ export interface WorldNameplatesProps {
     height?: number;
     roles?: readonly CatalogEntityRole[];
     resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
-    /** Hide nameplates for entities farther than this from the player (world units). Default 40. */
+    /** Hide nameplates beyond this camera distance in world units. Default 40. */
     maxDistance?: number;
-    /** Hide the plate when world geometry stands between the player and the entity. Default false. */
+    /** Hide plates behind blocking geometry from the render camera. Default true; false explicitly reveals through walls. */
     occlude?: boolean;
     /** Minimum ms between position/health refreshes — trades smoothness for fewer re-renders at scale. Default 120. */
     tickMs?: number;
+    /** Maximum overlays and occlusion rays per refresh. Default 64, capped at 256. */
+    maxSamples?: number;
+    /** Authored display name. Return null to omit a plate; default suppresses machine identifiers. */
+    resolveName?: (entity: SceneEntity) => string | null;
     /** 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. */
     showHealth?: boolean;
     className?: string;
@@ -45,7 +53,7 @@ export interface WorldNameplatesProps {
  *
  * @capability nameplates billboarded name + HP bar over nearby entities
  */
-export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, occlude, tickMs, showHealth, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
+export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, occlude, tickMs, maxSamples, resolveName, 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

@@ -9,14 +9,16 @@ import { useCameraShake } from "../camera/shakeChannel.js";
 import { CALIBRATED_TRAUMA_SHAKE_DECAY_PER_SECOND } from "../camera/rigMath.js";
 import { readFirstPersonMuzzle } from "../camera/GameFirstPersonCamera.js";
 import { resolveFloatTextStyle } from "./floatTextStyle.js";
-import { collectNameplateSamples, collectWorldBarSamples, paintWorldBarSamples, } from "./worldBarSamples.js";
+import { collectNameplateSamples, collectWorldBarSamples, paintWorldBarSamples, refreshWorldBarSamples, } from "./worldBarSamples.js";
 import { telegraphPulseOpacity } from "./telegraphPulse.js";
+import { useRenderVisibility } from "../visibility/CullingProvider.js";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
 export { collectNameplateSamples, collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
 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, occlude = false, }) {
+export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxDistance = 60, occlude = true, tickMs = 80, maxSamples = 64, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
@@ -24,7 +26,10 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxD
     const canvasRef = useRef(null);
     const samplesRef = useRef([]);
     const projectRef = useRef(new THREE.Vector3());
-    useFrame(() => {
+    const lastTickRef = useRef(-Infinity);
+    const visibility = useRenderVisibility();
+    useFrame((state) => {
+        const nowMs = state.clock.elapsedTime * 1000;
         const canvas = canvasRef.current;
         if (canvas === null)
             return;
@@ -38,9 +43,15 @@ 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, occlude);
+        if (nowMs - lastTickRef.current >= Math.max(0, tickMs)) {
+            lastTickRef.current = nowMs;
+            collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current, maxDistance, occlude, { maxSamples, isVisible: visibility.current });
+        }
+        else {
+            refreshWorldBarSamples(ctx, height, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current, maxDistance, { isVisible: visibility.current });
+        }
         paintWorldBarSamples(canvas, samplesRef.current, dpr);
-    });
+    }, CAMERA_POST_FRAME_PRIORITY + 0.01);
     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,23 +62,24 @@ 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, occlude = false, tickMs = 120, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
+export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, occlude = true, tickMs = 120, maxSamples = 64, resolveName, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
     const [samples, setSamples] = useState([]);
     const samplesRef = useRef([]);
     const projectRef = useRef(new THREE.Vector3());
-    const lastTickRef = useRef(0);
+    const lastTickRef = useRef(-Infinity);
+    const visibility = useRenderVisibility();
     useFrame((state) => {
         const nowMs = state.clock.elapsedTime * 1000;
-        if (nowMs - lastTickRef.current < tickMs)
+        if (nowMs - lastTickRef.current < Math.max(0, tickMs))
             return;
         lastTickRef.current = nowMs;
         camera.updateMatrixWorld();
-        collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, { width: size.width, height: size.height }, samplesRef.current, projectRef.current, maxDistance, occlude);
+        collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, { width: size.width, height: size.height }, samplesRef.current, projectRef.current, maxDistance, occlude, { maxSamples, isVisible: visibility.current, ...(resolveName === undefined ? {} : { resolveName }) });
         setSamples([...samplesRef.current]);
-    });
+    }, CAMERA_POST_FRAME_PRIORITY + 0.01);
     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: {
                     position: "absolute",
                     left: sample.x,
@@ -233,6 +245,7 @@ export function CombatCameraShake() {
 }
 export function ProjectileTracers({ lifeMs = 130 }) {
     const ctx = useGameContext();
+    const camera = useThree((state) => state.camera);
     const [tracers, setTracers] = useState([]);
     const nextId = useRef(0);
     const timers = useRef(new Set());
@@ -246,7 +259,7 @@ export function ProjectileTracers({ lifeMs = 130 }) {
             const id = nextId.current++;
             const start = new THREE.Vector3(event.origin[0], event.origin[1], event.origin[2]);
             if (event.from === ctx.player.userId)
-                readFirstPersonMuzzle(start);
+                readFirstPersonMuzzle(start, camera);
             setTracers((current) => [
                 ...current,
                 {
@@ -266,7 +279,7 @@ export function ProjectileTracers({ lifeMs = 130 }) {
                 clearTimeout(handle);
             timers.current.clear();
         };
-    }, [ctx, lifeMs]);
+    }, [ctx, camera, lifeMs]);
     return (_jsx(_Fragment, { children: tracers.map((tracer) => (_jsx(Line, { points: tracer.points, color: "#fde68a", lineWidth: 2, transparent: true, opacity: 0.85 }, tracer.id))) }));
 }
 export function Reticle({ className }) {

package/dist/world/WorldParticles.d.ts

@@ -1,31 +1,18 @@
 import { type ReactElement } from "react";
 import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+import { type Vec3 } from "@jgengine/core/vfx/particles";
 import type { ParticleEmitterSpec } from "@jgengine/core/vfx/particleDirector";
-/**
- * The per-effect particle pool a graphics tier allows: the requested `max`
- * clamped to the tier cap, so lower tiers degrade density instead of dropping
- * effects entirely.
- */
+/** The requested visual pool clamped to the graphics tier. */
 export declare function resolveParticleBudget(quality: GraphicsQuality, requested: number | undefined, particleCap?: number): number;
-/**
- * Whether a spec change touches something the JSX reads (blending, static offset,
- * follow binding) and therefore needs a React re-render — config-only retunes are
- * applied imperatively to the live system and must stay render-free.
- *
- * @internal WorldParticles render-boundary helper, exported for its regression test.
- */
+/** @internal Config retunes stay imperative; output changes require React rendering. */
 export declare function specNeedsRender(prev: ParticleEmitterSpec, next: ParticleEmitterSpec): boolean;
-/**
- * Renders `ctx.particles` — the game-reachable particle seam. Standing emitters
- * become persistent `ParticleField`s (recreated only when their pool size changes,
- * retuned in place otherwise), `follow` emitters track their entity's live pose
- * each frame, and drained bursts become transient systems reaped once empty.
- * Auto-mounted by the player shell; pools are capped by graphics quality via
- * {@link resolveParticleBudget}.
- *
- * @internal
- */
-export declare function WorldParticles({ quality, particleCap }: {
+/** @internal Transform a simulation vector through a followed yaw and origin. */
+export declare function transformParticleVector(point: Vec3, origin: Vec3, yaw: number, inverse?: boolean, out?: [number, number, number]): Vec3;
+/** @internal Cosmetic catch-up follows game time, with bounded work after suspension. */
+export declare function resolveParticleDelta(previousTime: number, gameTime: number): number;
+/** Renders the existing director and pooled simulator; named bursts reuse the standing pool. @internal */
+export declare function WorldParticles({ quality, particleCap, diagnostics }: {
     quality: GraphicsQuality;
     particleCap?: number;
+    diagnostics?: boolean;
 }): ReactElement;