@jgengine/shell 0.9.0 → 0.11.0

package/dist/useShellMultiplayerSync.js

@@ -0,0 +1,98 @@
+import { useEffect } from "react";
+import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { attachWorldSync } from "./worldSync.js";
+/** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
+export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers) {
+    useEffect(() => {
+        if (ctx === null || multiplayer === null)
+            return;
+        let disposed = false;
+        const cleanups = [];
+        void multiplayer.backend.transport
+            .joinServer({ gameId: multiplayer.gameId })
+            .then((joined) => {
+            if (disposed) {
+                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId });
+                return;
+            }
+            serverIdRef.current = joined.serverId;
+            if (isServerAuthoritative(playable.game.multiplayer) && multiplayer.backend.feeds !== undefined) {
+                cleanups.push(attachWorldSync(multiplayer.backend.feeds, joined.serverId, ctx));
+            }
+            cleanups.push(multiplayer.backend.presenceSync.subscribe(joined.serverId, (rows) => {
+                setRemotePlayers(rows.filter((row) => row.userId !== multiplayer.userId));
+            }));
+            const seen = new Set();
+            let injecting = false;
+            for (const action of multiplayer.feedActions) {
+                cleanups.push(ctx.game.feed.subscribe(action, (entry) => {
+                    if (injecting)
+                        return;
+                    void multiplayer.backend
+                        .pushFeedEntry({
+                        serverId: joined.serverId,
+                        action,
+                        entry: { at: entry.at, data: entry.data, from: multiplayer.userId },
+                    })
+                        .catch(() => undefined);
+                }));
+                const remoteUnsub = multiplayer.backend.feeds?.subscribeFeed({ serverId: joined.serverId, action }, (view) => {
+                    for (const raw of view.entries) {
+                        const remote = raw;
+                        if (typeof remote.from !== "string" || remote.from === multiplayer.userId)
+                            continue;
+                        const key = `${action}|${remote.from}|${remote.at ?? 0}`;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        injecting = true;
+                        ctx.game.feed.push(action, remote.data);
+                        injecting = false;
+                    }
+                });
+                if (remoteUnsub !== undefined)
+                    cleanups.push(remoteUnsub);
+            }
+            const chatSync = multiplayer.backend.chatSyncFor?.(joined.serverId);
+            if (chatSync !== undefined && ctx.game.chat !== undefined) {
+                const chat = ctx.game.chat;
+                const globalChannelIds = new Set(chat
+                    .channels()
+                    .filter((channel) => channel.kind === "global")
+                    .map((channel) => channel.id));
+                const seenRemoteChat = new Set();
+                cleanups.push(ctx.game.events.subscribe("chat.message", (event) => {
+                    if (event.fromUserId !== multiplayer.userId)
+                        return;
+                    if (!globalChannelIds.has(event.channelId))
+                        return;
+                    void chatSync.send(event.channelId, event.body).catch(() => undefined);
+                }));
+                for (const channelId of globalChannelIds) {
+                    cleanups.push(chatSync.subscribe(channelId, (messages) => {
+                        for (const message of messages) {
+                            if (message.fromUserId === multiplayer.userId)
+                                continue;
+                            if (seenRemoteChat.has(message.id))
+                                continue;
+                            seenRemoteChat.add(message.id);
+                            chat.send(message.fromUserId, message.channelId, message.body);
+                        }
+                    }));
+                }
+            }
+        })
+            .catch(() => undefined);
+        return () => {
+            disposed = true;
+            for (const cleanup of cleanups)
+                cleanup();
+            const serverId = serverIdRef.current;
+            serverIdRef.current = null;
+            setRemotePlayers([]);
+            if (serverId !== null) {
+                void multiplayer.backend.transport.leaveServer({ serverId }).catch(() => undefined);
+            }
+        };
+    }, [ctx, multiplayer, playable]);
+}

package/dist/visibility/CullingProvider.js

@@ -4,7 +4,7 @@ import { useThree, useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { createVisibilitySystem } from "@jgengine/core/visibility/visibilitySystem";
-import { CAMERA_POST_FRAME_PRIORITY } from "../camera/index.js";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
 const ALWAYS_VISIBLE = () => true;
 const alwaysVisibleRef = { current: ALWAYS_VISIBLE };
 const CullingContext = createContext(null);

package/dist/water/OceanConfig.d.ts

@@ -96,7 +96,9 @@ export declare const OCEAN_QUALITY_PRESETS: Record<OceanQualityPreset, {
     resolution: number;
 }>;
 export declare const DEFAULT_OCEAN_CONFIG: ResolvedOceanConfig;
+/** @internal */
 export declare function createOceanConfig(patch?: OceanConfig): ResolvedOceanConfig;
+/** @internal */
 export declare function buildOceanWaveUniforms(config: ResolvedOceanConfig): {
     directions: THREE.Vector2[];
     params: THREE.Vector4[];

package/dist/water/OceanConfig.js

@@ -87,6 +87,7 @@ function resolveWave(wave, fallback, config, customWaves) {
         steepness: clamp(finiteOr(wave?.steepness, fallback.steepness) * config.steepness, 0, 1.2),
     };
 }
+/** @internal */
 export function createOceanConfig(patch = {}) {
     const quality = patch.quality ?? DEFAULT_OCEAN_CONFIG.quality;
     const preset = OCEAN_QUALITY_PRESETS[quality];
@@ -126,6 +127,7 @@ export function createOceanConfig(patch = {}) {
     const waves = Array.from({ length: MAX_OCEAN_WAVES }, (_, index) => resolveWave(inputWaves[index], defaultWaves[index], withoutWaves, customWaves));
     return { ...withoutWaves, waves };
 }
+/** @internal */
 export function buildOceanWaveUniforms(config) {
     const directions = [];
     const params = [];

package/dist/weather/fireSpreadPose.d.ts

@@ -1,2 +1,3 @@
 import type { Euler, Quaternion } from "three";
+/** @internal */
 export declare function setBillboardQuaternion(quaternion: Quaternion, euler: Euler, yaw: number): void;

package/dist/weather/fireSpreadPose.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function setBillboardQuaternion(quaternion, euler, yaw) {
     euler.set(0, yaw, 0);
     quaternion.setFromEuler(euler);

package/dist/weather/weatherGeometry.d.ts

@@ -1,2 +1,3 @@
 import * as THREE from "three";
+/** @internal */
 export declare function createWeatherQuadGeometry(maxCount: number, seed: number): THREE.InstancedBufferGeometry;

package/dist/weather/weatherGeometry.js

@@ -1,5 +1,6 @@
 import * as THREE from "three";
 import { createWeatherSeedAttributes } from "./weatherMath.js";
+/** @internal */
 export function createWeatherQuadGeometry(maxCount, seed) {
     const count = Math.max(0, Math.floor(maxCount));
     const geometry = new THREE.InstancedBufferGeometry();

package/dist/weather/weatherMath.d.ts

@@ -2,10 +2,13 @@ export declare const DEFAULT_RAIN_COUNT = 2000;
 export declare const DEFAULT_SNOW_COUNT = 1500;
 export declare const DEFAULT_RAIN_DENSITY = 0.45;
 export declare const DEFAULT_SNOW_DENSITY = 0.5;
+/** @internal */
 export declare function clampWeatherRatio(value: number): number;
+/** @internal */
 export declare function resolveWeatherInstanceCount(maxCount: number, density: number, budget?: number): number;
 export interface WeatherSeedAttributes {
     spawn: Float32Array;
     drift: Float32Array;
 }
+/** @internal */
 export declare function createWeatherSeedAttributes(maxCount: number, seed: number): WeatherSeedAttributes;

package/dist/weather/weatherMath.js

@@ -2,6 +2,7 @@ export const DEFAULT_RAIN_COUNT = 2000;
 export const DEFAULT_SNOW_COUNT = 1500;
 export const DEFAULT_RAIN_DENSITY = 0.45;
 export const DEFAULT_SNOW_DENSITY = 0.5;
+/** @internal */
 export function clampWeatherRatio(value) {
     if (!Number.isFinite(value))
         return 0;
@@ -11,11 +12,13 @@ export function clampWeatherRatio(value) {
         return 1;
     return value;
 }
+/** @internal */
 export function resolveWeatherInstanceCount(maxCount, density, budget) {
     const safeMax = Math.max(0, Math.floor(maxCount));
     const capped = budget === undefined ? safeMax : Math.min(safeMax, Math.max(0, Math.floor(budget)));
     return Math.floor(capped * clampWeatherRatio(density));
 }
+/** @internal */
 export function createWeatherSeedAttributes(maxCount, seed) {
     const count = Math.max(0, Math.floor(maxCount));
     const spawn = new Float32Array(count * 3);

package/dist/weather/weatherUniforms.d.ts

@@ -11,8 +11,11 @@ export interface WeatherUniformOptions {
     lightning?: number;
     timeScale?: number;
 }
+/** @internal */
 export declare function createWeatherUniformSet(options?: WeatherUniformOptions): WeatherUniformSet;
+/** @internal */
 export declare function WeatherUniformProvider({ children, ...options }: WeatherUniformOptions & {
     children: ReactNode;
 }): import("react").JSX.Element;
+/** @internal */
 export declare function useWeatherUniformSet(options?: WeatherUniformOptions): WeatherUniformSet;

package/dist/weather/weatherUniforms.js

@@ -3,6 +3,7 @@ import { createContext, useContext, useMemo } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 const WeatherUniformContext = createContext(null);
+/** @internal */
 export function createWeatherUniformSet(options = {}) {
     const wind = options.wind ?? [0, 0, 0];
     return {
@@ -21,11 +22,13 @@ function useUniformTicker(uniforms, options, enabled = true) {
         uniforms.lightning.value = options.lightning ?? 0;
     });
 }
+/** @internal */
 export function WeatherUniformProvider({ children, ...options }) {
     const uniforms = useMemo(() => createWeatherUniformSet(options), []);
     useUniformTicker(uniforms, options);
     return _jsx(WeatherUniformContext.Provider, { value: uniforms, children: children });
 }
+/** @internal */
 export function useWeatherUniformSet(options = {}) {
     const shared = useContext(WeatherUniformContext);
     const local = useMemo(() => createWeatherUniformSet(options), []);

package/dist/world/RetainedVfx.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Renders retained VFX instances (`combat.vfxInstance` ops from {@link GameContext}'s `scene.entity.vfxInstance`
+ * store) as long-lived beams whose endpoints follow live entity poses. Auto-mounted by the player shell alongside
+ * the one-shot {@link WorldSpellVfx} overlay. `upsert`/`update` mutate render resources imperatively (no per-frame
+ * React allocation); only create/stop change the mounted set, and `stop` fades out over its requested duration.
+ * Beam is the first shipped retained renderer; other kinds are ignored here for a future renderer to claim.
+ *
+ * @internal
+ */
+export declare function RetainedVfx(): import("react").JSX.Element;

package/dist/world/RetainedVfx.js

@@ -0,0 +1,136 @@
+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 * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+const UP = new THREE.Vector3(0, 1, 0);
+/**
+ * Resolve an endpoint into `out`. A world point is used literally; an entity id resolves to its live pose lifted
+ * by `lift` (so a beam meets an entity near chest height, not its feet). Returns false when an entity ref is
+ * missing, letting the caller hide the effect until the target exists again.
+ */
+function resolveRef(ctx, ref, lift, out) {
+    if (ref === undefined)
+        return false;
+    if (typeof ref === "string") {
+        const entity = ctx.scene.entity.get(ref);
+        if (entity === null)
+            return false;
+        out.set(entity.position[0], entity.position[1] + lift, entity.position[2]);
+        return true;
+    }
+    out.set(ref[0], ref[1], ref[2]);
+    return true;
+}
+/**
+ * One retained beam mesh. It reads its authoritative state from the shared live map every frame and resolves
+ * `from`/`to` refs against the entity store, so an endpoint bound to a moving entity follows it with no per-frame
+ * command traffic or React re-render — parameter updates mutate the render resources imperatively.
+ */
+function RetainedBeam({ id, live, onFadeComplete, }) {
+    const ctx = useGameContext();
+    const meshRef = useRef(null);
+    const matRef = useRef(null);
+    const from = useRef(new THREE.Vector3());
+    const to = useRef(new THREE.Vector3());
+    const delta = useRef(new THREE.Vector3());
+    const quat = useRef(new THREE.Quaternion());
+    useFrame(() => {
+        const entry = live.get(id);
+        const mesh = meshRef.current;
+        const mat = matRef.current;
+        if (entry === undefined || mesh === null || mat === null)
+            return;
+        const lift = entry.state.params?.lift ?? 1;
+        const hasFrom = resolveRef(ctx, entry.state.from, lift, from.current);
+        const hasTo = resolveRef(ctx, entry.state.to, lift, to.current);
+        if (!hasFrom || !hasTo) {
+            mesh.visible = false;
+            return;
+        }
+        delta.current.subVectors(to.current, from.current);
+        const length = Math.max(0.001, delta.current.length());
+        mesh.visible = true;
+        mesh.position.set((from.current.x + to.current.x) / 2, (from.current.y + to.current.y) / 2, (from.current.z + to.current.z) / 2);
+        quat.current.setFromUnitVectors(UP, delta.current.normalize());
+        mesh.quaternion.copy(quat.current);
+        const thickness = entry.state.radius ?? 0.12;
+        mesh.scale.set(thickness, length, thickness);
+        mat.color.set(entry.state.color);
+        const baseOpacity = entry.state.params?.opacity ?? 0.85;
+        if (entry.fade === null) {
+            mat.opacity = baseOpacity;
+        }
+        else {
+            const p = (performance.now() - entry.fade.startedAt) / Math.max(1, entry.fade.ms);
+            if (p >= 1) {
+                onFadeComplete(id);
+                return;
+            }
+            mat.opacity = baseOpacity * (1 - p);
+        }
+    });
+    return (_jsxs("mesh", { ref: meshRef, renderOrder: 998, visible: false, children: [_jsx("cylinderGeometry", { args: [1, 1, 1, 8, 1, true] }), _jsx("meshBasicMaterial", { ref: matRef, transparent: true, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 })] }));
+}
+/**
+ * Renders retained VFX instances (`combat.vfxInstance` ops from {@link GameContext}'s `scene.entity.vfxInstance`
+ * store) as long-lived beams whose endpoints follow live entity poses. Auto-mounted by the player shell alongside
+ * the one-shot {@link WorldSpellVfx} overlay. `upsert`/`update` mutate render resources imperatively (no per-frame
+ * React allocation); only create/stop change the mounted set, and `stop` fades out over its requested duration.
+ * Beam is the first shipped retained renderer; other kinds are ignored here for a future renderer to claim.
+ *
+ * @internal
+ */
+export function RetainedVfx() {
+    const ctx = useGameContext();
+    const live = useRef(new Map()).current;
+    const [ids, setIds] = useState([]);
+    useEffect(() => {
+        // Seed from any instances created before this overlay mounted.
+        for (const state of ctx.scene.entity.vfxInstance.list()) {
+            if (state.kind !== "beam")
+                continue;
+            live.set(state.id, { state, fade: null });
+        }
+        if (live.size > 0)
+            setIds([...live.keys()]);
+        const off = ctx.game.events.on("combat.vfxInstance", (op) => {
+            if (op.op === "stop") {
+                const entry = live.get(op.id);
+                if (entry === undefined)
+                    return;
+                if (op.fadeMs !== undefined && op.fadeMs > 0) {
+                    entry.fade = { ms: op.fadeMs, startedAt: performance.now() };
+                }
+                else {
+                    live.delete(op.id);
+                    setIds([...live.keys()]);
+                }
+                return;
+            }
+            const state = op.instance;
+            if (state === undefined || state.kind !== "beam")
+                return;
+            const existing = live.get(op.id);
+            if (existing === undefined) {
+                live.set(op.id, { state, fade: null });
+                setIds([...live.keys()]);
+            }
+            else {
+                // Update: mutate state in place; RetainedBeam reads it next frame (no React re-render).
+                existing.state = state;
+                existing.fade = null;
+            }
+        });
+        return () => {
+            off();
+            live.clear();
+            setIds([]);
+        };
+    }, [ctx, live]);
+    function removeId(id) {
+        live.delete(id);
+        setIds((current) => current.filter((entry) => entry !== id));
+    }
+    return (_jsx(_Fragment, { children: ids.map((id) => (_jsx(RetainedBeam, { id: id, live: live, onFadeComplete: removeId }, id))) }));
+}

package/dist/world/WorldHud.d.ts

@@ -1,14 +1,63 @@
+import { type ReactNode } from "react";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
-export type { WorldBarSample } from "./worldBarSamples.js";
-export { collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
+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, }: {
+export declare function WorldEntityBars({ statId, height, roles, resolveRole, maxDistance, }: {
     statId: string;
     height?: number;
     roles?: readonly CatalogEntityRole[];
     resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
+    /** Hide bars for entities farther than this from the player (world units). Default 60. */
+    maxDistance?: number;
 }): import("react").JSX.Element;
+/** Props for `WorldNameplates` — entity filter, refresh rate, and headless className/render hooks. */
+export interface WorldNameplatesProps {
+    statId?: string;
+    height?: number;
+    roles?: readonly CatalogEntityRole[];
+    resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
+    /** Hide nameplates for entities farther than this from the player (world units). Default 40. */
+    maxDistance?: number;
+    /** Minimum ms between position/health refreshes — trades smoothness for fewer re-renders at scale. Default 120. */
+    tickMs?: number;
+    className?: string;
+    nameplateClassName?: string;
+    nameClassName?: string;
+    barClassName?: string;
+    fillClassName?: string;
+    /** Full override for one nameplate's markup; receives the raw sample (name, percent, screen x/y). */
+    renderNameplate?: (sample: NameplateSample) => ReactNode;
+}
+/**
+ * Billboarded name + 78×6px HP bar over every nearby non-local entity that
+ * passes `roles`/`maxDistance` — headless (className/data-* slots on every
+ * part, `renderNameplate` for a full swap), turned on declaratively via
+ * `defineGame({ nameplates })` rather than mounted by hand.
+ *
+ * @capability nameplates billboarded name + HP bar over nearby entities
+ */
+export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, tickMs, 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. */
+    color?: string;
+    /** Fixed ring radius; omitted derives one from the object's catalog `halfExtents` (falls back to 1.2). */
+    radius?: number;
+    /** Ground offset so the ring doesn't z-fight the object's base. Default 0.05. */
+    y?: number;
+}
+/**
+ * Ground ring over every `ctx.scene.object.selection`-ed placed object — the object-layer counterpart
+ * to `WorldEntityBars`/`WorldNameplates`. Mount it once in the game's scene (headless: no defaults are
+ * imposed beyond a visible ring) instead of hand-rolling a selection highlight through `WorldOverlay`
+ * against external state.
+ *
+ * @capability world-object-highlights ground-ring highlight over every selected placed object
+ */
+export declare function WorldObjectHighlights({ color, radius, y }: WorldObjectHighlightsProps): import("react").JSX.Element;
 export declare function WorldFloatText({ height, lifeMs }: {
     height?: number;
     lifeMs?: number;

package/dist/world/WorldHud.js

@@ -5,16 +5,17 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 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 { collectWorldBarSamples, paintWorldBarSamples, } from "./worldBarSamples.js";
+import { collectNameplateSamples, collectWorldBarSamples, paintWorldBarSamples, } from "./worldBarSamples.js";
 import { telegraphPulseOpacity } from "./telegraphPulse.js";
-export { collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
+export { collectNameplateSamples, collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
 export { telegraphPulseOpacity } from "./telegraphPulse.js";
-const MUZZLE_HEIGHT = 1.4;
 function pinOverlayToViewport(_el, _camera, size) {
     return [size.width / 2, size.height / 2];
 }
-export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, }) {
+export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxDistance = 60, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
@@ -36,11 +37,91 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, }) {
             canvas.height = pixelH;
         }
         camera.updateMatrixWorld();
-        collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current);
+        collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current, maxDistance);
         paintWorldBarSamples(canvas, samplesRef.current, dpr);
     });
     return (_jsx(Html, { fullscreen: true, calculatePosition: pinOverlayToViewport, zIndexRange: [20, 0], style: { pointerEvents: "none" }, children: _jsx("canvas", { ref: canvasRef, style: { width: "100%", height: "100%", display: "block", pointerEvents: "none" } }) }));
 }
+/**
+ * Billboarded name + 78×6px HP bar over every nearby non-local entity that
+ * passes `roles`/`maxDistance` — headless (className/data-* slots on every
+ * part, `renderNameplate` for a full swap), turned on declaratively via
+ * `defineGame({ nameplates })` rather than mounted by hand.
+ *
+ * @capability nameplates billboarded name + HP bar over nearby entities
+ */
+export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, tickMs = 120, 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);
+    useFrame((state) => {
+        const nowMs = state.clock.elapsedTime * 1000;
+        if (nowMs - lastTickRef.current < 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);
+        setSamples([...samplesRef.current]);
+    });
+    return (_jsx(Html, { fullscreen: true, calculatePosition: pinOverlayToViewport, zIndexRange: [19, 0], style: { pointerEvents: "none" }, children: _jsx("div", { className: className, "data-nameplates": true, children: samples.map((sample) => renderNameplate !== undefined ? (_jsx("div", { style: { position: "absolute", left: sample.x, top: sample.y }, children: renderNameplate(sample) }, sample.id)) : (_jsxs("div", { className: nameplateClassName, "data-nameplate": sample.id, style: {
+                    position: "absolute",
+                    left: sample.x,
+                    top: sample.y,
+                    transform: "translate(-50%, -100%)",
+                    display: "flex",
+                    flexDirection: "column",
+                    alignItems: "center",
+                    gap: 2,
+                    fontFamily: "ui-sans-serif, system-ui, sans-serif",
+                }, children: [_jsx("span", { className: nameClassName, "data-nameplate-name": true, style: {
+                            fontSize: 12,
+                            fontWeight: 700,
+                            color: "#f1f5f9",
+                            textShadow: "0 1px 3px rgba(0,0,0,0.9)",
+                            whiteSpace: "nowrap",
+                        }, children: sample.name }), sample.percent !== null ? (_jsx("span", { className: barClassName, "data-nameplate-bar": true, style: {
+                            display: "block",
+                            width: 78,
+                            height: 6,
+                            borderRadius: 2,
+                            background: "rgba(0,0,0,0.65)",
+                            border: "1px solid rgba(0,0,0,0.8)",
+                            overflow: "hidden",
+                        }, children: _jsx("span", { className: fillClassName, "data-nameplate-fill": true, style: {
+                                display: "block",
+                                width: `${sample.percent * 100}%`,
+                                height: "100%",
+                                background: sample.percent > 0.5 ? "#22c55e" : sample.percent > 0.25 ? "#f59e0b" : "#ef4444",
+                            } }) })) : null] }, sample.id))) }) }));
+}
+/**
+ * Ground ring over every `ctx.scene.object.selection`-ed placed object — the object-layer counterpart
+ * to `WorldEntityBars`/`WorldNameplates`. Mount it once in the game's scene (headless: no defaults are
+ * imposed beyond a visible ring) instead of hand-rolling a selection highlight through `WorldOverlay`
+ * against external state.
+ *
+ * @capability world-object-highlights ground-ring highlight over every selected placed object
+ */
+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]);
+    return (_jsx(_Fragment, { children: ids.map((id) => {
+            const object = ctx.scene.object.get(id);
+            if (object === null)
+                return null;
+            const halfExtents = ctx.scene.object.catalog(id)?.halfExtents;
+            const ringRadius = radius ?? (halfExtents === undefined ? 1.2 : Math.max(halfExtents[0], halfExtents[2]) * 1.35);
+            return (_jsxs("mesh", { position: [object.position[0], object.position[1] + y, object.position[2]], rotation: [-Math.PI / 2, 0, 0], renderOrder: 998, children: [_jsx("ringGeometry", { args: [ringRadius * 0.82, ringRadius, 40] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85, side: THREE.DoubleSide, depthWrite: false, toneMapped: false })] }, id));
+        }) }));
+}
 function FloatTextItem({ event, lifeMs }) {
     const [shown, setShown] = useState(false);
     const style = useMemo(() => resolveFloatTextStyle(event), [event]);
@@ -142,6 +223,10 @@ export function CombatCameraShake() {
     const shake = useCameraShake();
     useEffect(() => {
         return ctx.game.events.on("combat.hitReaction", (event) => {
+            if (event.trauma !== undefined) {
+                shake.shake(event.trauma, CALIBRATED_TRAUMA_SHAKE_DECAY_PER_SECOND);
+                return;
+            }
             if (event.shake === undefined)
                 return;
             shake.shake(event.shake.amplitude, event.shake.decay);
@@ -157,14 +242,14 @@ export function ProjectileTracers({ lifeMs = 130 }) {
     useEffect(() => {
         const unsub = ctx.game.events.on("projectile.settled", (event) => {
             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);
             setTracers((current) => [
                 ...current,
                 {
                     id,
-                    points: [
-                        new THREE.Vector3(event.origin[0], event.origin[1] + MUZZLE_HEIGHT, event.origin[2]),
-                        new THREE.Vector3(event.at[0], event.at[1], event.at[2]),
-                    ],
+                    points: [start, new THREE.Vector3(event.at[0], event.at[1], event.at[2])],
                 },
             ]);
             const handle = setTimeout(() => {

package/dist/world/WorldScene.d.ts

@@ -0,0 +1,21 @@
+import { type ComponentType, type ReactNode } from "react";
+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, }: {
+    entitySprites: Record<string, EntitySpriteConfig> | undefined;
+    entityModels: Record<string, string | ModelConfig> | undefined;
+    objectModels: Record<string, string | ModelConfig> | undefined;
+    objectStyles: Record<string, ObjectStyle> | undefined;
+    environment: ComponentType | undefined;
+    assets: AssetCatalog;
+    renderEntity: ((entity: SceneEntity) => ReactNode) | undefined;
+    renderObject: ((object: SceneObject) => ReactNode) | undefined;
+    selectedIds: ReadonlySet<string>;
+    hideLocalActor: boolean;
+}): import("react").JSX.Element;
+export declare function RemotePlayers({ rows }: {
+    rows: PresencePoseRow[];
+}): import("react").JSX.Element;