@jgengine/shell 0.10.0 → 0.12.0

package/dist/world/WorldHud.js

@@ -5,11 +5,12 @@ 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";
 function pinOverlayToViewport(_el, _camera, size) {
     return [size.width / 2, size.height / 2];
@@ -41,6 +42,86 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxD
     });
     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);

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;

package/dist/world/WorldScene.js

@@ -0,0 +1,186 @@
+import { Fragment as _Fragment, 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 { objectVisualScale } from "@jgengine/core/scene/objectStore";
+import { WORLD_ITEM_ENTITY_NAME } from "@jgengine/core/game/worldItem";
+import { beginFallbackSeam, endFallbackPass, reportFallbackSeam, } from "@jgengine/core/devtools/fallbackSeams";
+import { useGameContext } from "@jgengine/react/provider";
+import { useSceneEntityIds, useSceneObjectIds, useGameStore, usePlayer, useTarget } from "@jgengine/react/hooks";
+import { colorFromId } from "../worldSky.js";
+import { DefaultSurface, detailMaps } from "../render/defaultSurface.js";
+import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
+import { resolveModel, resolveEntityModel, tryResolveCatalogModel } from "../render/resolveModel.js";
+import { useRenderVisibility } from "../visibility/CullingProvider.js";
+import { writeEntityPose } from "./entityPose.js";
+import { POINTER_ENTITY_KEY, POINTER_OBJECT_KEY } from "../pointer/pointerService.js";
+const GROUND_SIZE = 160;
+const GROUND_SEGMENTS = 80;
+function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, selected, onSelect, }) {
+    const groupRef = useRef(null);
+    const ctx = useGameContext();
+    const visibleRef = useRenderVisibility();
+    const entityId = entity.id;
+    const role = entity.role;
+    const name = entity.name;
+    const color = isLocal ? "#4ade80" : role === "npc" ? colorFromId(name) : "#9ca3af";
+    useFrame(() => {
+        const group = groupRef.current;
+        if (group === null)
+            return;
+        const live = ctx.scene.entity.get(entityId);
+        if (live === null)
+            return;
+        writeEntityPose(group, live);
+        group.visible = visibleRef.current(entityId);
+    });
+    return (_jsxs("group", { ref: groupRef, userData: { [POINTER_ENTITY_KEY]: entityId }, onPointerDown: (event) => {
+            event.stopPropagation();
+            if (isLocal)
+                return;
+            const live = ctx.scene.entity.get(entityId);
+            if (live !== null)
+                onSelect(live);
+        }, children: [selected ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [0.8, 0.95, 32] }), _jsx("meshBasicMaterial", { color: "#34d399", transparent: true, opacity: 0.9 })] })) : null, custom !== undefined && custom !== null ? (custom) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: entityId, fallback: sprite !== undefined ? _jsx(EntitySprite, { sprite: sprite }) : undefined })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, castShadow: true, receiveShadow: true, children: [_jsx("sphereGeometry", { args: [0.45, 24, 24] }), _jsx(DefaultSurface, { color: color })] })) : (_jsxs("group", { scale: ctx.scene.entity.visualScaleOf(entityId), children: [_jsxs("mesh", { "position-y": 0.95, castShadow: true, receiveShadow: true, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx(DefaultSurface, { color: color, roughness: 0.6 })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
+}
+function ObjectMarker({ object, custom, model, style, }) {
+    const groupRef = useRef(null);
+    const ctx = useGameContext();
+    const visibleRef = useRenderVisibility();
+    const instanceId = object.instanceId;
+    const [scaleX, scaleY, scaleZ] = objectVisualScale(object.visual);
+    const color = object.visual?.color ?? style?.color ?? colorFromId(object.catalogId);
+    const opacity = object.visual?.opacity ?? style?.opacity ?? 1;
+    useFrame(() => {
+        const group = groupRef.current;
+        if (group === null)
+            return;
+        const live = ctx.scene.object.get(instanceId);
+        if (live === null)
+            return;
+        writeEntityPose(group, live);
+        group.visible = visibleRef.current(instanceId);
+    });
+    return (_jsx("group", { ref: groupRef, userData: { [POINTER_OBJECT_KEY]: instanceId }, children: custom !== undefined && custom !== null ? (custom) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: instanceId })) : style?.hidden === true ? null : (_jsxs("mesh", { "position-y": 0.5 * scaleY, scale: [scaleX, scaleY, scaleZ], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx(DefaultSurface, { color: color, transparent: opacity < 1, opacity: opacity })] })) }));
+}
+function GroundPlane() {
+    const geometry = useMemo(() => {
+        const next = new THREE.PlaneGeometry(GROUND_SIZE, GROUND_SIZE, GROUND_SEGMENTS, GROUND_SEGMENTS);
+        const positions = next.attributes.position;
+        const base = new THREE.Color("#33452f");
+        const high = new THREE.Color("#4a5c3a");
+        const colors = new Float32Array(positions.count * 3);
+        const tmp = new THREE.Color();
+        for (let index = 0; index < positions.count; index += 1) {
+            const x = positions.getX(index);
+            const y = positions.getY(index);
+            const height = Math.sin(x * 0.16) * 0.12 +
+                Math.cos(y * 0.11) * 0.1 +
+                Math.sin((x + y) * 0.05) * 0.16;
+            positions.setZ(index, height);
+            const blend = 0.5 + Math.sin(x * 0.21) * 0.25 + Math.cos(y * 0.17) * 0.25;
+            tmp.copy(base).lerp(high, Math.min(1, Math.max(0, blend)));
+            colors[index * 3] = tmp.r;
+            colors[index * 3 + 1] = tmp.g;
+            colors[index * 3 + 2] = tmp.b;
+        }
+        next.setAttribute("color", new THREE.BufferAttribute(colors, 3));
+        next.computeVertexNormals();
+        return next;
+    }, []);
+    const material = useMemo(() => {
+        const normal = detailMaps().normal.clone();
+        normal.repeat.set(48, 48);
+        normal.needsUpdate = true;
+        return new THREE.MeshStandardMaterial({
+            vertexColors: true,
+            roughness: 0.95,
+            metalness: 0,
+            normalMap: normal,
+            normalScale: new THREE.Vector2(0.8, 0.8),
+            envMapIntensity: 0.4,
+        });
+    }, []);
+    useEffect(() => () => material.dispose(), [material]);
+    return _jsx("mesh", { "rotation-x": -Math.PI / 2, geometry: geometry, material: material, receiveShadow: true });
+}
+function RockField() {
+    const rocks = useMemo(() => Array.from({ length: 18 }, (_, index) => {
+        const angle = index * 2.399963229728653;
+        const radius = 10 + ((index * 17) % 58);
+        return {
+            id: `rock-${index}`,
+            x: Math.cos(angle) * radius,
+            z: Math.sin(angle) * radius,
+            scale: 0.45 + ((index * 13) % 11) / 10,
+            rotation: angle,
+        };
+    }), []);
+    return (_jsx(_Fragment, { children: rocks.map((rock) => (_jsxs("mesh", { position: [rock.x, 0.25 * rock.scale, rock.z], rotation: [0.1, rock.rotation, -0.08], scale: [rock.scale * 1.4, rock.scale * 0.7, rock.scale], castShadow: true, receiveShadow: true, children: [_jsx("dodecahedronGeometry", { args: [0.8, 1] }), _jsx(DefaultSurface, { color: "#6b6f63", roughness: 0.95 })] }, rock.id))) }));
+}
+function WorldEnvironment({ environment: Environment }) {
+    // Dev diagnostic (no-op unless armed): a missing environment component means the default green
+    // ground/rocks stand in for an unauthored scene. Re-zero then report so this is idempotent.
+    beginFallbackSeam("ground");
+    if (Environment !== undefined)
+        return _jsx(Environment, {});
+    reportFallbackSeam("ground", "noScene");
+    return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx(RockField, {})] }));
+}
+function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {
+    const ctx = useGameContext();
+    const entityIds = useSceneEntityIds();
+    const objectIds = useSceneObjectIds();
+    const player = usePlayer();
+    const targetId = useTarget(player.userId);
+    const controlledId = useGameStore((c) => c.player.possession.active(player.userId));
+    const handleSelect = (entity) => {
+        const relation = ctx.scene.entity.canReceive(entity.id, "damage") === null ? "hostile" : "friendly";
+        ctx.scene.entity.setTarget(controlledId, relation === "hostile" || entity.role === "npc" ? entity.id : null);
+    };
+    // Dev diagnostic (no-op unless armed): re-zero the entity/object seams before this render re-tallies
+    // which actors fall back to primitives. Committing the log runs in a useEffect after the render.
+    beginFallbackSeam("entity");
+    beginFallbackSeam("object");
+    useEffect(() => {
+        endFallbackPass();
+    });
+    return (_jsxs(_Fragment, { children: [entityIds.map((entityId) => {
+                const entity = ctx.scene.entity.get(entityId);
+                if (entity === null || entity.name === WORLD_ITEM_ENTITY_NAME)
+                    return null;
+                if (hideLocalActor && entityId === controlledId)
+                    return null;
+                const custom = renderEntity?.(entity);
+                const model = resolveEntityModel(entityModels?.[entity.name], assets, entity.name);
+                const sprite = entitySprites?.[entity.name];
+                // Entity models resolve via the hard resolveModel (throws on a present-but-missing id), so
+                // reaching the primitive capsule with no model or sprite means the mapping was omitted.
+                if ((custom === undefined || custom === null) && model === undefined && sprite === undefined) {
+                    reportFallbackSeam("entity", "omittedMapping");
+                }
+                return (_jsx(EntityMarker, { entity: entity, custom: custom, model: model, sprite: sprite, isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), onSelect: handleSelect }, entityId));
+            }), objectIds.map((instanceId) => {
+                const object = ctx.scene.object.get(instanceId);
+                if (object === null)
+                    return null;
+                const custom = renderObject?.(object);
+                const model = resolveModel(objectModels?.[object.catalogId], assets, {
+                    seam: "objectModels",
+                    key: object.catalogId,
+                }) ?? tryResolveCatalogModel(object.catalogId, assets);
+                const style = objectStyles?.[object.catalogId];
+                // Reaching the primitive box means no model resolved. A present-but-unresolved objectModels
+                // key implies its asset pack is not pulled; an absent key is an omitted (often intended) mapping.
+                if ((custom === undefined || custom === null) && model === undefined && style?.hidden !== true) {
+                    reportFallbackSeam("object", objectModels?.[object.catalogId] === undefined ? "omittedMapping" : "unpulledPack");
+                }
+                return (_jsx(ObjectMarker, { object: object, custom: custom, model: model, style: style }, instanceId));
+            })] }));
+}
+export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {
+    return (_jsxs(_Fragment, { children: [_jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor })] }));
+}
+export function RemotePlayers({ rows }) {
+    return (_jsx(_Fragment, { children: rows.map((row) => (_jsxs("group", { position: [row.position.x, row.position.y, row.position.z], "rotation-y": row.rotationY, children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: colorFromId(row.userId) })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] }, row.userId))) }));
+}

package/dist/world/WorldVfx.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Renders `combat.vfx` bursts as additive sprite-particle effects in the world scene. Auto-mounted by the
+ * player shell alongside the other world overlays; games emit effects via `ctx.scene.entity.vfx(...)`.
+ *
+ * @internal
+ */
+export declare function WorldSpellVfx({ tailMs }: {
+    tailMs?: number;
+}): import("react").JSX.Element;

package/dist/world/WorldVfx.js

@@ -0,0 +1,184 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+const PARTICLE_COUNT = {
+    projectile: 7,
+    beam: 6,
+    nova: 14,
+    glow: 10,
+    spark: 12,
+};
+function planarDir() {
+    const angle = Math.random() * Math.PI * 2;
+    return new THREE.Vector3(Math.cos(angle), 0, Math.sin(angle));
+}
+function sphereDir() {
+    return new THREE.Vector3(Math.random() * 2 - 1, Math.random() * 2 - 1, Math.random() * 2 - 1)
+        .normalize();
+}
+function makeParticles(kind) {
+    const count = PARTICLE_COUNT[kind];
+    const out = [];
+    for (let i = 0; i < count; i += 1) {
+        if (kind === "nova") {
+            out.push({ offset: new THREE.Vector3(), dir: planarDir(), speed: 1, size: 0.5 + Math.random() * 0.4, delay: 0 });
+        }
+        else if (kind === "spark") {
+            const dir = sphereDir();
+            dir.y = Math.abs(dir.y) * 0.6 + 0.2;
+            out.push({ offset: new THREE.Vector3(), dir, speed: 2.4 + Math.random() * 1.8, size: 0.28 + Math.random() * 0.22, delay: 0 });
+        }
+        else if (kind === "glow") {
+            out.push({
+                offset: planarDir().multiplyScalar(0.35 + Math.random() * 0.5),
+                dir: new THREE.Vector3(0, 1, 0),
+                speed: 0.5 + Math.random() * 0.6,
+                size: 0.55 + Math.random() * 0.5,
+                delay: Math.random() * 0.3,
+            });
+        }
+        else if (kind === "beam") {
+            out.push({ offset: new THREE.Vector3(), dir: new THREE.Vector3(), speed: 0, size: 0.45 + Math.random() * 0.3, delay: 0 });
+        }
+        else {
+            out.push({
+                offset: sphereDir().multiplyScalar(0.12),
+                dir: new THREE.Vector3(),
+                speed: 0,
+                size: 0.4 + Math.random() * 0.25,
+                delay: i * 0.05,
+            });
+        }
+    }
+    return out;
+}
+function useRadialTexture() {
+    return useMemo(() => {
+        const size = 64;
+        const canvas = document.createElement("canvas");
+        canvas.width = size;
+        canvas.height = size;
+        const c = canvas.getContext("2d");
+        if (c !== null) {
+            const gradient = c.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+            gradient.addColorStop(0, "rgba(255,255,255,1)");
+            gradient.addColorStop(0.35, "rgba(255,255,255,0.65)");
+            gradient.addColorStop(1, "rgba(255,255,255,0)");
+            c.fillStyle = gradient;
+            c.fillRect(0, 0, size, size);
+        }
+        const texture = new THREE.CanvasTexture(canvas);
+        texture.needsUpdate = true;
+        return texture;
+    }, []);
+}
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function VfxItem({ event, texture }) {
+    const born = useRef(performance.now());
+    const sprites = useRef([]);
+    const ringRef = useRef(null);
+    const ringMat = useRef(null);
+    const beamMat = useRef(null);
+    const color = useMemo(() => new THREE.Color(event.color), [event.color]);
+    const from = useMemo(() => new THREE.Vector3(event.from[0], event.from[1] + 1, event.from[2]), [event.from]);
+    const to = useMemo(() => (event.to === undefined ? from.clone() : new THREE.Vector3(event.to[0], event.to[1] + 1, event.to[2])), [event.to, from]);
+    const radius = event.radius ?? 2.5;
+    const beam = useMemo(() => {
+        const delta = new THREE.Vector3().subVectors(to, from);
+        const length = Math.max(0.001, delta.length());
+        const mid = new THREE.Vector3().addVectors(from, to).multiplyScalar(0.5);
+        const quat = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), delta.clone().normalize());
+        return { length, mid, quat };
+    }, [from, to]);
+    const particles = useMemo(() => makeParticles(event.kind), [event.kind]);
+    const scratch = useRef(new THREE.Vector3());
+    useFrame(() => {
+        const p = clamp01((performance.now() - born.current) / event.durationMs);
+        const kind = event.kind;
+        for (let i = 0; i < particles.length; i += 1) {
+            const sprite = sprites.current[i];
+            const particle = particles[i];
+            if (sprite === undefined || sprite === null || particle === undefined)
+                continue;
+            const pos = scratch.current;
+            let opacity = 0;
+            let scale = particle.size;
+            if (kind === "projectile") {
+                const travel = clamp01(p * 1.15 - particle.delay);
+                pos.copy(from).lerp(to, travel).add(particle.offset);
+                opacity = (1 - p) * (i === 0 ? 1 : 0.55);
+                scale = particle.size * (i === 0 ? 1 : 0.7);
+            }
+            else if (kind === "beam") {
+                pos.copy(from).lerp(to, i / Math.max(1, particles.length - 1));
+                opacity = (1 - p) * 0.8;
+            }
+            else if (kind === "nova") {
+                pos.set(event.from[0], event.from[1] + 0.4, event.from[2]).addScaledVector(particle.dir, radius * p);
+                opacity = (1 - p) * 0.9;
+            }
+            else if (kind === "glow") {
+                const local = clamp01(p - particle.delay);
+                pos.copy(from).add(particle.offset).addScaledVector(particle.dir, particle.speed * local);
+                opacity = Math.sin(clamp01(p) * Math.PI) * 0.9;
+                scale = particle.size * (0.8 + 0.3 * Math.sin(local * Math.PI));
+            }
+            else {
+                pos.copy(to).addScaledVector(particle.dir, particle.speed * p);
+                pos.y -= p * p * 1.4;
+                opacity = (1 - p) * 0.95;
+            }
+            sprite.position.copy(pos);
+            sprite.scale.set(scale, scale, 1);
+            const material = sprite.material;
+            material.opacity = opacity;
+        }
+        if (ringRef.current !== null && ringMat.current !== null) {
+            const s = Math.max(0.001, radius * p);
+            ringRef.current.scale.set(s, s, s);
+            ringMat.current.opacity = (1 - p) * 0.7;
+        }
+        if (beamMat.current !== null) {
+            beamMat.current.opacity = (1 - p) * 0.85;
+        }
+    });
+    return (_jsxs("group", { children: [particles.map((_, i) => (_jsx("sprite", { ref: (node) => {
+                    sprites.current[i] = node;
+                }, children: _jsx("spriteMaterial", { map: texture, color: color, transparent: true, depthWrite: false, depthTest: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 }) }, i))), event.kind === "nova" && (_jsxs("mesh", { ref: ringRef, position: [event.from[0], event.from[1] + 0.06, event.from[2]], rotation: [-Math.PI / 2, 0, 0], renderOrder: 998, children: [_jsx("ringGeometry", { args: [0.82, 1, 48] }), _jsx("meshBasicMaterial", { ref: ringMat, color: color, transparent: true, side: THREE.DoubleSide, depthWrite: false, depthTest: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 })] })), event.kind === "beam" && (_jsxs("mesh", { position: [beam.mid.x, beam.mid.y, beam.mid.z], quaternion: [beam.quat.x, beam.quat.y, beam.quat.z, beam.quat.w], renderOrder: 998, children: [_jsx("cylinderGeometry", { args: [0.12, 0.12, beam.length, 8, 1, true] }), _jsx("meshBasicMaterial", { ref: beamMat, color: color, transparent: true, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 })] }))] }));
+}
+/**
+ * Renders `combat.vfx` bursts as additive sprite-particle effects in the world scene. Auto-mounted by the
+ * player shell alongside the other world overlays; games emit effects via `ctx.scene.entity.vfx(...)`.
+ *
+ * @internal
+ */
+export function WorldSpellVfx({ tailMs = 200 }) {
+    const ctx = useGameContext();
+    const texture = useRadialTexture();
+    const [active, setActive] = useState([]);
+    const key = useRef(0);
+    const timers = useRef(new Set());
+    useEffect(() => {
+        const pending = timers.current;
+        const off = ctx.game.events.on("combat.vfx", (event) => {
+            const entry = { key: key.current++, event };
+            setActive((current) => [...current, entry]);
+            const timer = setTimeout(() => {
+                pending.delete(timer);
+                setActive((current) => current.filter((item) => item.key !== entry.key));
+            }, event.durationMs + tailMs);
+            pending.add(timer);
+        });
+        return () => {
+            off();
+            for (const timer of pending)
+                clearTimeout(timer);
+            pending.clear();
+        };
+    }, [ctx, tailMs]);
+    return (_jsx(_Fragment, { children: active.map((item) => (_jsx(VfxItem, { event: item.event, texture: texture }, item.key))) }));
+}

package/dist/world/entityPose.d.ts

@@ -10,5 +10,7 @@ export interface PoseSource {
     position: readonly [number, number, number];
     rotationY: number;
 }
+/** @internal */
 export declare function writeEntityPose(target: PoseWritable, source: PoseSource): void;
+/** @internal */
 export declare function posesEqual(a: PoseSource, b: PoseSource): boolean;

package/dist/world/entityPose.js

@@ -1,7 +1,9 @@
+/** @internal */
 export function writeEntityPose(target, source) {
     target.position.set(source.position[0], source.position[1], source.position[2]);
     target.rotation.y = source.rotationY;
 }
+/** @internal */
 export function posesEqual(a, b) {
     return (a.position[0] === b.position[0] &&
         a.position[1] === b.position[1] &&

package/dist/world/floatTextStyle.d.ts

@@ -11,4 +11,5 @@ export interface FloatTextStyle {
     fontWeight: number;
     glow: string;
 }
+/** @internal */
 export declare function resolveFloatTextStyle(info: FloatTextInfo): FloatTextStyle;

package/dist/world/floatTextStyle.js

@@ -12,6 +12,7 @@ const ELEMENT_COLORS = {
     holy: "#fef08a",
     void: "#c084fc",
 };
+/** @internal */
 export function resolveFloatTextStyle(info) {
     const crit = info.crit === true || info.hitType === "crit";
     let color;

package/dist/world/telegraphPulse.d.ts

@@ -1 +1,2 @@
+/** @internal */
 export declare function telegraphPulseOpacity(bornMs: number, windupMs: number, nowMs: number): number;

package/dist/world/telegraphPulse.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function telegraphPulseOpacity(bornMs, windupMs, nowMs) {
     const progress = Math.max(0, Math.min(1, (nowMs - bornMs) / Math.max(1, windupMs)));
     return 0.45 + 0.5 * progress;

package/dist/world/worldBarSamples.d.ts

@@ -16,6 +16,7 @@ export interface Projectable {
     y: number;
     z: number;
 }
+/** @internal */
 export declare function collectWorldBarSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
     matrixWorldInverse: unknown;
     projectionMatrix: unknown;
@@ -23,6 +24,30 @@ export declare function collectWorldBarSamples(ctx: GameContext, statId: string,
     width: number;
     height: number;
 }, into: WorldBarSample[], project: Projectable, maxDistance?: number): number;
+/** One entity's projected nameplate: screen `x`/`y`, display `name`, health `percent` (or `null` when statless), and world `distance` from the player. */
+export interface NameplateSample {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    /** Health-stat fraction 0..1, or `null` when the entity carries no `statId` stat (name-only nameplate). */
+    percent: number | null;
+    distance: number;
+}
+/**
+ * Projects every non-local, role/distance-filtered entity into `into` as a
+ * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
+ * own renderer by calling this directly instead of the component.
+ * @internal
+ */
+export declare function collectNameplateSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
+    matrixWorldInverse: unknown;
+    projectionMatrix: unknown;
+}, viewport: {
+    width: number;
+    height: number;
+}, into: NameplateSample[], project: Projectable, maxDistance?: number): number;
+/** @internal */
 export declare function paintWorldBarSamples(canvas: {
     width: number;
     height: number;

package/dist/world/worldBarSamples.js

@@ -1,4 +1,5 @@
 import { worldHealthBarAllowsRole } from "@jgengine/core/game/playableGame";
+/** @internal */
 export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 60) {
     into.length = 0;
     const playerId = ctx.player.userId;
@@ -28,6 +29,43 @@ export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole,
     }
     return into.length;
 }
+/**
+ * Projects every non-local, role/distance-filtered entity into `into` as a
+ * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
+ * own renderer by calling this directly instead of the component.
+ * @internal
+ */
+export function collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 40) {
+    into.length = 0;
+    const playerId = ctx.player.userId;
+    const player = ctx.scene.entity.get(playerId);
+    for (const entity of ctx.scene.entity.list()) {
+        if (entity.id === playerId)
+            continue;
+        if (!worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
+            continue;
+        const distance = player === null
+            ? 0
+            : Math.hypot(entity.position[0] - player.position[0], entity.position[2] - player.position[2]);
+        if (player !== null && distance > maxDistance)
+            continue;
+        const stat = ctx.scene.entity.stats.get(entity.id, statId);
+        let percent = null;
+        if (stat !== null) {
+            const range = stat.max - stat.min;
+            percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
+        }
+        project.set(entity.position[0], entity.position[1] + height, entity.position[2]);
+        project.project(camera);
+        if (project.z < -1 || project.z > 1)
+            continue;
+        const x = (project.x * 0.5 + 0.5) * viewport.width;
+        const y = (-project.y * 0.5 + 0.5) * viewport.height;
+        into.push({ id: entity.id, name: entity.name, x, y, percent, distance });
+    }
+    return into.length;
+}
+/** @internal */
 export function paintWorldBarSamples(canvas, samples, dpr, barWidthPx = 112, barHeightPx = 10) {
     const g = canvas.getContext("2d");
     if (g === null)