@jgengine/shell 0.14.0 → 0.15.0-next.0

package/dist/vfx/ParticleField.d.ts

@@ -0,0 +1,32 @@
+import { type ReactElement } from "react";
+import type { ParticleSystem } from "@jgengine/core/vfx/particles";
+/** How particle fragments composite: `additive` for fire/sparks/magic glow, `normal` for smoke/dust. */
+export type ParticleBlending = "additive" | "normal";
+/** Props for {@link ParticleField}. */
+export interface ParticleFieldProps {
+    /** The core simulation to render (from `createParticleSystem`). */
+    system: ParticleSystem;
+    /**
+     * Advance the simulation each frame with the render delta. Leave `true` for a
+     * fire-and-forget effect; set `false` when your game loop already ticks the
+     * system (so it advances exactly once per fixed step).
+     */
+    advance?: boolean;
+    /** Compositing mode. Default `additive` (glowy). */
+    blending?: ParticleBlending;
+    /** Pixel-size multiplier applied to every particle's world radius. Default 300. */
+    scale?: number;
+    /** Write depth (occludes particles behind geometry). Default `false` so a glow layer never self-occludes. */
+    depthWrite?: boolean;
+}
+/**
+ * Renders a core `ParticleSystem` as a GPU point cloud: one draw call, per-particle
+ * size / color / alpha via a soft-round shader, and a `drawRange` clamped to the live
+ * count so dead particles cost nothing. The simulation stays engine-side and
+ * genre-agnostic; this is purely how it reaches the screen. By default it advances
+ * the sim with the frame delta — pass `advance={false}` to drive it from your own
+ * fixed loop instead.
+ *
+ * @capability particle-field render a core particle system as a soft-point GPU cloud with per-particle size, color, and alpha
+ */
+export declare function ParticleField({ system, advance, blending, scale, depthWrite, }: ParticleFieldProps): ReactElement;

package/dist/vfx/ParticleField.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+const VERTEX_SHADER = /* glsl */ `
+  attribute float aSize;
+  attribute float aAlpha;
+  attribute vec3 aColor;
+  varying float vAlpha;
+  varying vec3 vColor;
+  uniform float uScale;
+  void main() {
+    vAlpha = aAlpha;
+    vColor = aColor;
+    vec4 mv = modelViewMatrix * vec4(position, 1.0);
+    gl_PointSize = aSize * uScale / max(0.0001, -mv.z);
+    gl_Position = projectionMatrix * mv;
+  }
+`;
+const FRAGMENT_SHADER = /* glsl */ `
+  varying float vAlpha;
+  varying vec3 vColor;
+  void main() {
+    // Soft round sprite: radial falloff from the point center, discard the corners.
+    vec2 d = gl_PointCoord - vec2(0.5);
+    float r = length(d);
+    if (r > 0.5) discard;
+    float soft = smoothstep(0.5, 0.0, r);
+    gl_FragColor = vec4(vColor, vAlpha * soft);
+  }
+`;
+/**
+ * Renders a core `ParticleSystem` as a GPU point cloud: one draw call, per-particle
+ * size / color / alpha via a soft-round shader, and a `drawRange` clamped to the live
+ * count so dead particles cost nothing. The simulation stays engine-side and
+ * genre-agnostic; this is purely how it reaches the screen. By default it advances
+ * the sim with the frame delta — pass `advance={false}` to drive it from your own
+ * fixed loop instead.
+ *
+ * @capability particle-field render a core particle system as a soft-point GPU cloud with per-particle size, color, and alpha
+ */
+export function ParticleField({ system, advance = true, blending = "additive", scale = 300, depthWrite = false, }) {
+    const pointsRef = useRef(null);
+    const dpr = useThree((state) => state.viewport.dpr);
+    const { geometry, material } = useMemo(() => {
+        const initial = system.buffers();
+        const max = initial.positions.length / 3;
+        const geo = new THREE.BufferGeometry();
+        geo.setAttribute("position", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
+        geo.setAttribute("aSize", new THREE.BufferAttribute(new Float32Array(max), 1));
+        geo.setAttribute("aColor", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
+        geo.setAttribute("aAlpha", new THREE.BufferAttribute(new Float32Array(max), 1));
+        geo.setDrawRange(0, 0);
+        const mat = new THREE.ShaderMaterial({
+            vertexShader: VERTEX_SHADER,
+            fragmentShader: FRAGMENT_SHADER,
+            uniforms: { uScale: { value: scale } },
+            transparent: true,
+            depthWrite,
+            blending: blending === "additive" ? THREE.AdditiveBlending : THREE.NormalBlending,
+        });
+        return { geometry: geo, material: mat };
+    }, [system, scale, depthWrite, blending]);
+    useEffect(() => {
+        return () => {
+            geometry.dispose();
+            material.dispose();
+        };
+    }, [geometry, material]);
+    useFrame((_, delta) => {
+        if (advance)
+            system.update(Math.min(delta, 0.1));
+        const buffers = system.buffers();
+        const count = buffers.count;
+        const pos = geometry.getAttribute("position");
+        const size = geometry.getAttribute("aSize");
+        const color = geometry.getAttribute("aColor");
+        const alpha = geometry.getAttribute("aAlpha");
+        pos.array.set(buffers.positions.subarray(0, count * 3));
+        size.array.set(buffers.sizes.subarray(0, count));
+        color.array.set(buffers.colors.subarray(0, count * 3));
+        alpha.array.set(buffers.alphas.subarray(0, count));
+        pos.needsUpdate = true;
+        size.needsUpdate = true;
+        color.needsUpdate = true;
+        alpha.needsUpdate = true;
+        geometry.setDrawRange(0, count);
+        material.uniforms.uScale.value = scale * dpr;
+    });
+    return _jsx("points", { ref: pointsRef, geometry: geometry, material: material, frustumCulled: false });
+}

package/dist/vfx/WorldFloatingText.d.ts

@@ -0,0 +1,32 @@
+import { type CSSProperties } from "react";
+import type { FloatingTextField, FloatingTextView } from "@jgengine/core/ui/floatingText";
+import { type FloatingTextLayoutOptions } from "@jgengine/react/floatingText";
+/** Props for {@link WorldFloatingText}. */
+export interface WorldFloatingTextProps extends FloatingTextLayoutOptions {
+    /** The core field to render (`createFloatingTextField`). */
+    field: FloatingTextField;
+    /**
+     * Advance the field each frame with the render delta. Leave `true` for a
+     * fire-and-forget overlay; set `false` when your game loop already ticks the
+     * field so it advances exactly once per fixed step.
+     */
+    advance?: boolean;
+    /** Per-`kind` art direction merged over the defaults (color, font, shadow). */
+    styleFor?: (view: FloatingTextView) => CSSProperties;
+    /** Base font size in px at `size === 1`. Default 20. */
+    fontSizePx?: number;
+    /** Class on the overlay layer. */
+    className?: string;
+}
+/**
+ * R3F one-line drop-in for world-anchored floating text: mounts inside the scene,
+ * (optionally) advances a core {@link FloatingTextField} each frame, samples the
+ * live camera to project every live entry to the screen, and renders
+ * `@jgengine/react`'s {@link FloatingText} through a fullscreen `<Html>` overlay.
+ * This is the turnkey way an R3F game gets damage numbers / heal pops / XP gains
+ * from its own field without wiring projection by hand — the camera binding,
+ * viewport culling, and depth stacking come for free. Skin per `kind` with `styleFor`.
+ *
+ * @capability floating-text R3F drop-in that advances a floating-text field and renders it camera-projected over the scene
+ */
+export declare function WorldFloatingText({ field, advance, styleFor, fontSizePx, className, ...layout }: WorldFloatingTextProps): import("react").JSX.Element;

package/dist/vfx/WorldFloatingText.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Html } from "@react-three/drei";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useState } from "react";
+import { FloatingText } from "@jgengine/react/floatingText";
+import { useWorldProjection } from "../world/WorldEntityFrames.js";
+function pinToViewport(_el, _camera, size) {
+    return [size.width / 2, size.height / 2];
+}
+/**
+ * R3F one-line drop-in for world-anchored floating text: mounts inside the scene,
+ * (optionally) advances a core {@link FloatingTextField} each frame, samples the
+ * live camera to project every live entry to the screen, and renders
+ * `@jgengine/react`'s {@link FloatingText} through a fullscreen `<Html>` overlay.
+ * This is the turnkey way an R3F game gets damage numbers / heal pops / XP gains
+ * from its own field without wiring projection by hand — the camera binding,
+ * viewport culling, and depth stacking come for free. Skin per `kind` with `styleFor`.
+ *
+ * @capability floating-text R3F drop-in that advances a floating-text field and renders it camera-projected over the scene
+ */
+export function WorldFloatingText({ field, advance = true, styleFor, fontSizePx, className, ...layout }) {
+    const size = useThree((state) => state.size);
+    const project = useWorldProjection();
+    const [, setTick] = useState(0);
+    useFrame((_, delta) => {
+        if (advance)
+            field.update(Math.min(delta, 0.1));
+        // Re-render every frame so projected positions follow the camera and the sim.
+        setTick((n) => n + 1);
+    });
+    return (_jsx(Html, { fullscreen: true, calculatePosition: pinToViewport, zIndexRange: [20, 0], style: { pointerEvents: "none" }, children: _jsx(FloatingText, { entries: field.active(), project: project, viewport: { width: size.width, height: size.height }, styleFor: styleFor, fontSizePx: fontSizePx, className: className, ...layout }) }));
+}

package/dist/water/Ocean.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 import { createOceanConfig } from "./OceanConfig.js";
 import { createOceanMaterial, syncOceanMaterial } from "./OceanMaterial.js";
 /** aDepth when no sampler is given: everywhere-deep, matching the pre-depth shader look. */
@@ -26,14 +27,10 @@ function createOceanGeometry(config, depthAt) {
 export function Ocean({ config, depthAt, ...meshProps }) {
     const resolved = useMemo(() => createOceanConfig(config), [config]);
     const elapsedRef = useRef(0);
-    const geometry = useMemo(() => createOceanGeometry(resolved, depthAt), [resolved, depthAt]);
-    const material = useMemo(() => createOceanMaterial(resolved), [resolved]);
-    useEffect(() => {
-        return () => geometry.dispose();
-    }, [geometry]);
+    const geometry = useDisposable(() => createOceanGeometry(resolved, depthAt), [resolved, depthAt]);
+    const material = useDisposable(() => createOceanMaterial(resolved), [resolved]);
     useEffect(() => {
         elapsedRef.current = 0;
-        return () => material.dispose();
     }, [material]);
     useFrame((_, delta) => {
         elapsedRef.current += delta * resolved.timeScale;

package/dist/weather/LightningStrike.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 const DEFAULT_COLOR = "#bdd4ff";
 function createRandom(seed) {
     let state = seed >>> 0;
@@ -80,8 +81,8 @@ function writeLightningGeometry(geometry, segments) {
 export function LightningStrike({ origin, target, strikeKey = 0, seed = 451, visible = true, duration = 0.18, color = DEFAULT_COLOR, glow = 2.4, branches = 5, jaggedness = 0.08, impactLight = 26, renderOrder = 20, }) {
     const lifeRef = useRef(0);
     const lightRef = useRef(null);
-    const geometry = useMemo(() => new THREE.BufferGeometry(), []);
-    const material = useMemo(() => new THREE.LineBasicMaterial({
+    const geometry = useDisposable(() => new THREE.BufferGeometry(), []);
+    const material = useDisposable(() => new THREE.LineBasicMaterial({
         color,
         transparent: true,
         opacity: 0,
@@ -94,9 +95,6 @@ export function LightningStrike({ origin, target, strikeKey = 0, seed = 451, vis
         next.renderOrder = renderOrder;
         return next;
     }, [geometry, material, renderOrder]);
-    useEffect(() => {
-        material.color.set(color);
-    }, [color, material]);
     useEffect(() => {
         if (!visible) {
             lifeRef.current = 0;
@@ -122,9 +120,5 @@ export function LightningStrike({ origin, target, strikeKey = 0, seed = 451, vis
         if (lightRef.current !== null)
             lightRef.current.intensity = amount * impactLight * flicker;
     });
-    useEffect(() => () => {
-        geometry.dispose();
-        material.dispose();
-    }, [geometry, material]);
     return (_jsxs(_Fragment, { children: [_jsx("primitive", { object: line }), _jsx("pointLight", { ref: lightRef, position: [target[0], target[1], target[2]], color: color, intensity: 0, distance: 56, decay: 2 })] }));
 }

package/dist/weather/RainField.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useMemo } from "react";
 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_RAIN_COUNT, DEFAULT_RAIN_DENSITY, resolveWeatherInstanceCount } from "./weatherMath.js";
 import { useWeatherUniformSet } from "./weatherUniforms.js";
@@ -11,8 +11,8 @@ const DEFAULT_RAIN_COLOR = "#b8c4d8";
 export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 22, length = 1.35, width = 0.018, opacity = 0.48, color = DEFAULT_RAIN_COLOR, lightning, timeScale, seed = 11939, renderOrder = 10, frustumCulled, }) {
     const { camera } = useThree();
     const shared = useWeatherUniformSet({ wind, lightning, timeScale });
-    const geometry = useMemo(() => createWeatherQuadGeometry(count, seed), [count, seed]);
-    const material = useMemo(() => {
+    const geometry = useDisposable(() => createWeatherQuadGeometry(count, seed), [count, seed]);
+    const material = useDisposable(() => {
         const uniforms = {
             uTime: shared.time,
             uWind: shared.wind,
@@ -99,9 +99,5 @@ export function RainField({ count = DEFAULT_RAIN_COUNT, density = DEFAULT_RAIN_D
         uniforms.uColor.value.set(color);
         geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
     });
-    useEffect(() => () => {
-        geometry.dispose();
-        material.dispose();
-    }, [geometry, material]);
     return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
 }

package/dist/weather/SnowField.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useMemo } from "react";
 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_SNOW_COUNT, DEFAULT_SNOW_DENSITY, resolveWeatherInstanceCount } from "./weatherMath.js";
 import { useWeatherUniformSet } from "./weatherUniforms.js";
@@ -11,8 +11,8 @@ const DEFAULT_SNOW_COLOR = "#ffffff";
 export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_DENSITY, budget, volume = DEFAULT_VOLUME, wind, origin = DEFAULT_ORIGIN, followCamera = true, speed = 3.2, size = 0.11, sway = 0.62, opacity = 0.86, color = DEFAULT_SNOW_COLOR, timeScale, seed = 72931, renderOrder = 11, frustumCulled, }) {
     const { camera } = useThree();
     const shared = useWeatherUniformSet({ wind, timeScale });
-    const geometry = useMemo(() => createWeatherQuadGeometry(count, seed), [count, seed]);
-    const material = useMemo(() => {
+    const geometry = useDisposable(() => createWeatherQuadGeometry(count, seed), [count, seed]);
+    const material = useDisposable(() => {
         const uniforms = {
             uTime: shared.time,
             uWind: shared.wind,
@@ -100,9 +100,5 @@ export function SnowField({ count = DEFAULT_SNOW_COUNT, density = DEFAULT_SNOW_D
         uniforms.uColor.value.set(color);
         geometry.instanceCount = resolveWeatherInstanceCount(count, density, budget);
     });
-    useEffect(() => () => {
-        geometry.dispose();
-        material.dispose();
-    }, [geometry, material]);
     return (_jsx("mesh", { geometry: geometry, material: material, frustumCulled: frustumCulled ?? !followCamera, renderOrder: renderOrder }));
 }

package/dist/world/DataObjects.js

@@ -2,14 +2,15 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 function clamp01(v) {
     return v < 0 ? 0 : v > 1 ? 1 : v;
 }
 export function DataObjects({ data, position, height, color, cellSize = 0.28, hovered = null, hoverColor = "#ffffff", onHover, grow, castShadow = true, receiveShadow = true, renderItem, }) {
     const meshRef = useRef(null);
     const dummy = useMemo(() => new THREE.Object3D(), []);
-    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
-    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.62, metalness: 0.04 }), []);
+    const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({ roughness: 0.62, metalness: 0.04 }), []);
     const hover = useMemo(() => new THREE.Color(hoverColor), [hoverColor]);
     const startRef = useRef(null);
     const capacity = data.length;
@@ -32,10 +33,6 @@ export function DataObjects({ data, position, height, color, cellSize = 0.28, ho
     useEffect(() => {
         startRef.current = null;
     }, [data]);
-    useEffect(() => () => {
-        geometry.dispose();
-        material.dispose();
-    }, [geometry, material]);
     const duration = grow?.duration ?? 0;
     useFrame((state) => {
         const mesh = meshRef.current;

package/dist/world/GridWorldScene.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { resolveGridInstances } from "@jgengine/core/world/gridInstances";
+import { useDisposable } from "../render/useDisposable.js";
 function isGridWorldFeature(feature) {
     return (feature.kind === "biomes" || feature.kind === "voxel" || feature.kind === "plots" || feature.kind === "tilemap");
 }
@@ -13,8 +14,8 @@ function isGridWorldFeature(feature) {
 export function GridWorldScene({ feature }) {
     const instances = useMemo(() => (isGridWorldFeature(feature) ? resolveGridInstances(feature) : []), [feature]);
     const meshRef = useRef(null);
-    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
-    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.9, metalness: 0 }), []);
+    const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({ roughness: 0.9, metalness: 0 }), []);
     const instanceColor = useMemo(() => new THREE.InstancedBufferAttribute(new Float32Array(Math.max(instances.length, 1) * 3), 3), [instances.length]);
     useEffect(() => {
         const mesh = meshRef.current;
@@ -44,10 +45,6 @@ export function GridWorldScene({ feature }) {
         mesh.instanceMatrix.needsUpdate = true;
         instanceColor.needsUpdate = true;
     }, [instances, instanceColor]);
-    useEffect(() => () => {
-        geometry.dispose();
-        material.dispose();
-    }, [geometry, material]);
     if (instances.length === 0)
         return null;
     return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, instances.length], castShadow: true, receiveShadow: true }));

package/dist/world/InstancedBodies.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 const SLEEPING_COLOR = new THREE.Color(0.32, 0.4, 0.62);
 const AWAKE_COLOR = new THREE.Color(0.45, 0.78, 0.5);
 const CONTACT_COLOR = new THREE.Color(0.96, 0.55, 0.18);
@@ -13,8 +14,8 @@ const DEFAULT_BASE = new THREE.Color(0.62, 0.64, 0.68);
  */
 export function InstancedBodies({ world, debugTint = false, baseColors, epoch = 0 }) {
     const meshRef = useRef(null);
-    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
-    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.85, metalness: 0, vertexColors: false }), []);
+    const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({ roughness: 0.85, metalness: 0, vertexColors: false }), []);
     const capacity = world.capacity;
     const instanceColor = useMemo(() => new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3), 3), [capacity]);
     useEffect(() => {
@@ -76,9 +77,5 @@ export function InstancedBodies({ world, debugTint = false, baseColors, epoch =
         }
         lastTintRef.current = debugTint;
     });
-    useEffect(() => () => {
-        geometry.dispose();
-        material.dispose();
-    }, [geometry, material]);
     return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, capacity], frustumCulled: false, castShadow: false, receiveShadow: false }));
 }

package/dist/world/InstancedJoints.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 /**
  * Debug overlay drawing a PhysicsWorld's joints (suspension, ragdoll links, carry tethers) as one
  * LineSegments batch. Endpoints are streamed each frame from `world.readJointSegments`; pair with
@@ -11,7 +12,7 @@ export function InstancedJoints({ world, color = "#f5c542" }) {
     const geometryRef = useRef(null);
     const positions = useMemo(() => new Float32Array(world.jointCapacity * 6), [world.jointCapacity]);
     const attribute = useMemo(() => new THREE.BufferAttribute(positions, 3), [positions]);
-    const material = useMemo(() => new THREE.LineBasicMaterial({ color }), [color]);
+    const material = useDisposable(() => new THREE.LineBasicMaterial({ color }), [color]);
     useEffect(() => {
         const geometry = geometryRef.current;
         if (geometry === null)
@@ -27,6 +28,5 @@ export function InstancedJoints({ world, color = "#f5c542" }) {
         attribute.needsUpdate = true;
         geometry.setDrawRange(0, count * 2);
     });
-    useEffect(() => () => material.dispose(), [material]);
     return (_jsxs("lineSegments", { frustumCulled: false, children: [_jsx("bufferGeometry", { ref: geometryRef }), _jsx("primitive", { object: material, attach: "material" })] }));
 }

package/dist/world/SpriteBatch.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame, useLoader, useThree } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 const DEFAULT_CAPACITY = 1024;
 const DEFAULT_ALPHA_TEST = 0.08;
 const XZ_BASE_QUATERNION = new THREE.Quaternion().setFromEuler(new THREE.Euler(-Math.PI / 2, 0, 0));
@@ -29,9 +30,9 @@ export function SpriteBatch({ url, columns = 1, rows = 1, capacity = DEFAULT_CAP
         }
         texture.needsUpdate = true;
     }, [texture, pixelated]);
-    const geometry = useMemo(() => new THREE.PlaneGeometry(1, 1), []);
+    const geometry = useDisposable(() => new THREE.PlaneGeometry(1, 1), []);
     const spriteUvOffset = useMemo(() => new THREE.InstancedBufferAttribute(new Float32Array(capacity * 2), 2), [capacity]);
-    const material = useMemo(() => {
+    const material = useDisposable(() => {
         const mat = new THREE.MeshBasicMaterial({
             map: texture,
             transparent: true,
@@ -104,9 +105,5 @@ uniform vec2 spriteUvScale;`)
         mesh.instanceMatrix.needsUpdate = true;
         spriteUvOffset.needsUpdate = true;
     });
-    useEffect(() => () => {
-        geometry.dispose();
-        material.dispose();
-    }, [geometry, material]);
     return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, capacity], frustumCulled: false, castShadow: false, receiveShadow: false }));
 }

package/dist/world/WorldEntityFrames.d.ts

@@ -0,0 +1,47 @@
+import { type ReactNode } from "react";
+import * as THREE from "three";
+import { type EntityFrameEntry, type EntityFrameLayoutOptions, type EntityFramePlacement, type EntityScreenProjection, type ProjectEntity } from "@jgengine/react/entityFrames";
+/**
+ * Returns a {@link ProjectEntity} bound to the live R3F camera and canvas size —
+ * the world→screen half of the data-first entity-frame seam. Call the returned
+ * function with a world position to get a CSS-pixel screen point (or `null`/`behind`
+ * when the point is outside the frustum). Reads the camera fresh on every call, so
+ * sample it inside a frame loop. Games that already own their entities use this to
+ * feed `@jgengine/react`'s `EntityFrames` without mirroring state into a store.
+ *
+ * @capability entity-frames R3F camera→screen projector for world-anchored frames
+ */
+export declare function useWorldProjection(): ProjectEntity;
+/**
+ * Pure world→screen projection: NDC via `camera.project`, mapped to CSS pixels.
+ * `behind` is set when the point falls outside the near/far clip range (NDC z
+ * beyond [-1, 1]), which covers positions behind the camera. Exposed for tests
+ * and for callers wiring their own frame loop around a bare THREE camera.
+ *
+ * @capability entity-frames pure world→screen projection for a bare THREE camera
+ */
+export declare function projectWorldToScreen(scratch: THREE.Vector3, camera: THREE.Camera, worldPosition: readonly [number, number, number], width: number, height: number): EntityScreenProjection;
+/** Props for {@link WorldEntityFrames}. */
+export interface WorldEntityFramesProps<E extends EntityFrameEntry> extends EntityFrameLayoutOptions {
+    /** Caller-owned entities to anchor; `worldPosition` is the overhead point. */
+    entries: readonly E[];
+    /** Renders one entity's frame — compose `HealthBar value/max` + a name, themed via `barTokens`. */
+    renderFrame: (entry: E, placement: EntityFramePlacement<E>) => ReactNode;
+    /** Min ms between projection refreshes — trades smoothness for fewer re-renders at scale. Default 0 (every frame). */
+    tickMs?: number;
+    /** Class on the overlay layer. */
+    className?: string;
+    /** Per-frame wrapper transform. Default `translate(-50%, -100%)`. */
+    anchorTransform?: string;
+}
+/**
+ * R3F convenience that mounts inside the scene, samples the live camera each
+ * frame (throttled by `tickMs`), and renders `@jgengine/react`'s {@link EntityFrames}
+ * through a fullscreen `<Html>` overlay. This is the one-line way an R3F game
+ * gets overhead enemy nameplates/health bars from its own entity array without a
+ * store: pass `entries` + a `renderFrame` that composes the shipped bars. The
+ * projection, viewport culling, and stacking come for free.
+ *
+ * @capability entity-frames R3F overhead entity frames from a caller-owned entity array
+ */
+export declare function WorldEntityFrames<E extends EntityFrameEntry>({ entries, renderFrame, tickMs, className, anchorTransform, ...layout }: WorldEntityFramesProps<E>): import("react").JSX.Element;

package/dist/world/WorldEntityFrames.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Html } from "@react-three/drei";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useCallback, useRef, useState } from "react";
+import * as THREE from "three";
+import { EntityFrames, } from "@jgengine/react/entityFrames";
+/**
+ * Returns a {@link ProjectEntity} bound to the live R3F camera and canvas size —
+ * the world→screen half of the data-first entity-frame seam. Call the returned
+ * function with a world position to get a CSS-pixel screen point (or `null`/`behind`
+ * when the point is outside the frustum). Reads the camera fresh on every call, so
+ * sample it inside a frame loop. Games that already own their entities use this to
+ * feed `@jgengine/react`'s `EntityFrames` without mirroring state into a store.
+ *
+ * @capability entity-frames R3F camera→screen projector for world-anchored frames
+ */
+export function useWorldProjection() {
+    const camera = useThree((state) => state.camera);
+    const size = useThree((state) => state.size);
+    const scratch = useRef(new THREE.Vector3());
+    return useCallback((worldPosition) => {
+        camera.updateMatrixWorld();
+        return projectWorldToScreen(scratch.current, camera, worldPosition, size.width, size.height);
+    }, [camera, size.width, size.height]);
+}
+/**
+ * Pure world→screen projection: NDC via `camera.project`, mapped to CSS pixels.
+ * `behind` is set when the point falls outside the near/far clip range (NDC z
+ * beyond [-1, 1]), which covers positions behind the camera. Exposed for tests
+ * and for callers wiring their own frame loop around a bare THREE camera.
+ *
+ * @capability entity-frames pure world→screen projection for a bare THREE camera
+ */
+export function projectWorldToScreen(scratch, camera, worldPosition, width, height) {
+    scratch.set(worldPosition[0], worldPosition[1], worldPosition[2]);
+    scratch.project(camera);
+    return {
+        x: (scratch.x * 0.5 + 0.5) * width,
+        y: (-scratch.y * 0.5 + 0.5) * height,
+        depth: scratch.z,
+        behind: scratch.z < -1 || scratch.z > 1,
+    };
+}
+function pinToViewport(_el, _camera, size) {
+    return [size.width / 2, size.height / 2];
+}
+/**
+ * R3F convenience that mounts inside the scene, samples the live camera each
+ * frame (throttled by `tickMs`), and renders `@jgengine/react`'s {@link EntityFrames}
+ * through a fullscreen `<Html>` overlay. This is the one-line way an R3F game
+ * gets overhead enemy nameplates/health bars from its own entity array without a
+ * store: pass `entries` + a `renderFrame` that composes the shipped bars. The
+ * projection, viewport culling, and stacking come for free.
+ *
+ * @capability entity-frames R3F overhead entity frames from a caller-owned entity array
+ */
+export function WorldEntityFrames({ entries, renderFrame, tickMs = 0, className, anchorTransform, ...layout }) {
+    const size = useThree((state) => state.size);
+    const project = useWorldProjection();
+    // Re-render on a frame cadence so projected screen positions follow the camera.
+    const [, setTick] = useState(0);
+    useThreeFrameTick(setTick, tickMs);
+    return (_jsx(Html, { fullscreen: true, calculatePosition: pinToViewport, zIndexRange: [19, 0], style: { pointerEvents: "none" }, children: _jsx(EntityFrames, { entries: entries, project: project, renderFrame: renderFrame, viewport: { width: size.width, height: size.height }, className: className, anchorTransform: anchorTransform, ...layout }) }));
+}
+/** Bumps a state setter on a throttled frame cadence to drive re-projection. */
+function useThreeFrameTick(setTick, tickMs) {
+    const last = useRef(0);
+    useFrame((state) => {
+        const elapsedMs = state.clock.elapsedTime * 1000;
+        if (elapsedMs - last.current < tickMs)
+            return;
+        last.current = elapsedMs;
+        setTick((n) => n + 1);
+    });
+}

package/dist/world/WorldHud.js

@@ -3,6 +3,7 @@ import { Html, Line } from "@react-three/drei";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useMemo, useRef, useState } from "react";
 import * as THREE from "three";
+import { useGameStore } from "@jgengine/react/hooks";
 import { useGameContext } from "@jgengine/react/provider";
 import { useCameraShake } from "../camera/shakeChannel.js";
 import { CALIBRATED_TRAUMA_SHAKE_DECAY_PER_SECOND } from "../camera/rigMath.js";
@@ -108,11 +109,7 @@ export function WorldNameplates({ statId = "health", height = 2.3, roles, resolv
  */
 export function WorldObjectHighlights({ color = "#facc15", radius, y = 0.05 }) {
     const ctx = useGameContext();
-    const [ids, setIds] = useState(() => ctx.scene.object.selection.list());
-    useEffect(() => {
-        setIds(ctx.scene.object.selection.list());
-        return ctx.subscribe(() => setIds(ctx.scene.object.selection.list()));
-    }, [ctx]);
+    const ids = useGameStore((c) => c.scene.object.selection.list());
     return (_jsx(_Fragment, { children: ids.map((id) => {
             const object = ctx.scene.object.get(id);
             if (object === null)
@@ -241,6 +238,11 @@ export function ProjectileTracers({ lifeMs = 130 }) {
     const timers = useRef(new Set());
     useEffect(() => {
         const unsub = ctx.game.events.on("projectile.settled", (event) => {
+            // fireProjectile is a generic seam (bullets, bolts, grenades, launchers). A straight
+            // muzzle→impact line only reads as a real shot for direct-fire projectiles; drawing one
+            // for an arced/lobbed shot fakes a beam through a path it never flew, so skip those.
+            if (event.ballistic)
+                return;
             const id = nextId.current++;
             const start = new THREE.Vector3(event.origin[0], event.origin[1], event.origin[2]);
             if (event.from === ctx.player.userId)

package/dist/world/WorldPings.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import { type MarkerCollection, type MarkerKindStyle, type MarkerView } from "@jgengine/core/world/markers";
+/** Props for {@link WorldPings}. */
+export interface WorldPingsProps {
+    /** Static views, an external marker source, or a native `MarkerSet` (e.g. the one a `createPingSystem` writes to). */
+    markers: MarkerCollection;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    /** Only render markers whose `meta.ping === true`. Default true; false renders every marker as a ping. */
+    pingsOnly?: boolean;
+    /** Height above the ground the arrowhead floats. Default 2.4. */
+    height?: number;
+    /** Draw a billboarded callout chip (glyph + `meta.callout`/`label`). Default true. */
+    showCallout?: boolean;
+    /** Full override for a ping's callout markup. */
+    renderCallout?: (marker: MarkerView, style: MarkerKindStyle) => ReactNode;
+}
+/**
+ * World-space pings — the in-scene side of a ping/marker: a bobbing downward
+ * arrowhead pointing at the spot, a ground ring, and a billboarded callout,
+ * colored by marker kind and fading in/out over the marker's lifetime. Reads a
+ * `MarkerSet` (typically the one a `createPingSystem` writes to), a marker
+ * source, or a static array; mount through `PlayableGame.WorldOverlay`.
+ *
+ * @capability world-pings in-scene ping markers — a bobbing downward arrowhead, ground ring, and billboarded callout per marker, colored by kind and fading over the marker's lifetime
+ */
+export declare function WorldPings({ markers, kindStyles, pingsOnly, height, showCallout, renderCallout, }: WorldPingsProps): ReactNode;