@jgengine/shell 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All eight `@jgengine/*` packages are versioned in lockstep, so this one file
+covers every release. Format follows [Keep a Changelog](https://keepachangelog.com);
+each release **leads with a Migrate block** — the concrete steps to move a game
+from the previous version onto the new APIs — because the point of a bump is to
+let consumers pick up the better stuff, not just to list what moved.
+
+Agents building on the published SDK can also read this programmatically:
+`import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
+same data as typed values, so an updater can diff its installed version against
+the latest and surface the migration steps.
+
+## Unreleased
+
+_Nothing yet._
+
+## 0.5.0
+
+An additive release: **every 0.4.0 API is unchanged**, so upgrading is only a
+version bump. New pure primitives across progression, inventory slots, world
+geometry, and React store bindings.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.5.0` (the eight packages version in lockstep).
+- No code change is required — 0.5.0 adds surface, it doesn't move or remove any.
+- Optional: replace a game's hand-rolled `progression/curves.ts` with the new `leveling(...)` track. `leveling({ xpForLevel: { kind: "power", base, exponent, round: "floor" }, maxLevel })` returns `xpForLevel`, `resolve`, and `grantXp(ctx.scene.entity.stats, userId, amount, onLevelUp?)` — a drop-in for the old `xpRequiredForLevel` / `resolveLevelProgress` / `grantXp` exports. `ctx.scene.entity.stats` satisfies the primitive's `LevelingStatAccess` structurally, so no adapter is needed.
+
+### Added
+
+- `@jgengine/core/game/progression` — genre-agnostic progression primitive. `curve(spec)` / `evalCurve(spec, x)` evaluate declarative scalar curves (`const`, `linear`, `power`, `geometric`, `steps`, `piecewise`, each with optional `round`/`min`/`max`) for speed-by-level, difficulty-by-wave, loot drop-rate ramps, and similar scaling. `leveling(config)` builds the stateful XP→level track (threshold accumulation, multi-level grants, cap handling, `stat.levelUp` emit) on top of an `xpForLevel` curve.
+- `@jgengine/core/inventory/slotModel` — pure slot-grid primitives (`createSlots`, `placeAt`, `removeAt`, `moveSlot`).
+- `@jgengine/core/world/geometry`, `/world/interiors`, `/world/placement` — pure world primitives: grid snapping, footprint AABBs and overlap, interior/exterior spaces, and placement validation.
+- `@jgengine/react/engineStore` — raw-store React bindings (`useEngineState`, `useEngineStore`, `useEngineEvent`).
+- Pure/functional tiers for the `trade`, `unlocks`, `quest`, and `feed` verbs in `@jgengine/core/game`.
+
+## 0.4.0
+
+Baseline release: the eight `@jgengine/*` packages (core, ws, sql, react,
+convex, node, shell, assets) as the first tracked version. No migration —
+this is the floor changelog entries are measured against.

package/dist/GamePlayerShell.js

@@ -1,7 +1,8 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Canvas, useFrame, useLoader } from "@react-three/fiber";
 import { Component, useEffect, useMemo, useRef, useState } from "react";
 import * as THREE from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { createActionStateTracker, hotbarSlotActionIndex, resolveActionCommand, toActionStateBindingMap, } from "@jgengine/core/input/actionBindings";
 import { resolveActivePrompt } from "@jgengine/core/interaction/proximityPrompt";
 import { advancePlayerMotion, createEmptyMovementKeys, createPlayerMotionState, resolveMovementIntent, } from "@jgengine/core/movement/movementModel";
@@ -10,6 +11,8 @@ import { useGameContext } from "@jgengine/react/provider";
 import { useSceneEntities, useSceneObjects, usePlayer, useTarget } from "@jgengine/react/hooks";
 import { GameProvider } from "@jgengine/react/provider";
 import { GAME_SIM_FRAME_PRIORITY, GameOrbitCamera } from "./camera/index.js";
+import { GameFirstPersonCamera } from "./camera/GameFirstPersonCamera.js";
+import { ProjectileTracers, Reticle, WorldEntityBars, WorldFloatText } from "./world/WorldHud.js";
 const DEV_USER_ID = "dev-player";
 const TURN_SPEED = 2.4;
 const PRIMARY_CLICK_MOVE_THRESHOLD_PX = 6;
@@ -51,7 +54,7 @@ function hotbarIdFor(playable) {
     const hud = declarations.find(([, declaration]) => declaration.hud === "hotbar");
     return (hud ?? declarations[0])?.[0] ?? null;
 }
-function executeHotbarSlot(ctx, hotbarId, slot, yaw) {
+function executeHotbarSlot(ctx, hotbarId, slot, yaw, pitch) {
     const stack = ctx.player.inventory.state(hotbarId).slots[slot];
     if (stack === undefined || stack === null)
         return { ok: false, error: `Hotbar slot ${slot + 1} is empty` };
@@ -59,7 +62,7 @@ function executeHotbarSlot(ctx, hotbarId, slot, yaw) {
         from: ctx.player.userId,
         itemId: stack.itemId,
         inventoryId: hotbarId,
-        aim: { yaw, pitch: 0 },
+        aim: { yaw, pitch },
     });
     return result.error === undefined ? { ok: true } : { ok: false, error: result.error };
 }
@@ -78,13 +81,27 @@ function EntitySprite({ sprite }) {
     }, [texture]);
     return (_jsx("sprite", { "position-y": sprite.y, scale: [sprite.width, sprite.height, 1], children: _jsx("spriteMaterial", { map: texture, transparent: true, alphaTest: 0.08, depthWrite: false }) }));
 }
-function EntityMarker({ entity, sprite, isLocal, targeted, onSelect, }) {
+function EntityModel({ model }) {
+    const gltf = useLoader(GLTFLoader, model.url);
+    const scene = useMemo(() => gltf.scene.clone(true), [gltf]);
+    const scale = model.scale ?? 1;
+    return _jsx("primitive", { object: scene, "position-y": model.y ?? 0, scale: [scale, scale, scale] });
+}
+function resolveModel(value, assets) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        return value;
+    const url = assets.resolve(value)?.url;
+    return url === undefined ? undefined : { url };
+}
+function EntityMarker({ entity, model, sprite, isLocal, targeted, onSelect, }) {
     const color = isLocal ? "#4ade80" : entity.role === "npc" ? colorFromId(entity.name) : "#9ca3af";
     return (_jsxs("group", { position: [entity.position[0], entity.position[1], entity.position[2]], "rotation-y": entity.rotationY, onPointerDown: (event) => {
             event.stopPropagation();
             if (!isLocal)
                 onSelect(entity);
-        }, children: [sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : entity.role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, children: [_jsx("sphereGeometry", { args: [0.45, 16, 16] }), _jsx("meshStandardMaterial", { color: color })] })) : (_jsxs(_Fragment, { children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: color })] }), _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] }));
+        }, children: [model !== undefined ? (_jsx(EntityModel, { model: model })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : entity.role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, children: [_jsx("sphereGeometry", { args: [0.45, 16, 16] }), _jsx("meshStandardMaterial", { color: color })] })) : (_jsxs(_Fragment, { children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: color })] }), _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 GroundPlane() {
     const geometry = useMemo(() => {
@@ -117,7 +134,7 @@ function RockField() {
     }), []);
     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], children: [_jsx("dodecahedronGeometry", { args: [0.8, 0] }), _jsx("meshStandardMaterial", { color: "#6b6f63", roughness: 1 })] }, rock.id))) }));
 }
-function WorldView({ entitySprites }) {
+function WorldView({ entitySprites, entityModels, objectModels, assets, }) {
     const ctx = useGameContext();
     const entities = useSceneEntities();
     const objects = useSceneObjects();
@@ -127,12 +144,16 @@ function WorldView({ entitySprites }) {
         const relation = ctx.scene.entity.canReceive(entity.id, "damage") === null ? "hostile" : "friendly";
         ctx.scene.entity.setTarget(player.userId, relation === "hostile" || entity.role === "npc" ? entity.id : null);
     };
-    return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx("gridHelper", { args: [160, 80, "#3a3f4a", "#2b2f38"], "position-y": 0.01 }), _jsx(RockField, {}), entities.map((entity) => (_jsx(EntityMarker, { entity: entity, sprite: entitySprites?.[entity.name], isLocal: entity.id === player.userId, targeted: entity.id === targetId, onSelect: handleSelect }, entity.id))), objects.map((object) => (_jsxs("mesh", { position: [object.position[0], object.position[1] + 0.5, object.position[2]], "rotation-y": object.rotationY, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx("meshStandardMaterial", { color: colorFromId(object.catalogId) })] }, object.instanceId)))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx("gridHelper", { args: [160, 80, "#3a3f4a", "#2b2f38"], "position-y": 0.01 }), _jsx(RockField, {}), entities.map((entity) => (_jsx(EntityMarker, { entity: entity, model: resolveModel(entityModels?.[entity.name], assets), sprite: entitySprites?.[entity.name], isLocal: entity.id === player.userId, targeted: entity.id === targetId, onSelect: handleSelect }, entity.id))), objects.map((object) => {
+                const model = resolveModel(objectModels?.[object.catalogId], assets) ??
+                    resolveModel(object.catalogId, assets);
+                return (_jsx("group", { position: [object.position[0], object.position[1], object.position[2]], "rotation-y": object.rotationY, children: model !== undefined ? (_jsx(EntityModel, { model: model })) : (_jsxs("mesh", { "position-y": 0.5, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx("meshStandardMaterial", { color: colorFromId(object.catalogId) })] })) }, object.instanceId));
+            })] }));
 }
 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))) }));
 }
-function FrameDriver({ ctx, playable, tracker, yawRef, primaryClickRef, onRuntimeError, multiplayer, serverIdRef, }) {
+function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, onRuntimeError, multiplayer, serverIdRef, }) {
     const motionRef = useRef(createPlayerMotionState());
     const hasReportedTickError = useRef(false);
     const slotActions = useMemo(() => findHotbarSlotActions(playable.game.input), [playable]);
@@ -201,7 +222,7 @@ function FrameDriver({ ctx, playable, tracker, yawRef, primaryClickRef, onRuntim
                 for (const { action, slot } of slotActions) {
                     if (!tracker.wasPressed(action))
                         continue;
-                    const result = executeHotbarSlot(ctx, hotbarId, slot, yawRef.current);
+                    const result = executeHotbarSlot(ctx, hotbarId, slot, yawRef.current, pitchRef.current);
                     if (!result.ok)
                         console.warn(`[jgengine:item-use] ${result.error}`);
                 }
@@ -214,7 +235,7 @@ function FrameDriver({ ctx, playable, tracker, yawRef, primaryClickRef, onRuntim
                         ? preferred
                         : slots.findIndex((stack) => stack !== null);
                     if (slot >= 0) {
-                        const result = executeHotbarSlot(ctx, hotbarId, slot, yawRef.current);
+                        const result = executeHotbarSlot(ctx, hotbarId, slot, yawRef.current, pitchRef.current);
                         if (!result.ok)
                             console.warn(`[jgengine:item-use] ${result.error}`);
                     }
@@ -230,7 +251,7 @@ function FrameDriver({ ctx, playable, tracker, yawRef, primaryClickRef, onRuntim
                         y: focus.position[1],
                         z: focus.position[2],
                         rotationY: focus.rotationY,
-                        rotationPitch: 0,
+                        rotationPitch: pitchRef.current,
                     });
                 }
             }
@@ -270,6 +291,7 @@ export function GamePlayerShell({ playable, multiplayer = null, }) {
     const [remotePlayers, setRemotePlayers] = useState([]);
     const wrapperRef = useRef(null);
     const yawRef = useRef(0);
+    const pitchRef = useRef(0);
     const serverIdRef = useRef(null);
     const cameraDraggingRef = useRef(false);
     const primaryClickRef = useRef(false);
@@ -370,6 +392,14 @@ export function GamePlayerShell({ playable, multiplayer = null, }) {
         return _jsx("div", { className: "h-full w-full bg-neutral-950" });
     const GameUI = playable.GameUI;
     const WorldOverlay = playable.WorldOverlay;
+    const firstPerson = playable.camera?.perspective === "first";
+    const showReticle = firstPerson && playable.camera?.firstPerson?.reticle !== false;
+    const worldBars = playable.worldHealthBars;
+    const barsStatId = worldBars === undefined || worldBars === false
+        ? null
+        : worldBars === true
+            ? "health"
+            : worldBars.statId ?? "health";
     return (_jsxs("div", { ref: wrapperRef, tabIndex: 0, className: "relative h-full w-full bg-neutral-950 outline-none", onKeyDown: (event) => {
             if (event.code === "Tab" || event.code === "Space")
                 event.preventDefault();
@@ -400,7 +430,7 @@ export function GamePlayerShell({ playable, multiplayer = null, }) {
             else if (event.deltaY > 0 && ctx.game.commands.has("ui.hotbarScrollPrev")) {
                 ctx.game.commands.run("ui.hotbarScrollPrev", {});
             }
-        }, children: [_jsxs(Canvas, { camera: { fov: 55, near: 0.1, far: 300 }, children: [_jsx("color", { attach: "background", args: ["#14161b"] }), _jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 }), _jsxs(GameProvider, { context: ctx, children: [_jsx(WorldView, { entitySprites: playable.entitySprites }), WorldOverlay !== undefined ? _jsx(WorldOverlay, {}) : null, _jsx(GameOrbitCamera, { yawRef: yawRef, config: playable.camera, followEntityId: playable.camera?.followEntityId, onCameraFollow: playable.camera?.onCameraFollow, onDragChange: (dragging) => {
+        }, children: [_jsxs(Canvas, { camera: { fov: 55, near: 0.1, far: 300 }, children: [_jsx("color", { attach: "background", args: ["#14161b"] }), _jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 }), _jsxs(GameProvider, { context: ctx, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, assets: playable.game.assets }), WorldOverlay !== undefined ? _jsx(WorldOverlay, {}) : null, barsStatId !== null ? _jsx(WorldEntityBars, { statId: barsStatId }) : null, _jsx(WorldFloatText, {}), _jsx(ProjectileTracers, {}), firstPerson ? (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: playable.camera?.firstPerson, followEntityId: playable.camera?.followEntityId })) : (_jsx(GameOrbitCamera, { yawRef: yawRef, pitchRef: pitchRef, config: playable.camera, followEntityId: playable.camera?.followEntityId, onCameraFollow: playable.camera?.onCameraFollow, onDragChange: (dragging) => {
                                     cameraDraggingRef.current = dragging;
-                                } })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, primaryClickRef: primaryClickRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef })] }), _jsx(GameUiErrorBoundary, { onRuntimeError: reportRuntimeError, children: _jsx(GameProvider, { context: ctx, children: _jsx(GameUI, {}) }) }), _jsx(DiagnosticOverlay, { diagnostics: diagnostics })] }));
+                                } }))] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef })] }), _jsx(GameUiErrorBoundary, { onRuntimeError: reportRuntimeError, children: _jsx(GameProvider, { context: ctx, children: _jsx(GameUI, {}) }) }), showReticle ? _jsx(Reticle, {}) : null, _jsx(DiagnosticOverlay, { diagnostics: diagnostics })] }));
 }

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -0,0 +1,9 @@
+import { type MutableRefObject } from "react";
+import type { FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
+export interface GameFirstPersonCameraProps {
+    yawRef: MutableRefObject<number>;
+    pitchRef: MutableRefObject<number>;
+    config?: FirstPersonCameraConfig;
+    followEntityId?: string;
+}
+export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;

package/dist/camera/GameFirstPersonCamera.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { usePlayer } from "@jgengine/react/hooks";
+import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
+const DEFAULT_EYE_HEIGHT = 1.6;
+const DEFAULT_SENSITIVITY = 0.0025;
+const DEFAULT_MAX_PITCH = 1.45;
+export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }) {
+    const eyeHeight = config?.eyeHeight ?? DEFAULT_EYE_HEIGHT;
+    const sensitivity = config?.sensitivity ?? DEFAULT_SENSITIVITY;
+    const maxPitch = config?.maxPitch ?? DEFAULT_MAX_PITCH;
+    const { userId } = usePlayer();
+    const ctx = useGameContext();
+    const camera = useThree((state) => state.camera);
+    const domElement = useThree((state) => state.gl.domElement);
+    const followId = followEntityId ?? userId;
+    useEffect(() => {
+        const requestLock = () => {
+            if (document.pointerLockElement !== domElement)
+                void domElement.requestPointerLock?.();
+        };
+        const onMove = (event) => {
+            if (document.pointerLockElement !== domElement)
+                return;
+            yawRef.current -= event.movementX * sensitivity;
+            pitchRef.current = Math.max(-maxPitch, Math.min(maxPitch, pitchRef.current - event.movementY * sensitivity));
+        };
+        domElement.addEventListener("click", requestLock);
+        window.addEventListener("mousemove", onMove);
+        return () => {
+            domElement.removeEventListener("click", requestLock);
+            window.removeEventListener("mousemove", onMove);
+        };
+    }, [domElement, sensitivity, maxPitch, yawRef, pitchRef]);
+    useFrame(() => {
+        const entity = ctx.scene.entity.get(followId);
+        if (entity === null)
+            return;
+        const cosPitch = Math.cos(pitchRef.current);
+        camera.position.set(entity.position[0], entity.position[1] + eyeHeight, entity.position[2]);
+        camera.lookAt(camera.position.x + Math.sin(yawRef.current) * cosPitch, camera.position.y + Math.sin(pitchRef.current), camera.position.z + Math.cos(yawRef.current) * cosPitch);
+    }, ORBIT_CAMERA_FRAME_PRIORITY);
+    if (config?.viewmodel === false)
+        return null;
+    return _jsx(FirstPersonViewmodel, { camera: camera });
+}
+function FirstPersonViewmodel({ camera }) {
+    const groupRef = useRef(null);
+    useFrame(() => {
+        const group = groupRef.current;
+        if (group === null)
+            return;
+        group.position.copy(camera.position);
+        group.quaternion.copy(camera.quaternion);
+        group.translateX(0.34);
+        group.translateY(-0.26);
+        group.translateZ(-0.72);
+    }, GAME_SIM_FRAME_PRIORITY);
+    return (_jsxs("group", { ref: groupRef, children: [_jsxs("mesh", { position: [0, 0, -0.22], children: [_jsx("boxGeometry", { args: [0.09, 0.11, 0.55] }), _jsx("meshStandardMaterial", { color: "#22262d", metalness: 0.6, roughness: 0.35 })] }), _jsxs("mesh", { position: [0, -0.13, 0.04], rotation: [0.35, 0, 0], children: [_jsx("boxGeometry", { args: [0.08, 0.18, 0.11] }), _jsx("meshStandardMaterial", { color: "#33373f", metalness: 0.4, roughness: 0.5 })] }), _jsxs("mesh", { position: [0, 0.03, -0.52], rotation: [Math.PI / 2, 0, 0], children: [_jsx("cylinderGeometry", { args: [0.022, 0.022, 0.18, 10] }), _jsx("meshStandardMaterial", { color: "#0e0f12", metalness: 0.7, roughness: 0.3 })] })] }));
+}

package/dist/camera/GameOrbitCamera.d.ts

@@ -5,6 +5,8 @@ import { type CameraFollowState, type OrbitCameraConfig, type Vec3 } from "./orb
 export type CameraFollowListener = (state: CameraFollowState) => void;
 export interface GameOrbitCameraProps {
     yawRef: MutableRefObject<number>;
+    /** Written each frame with the camera's look elevation (radians) for aim.pitch. */
+    pitchRef?: MutableRefObject<number>;
     config?: Partial<OrbitCameraConfig>;
     followEntityId?: string;
     /** Override orbit target derived from the followed entity. */
@@ -12,6 +14,6 @@ export interface GameOrbitCameraProps {
     onDragChange?: (dragging: boolean) => void;
     onCameraFollow?: CameraFollowListener;
 }
-export declare function GameOrbitCamera({ yawRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, }: GameOrbitCameraProps): import("react").JSX.Element;
+export declare function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, }: GameOrbitCameraProps): import("react").JSX.Element;
 /** Seed orbit target before controls mount (demo spawn at origin). */
 export declare function seedOrbitCameraTarget(camera: Camera, target: Vector3, distance: number, height: number): void;

package/dist/camera/GameOrbitCamera.js

@@ -5,8 +5,8 @@ import { useEffect, useRef } from "react";
 import { MOUSE, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
-import { ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
-export function GameOrbitCamera({ yawRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, }) {
+import { cameraLookPitch, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
+export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, }) {
     const config = resolveOrbitCameraConfig(configPatch);
     const controlsRef = useRef(null);
     const runtimeRef = useRef(null);
@@ -61,6 +61,9 @@ export function GameOrbitCamera({ yawRef, config: configPatch, followEntityId, r
         };
         const [px, , pz] = entity.position;
         yawRef.current = orbitYawFromCamera(camera.position.x, camera.position.z, px, pz);
+        if (pitchRef !== undefined) {
+            pitchRef.current = cameraLookPitch({ x: camera.position.x, y: camera.position.y, z: camera.position.z }, stepped.target);
+        }
         onCameraFollow?.({
             entityId: followId,
             target: stepped.target,
@@ -68,7 +71,7 @@ export function GameOrbitCamera({ yawRef, config: configPatch, followEntityId, r
             distance: runtimeRef.current.lockedDistance ?? stepped.distance,
         });
     }, ORBIT_CAMERA_FRAME_PRIORITY);
-    return (_jsx(OrbitControls, { ref: controlsRef, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, enablePan: false, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, maxPolarAngle: Math.PI / 2.05, minPolarAngle: 0.12, screenSpacePanning: false, mouseButtons: { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.DOLLY, RIGHT: undefined }, onStart: () => {
+    return (_jsx(OrbitControls, { ref: controlsRef, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, enablePan: false, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, maxPolarAngle: config.maxPolarAngle, minPolarAngle: config.minPolarAngle, screenSpacePanning: false, mouseButtons: { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.DOLLY, RIGHT: undefined }, onStart: () => {
             draggingRef.current = true;
             onDragChange?.(true);
         }, onEnd: () => {

package/dist/camera/index.d.ts

@@ -1,2 +1,2 @@
 export { GameOrbitCamera, type CameraFollowListener, type GameOrbitCameraProps } from "./GameOrbitCamera.js";
-export { cameraFollowStep, DEFAULT_ORBIT_CAMERA, distanceBetween, GAME_SIM_FRAME_PRIORITY, lerpVec3, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, resolveTargetSmoothing, seedOrbitFollowState, smoothBlend, type CameraFollowState, type OrbitCameraConfig, type OrbitFollowRuntimeState, type ResolvedOrbitCameraConfig, type Vec3, } from "./orbitCameraMath.js";
+export { cameraFollowStep, cameraLookPitch, DEFAULT_ORBIT_CAMERA, distanceBetween, GAME_SIM_FRAME_PRIORITY, lerpVec3, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, resolveTargetSmoothing, seedOrbitFollowState, smoothBlend, type CameraFollowState, type OrbitCameraConfig, type OrbitFollowRuntimeState, type ResolvedOrbitCameraConfig, type Vec3, } from "./orbitCameraMath.js";

package/dist/camera/index.js

@@ -1,2 +1,2 @@
 export { GameOrbitCamera } from "./GameOrbitCamera.js";
-export { cameraFollowStep, DEFAULT_ORBIT_CAMERA, distanceBetween, GAME_SIM_FRAME_PRIORITY, lerpVec3, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, resolveTargetSmoothing, seedOrbitFollowState, smoothBlend, } from "./orbitCameraMath.js";
+export { cameraFollowStep, cameraLookPitch, DEFAULT_ORBIT_CAMERA, distanceBetween, GAME_SIM_FRAME_PRIORITY, lerpVec3, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, resolveTargetSmoothing, seedOrbitFollowState, smoothBlend, } from "./orbitCameraMath.js";

package/dist/camera/orbitCameraMath.d.ts

@@ -1,5 +1,7 @@
 /** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane. */
 export declare function orbitYawFromCamera(cameraX: number, cameraZ: number, targetX: number, targetZ: number): number;
+/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera. */
+export declare function cameraLookPitch(camera: Vec3, target: Vec3): number;
 export interface Vec3 {
     x: number;
     y: number;
@@ -34,6 +36,9 @@ export interface OrbitCameraConfig {
     dragTargetSmoothing?: number;
     /** Exponential smoothing when re-locking orbit distance. */
     distanceSmoothing?: number;
+    /** Vertical clamp (three.js polar angle, radians): 0 = top-down over the head, PI/2 = level, >PI/2 = look up from below the target. Widen to allow top-down or vertical aim; leave unset for the standard chase feel. */
+    minPolarAngle?: number;
+    maxPolarAngle?: number;
 }
 /** Fully resolved shell config after merging with DEFAULT_ORBIT_CAMERA. */
 export interface ResolvedOrbitCameraConfig {
@@ -51,6 +56,8 @@ export interface ResolvedOrbitCameraConfig {
     targetSmoothing: number;
     dragTargetSmoothing: number;
     distanceSmoothing: number;
+    minPolarAngle: number;
+    maxPolarAngle: number;
 }
 export declare const DEFAULT_ORBIT_CAMERA: ResolvedOrbitCameraConfig;
 /** Run simulation/movement before orbit follow so poses are current. */

package/dist/camera/orbitCameraMath.js

@@ -4,6 +4,11 @@ export function orbitYawFromCamera(cameraX, cameraZ, targetX, targetZ) {
     const dz = targetZ - cameraZ;
     return Math.atan2(dx, dz);
 }
+/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera. */
+export function cameraLookPitch(camera, target) {
+    const horizontal = Math.hypot(target.x - camera.x, target.z - camera.z);
+    return Math.atan2(target.y - camera.y, horizontal);
+}
 export const DEFAULT_ORBIT_CAMERA = {
     minDistance: 4,
     maxDistance: 28,
@@ -18,6 +23,8 @@ export const DEFAULT_ORBIT_CAMERA = {
     targetSmoothing: 8,
     dragTargetSmoothing: 11,
     distanceSmoothing: 5,
+    minPolarAngle: 0.12,
+    maxPolarAngle: Math.PI / 2.05,
 };
 /** Run simulation/movement before orbit follow so poses are current. */
 export const GAME_SIM_FRAME_PRIORITY = 0;

package/dist/world/WorldHud.d.ts

@@ -0,0 +1,14 @@
+export declare function WorldEntityBars({ statId, height }: {
+    statId: string;
+    height?: number;
+}): import("react").JSX.Element;
+export declare function WorldFloatText({ height, lifeMs }: {
+    height?: number;
+    lifeMs?: number;
+}): import("react").JSX.Element;
+export declare function ProjectileTracers({ lifeMs }: {
+    lifeMs?: number;
+}): import("react").JSX.Element;
+export declare function Reticle({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/world/WorldHud.js

@@ -0,0 +1,78 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Html, Line } from "@react-three/drei";
+import { useEffect, useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { useEntityStat, useSceneEntities } from "@jgengine/react/hooks";
+const MUZZLE_HEIGHT = 1.4;
+function EntityBar({ entity, statId, height }) {
+    const stat = useEntityStat(entity.id, statId);
+    if (stat === null)
+        return null;
+    const range = stat.max - stat.min;
+    const percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
+    return (_jsx(Html, { position: [entity.position[0], entity.position[1] + height, entity.position[2]], center: true, distanceFactor: 12, zIndexRange: [20, 0], children: _jsx("div", { className: "h-2.5 w-28 overflow-hidden rounded-sm border border-black/70 bg-black/70 shadow", children: _jsx("div", { className: "h-full bg-gradient-to-r from-rose-600 to-red-400", style: { width: `${percent * 100}%` } }) }) }));
+}
+export function WorldEntityBars({ statId, height = 2.2 }) {
+    const ctx = useGameContext();
+    const entities = useSceneEntities();
+    const playerId = ctx.player.userId;
+    return (_jsx(_Fragment, { children: entities.map((entity) => entity.id === playerId ? null : (_jsx(EntityBar, { entity: entity, statId: statId, height: height }, entity.id))) }));
+}
+function FloatTextItem({ text, kind, lifeMs }) {
+    const [shown, setShown] = useState(false);
+    useEffect(() => {
+        const raf = requestAnimationFrame(() => setShown(true));
+        return () => cancelAnimationFrame(raf);
+    }, []);
+    return (_jsx("span", { className: kind === "heal" ? "text-emerald-300" : "text-amber-200", style: {
+            display: "inline-block",
+            fontWeight: 800,
+            fontSize: "18px",
+            textShadow: "0 1px 3px rgba(0,0,0,0.95)",
+            transition: `transform ${lifeMs}ms ease-out, opacity ${lifeMs}ms ease-out`,
+            transform: shown ? "translateY(-30px)" : "translateY(0)",
+            opacity: shown ? 0 : 1,
+        }, children: text }));
+}
+export function WorldFloatText({ height = 1.9, lifeMs = 950 }) {
+    const ctx = useGameContext();
+    const [floaters, setFloaters] = useState([]);
+    const nextId = useRef(0);
+    useEffect(() => {
+        return ctx.game.events.on("entity.floatText", (event) => {
+            const id = nextId.current++;
+            setFloaters((current) => [
+                ...current,
+                { id, position: event.position, text: event.text, kind: event.kind },
+            ]);
+            window.setTimeout(() => setFloaters((current) => current.filter((floater) => floater.id !== id)), lifeMs);
+        });
+    }, [ctx, lifeMs]);
+    return (_jsx(_Fragment, { children: floaters.map((floater) => (_jsx(Html, { position: [floater.position[0], floater.position[1] + height, floater.position[2]], center: true, distanceFactor: 12, zIndexRange: [30, 0], children: _jsx(FloatTextItem, { text: floater.text, kind: floater.kind, lifeMs: lifeMs }) }, floater.id))) }));
+}
+export function ProjectileTracers({ lifeMs = 130 }) {
+    const ctx = useGameContext();
+    const [tracers, setTracers] = useState([]);
+    const nextId = useRef(0);
+    useEffect(() => {
+        return ctx.game.events.on("projectile.settled", (event) => {
+            const id = nextId.current++;
+            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]),
+                    ],
+                },
+            ]);
+            window.setTimeout(() => setTracers((current) => current.filter((tracer) => tracer.id !== id)), lifeMs);
+        });
+    }, [ctx, lifeMs]);
+    return (_jsx(_Fragment, { children: tracers.map((tracer) => (_jsx(Line, { points: tracer.points, color: "#fde68a", lineWidth: 2, transparent: true, opacity: 0.85 }, tracer.id))) }));
+}
+export function Reticle({ className }) {
+    return (_jsx("div", { className: className ?? "pointer-events-none absolute inset-0 z-20 flex items-center justify-center", children: _jsxs("div", { className: "relative h-6 w-6", children: [_jsx("span", { className: "absolute left-1/2 top-1/2 h-1.5 w-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-white/90 shadow" }), _jsx("span", { className: "absolute left-1/2 top-0 h-2 w-px -translate-x-1/2 bg-white/80" }), _jsx("span", { className: "absolute bottom-0 left-1/2 h-2 w-px -translate-x-1/2 bg-white/80" }), _jsx("span", { className: "absolute left-0 top-1/2 h-px w-2 -translate-y-1/2 bg-white/80" }), _jsx("span", { className: "absolute right-0 top-1/2 h-px w-2 -translate-y-1/2 bg-white/80" })] }) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -10,7 +10,10 @@
     "url": "git+https://github.com/Noisemaker111/jgengine.git",
     "directory": "packages/shell"
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "exports": {
     "./*": {
       "types": "./dist/*.d.ts",
@@ -18,14 +21,14 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
-    "check-types": "tsc --noEmit -p tsconfig.json",
+    "build": "tsgo -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
+    "check-types": "tsgo --noEmit -p tsconfig.json",
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.3.0",
-    "@jgengine/react": "^0.3.0",
-    "@jgengine/ws": "^0.3.0"
+    "@jgengine/core": "^0.5.0",
+    "@jgengine/react": "^0.5.0",
+    "@jgengine/ws": "^0.5.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",