@jgengine/shell 0.19.0 → 0.22.0

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;

package/dist/world/WorldParticles.js

@@ -1,91 +1,183 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useRef, useState } from "react";
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { createParticleSystem } from "@jgengine/core/vfx/particles";
 import { useGameContext } from "@jgengine/react/provider";
 import { ParticleField } from "../vfx/ParticleField.js";
 const QUALITY_POOL_CAP = { low: 128, medium: 256, high: 512, ultra: 1024 };
-/**
- * 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 function resolveParticleBudget(quality, requested, particleCap) {
-    const cap = Math.max(1, Math.floor(particleCap ?? QUALITY_POOL_CAP[quality]));
-    return Math.max(1, Math.min(requested ?? cap, cap));
+    const rawCap = particleCap ?? QUALITY_POOL_CAP[quality];
+    const cap = Number.isFinite(rawCap) ? Math.max(1, Math.floor(rawCap)) : QUALITY_POOL_CAP[quality];
+    return Number.isFinite(requested) ? Math.max(1, Math.floor(Math.min(requested, cap))) : cap;
 }
 const MAX_CONCURRENT_BURSTS = 32;
-/**
- * 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.
- */
+const ZERO = [0, 0, 0];
+/** @internal Config retunes stay imperative; output changes require React rendering. */
 export function specNeedsRender(prev, next) {
-    if (prev.blending !== next.blending || prev.follow !== next.follow)
+    if (prev.blending !== next.blending || prev.follow !== next.follow || prev.space !== next.space)
         return true;
-    const a = prev.offset;
-    const b = next.offset;
+    if (prev.render?.shape !== next.render?.shape || prev.render?.stretch !== next.render?.stretch)
+        return true;
+    const a = prev.offset, b = next.offset;
     if (a === b)
         return false;
     if (a === undefined || b === undefined)
         return true;
     return a[0] !== b[0] || a[1] !== b[1] || a[2] !== b[2];
 }
-/**
- * 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 function WorldParticles({ quality, particleCap }) {
+/** @internal Transform a simulation vector through a followed yaw and origin. */
+export function transformParticleVector(point, origin, yaw, inverse = false, out = [0, 0, 0]) {
+    const c = Math.cos(yaw), s = Math.sin(yaw);
+    const x = inverse ? point[0] - origin[0] : point[0];
+    const y = inverse ? point[1] - origin[1] : point[1];
+    const z = inverse ? point[2] - origin[2] : point[2];
+    out[0] = inverse ? c * x - s * z : origin[0] + c * x + s * z;
+    out[1] = inverse ? y : origin[1] + y;
+    out[2] = inverse ? s * x + c * z : origin[2] - s * x + c * z;
+    return out;
+}
+/** @internal Cosmetic catch-up follows game time, with bounded work after suspension. */
+export function resolveParticleDelta(previousTime, gameTime) {
+    return Number.isFinite(previousTime) && Number.isFinite(gameTime) ? Math.max(0, Math.min(0.1, gameTime - previousTime)) : 0;
+}
+/** Renders the existing director and pooled simulator; named bursts reuse the standing pool. @internal */
+export function WorldParticles({ quality, particleCap, diagnostics = false }) {
     const ctx = useGameContext();
     const emittersRef = useRef(new Map());
     const burstsRef = useRef([]);
+    const previousTime = useRef(ctx.time.now());
+    const timing = useRef({ poolsCreated: 0, poolsRetired: 0, updateSamples: 0, lastUpdateMs: 0, totalUpdateMs: 0, maxUpdateMs: 0, droppedCatchupSeconds: 0 });
+    const resources = useRef({ fieldsMounted: 0, fieldsUnmounted: 0, liveFields: 0, attributeBytes: 0, totalUploadMs: 0, maxUploadMs: 0, uploadSamples: 0 });
     const [, setGeneration] = useState(0);
+    function pose(spec) {
+        const offset = spec.offset ?? [0, 0, 0];
+        const entity = spec.follow === undefined ? undefined : ctx.scene.entity.get(spec.follow);
+        if (entity === undefined || entity === null)
+            return { position: offset, yaw: 0, found: spec.follow === undefined };
+        if (spec.space === "local")
+            return { position: transformParticleVector(offset, entity.position, entity.rotationY), yaw: entity.rotationY, found: true };
+        return { position: [entity.position[0] + offset[0], entity.position[1] + offset[1], entity.position[2] + offset[2]], yaw: 0, found: true };
+    }
+    function syncPose(instance) {
+        const resolved = pose(instance.spec);
+        instance.pose = resolved;
+        if (instance.spec.space === "local" && resolved.found) {
+            instance.group?.position.set(...resolved.position);
+            if (instance.group !== null)
+                instance.group.rotation.y = resolved.yaw;
+        }
+        else if (instance.spec.space !== "local") {
+            const base = instance.spec.follow === undefined ? instance.spec.config.position ?? [0, 0, 0] : [0, 0, 0];
+            instance.system.configure({ position: [resolved.position[0] + base[0], resolved.position[1] + base[1], resolved.position[2] + base[2]] });
+        }
+        if (resolved.found && instance.spec.active !== false)
+            instance.system.start();
+        else
+            instance.system.stop();
+    }
+    function collisionFor(spec, frozenPose) {
+        return (from, to) => {
+            const current = spec();
+            const local = current.space === "local";
+            const resolved = frozenPose ?? emittersRef.current.get(current.id)?.pose ?? pose(current);
+            const start = local ? transformParticleVector(from, resolved.position, resolved.yaw) : from;
+            const end = local ? transformParticleVector(to, resolved.position, resolved.yaw) : to;
+            const direction = [end[0] - start[0], end[1] - start[1], end[2] - start[2]];
+            const maxDistance = Math.hypot(...direction);
+            if (maxDistance === 0)
+                return null;
+            const hit = ctx.scene.raycast({ origin: start, direction, maxDistance,
+                filter: { entities: false, objects: true, terrain: true, walls: true } });
+            if (hit === null)
+                return null;
+            return { position: local ? transformParticleVector(hit.point, resolved.position, resolved.yaw, true) : hit.point,
+                normal: local ? transformParticleVector(hit.normal, [0, 0, 0], resolved.yaw, true) : hit.normal };
+        };
+    }
+    function accelerationFor(spec, frozenPose) {
+        const worldScratch = [0, 0, 0];
+        const forceScratch = [0, 0, 0];
+        return (position, _velocity, out) => {
+            const current = spec();
+            const influence = current.environment;
+            if (influence === undefined) {
+                out[0] = out[1] = out[2] = 0;
+                return out;
+            }
+            const resolved = frozenPose ?? emittersRef.current.get(current.id)?.pose ?? pose(current);
+            const local = current.space === "local";
+            const world = local ? transformParticleVector(position, resolved.position, resolved.yaw, false, worldScratch) : position;
+            const force = ctx.environment.accelerationAt(world, ctx.time.now(), influence.windResponse ?? 0, influence.maxAcceleration ?? 100, influence.mask ?? 0xffffffff, forceScratch);
+            const result = local ? transformParticleVector(force, ZERO, resolved.yaw, true, forceScratch) : force;
+            out[0] = result[0];
+            out[1] = result[1];
+            out[2] = result[2];
+            return out;
+        };
+    }
     useEffect(() => {
         const emitters = emittersRef.current;
         function sync() {
             let changed = false;
-            const specs = ctx.particles.emitters();
             const liveIds = new Set();
-            for (const spec of specs) {
+            for (const spec of ctx.particles.emitters()) {
                 liveIds.add(spec.id);
                 const poolMax = resolveParticleBudget(quality, spec.config.max, particleCap);
                 const current = emitters.get(spec.id);
                 if (current === undefined || current.poolMax !== poolMax) {
-                    emitters.set(spec.id, {
-                        spec,
-                        poolMax,
-                        system: createParticleSystem({ ...spec.config, max: poolMax, seed: spec.id }),
-                    });
+                    const next = { spec, poolMax, group: current?.group ?? null, pose: pose(spec),
+                        system: createParticleSystem({ ...spec.config, max: poolMax, seed: spec.config.seed ?? spec.id }, { collision: collisionFor(() => next.spec), acceleration: accelerationFor(() => next.spec) }) };
+                    if (current !== undefined) {
+                        next.system.restore(current.system.snapshot());
+                        next.system.configure({ ...spec.config, max: poolMax, seed: spec.config.seed ?? spec.id }, true);
+                    }
+                    timing.current.poolsCreated++;
+                    if (current !== undefined)
+                        timing.current.poolsRetired++;
+                    emitters.set(spec.id, next);
+                    syncPose(next);
                     changed = true;
                 }
                 else if (current.spec !== spec) {
                     if (specNeedsRender(current.spec, spec))
                         changed = true;
-                    current.system.configure({ ...spec.config, max: poolMax });
+                    current.system.configure({ ...spec.config, max: poolMax, seed: spec.config.seed ?? spec.id }, true);
                     current.spec = spec;
+                    syncPose(current);
                 }
             }
             for (const id of emitters.keys()) {
                 if (liveIds.has(id))
                     continue;
                 emitters.delete(id);
+                timing.current.poolsRetired++;
                 changed = true;
             }
             for (const burst of ctx.particles.drainBursts()) {
+                const named = burst.emitterId === undefined ? undefined : emitters.get(burst.emitterId);
+                if (named !== undefined) {
+                    syncPose(named);
+                    named.system.emit(burst.count);
+                    continue;
+                }
                 const poolMax = resolveParticleBudget(quality, Math.min(burst.count, burst.config.max ?? burst.count), particleCap);
-                const system = createParticleSystem({ ...burst.config, max: poolMax, seed: burst.seq });
+                const spec = { id: `burst:${burst.seq}`, config: burst.config, ...burst.options };
+                const resolved = pose(spec);
+                const system = createParticleSystem({ ...burst.config, rate: 0, max: poolMax, seed: burst.config.seed ?? burst.seq }, { collision: collisionFor(() => spec, resolved), acceleration: accelerationFor(() => spec, resolved) });
+                if (spec.space !== "local") {
+                    const base = spec.follow === undefined ? burst.config.position ?? [0, 0, 0] : [0, 0, 0];
+                    system.configure({ position: [resolved.position[0] + base[0], resolved.position[1] + base[1], resolved.position[2] + base[2]] });
+                }
                 system.emit(burst.count);
-                burstsRef.current.push({ seq: burst.seq, system, blending: burst.blending ?? "additive" });
-                if (burstsRef.current.length > MAX_CONCURRENT_BURSTS)
+                timing.current.poolsCreated++;
+                burstsRef.current.push({ seq: burst.seq, system, blending: burst.blending ?? "additive", render: spec.render, collisionEffect: spec.collisionEffect,
+                    position: spec.space === "local" ? resolved.position : [0, 0, 0], rotationY: spec.space === "local" ? resolved.yaw : 0 });
+                if (burstsRef.current.length > MAX_CONCURRENT_BURSTS) {
                     burstsRef.current.shift();
+                    timing.current.poolsRetired++;
+                }
                 changed = true;
             }
             if (changed)
@@ -93,36 +185,92 @@ export function WorldParticles({ quality, particleCap }) {
         }
         sync();
         const off = ctx.particles.subscribe(sync);
+        return off;
+    }, [ctx, quality, particleCap]);
+    useEffect(() => {
+        if (!diagnostics)
+            return;
+        return devtools.probes.register("particles", () => {
+            let count = 0, capacity = 0, renderBufferBytes = 0;
+            const read = (system) => {
+                const buffers = system.buffers();
+                count += system.count();
+                capacity += buffers.positions.length / 3;
+                renderBufferBytes += buffers.positions.byteLength + buffers.previousPositions.byteLength + buffers.velocities.byteLength + buffers.sizes.byteLength + buffers.colors.byteLength + buffers.alphas.byteLength + buffers.ids.byteLength;
+            };
+            for (const instance of emittersRef.current.values())
+                read(instance.system);
+            for (const burst of burstsRef.current)
+                read(burst.system);
+            const sample = timing.current, fields = resources.current;
+            return { scope: "WorldParticles", emitters: emittersRef.current.size, bursts: burstsRef.current.length, count, capacity, renderBufferBytes,
+                poolsCreated: sample.poolsCreated, poolsRetired: sample.poolsRetired,
+                updateSamples: sample.updateSamples, lastUpdateMs: sample.lastUpdateMs, maxUpdateMs: sample.maxUpdateMs,
+                avgUpdateMs: sample.updateSamples === 0 ? 0 : sample.totalUpdateMs / sample.updateSamples,
+                droppedCatchupSeconds: sample.droppedCatchupSeconds,
+                resources: { ...fields, avgUploadMsPerField: fields.uploadSamples === 0 ? 0 : fields.totalUploadMs / fields.uploadSamples } };
+        });
+    }, [ctx, diagnostics]);
+    useEffect(() => {
+        previousTime.current = ctx.time.now();
         return () => {
-            off();
-            emitters.clear();
+            timing.current.poolsRetired += emittersRef.current.size + burstsRef.current.length;
+            emittersRef.current.clear();
             burstsRef.current = [];
         };
-    }, [ctx, quality, particleCap]);
+    }, [ctx]);
     useFrame(() => {
+        const started = diagnostics ? performance.now() : 0;
+        const gameTime = ctx.time.now();
+        const dt = resolveParticleDelta(previousTime.current, gameTime);
+        if (diagnostics)
+            timing.current.droppedCatchupSeconds += Math.max(0, gameTime - previousTime.current - dt);
+        previousTime.current = gameTime;
+        const impacts = [];
+        const collect = (id, system, effect, origin, yaw = 0) => {
+            const events = system.drainEvents();
+            for (const event of events) {
+                if (origin !== undefined) {
+                    event.position = transformParticleVector(event.position, origin, yaw);
+                    event.velocity = transformParticleVector(event.velocity, [0, 0, 0], yaw);
+                    if (event.normal !== undefined)
+                        event.normal = transformParticleVector(event.normal, [0, 0, 0], yaw);
+                }
+                if (effect !== undefined && event.type === "collision" && impacts.length < 16)
+                    impacts.push({ effect, event });
+            }
+            ctx.particles.reportEvents(id, events);
+        };
         for (const instance of emittersRef.current.values()) {
-            const follow = instance.spec.follow;
-            if (follow === undefined)
-                continue;
-            const entity = ctx.scene.entity.get(follow);
-            if (entity === null || entity === undefined)
-                continue;
-            const offset = instance.spec.offset ?? [0, 0, 0];
-            instance.system.configure({
-                position: [
-                    entity.position[0] + offset[0],
-                    entity.position[1] + offset[1],
-                    entity.position[2] + offset[2],
-                ],
-            });
+            syncPose(instance);
+            instance.system.update(dt);
+            const resolved = instance.spec.space === "local" ? instance.pose : undefined;
+            collect(instance.spec.id, instance.system, instance.spec.collisionEffect, resolved?.position, resolved?.yaw);
+        }
+        let finished = false;
+        for (const burst of burstsRef.current) {
+            burst.system.update(dt);
+            collect(`burst:${burst.seq}`, burst.system, burst.collisionEffect, burst.position, burst.rotationY);
+            if (burst.system.count() === 0) {
+                finished = true;
+                timing.current.poolsRetired++;
+            }
         }
-        const finished = burstsRef.current.filter((burst) => burst.system.count() === 0);
-        if (finished.length > 0) {
+        if (finished) {
             burstsRef.current = burstsRef.current.filter((burst) => burst.system.count() > 0);
             setGeneration((n) => n + 1);
         }
+        for (const { effect, event } of impacts) {
+            const { collision: _, ...config } = effect.config;
+            ctx.particles.burst({ ...config, position: event.position, rate: 0, deathEvents: false }, effect.count, effect.blending, { render: effect.render });
+        }
+        if (diagnostics) {
+            const elapsed = performance.now() - started, sample = timing.current;
+            sample.lastUpdateMs = elapsed;
+            sample.totalUpdateMs += elapsed;
+            sample.maxUpdateMs = Math.max(sample.maxUpdateMs, elapsed);
+            sample.updateSamples++;
+        }
     });
-    return (_jsxs(_Fragment, { children: [Array.from(emittersRef.current.values()).map((instance) => (_jsx("group", { position: instance.spec.follow === undefined && instance.spec.offset !== undefined
-                    ? instance.spec.offset
-                    : [0, 0, 0], children: _jsx(ParticleField, { system: instance.system, blending: instance.spec.blending ?? "normal" }) }, instance.spec.id))), burstsRef.current.map((burst) => (_jsx(ParticleField, { system: burst.system, blending: burst.blending }, burst.seq)))] }));
+    return _jsxs(_Fragment, { children: [Array.from(emittersRef.current.values()).map((instance) => _jsx("group", { ref: (group) => { instance.group = group; }, children: _jsx(ParticleField, { system: instance.system, advance: false, blending: instance.spec.blending ?? "normal", render: instance.spec.render, metrics: diagnostics ? resources.current : undefined }) }, instance.spec.id)), burstsRef.current.map((burst) => _jsx("group", { position: burst.position, rotation: [0, burst.rotationY, 0], children: _jsx(ParticleField, { system: burst.system, advance: false, blending: burst.blending, render: burst.render, metrics: diagnostics ? resources.current : undefined }) }, burst.seq))] });
 }

package/dist/world/WorldScene.d.ts

@@ -1,10 +1,11 @@
 import { type ComponentType, type ReactNode } from "react";
+import { type EditorDocument } from "@jgengine/core/editor/index";
 import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import { type SceneObject } from "@jgengine/core/scene/objectStore";
 import type { EntitySpriteConfig, ModelConfig, ObjectStyle } from "@jgengine/core/game/playableGame";
 import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
-export declare function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }: {
+export declare function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }: {
     entitySprites: Record<string, EntitySpriteConfig> | undefined;
     entityModels: Record<string, string | ModelConfig> | undefined;
     objectModels: Record<string, string | ModelConfig> | undefined;
@@ -15,6 +16,7 @@ export declare function WorldView({ entitySprites, entityModels, objectModels, o
     renderObject: ((object: SceneObject) => ReactNode) | undefined;
     selectedIds: ReadonlySet<string>;
     hideLocalActor: boolean;
+    editorLayers?: EditorDocument | undefined;
 }): import("react").JSX.Element;
 export declare function RemotePlayers({ rows, presenceInterpolationMs }: {
     rows: PresencePoseRow[];