@jgengine/shell 0.10.0 → 0.11.0

package/dist/GameUiPreview.js

@@ -37,7 +37,6 @@ export const defaultUiScenario = (ctx, playable) => {
 export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
     const [ctx, setCtx] = useState(null);
     useEffect(() => {
-        playable.game.scene.clear();
         const context = createGameContext({
             definition: playable.game,
             content: playable.content,
@@ -53,7 +52,6 @@ export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
         }
         setCtx(context);
         return () => {
-            playable.game.scene.clear();
             setCtx(null);
         };
     }, [playable, scenario]);

package/dist/audio/audioEngine.js

@@ -1,4 +1,5 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { createDisposer } from "@jgengine/core/game/defineGame";
 import { MusicDirector } from "./musicDirector.js";
 import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 function createNoopEngine() {
@@ -74,6 +75,7 @@ export function createAudioEngine(config = {}) {
         return pending;
     }
     let listenerPosition = { x: 0, y: 0, z: 0 };
+    const activeSpatialUpdaters = new Set();
     function playInternal(soundId, position, loop) {
         const sound = sounds[soundId];
         if (sound === undefined)
@@ -89,35 +91,54 @@ export function createAudioEngine(config = {}) {
         }
         if (sound.url === undefined)
             return null;
-        let gainNode = null;
-        let stopped = false;
+        const disposer = createDisposer();
+        let liveGain = null;
+        function updateGain() {
+            if (liveGain !== null) {
+                liveGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            }
+        }
         void loadBuffer(sound.url).then((buffer) => {
-            if (stopped || buffer === null)
+            if (buffer === null)
                 return;
             const sourceNode = context.createBufferSource();
             sourceNode.buffer = buffer;
             sourceNode.loop = loop || (sound.loop ?? false);
-            gainNode = context.createGain();
+            const gainNode = context.createGain();
             gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             sourceNode.connect(gainNode);
             gainNode.connect(bus);
             sourceNode.start();
+            liveGain = gainNode;
+            disposer.onDispose(() => {
+                try {
+                    sourceNode.stop();
+                }
+                catch {
+                }
+                sourceNode.disconnect();
+                gainNode.disconnect();
+                liveGain = null;
+            });
         });
+        if (loop)
+            activeSpatialUpdaters.add(updateGain);
         return {
             setPosition(next) {
                 currentPosition = next;
-                if (gainNode !== null) {
-                    gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-                }
+                updateGain();
             },
             stop() {
-                stopped = true;
+                activeSpatialUpdaters.delete(updateGain);
+                disposer.dispose();
             },
         };
     }
     return {
         setListenerPose(position) {
             listenerPosition = position;
+            for (const updateGain of activeSpatialUpdaters)
+                updateGain();
         },
         playOneShot(soundId, position) {
             void context.resume().catch(() => undefined);
@@ -140,6 +161,7 @@ export function createAudioEngine(config = {}) {
             void context.resume().catch(() => undefined);
         },
         dispose() {
+            activeSpatialUpdaters.clear();
             director?.dispose();
             void context.close().catch(() => undefined);
         },

package/dist/audio/audioWire.d.ts

@@ -0,0 +1,22 @@
+import type { AudioEngine } from "./audioEngine.js";
+type AudioPlayPayload = {
+    sound: string;
+    at?: readonly [number, number, number];
+};
+type AudioMusicPayload = {
+    theme: string | null;
+    transpose?: number;
+};
+/** Minimal event bus the shell wires to the audio engine. @internal */
+export type AudioEventBus = {
+    on(event: "audio.play", handler: (payload: AudioPlayPayload) => void): () => void;
+    on(event: "audio.music", handler: (payload: AudioMusicPayload) => void): () => void;
+    on(event: "audio.resume", handler: () => void): () => void;
+};
+/**
+ * Subscribe game audio events to the shell audio engine.
+ * Returns a single unsubscribe that tears all three listeners down.
+ * @internal
+ */
+export declare function attachAudioEventWire(events: AudioEventBus, audioEngine: Pick<AudioEngine, "playOneShot" | "playMusic" | "resume">): () => void;
+export {};

package/dist/audio/audioWire.js

@@ -0,0 +1,19 @@
+/**
+ * Subscribe game audio events to the shell audio engine.
+ * Returns a single unsubscribe that tears all three listeners down.
+ * @internal
+ */
+export function attachAudioEventWire(events, audioEngine) {
+    const offPlay = events.on("audio.play", ({ sound, at }) => {
+        audioEngine.playOneShot(sound, at === undefined ? undefined : { x: at[0], y: at[1], z: at[2] });
+    });
+    const offMusic = events.on("audio.music", ({ theme, transpose }) => {
+        audioEngine.playMusic(theme, transpose === undefined ? undefined : { transpose });
+    });
+    const offResume = events.on("audio.resume", () => audioEngine.resume());
+    return () => {
+        offPlay();
+        offMusic();
+        offResume();
+    };
+}

package/dist/behaviour.d.ts

@@ -8,5 +8,6 @@ export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.
- */
+  * @internal
+  */
 export declare function useBehaviourWorld(world: BehaviourWorld, scaleDt?: (rawDt: number) => number): void;

package/dist/behaviour.js

@@ -10,7 +10,8 @@ export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.
- */
+  * @internal
+  */
 export function useBehaviourWorld(world, scaleDt) {
     const driverRef = useRef(createBehaviourWorldDriver(world));
     useEffect(() => {

package/dist/behaviourAttach.d.ts

@@ -1,5 +1,6 @@
 import type { Object3D } from "three";
 import { Behaviour, type BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+/** @internal */
 export declare class Object3DBehaviour extends Behaviour {
     /** @internal */ _object: Object3D | null;
     get object(): Object3D;

package/dist/behaviourAttach.js

@@ -1,4 +1,5 @@
 import { Behaviour } from "@jgengine/core/behaviour/behaviour";
+/** @internal */
 export class Object3DBehaviour extends Behaviour {
     /** @internal */ _object = null;
     get object() {

package/dist/behaviourDriver.d.ts

@@ -1,4 +1,5 @@
 import type { BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+/** @internal */
 export declare function createBehaviourWorldDriver(world: BehaviourWorld): {
     start(): void;
     stop(): void;

package/dist/behaviourDriver.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createBehaviourWorldDriver(world) {
     let running = false;
     return {

package/dist/boundActionDispatch.d.ts

@@ -0,0 +1,13 @@
+import { type ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { ActionCodesMap } from "@jgengine/core/input/actionBindings";
+import { type CommandSink } from "./commandSink.js";
+/** Actions the shell consumes natively and never routes to a same-named command. @internal */
+export declare const RESERVED_INPUT_ACTIONS: ReadonlySet<string>;
+/** Actions from `input` currently held down, for `ctx.input.publish` (#164.1); includes reserved movement/jump actions. @internal */
+export declare function heldActionsFor(tracker: Pick<ActionStateTracker<string>, "isDown">, actions: readonly string[]): string[];
+/** Whether a bound action should fire this frame: on press, or on repeat interval while held (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export declare function shouldFireBoundAction(tracker: Pick<ActionStateTracker<string>, "isDown" | "wasPressed">, action: string, input: ActionCodesMap | undefined, repeatFiredAt: ReadonlyMap<string, number>, now: number): boolean;
+/** Resolves and runs the command bound to `action` via the shell's action→command convention (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export declare function dispatchBoundAction(ctx: GameContext, action: string, yaw: number, pitch: number, aim: Aim, reserved?: ReadonlySet<string>, sink?: CommandSink): void;

package/dist/boundActionDispatch.js

@@ -0,0 +1,37 @@
+import { actionRepeatMs, resolveActionCommand, shouldDispatchAction, } from "@jgengine/core/input/actionBindings";
+import { localCommandSink } from "./commandSink.js";
+/** Actions the shell consumes natively and never routes to a same-named command. @internal */
+export const RESERVED_INPUT_ACTIONS = new Set([
+    "moveForward",
+    "moveBack",
+    "moveLeft",
+    "moveRight",
+    "turnLeft",
+    "turnRight",
+    "sprint",
+    "jump",
+    "tabTarget",
+    "clearTarget",
+    "useAbility",
+    "interact",
+]);
+/** Actions from `input` currently held down, for `ctx.input.publish` (#164.1); includes reserved movement/jump actions. @internal */
+export function heldActionsFor(tracker, actions) {
+    return actions.filter((action) => tracker.isDown(action));
+}
+/** Whether a bound action should fire this frame: on press, or on repeat interval while held (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export function shouldFireBoundAction(tracker, action, input, repeatFiredAt, now) {
+    return shouldDispatchAction({
+        pressed: tracker.wasPressed(action),
+        down: tracker.isDown(action),
+        repeatMs: actionRepeatMs(input?.[action]),
+        lastFiredAt: repeatFiredAt.get(action) ?? null,
+        now,
+    });
+}
+/** Resolves and runs the command bound to `action` via the shell's action→command convention (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export function dispatchBoundAction(ctx, action, yaw, pitch, aim, reserved = RESERVED_INPUT_ACTIONS, sink = localCommandSink(ctx)) {
+    const command = resolveActionCommand(action, (name) => ctx.game.commands.has(name), reserved);
+    if (command !== null)
+        sink.run(command, { yaw, pitch, aim });
+}

package/dist/camera/GameCameraRig.d.ts

@@ -1,6 +1,7 @@
-import { type MutableRefObject } from "react";
+import { type ComponentType, type MutableRefObject } from "react";
 import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
 import type { CameraDirector } from "@jgengine/core/runtime/cameraDirector";
+import { type ViewmodelProps } from "./GameFirstPersonCamera.js";
 export { resolveRigKind } from "./rigResolve.js";
 export interface GameCameraRigProps {
     yawRef: MutableRefObject<number>;
@@ -12,5 +13,7 @@ export interface GameCameraRigProps {
     panKeysEnabled?: boolean;
     /** Runtime follow/cinematic override (#196.2). While present it wins over the static `config` for any field it reports non-`undefined`/non-`null`; absent (or an all-`undefined` snapshot) is a no-op. */
     director?: CameraDirector;
+    /** Custom first-person viewmodel (#542); read only when the resolved rig is `"first"`. */
+    viewmodel?: ComponentType<ViewmodelProps>;
 }
-export declare function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, }: GameCameraRigProps): import("react").JSX.Element;
+export declare function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, viewmodel, }: GameCameraRigProps): import("react").JSX.Element;

package/dist/camera/GameCameraRig.js

@@ -8,7 +8,7 @@ import { resolveDirectedCamera } from "./rigMath.js";
 import { resolveRigKind, turntableAsObserver } from "./rigResolve.js";
 import { CameraShakeContext, createCameraShakeChannel } from "./shakeChannel.js";
 export { resolveRigKind } from "./rigResolve.js";
-export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, }) {
+export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, viewmodel, }) {
     const channel = useMemo(() => createCameraShakeChannel(config?.shake?.decayPerSecond), [config?.shake?.decayPerSecond]);
     const [, notifyDirectorChange] = useReducer((count) => count + 1, 0);
     useEffect(() => {
@@ -27,7 +27,7 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
         const kind = resolveRigKind(config);
         switch (kind) {
             case "first":
-                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined }));
+                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined, viewmodel: viewmodel }));
             case "topDown":
                 return _jsx(TopDownRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
             case "rts":

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -1,12 +1,19 @@
-import { type MutableRefObject } from "react";
+import { type ComponentType, type MutableRefObject } from "react";
 import * as THREE from "three";
 import type { FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
+import type { EntityRenderCues } from "@jgengine/core/combat/renderCues";
 /** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
 export declare function readFirstPersonMuzzle(target: THREE.Vector3): boolean;
+/** Props handed to a custom viewmodel component (#542): a live cue ref (velocity/bob/firing/reloading/recoil/hit) for the followed entity, driven from your own `useFrame` — read `cuesRef.current` there rather than storing it as render state. */
+export interface ViewmodelProps {
+    cuesRef: MutableRefObject<EntityRenderCues>;
+}
 export interface GameFirstPersonCameraProps {
     yawRef: MutableRefObject<number>;
     pitchRef: MutableRefObject<number>;
     config?: FirstPersonCameraConfig;
     followEntityId?: string;
+    /** Custom viewmodel component replacing the built-in three-mesh gun, rendered inside the same camera-locked, muzzle-tracked anchor. Ignored when `config.viewmodel === false`. */
+    viewmodel?: ComponentType<ViewmodelProps>;
 }
-export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;
+export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;

package/dist/camera/GameFirstPersonCamera.js

@@ -5,6 +5,7 @@ import * as THREE from "three";
 import { DEFAULT_EYE_HEIGHT } from "@jgengine/core/combat/shotOrigin";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
+import { useEntityRenderCues } from "../render/useEntityRenderCues.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
 const DEFAULT_SENSITIVITY = 0.0025;
@@ -21,7 +22,7 @@ export function readFirstPersonMuzzle(target) {
     target.copy(muzzleWorld);
     return true;
 }
-export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }) {
+export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }) {
     const eyeHeight = config?.eyeHeight ?? DEFAULT_EYE_HEIGHT;
     const sensitivity = config?.sensitivity ?? DEFAULT_SENSITIVITY;
     const maxPitch = config?.maxPitch ?? DEFAULT_MAX_PITCH;
@@ -32,6 +33,7 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     const domElement = useThree((state) => state.gl.domElement);
     const followId = followEntityId ?? userId;
     const seededRef = useRef(false);
+    const cuesRef = useEntityRenderCues(followId);
     useEffect(() => {
         const requestLock = () => {
             if (window.matchMedia?.("(pointer: coarse)").matches)
@@ -73,9 +75,9 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     }, ORBIT_CAMERA_FRAME_PRIORITY);
     if (config?.viewmodel === false)
         return null;
-    return _jsx(FirstPersonViewmodel, { camera: camera });
+    return _jsx(FirstPersonViewmodel, { camera: camera, viewmodel: viewmodel, cuesRef: cuesRef });
 }
-function FirstPersonViewmodel({ camera }) {
+function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, }) {
     const groupRef = useRef(null);
     useEffect(() => () => {
         muzzleTracked = false;
@@ -92,5 +94,8 @@ function FirstPersonViewmodel({ camera }) {
         muzzleWorld.copy(MUZZLE_OFFSET).applyQuaternion(camera.quaternion).add(camera.position);
         muzzleTracked = true;
     }, GAME_SIM_FRAME_PRIORITY);
+    if (Viewmodel !== undefined) {
+        return (_jsx("group", { ref: groupRef, children: _jsx(Viewmodel, { cuesRef: cuesRef }) }));
+    }
     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/GameInspectionCamera.d.ts

@@ -2,5 +2,5 @@ import { type InspectionCameraConfig } from "./inspectionCameraMath.js";
 export interface GameInspectionCameraProps {
     config?: InspectionCameraConfig;
 }
-/** Model-viewer style rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
+/** Model-viewer / editor rig (#207.7, #866): left-click selects (editor), middle-drag pans, right-drag orbits, scroll zooms toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
 export declare function GameInspectionCamera({ config: configPatch }: GameInspectionCameraProps): import("react").JSX.Element;

package/dist/camera/GameInspectionCamera.js

@@ -4,7 +4,7 @@ import { useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { MOUSE } from "three";
 import { resolveInspectionCameraConfig, resolveInspectionZoomToCursor, seedInspectionCamera, } from "./inspectionCameraMath.js";
-/** Model-viewer style rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
+/** Model-viewer / editor rig (#207.7, #866): left-click selects (editor), middle-drag pans, right-drag orbits, scroll zooms toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
 export function GameInspectionCamera({ config: configPatch }) {
     const config = resolveInspectionCameraConfig(configPatch);
     const controlsRef = useRef(null);
@@ -31,5 +31,5 @@ export function GameInspectionCamera({ config: configPatch }) {
         camera.position.add(controls.target.clone().sub(previous));
         controls.update();
     }, [camera, config.target.x, config.target.y, config.target.z]);
-    return (_jsx(OrbitControls, { ref: controlsRef, makeDefault: true, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, zoomToCursor: resolveInspectionZoomToCursor(config.anchor), enablePan: config.pan, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, minPolarAngle: config.minPolarAngle, maxPolarAngle: config.maxPolarAngle, screenSpacePanning: true, mouseButtons: { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.PAN, RIGHT: MOUSE.PAN } }));
+    return (_jsx(OrbitControls, { ref: controlsRef, makeDefault: true, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, zoomToCursor: resolveInspectionZoomToCursor(config.anchor), enablePan: config.pan, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, minPolarAngle: config.minPolarAngle, maxPolarAngle: config.maxPolarAngle, screenSpacePanning: true, mouseButtons: { LEFT: undefined, MIDDLE: MOUSE.PAN, RIGHT: MOUSE.ROTATE } }));
 }

package/dist/camera/GameOrbitCamera.js

@@ -5,7 +5,7 @@ import { useEffect, useRef } from "react";
 import { MOUSE, PerspectiveCamera, Raycaster, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
-import { cameraLookPitch, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
+import { cameraLookPitch, compensatedFov, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
 import { usePlayerFov } from "./PlayerFov.js";
 export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, pointerControls = false, }) {
     const config = resolveOrbitCameraConfig(configPatch);
@@ -20,6 +20,12 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
     const raycasterRef = useRef(new Raycaster());
     const collisionDirRef = useRef(new Vector3());
     const collisionOriginRef = useRef(new Vector3());
+    const followPayloadRef = useRef({
+        entityId: "",
+        target: { x: 0, y: 0, z: 0 },
+        camera: { x: 0, y: 0, z: 0 },
+        distance: 0,
+    });
     const followId = followEntityId ?? userId;
     useEffect(() => {
         const entity = ctx.scene.entity.get(followId);
@@ -60,12 +66,15 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
             camera.position.set(stepped.camera.x, stepped.camera.y, stepped.camera.z);
         }
         controls.update();
+        let desiredDistance = 0;
+        let pulledDistance = 0;
         if (config.collision.enabled) {
             const t = stepped.target;
             const dx = camera.position.x - t.x;
             const dy = camera.position.y - t.y;
             const dz = camera.position.z - t.z;
             const dist = Math.hypot(dx, dy, dz);
+            desiredDistance = dist;
             if (dist > config.collision.minTargetDistance) {
                 const dir = collisionDirRef.current.set(dx / dist, dy / dist, dz / dist);
                 const ray = raycasterRef.current;
@@ -87,6 +96,7 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
                 if (blocked > 0) {
                     const pulled = Math.max(config.collision.minTargetDistance, blocked - config.collision.padding);
                     camera.position.set(t.x + dir.x * pulled, t.y + dir.y * pulled, t.z + dir.z * pulled);
+                    pulledDistance = pulled;
                 }
             }
         }
@@ -102,17 +112,22 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
         }
         if (camera.isPerspectiveCamera === true) {
             const perspective = camera;
-            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
-                perspective.fov = playerFov.fov;
+            const targetFov = pulledDistance > 0 && pulledDistance < desiredDistance
+                ? compensatedFov(playerFov.fov, desiredDistance, pulledDistance)
+                : playerFov.fov;
+            if (Math.abs(perspective.fov - targetFov) > 0.001) {
+                perspective.fov = targetFov;
                 perspective.updateProjectionMatrix();
             }
         }
-        onCameraFollow?.({
-            entityId: followId,
-            target: stepped.target,
-            camera: runtimeRef.current.camera,
-            distance: runtimeRef.current.lockedDistance ?? stepped.distance,
-        });
+        if (onCameraFollow !== undefined) {
+            const payload = followPayloadRef.current;
+            payload.entityId = followId;
+            payload.target = stepped.target;
+            payload.camera = runtimeRef.current.camera;
+            payload.distance = runtimeRef.current.lockedDistance ?? stepped.distance;
+            onCameraFollow(payload);
+        }
     }, 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: config.maxPolarAngle, minPolarAngle: config.minPolarAngle, screenSpacePanning: false, mouseButtons: pointerControls
             ? { LEFT: undefined, MIDDLE: MOUSE.ROTATE, RIGHT: undefined }

package/dist/camera/cameraBlendMath.d.ts

@@ -8,6 +8,9 @@ export interface CameraBlendScratch {
     elapsed: number;
     duration: number;
 }
+/** @internal */
 export declare function createCameraBlendScratch(Vector3Ctor: new () => Vector3, QuaternionCtor: new () => Quaternion): CameraBlendScratch;
+/** @internal */
 export declare function captureCameraBlendFrom(scratch: CameraBlendScratch, position: Vector3, quaternion: Quaternion, fov: number, duration: number): void;
+/** @internal */
 export declare function applyCameraBlendStep(scratch: CameraBlendScratch, camera: Camera, targetFov: number, dt: number): boolean;

package/dist/camera/cameraBlendMath.js

@@ -1,4 +1,5 @@
 import { smoothstep } from "./rigMath.js";
+/** @internal */
 export function createCameraBlendScratch(Vector3Ctor, QuaternionCtor) {
     return {
         fromPos: new Vector3Ctor(),
@@ -10,6 +11,7 @@ export function createCameraBlendScratch(Vector3Ctor, QuaternionCtor) {
         duration: 0,
     };
 }
+/** @internal */
 export function captureCameraBlendFrom(scratch, position, quaternion, fov, duration) {
     scratch.fromPos.copy(position);
     scratch.fromQuat.copy(quaternion);
@@ -20,6 +22,7 @@ export function captureCameraBlendFrom(scratch, position, quaternion, fov, durat
 function isPerspective(camera) {
     return camera.isPerspectiveCamera === true;
 }
+/** @internal */
 export function applyCameraBlendStep(scratch, camera, targetFov, dt) {
     scratch.elapsed += dt;
     const t = scratch.duration <= 0 ? 1 : Math.min(scratch.elapsed / scratch.duration, 1);

package/dist/camera/fovPreference.d.ts

@@ -7,13 +7,17 @@ export interface PlayerFovBounds {
     max: number;
     defaultFov: number;
 }
+/** @internal */
 export declare function resolvePlayerFovBounds(options?: {
     min?: number;
     max?: number;
     default?: number;
 }): PlayerFovBounds;
+/** @internal */
 export declare function clampPlayerFov(value: unknown, min?: number, max?: number): number;
+/** @internal */
 export declare function loadPlayerFov(bounds?: PlayerFovBounds, storage?: Pick<Storage, "getItem"> | null | undefined): number;
+/** @internal */
 export declare function savePlayerFov(value: number, bounds?: PlayerFovBounds, storage?: Pick<Storage, "setItem"> | null | undefined): number;
 /**
  * Composition model for perspective rigs:
@@ -21,5 +25,6 @@ export declare function savePlayerFov(value: number, bounds?: PlayerFovBounds, s
  * - poseFov is the rig's authored FOV (includes chase-speed modulation, ADS zoom, transitions)
  * - relative mode shifts the authored FOV by (preference − default) so mods still stack
  * - absolute mode (cinematic keyframes) keeps the authored FOV as-is
- */
+  * @internal
+  */
 export declare function composePlayerFov(preference: number, poseFov: number, mode?: "relative" | "absolute", bounds?: PlayerFovBounds): number;

package/dist/camera/fovPreference.js

@@ -3,6 +3,7 @@ export const PLAYER_FOV_DEFAULT = CAMERA_FRUSTUM_DEFAULTS.fov;
 export const PLAYER_FOV_MIN = 40;
 export const PLAYER_FOV_MAX = 120;
 export const PLAYER_FOV_STORAGE_KEY = "jgengine:player-fov";
+/** @internal */
 export function resolvePlayerFovBounds(options) {
     const min = Number.isFinite(options?.min) ? options.min : PLAYER_FOV_MIN;
     const max = Number.isFinite(options?.max) ? options.max : PLAYER_FOV_MAX;
@@ -11,6 +12,7 @@ export function resolvePlayerFovBounds(options) {
     const defaultFov = clampPlayerFov(options?.default ?? PLAYER_FOV_DEFAULT, lo, hi);
     return { min: lo, max: hi, defaultFov };
 }
+/** @internal */
 export function clampPlayerFov(value, min = PLAYER_FOV_MIN, max = PLAYER_FOV_MAX) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return clampPlayerFov(PLAYER_FOV_DEFAULT, min, max);
@@ -20,6 +22,7 @@ export function clampPlayerFov(value, min = PLAYER_FOV_MIN, max = PLAYER_FOV_MAX
         return max;
     return value;
 }
+/** @internal */
 export function loadPlayerFov(bounds = resolvePlayerFovBounds(), storage = defaultStorage()) {
     if (storage == null)
         return bounds.defaultFov;
@@ -33,6 +36,7 @@ export function loadPlayerFov(bounds = resolvePlayerFovBounds(), storage = defau
         return bounds.defaultFov;
     }
 }
+/** @internal */
 export function savePlayerFov(value, bounds = resolvePlayerFovBounds(), storage = defaultStorage()) {
     const next = clampPlayerFov(value, bounds.min, bounds.max);
     if (storage == null)
@@ -51,7 +55,8 @@ export function savePlayerFov(value, bounds = resolvePlayerFovBounds(), storage
  * - poseFov is the rig's authored FOV (includes chase-speed modulation, ADS zoom, transitions)
  * - relative mode shifts the authored FOV by (preference − default) so mods still stack
  * - absolute mode (cinematic keyframes) keeps the authored FOV as-is
- */
+  * @internal
+  */
 export function composePlayerFov(preference, poseFov, mode = "relative", bounds = resolvePlayerFovBounds()) {
     if (mode === "absolute")
         return clampPlayerFov(poseFov, bounds.min, bounds.max);

package/dist/camera/index.d.ts

@@ -1,12 +1,9 @@
+/** Public camera surface for games. Pure rig math lives in sibling modules (package-internal). */
 export { GameOrbitCamera, type CameraFollowListener, type GameOrbitCameraProps } from "./GameOrbitCamera.js";
-export { GameFirstPersonCamera, type GameFirstPersonCameraProps } from "./GameFirstPersonCamera.js";
+export { GameFirstPersonCamera, readFirstPersonMuzzle, type GameFirstPersonCameraProps, type ViewmodelProps, } from "./GameFirstPersonCamera.js";
 export { GameInspectionCamera, type GameInspectionCameraProps } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind, type GameCameraRigProps } from "./GameCameraRig.js";
 export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, type PlayerFovState, } from "./PlayerFov.js";
-export { PLAYER_FOV_DEFAULT, PLAYER_FOV_MAX, PLAYER_FOV_MIN, PLAYER_FOV_STORAGE_KEY, clampPlayerFov, composePlayerFov, loadPlayerFov, resolvePlayerFovBounds, savePlayerFov, type PlayerFovBounds, } from "./fovPreference.js";
-export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, SideScrollRig, TopDownRig, type RigProps, } from "./cameraRigs.js";
-export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, type CameraBlendScratch, } from "./cameraBlendMath.js";
 export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCameraShakeChannel, useCameraShake, type CameraShakeChannel, } from "./shakeChannel.js";
-export { addTrauma, angleDelta, blendShoulder, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, createTrauma, crossfadePose, forwardVector, lerp, lockOnPose, observerPose, resolveChase, resolveDirectedCamera, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, rightVector, rtsPanKeysConflict, seatPose, shakeOffset, shoulderPose, sideScrollFollowBlend, smoothstep, smoothYaw, speedToFov, springArmStep, stepTrauma, topDownPose, yawTo, type CameraPose, type DirectorCameraValues, type ResolvedChase, type ResolvedDirectedCamera, type ResolvedObserver, type ResolvedShoulder, type ResolvedSideScroll, type ResolvedTopDown, type ShakeOffset, type StaticCameraValues, type TraumaState, } from "./rigMath.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";
-export { resolveInspectionCameraConfig, resolveInspectionZoomToCursor, seedInspectionCamera, type InspectionCameraConfig, type InspectionZoomAnchor, type ResolvedInspectionCameraConfig, } from "./inspectionCameraMath.js";
+export { rtsPanKeysConflict } from "./rigMath.js";
+export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";

package/dist/camera/index.js

@@ -1,12 +1,9 @@
+/** Public camera surface for games. Pure rig math lives in sibling modules (package-internal). */
 export { GameOrbitCamera } from "./GameOrbitCamera.js";
-export { GameFirstPersonCamera } from "./GameFirstPersonCamera.js";
+export { GameFirstPersonCamera, readFirstPersonMuzzle, } from "./GameFirstPersonCamera.js";
 export { GameInspectionCamera } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind } from "./GameCameraRig.js";
 export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, } from "./PlayerFov.js";
-export { PLAYER_FOV_DEFAULT, PLAYER_FOV_MAX, PLAYER_FOV_MIN, PLAYER_FOV_STORAGE_KEY, clampPlayerFov, composePlayerFov, loadPlayerFov, resolvePlayerFovBounds, savePlayerFov, } from "./fovPreference.js";
-export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, SideScrollRig, TopDownRig, } from "./cameraRigs.js";
-export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
 export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCameraShakeChannel, useCameraShake, } from "./shakeChannel.js";
-export { addTrauma, angleDelta, blendShoulder, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, createTrauma, crossfadePose, forwardVector, lerp, lockOnPose, observerPose, resolveChase, resolveDirectedCamera, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, rightVector, rtsPanKeysConflict, seatPose, shakeOffset, shoulderPose, sideScrollFollowBlend, smoothstep, smoothYaw, speedToFov, springArmStep, stepTrauma, topDownPose, yawTo, } from "./rigMath.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";
-export { resolveInspectionCameraConfig, resolveInspectionZoomToCursor, seedInspectionCamera, } from "./inspectionCameraMath.js";
+export { rtsPanKeysConflict } from "./rigMath.js";
+export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";

package/dist/camera/inspectionCameraMath.d.ts

@@ -15,11 +15,16 @@ export interface ResolvedInspectionCameraConfig {
     zoomSpeed: number;
     dampingFactor: number;
 }
+/** @internal */
 export declare function resolveInspectionCameraConfig(config?: InspectionCameraConfig): ResolvedInspectionCameraConfig;
-/** Seeds the camera/target world position before OrbitControls mounts. Falls back to `initialDistance` behind `target` on the -Z axis, raised by 40% of that distance, when `initialPosition` is unset. */
+/** Seeds the camera/target world position before OrbitControls mounts. Falls back to `initialDistance` behind `target` on the -Z axis, raised by 40% of that distance, when `initialPosition` is unset.
+ * @internal
+ */
 export declare function seedInspectionCamera(config: ResolvedInspectionCameraConfig): {
     camera: Vec3;
     target: Vec3;
 };
-/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag. */
+/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag.
+ * @internal
+ */
 export declare function resolveInspectionZoomToCursor(anchor: InspectionZoomAnchor): boolean;