@jgengine/shell 0.8.0 → 0.10.0

package/dist/camera/GameFirstPersonCamera.js

@@ -2,21 +2,36 @@ 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 { DEFAULT_EYE_HEIGHT } from "@jgengine/core/combat/shotOrigin";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
+import { usePlayerFov } from "./PlayerFov.js";
 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;
+const VIEWMODEL_ORIGIN = new THREE.Vector3(0.34, -0.26, -0.72);
+const MUZZLE_TIP_LOCAL = new THREE.Vector3(0, 0.03, -0.61);
+const MUZZLE_OFFSET = VIEWMODEL_ORIGIN.clone().add(MUZZLE_TIP_LOCAL);
+const muzzleWorld = new THREE.Vector3();
+let muzzleTracked = false;
+/** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
+export function readFirstPersonMuzzle(target) {
+    if (!muzzleTracked)
+        return false;
+    target.copy(muzzleWorld);
+    return true;
+}
 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 playerFov = usePlayerFov();
     const camera = useThree((state) => state.camera);
     const domElement = useThree((state) => state.gl.domElement);
     const followId = followEntityId ?? userId;
+    const seededRef = useRef(false);
     useEffect(() => {
         const requestLock = () => {
             if (window.matchMedia?.("(pointer: coarse)").matches)
@@ -41,9 +56,20 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
         const entity = ctx.scene.entity.get(followId);
         if (entity === null)
             return;
+        if (!seededRef.current) {
+            seededRef.current = true;
+            yawRef.current = entity.rotationY;
+        }
         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);
+        if (camera.isPerspectiveCamera === true) {
+            const perspective = camera;
+            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
+                perspective.fov = playerFov.fov;
+                perspective.updateProjectionMatrix();
+            }
+        }
     }, ORBIT_CAMERA_FRAME_PRIORITY);
     if (config?.viewmodel === false)
         return null;
@@ -51,15 +77,20 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
 }
 function FirstPersonViewmodel({ camera }) {
     const groupRef = useRef(null);
+    useEffect(() => () => {
+        muzzleTracked = false;
+    }, []);
     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);
+        group.translateX(VIEWMODEL_ORIGIN.x);
+        group.translateY(VIEWMODEL_ORIGIN.y);
+        group.translateZ(VIEWMODEL_ORIGIN.z);
+        muzzleWorld.copy(MUZZLE_OFFSET).applyQuaternion(camera.quaternion).add(camera.position);
+        muzzleTracked = true;
     }, 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/GameInspectionCamera.js

@@ -20,5 +20,16 @@ export function GameInspectionCamera({ config: configPatch }) {
         controlsRef.current?.update();
         seededRef.current = true;
     }, [camera, config]);
-    return (_jsx(OrbitControls, { ref: controlsRef, 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 } }));
+    useEffect(() => {
+        if (!seededRef.current)
+            return;
+        const controls = controlsRef.current;
+        if (controls === null)
+            return;
+        const previous = controls.target.clone();
+        controls.target.set(config.target.x, config.target.y, config.target.z);
+        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 } }));
 }

package/dist/camera/GameOrbitCamera.js

@@ -2,10 +2,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { OrbitControls } from "@react-three/drei";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
-import { MOUSE, Vector3 } from "three";
+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 { usePlayerFov } from "./PlayerFov.js";
 export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, pointerControls = false, }) {
     const config = resolveOrbitCameraConfig(configPatch);
     const controlsRef = useRef(null);
@@ -13,7 +14,12 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
     const draggingRef = useRef(false);
     const { userId } = usePlayer();
     const ctx = useGameContext();
+    const playerFov = usePlayerFov();
     const camera = useThree((state) => state.camera);
+    const scene = useThree((state) => state.scene);
+    const raycasterRef = useRef(new Raycaster());
+    const collisionDirRef = useRef(new Vector3());
+    const collisionOriginRef = useRef(new Vector3());
     const followId = followEntityId ?? userId;
     useEffect(() => {
         const entity = ctx.scene.entity.get(followId);
@@ -54,6 +60,36 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
             camera.position.set(stepped.camera.x, stepped.camera.y, stepped.camera.z);
         }
         controls.update();
+        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);
+            if (dist > config.collision.minTargetDistance) {
+                const dir = collisionDirRef.current.set(dx / dist, dy / dist, dz / dist);
+                const ray = raycasterRef.current;
+                ray.set(collisionOriginRef.current.set(t.x, t.y, t.z), dir);
+                ray.near = config.collision.minTargetDistance;
+                ray.far = dist;
+                let blocked = 0;
+                for (const hit of ray.intersectObjects(scene.children, true)) {
+                    const obj = hit.object;
+                    if (!obj.visible)
+                        continue;
+                    if (obj.isSprite === true)
+                        continue;
+                    if (obj.userData.jgCameraTransparent === true)
+                        continue;
+                    blocked = hit.distance;
+                    break;
+                }
+                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);
+                }
+            }
+        }
         runtimeRef.current = {
             target: stepped.target,
             camera: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
@@ -64,6 +100,13 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
         if (pitchRef !== undefined) {
             pitchRef.current = cameraLookPitch({ x: camera.position.x, y: camera.position.y, z: camera.position.z }, stepped.target);
         }
+        if (camera.isPerspectiveCamera === true) {
+            const perspective = camera;
+            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
+                perspective.fov = playerFov.fov;
+                perspective.updateProjectionMatrix();
+            }
+        }
         onCameraFollow?.({
             entityId: followId,
             target: stepped.target,

package/dist/camera/PlayerFov.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+import { type PlayerFovBounds } from "./fovPreference.js";
+export interface PlayerFovState {
+    fov: number;
+    bounds: PlayerFovBounds;
+    enabled: boolean;
+    persist: boolean;
+    setFov: (value: number) => void;
+    compose: (poseFov: number, mode?: "relative" | "absolute") => number;
+}
+export declare function PlayerFovProvider({ config, orthographic, children, }: {
+    config?: GameCameraConfig;
+    orthographic: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function usePlayerFov(): PlayerFovState;
+export declare function PlayerFovSlider(): import("react").JSX.Element | null;

package/dist/camera/PlayerFov.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useState, } from "react";
+import { composePlayerFov, loadPlayerFov, resolvePlayerFovBounds, savePlayerFov, } from "./fovPreference.js";
+const PlayerFovContext = createContext(null);
+export function PlayerFovProvider({ config, orthographic, children, }) {
+    const bounds = useMemo(() => resolvePlayerFovBounds({
+        min: config?.playerFov?.min,
+        max: config?.playerFov?.max,
+        default: config?.playerFov?.default ?? config?.frustum?.fov,
+    }), [config?.playerFov?.min, config?.playerFov?.max, config?.playerFov?.default, config?.frustum?.fov]);
+    const persist = config?.playerFov?.persist !== false;
+    const showControl = !orthographic && config?.playerFov?.control !== false;
+    const [fov, setFovState] = useState(() => persist ? loadPlayerFov(bounds) : bounds.defaultFov);
+    const setFov = useCallback((value) => {
+        setFovState(persist ? savePlayerFov(value, bounds) : savePlayerFov(value, bounds, null));
+    }, [bounds, persist]);
+    const compose = useCallback((poseFov, mode = "relative") => orthographic ? poseFov : composePlayerFov(fov, poseFov, mode, bounds), [bounds, fov, orthographic]);
+    const value = useMemo(() => ({
+        fov,
+        bounds,
+        enabled: showControl,
+        persist,
+        setFov,
+        compose,
+    }), [bounds, compose, fov, persist, setFov, showControl]);
+    return _jsx(PlayerFovContext.Provider, { value: value, children: children });
+}
+export function usePlayerFov() {
+    const value = useContext(PlayerFovContext);
+    if (value === null) {
+        const bounds = resolvePlayerFovBounds();
+        return {
+            fov: bounds.defaultFov,
+            bounds,
+            enabled: false,
+            persist: false,
+            setFov: () => undefined,
+            compose: (poseFov) => poseFov,
+        };
+    }
+    return value;
+}
+export function PlayerFovSlider() {
+    const { fov, setFov, bounds, enabled } = usePlayerFov();
+    if (!enabled)
+        return null;
+    return (_jsxs("label", { className: "pointer-events-auto absolute bottom-3 right-3 z-20 flex items-center gap-2 rounded-md bg-neutral-950/75 px-2.5 py-1.5 text-[11px] font-medium tracking-wide text-neutral-200 shadow-lg ring-1 ring-white/10 backdrop-blur-sm", children: [_jsx("span", { className: "text-neutral-400", children: "FOV" }), _jsx("input", { type: "range", min: bounds.min, max: bounds.max, step: 1, value: fov, "aria-label": "Field of view", className: "h-1 w-24 cursor-pointer accent-emerald-400", onChange: (event) => setFov(Number(event.target.value)) }), _jsx("span", { className: "w-7 tabular-nums text-neutral-100", children: Math.round(fov) })] }));
+}

package/dist/camera/cameraBlendMath.d.ts

@@ -0,0 +1,13 @@
+import type { Camera, Quaternion, Vector3 } from "three";
+export interface CameraBlendScratch {
+    fromPos: Vector3;
+    fromQuat: Quaternion;
+    toPos: Vector3;
+    toQuat: Quaternion;
+    fov: number;
+    elapsed: number;
+    duration: number;
+}
+export declare function createCameraBlendScratch(Vector3Ctor: new () => Vector3, QuaternionCtor: new () => Quaternion): CameraBlendScratch;
+export declare function captureCameraBlendFrom(scratch: CameraBlendScratch, position: Vector3, quaternion: Quaternion, fov: number, duration: number): void;
+export declare function applyCameraBlendStep(scratch: CameraBlendScratch, camera: Camera, targetFov: number, dt: number): boolean;

package/dist/camera/cameraBlendMath.js

@@ -0,0 +1,36 @@
+import { smoothstep } from "./rigMath.js";
+export function createCameraBlendScratch(Vector3Ctor, QuaternionCtor) {
+    return {
+        fromPos: new Vector3Ctor(),
+        fromQuat: new QuaternionCtor(),
+        toPos: new Vector3Ctor(),
+        toQuat: new QuaternionCtor(),
+        fov: 55,
+        elapsed: 0,
+        duration: 0,
+    };
+}
+export function captureCameraBlendFrom(scratch, position, quaternion, fov, duration) {
+    scratch.fromPos.copy(position);
+    scratch.fromQuat.copy(quaternion);
+    scratch.fov = fov;
+    scratch.elapsed = 0;
+    scratch.duration = duration;
+}
+function isPerspective(camera) {
+    return camera.isPerspectiveCamera === true;
+}
+export function applyCameraBlendStep(scratch, camera, targetFov, dt) {
+    scratch.elapsed += dt;
+    const t = scratch.duration <= 0 ? 1 : Math.min(scratch.elapsed / scratch.duration, 1);
+    const eased = smoothstep(t);
+    scratch.toPos.copy(camera.position);
+    scratch.toQuat.copy(camera.quaternion);
+    camera.position.lerpVectors(scratch.fromPos, scratch.toPos, eased);
+    camera.quaternion.slerpQuaternions(scratch.fromQuat, scratch.toQuat, eased);
+    if (isPerspective(camera)) {
+        camera.fov = scratch.fov + (targetFov - scratch.fov) * eased;
+        camera.updateProjectionMatrix();
+    }
+    return t >= 1;
+}

package/dist/camera/cameraRigs.d.ts

@@ -1,5 +1,6 @@
 import { type MutableRefObject } from "react";
 import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, type CameraBlendScratch, } from "./cameraBlendMath.js";
 export declare const CAMERA_RIG_FRAME_PRIORITY = -1;
 export declare const CAMERA_POST_FRAME_PRIORITY: number;
 export interface RigProps {
@@ -7,6 +8,8 @@ export interface RigProps {
     pitchRef: MutableRefObject<number>;
     config?: GameCameraConfig;
     followEntityId?: string | null;
+    /** When true, pose FOV is treated as absolute (cinematic keyframes). */
+    absoluteFov?: boolean;
 }
 export declare function TopDownRig(props: RigProps): null;
 /** Fixed side-on 2.5D follow rig: watches the followed entity from the perpendicular axis, never reading WASD/mouse-look. */

package/dist/camera/cameraRigs.js

@@ -4,8 +4,11 @@ import { PerspectiveCamera, Quaternion, Vector3 } from "three";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useGameContext } from "@jgengine/react/provider";
 import { ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
-import { chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothstep, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
+import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
+import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
+import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
+export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
 export const CAMERA_RIG_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY;
 export const CAMERA_POST_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY + 0.5;
 function isPerspective(camera) {
@@ -47,45 +50,35 @@ function readFollow(ctx, followId) {
 function useCameraCommit(props, followId) {
     const camera = useThree((state) => state.camera);
     const shake = useCameraShake();
+    const playerFov = usePlayerFov();
     const shakeConfig = props.config?.shake;
     const transitionSeconds = props.config?.transitionSeconds ?? 0.6;
-    const blendRef = useRef(null);
+    const blendScratchRef = useRef(createCameraBlendScratch(Vector3, Quaternion));
+    const blendingRef = useRef(false);
     const lastPoseRef = useRef(null);
     const farWarnedRef = useRef(false);
     const beginTransition = () => {
         if (transitionSeconds <= 0)
             return;
-        blendRef.current = {
-            position: camera.position.clone(),
-            quaternion: camera.quaternion.clone(),
-            fov: currentFov(camera),
-            elapsed: 0,
-            duration: transitionSeconds,
-        };
+        captureCameraBlendFrom(blendScratchRef.current, camera.position, camera.quaternion, currentFov(camera), transitionSeconds);
+        blendingRef.current = true;
     };
     const commit = (pose, dt) => {
-        lastPoseRef.current = pose;
-        applyPose(camera, pose);
+        const composed = {
+            ...pose,
+            fov: playerFov.compose(pose.fov, props.absoluteFov === true ? "absolute" : "relative"),
+        };
+        lastPoseRef.current = composed;
+        applyPose(camera, composed);
         const lookDistance = Math.hypot(pose.position.x - pose.lookAt.x, pose.position.y - pose.lookAt.y, pose.position.z - pose.lookAt.z);
         if (!farWarnedRef.current && isPerspective(camera) && lookDistance > camera.far) {
             farWarnedRef.current = true;
             console.warn(`[jgengine:camera] the "${props.config?.rig ?? "orbit"}" rig placed the camera ${Math.round(lookDistance)} world units from its look target, beyond the far plane (${camera.far}) — everything near the target is frustum-culled and the world renders empty. Check the rig config (topDown pitch is elevation: PI/2 = straight down, near 0 = grazing) or raise camera.frustum.far.`);
         }
-        const blend = blendRef.current;
-        if (blend !== null) {
-            blend.elapsed += dt;
-            const t = blend.duration <= 0 ? 1 : Math.min(blend.elapsed / blend.duration, 1);
-            const eased = smoothstep(t);
-            const targetPos = camera.position.clone();
-            const targetQuat = camera.quaternion.clone();
-            camera.position.lerpVectors(blend.position, targetPos, eased);
-            camera.quaternion.slerpQuaternions(blend.quaternion, targetQuat, eased);
-            if (isPerspective(camera)) {
-                camera.fov = blend.fov + (pose.fov - blend.fov) * eased;
-                camera.updateProjectionMatrix();
-            }
-            if (t >= 1)
-                blendRef.current = null;
+        if (blendingRef.current) {
+            const done = applyCameraBlendStep(blendScratchRef.current, camera, composed.fov, dt);
+            if (done)
+                blendingRef.current = false;
         }
         shake.step(dt);
         const offset = shake.sample(shakeConfig);
@@ -96,9 +89,9 @@ function useCameraCommit(props, followId) {
         }
         props.config?.onCameraFollow?.({
             entityId: followId ?? "",
-            target: pose.lookAt,
+            target: composed.lookAt,
             camera: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
-            distance: Math.hypot(camera.position.x - pose.lookAt.x, camera.position.y - pose.lookAt.y, camera.position.z - pose.lookAt.z),
+            distance: Math.hypot(camera.position.x - composed.lookAt.x, camera.position.y - composed.lookAt.y, camera.position.z - composed.lookAt.z),
         });
     };
     return { camera, commit, beginTransition };
@@ -425,21 +418,28 @@ export function ChaseRig(props) {
     const ctx = useGameContext();
     const followId = resolveFollowId(props.followEntityId, userId);
     const config = props.config?.chase;
-    const resolved = useMemo(() => resolveChase(config), [config]);
-    const { commit, beginTransition } = useCameraCommit(props, followId);
+    const staticResolved = useMemo(() => resolveChase(config), [config]);
+    const { camera, commit, beginTransition } = useCameraCommit(props, followId);
     const shake = useCameraShake();
     const posRef = useRef(null);
     const lastFollowRef = useRef(null);
+    const lastYawRef = useRef(null);
+    const rollRef = useRef(0);
     const view = config?.view ?? "chase";
     useEffect(beginTransition, [view]);
     useFrame((_, dt) => {
+        const tuning = ctx.camera.chaseTuning();
+        const resolved = tuning === null ? staticResolved : resolveChase({ ...config, ...tuning });
         const sample = readFollow(ctx, followId);
         const follow = sample?.pos ?? { x: 0, y: 0, z: 0 };
         const yaw = sample?.yaw ?? 0;
         const last = lastFollowRef.current ?? follow;
         const speed = dt > 0 ? Math.hypot(follow.x - last.x, follow.z - last.z) / dt : 0;
         lastFollowRef.current = follow;
-        const fov = speedToFov(speed, config?.fov);
+        const lastYaw = lastYawRef.current ?? yaw;
+        lastYawRef.current = yaw;
+        rollRef.current = bankRollStep(rollRef.current, yaw, lastYaw, dt, resolved);
+        const fov = speedToFov(speed, tuning?.fov ?? config?.fov);
         if (view !== "chase") {
             const seat = view === "cockpit"
                 ? config?.seatOffsets?.cockpit ?? { x: 0, y: 1.2, z: 0.1 }
@@ -454,15 +454,18 @@ export function ChaseRig(props) {
             commit(pose, dt);
             return;
         }
-        const desired = chaseDesiredPosition(follow, yaw, resolved);
+        const led = leadFollowPoint(follow, last, dt, resolved);
+        const desired = chaseDesiredPosition(led, yaw, resolved);
         const prev = posRef.current ?? desired;
         const smoothed = springArmStep(prev, desired, resolved.springDamping, dt);
         posRef.current = smoothed;
         if (resolved.shakePerSpeed > 0 && speed > 0) {
             shake.shake(Math.min(resolved.shakePerSpeed * speed * dt, 0.1));
         }
-        const pose = { position: smoothed, lookAt: chaseLookAt(follow, yaw, resolved), fov };
+        const pose = { position: smoothed, lookAt: chaseLookAt(led, yaw, resolved), fov };
         commit(pose, dt);
+        if (rollRef.current !== 0)
+            camera.rotateZ(rollRef.current);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }

package/dist/camera/fovPreference.d.ts

@@ -0,0 +1,25 @@
+export declare const PLAYER_FOV_DEFAULT: 55;
+export declare const PLAYER_FOV_MIN = 40;
+export declare const PLAYER_FOV_MAX = 120;
+export declare const PLAYER_FOV_STORAGE_KEY = "jgengine:player-fov";
+export interface PlayerFovBounds {
+    min: number;
+    max: number;
+    defaultFov: number;
+}
+export declare function resolvePlayerFovBounds(options?: {
+    min?: number;
+    max?: number;
+    default?: number;
+}): PlayerFovBounds;
+export declare function clampPlayerFov(value: unknown, min?: number, max?: number): number;
+export declare function loadPlayerFov(bounds?: PlayerFovBounds, storage?: Pick<Storage, "getItem"> | null | undefined): number;
+export declare function savePlayerFov(value: number, bounds?: PlayerFovBounds, storage?: Pick<Storage, "setItem"> | null | undefined): number;
+/**
+ * Composition model for perspective rigs:
+ * - preference is the player base FOV
+ * - 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
+ */
+export declare function composePlayerFov(preference: number, poseFov: number, mode?: "relative" | "absolute", bounds?: PlayerFovBounds): number;

package/dist/camera/fovPreference.js

@@ -0,0 +1,73 @@
+import { CAMERA_FRUSTUM_DEFAULTS } from "@jgengine/core/game/playableGame";
+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";
+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;
+    const lo = Math.min(min, max);
+    const hi = Math.max(min, max);
+    const defaultFov = clampPlayerFov(options?.default ?? PLAYER_FOV_DEFAULT, lo, hi);
+    return { min: lo, max: hi, defaultFov };
+}
+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);
+    if (value < min)
+        return min;
+    if (value > max)
+        return max;
+    return value;
+}
+export function loadPlayerFov(bounds = resolvePlayerFovBounds(), storage = defaultStorage()) {
+    if (storage == null)
+        return bounds.defaultFov;
+    try {
+        const raw = storage.getItem(PLAYER_FOV_STORAGE_KEY);
+        if (raw === null)
+            return bounds.defaultFov;
+        return clampPlayerFov(Number(raw), bounds.min, bounds.max);
+    }
+    catch {
+        return bounds.defaultFov;
+    }
+}
+export function savePlayerFov(value, bounds = resolvePlayerFovBounds(), storage = defaultStorage()) {
+    const next = clampPlayerFov(value, bounds.min, bounds.max);
+    if (storage == null)
+        return next;
+    try {
+        storage.setItem(PLAYER_FOV_STORAGE_KEY, String(next));
+    }
+    catch {
+        /* ignore quota / private-mode failures */
+    }
+    return next;
+}
+/**
+ * Composition model for perspective rigs:
+ * - preference is the player base FOV
+ * - 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
+ */
+export function composePlayerFov(preference, poseFov, mode = "relative", bounds = resolvePlayerFovBounds()) {
+    if (mode === "absolute")
+        return clampPlayerFov(poseFov, bounds.min, bounds.max);
+    const pref = clampPlayerFov(preference, bounds.min, bounds.max);
+    if (!Number.isFinite(poseFov))
+        return pref;
+    return clampPlayerFov(pref + (poseFov - PLAYER_FOV_DEFAULT), bounds.min, bounds.max);
+}
+function defaultStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}

package/dist/camera/index.d.ts

@@ -2,7 +2,10 @@ export { GameOrbitCamera, type CameraFollowListener, type GameOrbitCameraProps }
 export { GameFirstPersonCamera, type GameFirstPersonCameraProps } 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";

package/dist/camera/index.js

@@ -2,7 +2,10 @@ export { GameOrbitCamera } from "./GameOrbitCamera.js";
 export { GameFirstPersonCamera } 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";

package/dist/camera/orbitCameraMath.d.ts

@@ -39,6 +39,23 @@ export interface OrbitCameraConfig {
     /** 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;
+    /** Spring-arm collision: raycast target→camera each frame and pull the boom in past occluders (walls, terrain) so the camera never clips inside geometry. */
+    collision?: OrbitCollisionConfig;
+}
+/** Spring-arm occlusion config for the orbit rig. */
+export interface OrbitCollisionConfig {
+    /** Enable the pull-in raycast. Default false (unchanged chase camera). */
+    enabled?: boolean;
+    /** Gap kept between the camera and the hit surface, world units. Default 0.35. */
+    padding?: number;
+    /** Ignore hits closer than this to the target — the player's own body. Default 1.2. */
+    minTargetDistance?: number;
+}
+/** An {@link OrbitCollisionConfig} with every field resolved to a concrete value. */
+export interface ResolvedOrbitCollision {
+    enabled: boolean;
+    padding: number;
+    minTargetDistance: number;
 }
 /** Fully resolved shell config after merging with DEFAULT_ORBIT_CAMERA. */
 export interface ResolvedOrbitCameraConfig {
@@ -58,6 +75,7 @@ export interface ResolvedOrbitCameraConfig {
     distanceSmoothing: number;
     minPolarAngle: number;
     maxPolarAngle: number;
+    collision: ResolvedOrbitCollision;
 }
 export declare const DEFAULT_ORBIT_CAMERA: ResolvedOrbitCameraConfig;
 /** Run simulation/movement before orbit follow so poses are current. */

package/dist/camera/orbitCameraMath.js

@@ -25,6 +25,7 @@ export const DEFAULT_ORBIT_CAMERA = {
     distanceSmoothing: 5,
     minPolarAngle: 0.12,
     maxPolarAngle: Math.PI / 2.05,
+    collision: { enabled: false, padding: 0.35, minTargetDistance: 1.2 },
 };
 /** Run simulation/movement before orbit follow so poses are current. */
 export const GAME_SIM_FRAME_PRIORITY = 0;
@@ -35,7 +36,11 @@ export function smoothBlend(deltaSeconds, speed) {
     return 1 - Math.exp(-speed * deltaSeconds);
 }
 export function resolveOrbitCameraConfig(patch) {
-    return { ...DEFAULT_ORBIT_CAMERA, ...patch };
+    return {
+        ...DEFAULT_ORBIT_CAMERA,
+        ...patch,
+        collision: { ...DEFAULT_ORBIT_CAMERA.collision, ...patch?.collision },
+    };
 }
 export function resolveTargetSmoothing(config, dragging) {
     if (dragging) {