@jgengine/shell 0.7.0 → 0.9.0

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, resolveTopDown, seatPose, shoulderPose, 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,39 +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 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;
+        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.`);
+        }
+        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);
@@ -90,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 };
@@ -141,6 +140,32 @@ export function TopDownRig(props) {
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }
+/** Fixed side-on 2.5D follow rig: watches the followed entity from the perpendicular axis, never reading WASD/mouse-look. */
+export function SideScrollRig(props) {
+    const { userId } = usePlayer();
+    const ctx = useGameContext();
+    const followId = resolveFollowId(props.followEntityId, userId);
+    const config = props.config?.sideScroll;
+    const resolved = useMemo(() => resolveSideScroll(config), [config]);
+    const { camera, commit, beginTransition } = useCameraCommit(props, followId);
+    const followRef = useRef(null);
+    useEffect(beginTransition, []);
+    useFrame((_, dt) => {
+        const sample = readFollow(ctx, followId);
+        const desired = sample?.pos ?? { x: 0, y: 0, z: 0 };
+        const prev = followRef.current ?? desired;
+        const blend = sideScrollFollowBlend(resolved.followSmoothing, dt);
+        const follow = {
+            x: prev.x + (desired.x - prev.x) * blend,
+            y: prev.y + (desired.y - prev.y) * blend,
+            z: prev.z + (desired.z - prev.z) * blend,
+        };
+        followRef.current = follow;
+        const pose = resolveSideScrollPose(follow, resolved, config?.fov ?? currentFov(camera));
+        commit(pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}
 function useHeldKeys(codes) {
     const held = useRef(new Set());
     useEffect(() => {
@@ -163,6 +188,7 @@ function useHeldKeys(codes) {
     return held;
 }
 const RTS_PAN_KEYS = ["KeyW", "KeyA", "KeyS", "KeyD", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "KeyQ", "KeyE"];
+const RTS_WASD_KEYS = new Set(["KeyW", "KeyA", "KeyS", "KeyD"]);
 export function RtsRig(props) {
     const { userId } = usePlayer();
     const ctx = useGameContext();
@@ -170,7 +196,9 @@ export function RtsRig(props) {
     const config = props.config?.rts;
     const resolved = useMemo(() => resolveTopDown(config), [config]);
     const { camera, commit, beginTransition } = useCameraCommit(props, followId);
-    const held = useHeldKeys(RTS_PAN_KEYS);
+    const wasdPanEnabled = followId === null && props.panKeysEnabled !== false;
+    const heldCodes = useMemo(() => (wasdPanEnabled ? RTS_PAN_KEYS : RTS_PAN_KEYS.filter((code) => !RTS_WASD_KEYS.has(code))), [wasdPanEnabled]);
+    const held = useHeldKeys(heldCodes);
     const centerRef = useRef({
         x: config?.start?.x ?? 0,
         y: 0,
@@ -390,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 }
@@ -419,20 +454,23 @@ 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;
 }
-function observerSubject(ctx, config) {
-    const bind = config?.bind;
+function observerSubject(ctx, config, followId) {
+    const bind = config?.bind ?? (followId !== null ? { kind: "entity", entityId: followId } : undefined);
     if (bind?.kind === "entity") {
         const entity = ctx.scene.entity.get(bind.entityId);
         if (entity !== null) {
@@ -450,15 +488,17 @@ function observerSubject(ctx, config) {
  * kill-cam rig. Distinct from every other rig, which drives from mouse/keys.
  */
 export function ObserverRig(props) {
+    const { userId } = usePlayer();
     const ctx = useGameContext();
     const config = props.config?.observer;
+    const followId = resolveFollowId(props.followEntityId, userId);
     const resolved = useMemo(() => resolveObserver(config), [config]);
     const angleRef = useRef(config?.startAngle ?? 0);
-    const { camera, commit, beginTransition } = useCameraCommit(props, observerSubject(ctx, config).boundEntityId);
+    const { camera, commit, beginTransition } = useCameraCommit(props, observerSubject(ctx, config, followId).boundEntityId);
     useEffect(beginTransition, []);
     useFrame((_, dt) => {
         angleRef.current += resolved.orbitSpeed * dt;
-        const { subject } = observerSubject(ctx, config);
+        const { subject } = observerSubject(ctx, config, followId);
         const pose = observerPose(subject, angleRef.current, resolved, config?.fov ?? currentFov(camera));
         commit(pose, dt);
     }, CAMERA_RIG_FRAME_PRIORITY);

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

@@ -1,7 +1,12 @@
 export { GameOrbitCamera, type CameraFollowListener, type GameOrbitCameraProps } from "./GameOrbitCamera.js";
 export { GameFirstPersonCamera, type GameFirstPersonCameraProps } from "./GameFirstPersonCamera.js";
+export { GameInspectionCamera, type GameInspectionCameraProps } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind, type GameCameraRigProps } from "./GameCameraRig.js";
-export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, TopDownRig, type RigProps, } from "./cameraRigs.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, resolveObserver, resolveShoulder, resolveTopDown, rightVector, seatPose, shakeOffset, shoulderPose, smoothstep, smoothYaw, speedToFov, springArmStep, stepTrauma, topDownPose, yawTo, type CameraPose, type ResolvedChase, type ResolvedObserver, type ResolvedShoulder, type ResolvedTopDown, type ShakeOffset, type TraumaState, } from "./rigMath.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";

package/dist/camera/index.js

@@ -1,7 +1,12 @@
 export { GameOrbitCamera } from "./GameOrbitCamera.js";
 export { GameFirstPersonCamera } from "./GameFirstPersonCamera.js";
+export { GameInspectionCamera } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind } from "./GameCameraRig.js";
-export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, TopDownRig, } from "./cameraRigs.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, resolveObserver, resolveShoulder, resolveTopDown, rightVector, seatPose, shakeOffset, shoulderPose, smoothstep, smoothYaw, speedToFov, springArmStep, stepTrauma, topDownPose, yawTo, } from "./rigMath.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";

package/dist/camera/inspectionCameraMath.d.ts

@@ -0,0 +1,25 @@
+import type { InspectionCameraConfig, InspectionZoomAnchor } from "@jgengine/core/game/playableGame";
+import type { Vec3 } from "./orbitCameraMath.js";
+export type { InspectionCameraConfig, InspectionZoomAnchor };
+export interface ResolvedInspectionCameraConfig {
+    anchor: InspectionZoomAnchor;
+    target: Vec3;
+    initialDistance: number;
+    initialPosition: Vec3 | null;
+    minDistance: number;
+    maxDistance: number;
+    minPolarAngle: number;
+    maxPolarAngle: number;
+    pan: boolean;
+    rotateSpeed: number;
+    zoomSpeed: number;
+    dampingFactor: number;
+}
+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. */
+export declare function seedInspectionCamera(config: ResolvedInspectionCameraConfig): {
+    camera: Vec3;
+    target: Vec3;
+};
+/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag. */
+export declare function resolveInspectionZoomToCursor(anchor: InspectionZoomAnchor): boolean;

package/dist/camera/inspectionCameraMath.js

@@ -0,0 +1,44 @@
+export function resolveInspectionCameraConfig(config) {
+    return {
+        anchor: config?.anchor ?? "target",
+        target: {
+            x: config?.target?.x ?? 0,
+            y: config?.target?.y ?? 0,
+            z: config?.target?.z ?? 0,
+        },
+        initialDistance: config?.initialDistance ?? 6,
+        initialPosition: config?.initialPosition === undefined
+            ? null
+            : {
+                x: config.initialPosition.x ?? 0,
+                y: config.initialPosition.y ?? 0,
+                z: config.initialPosition.z ?? 0,
+            },
+        minDistance: config?.minDistance ?? 2,
+        maxDistance: config?.maxDistance ?? 20,
+        minPolarAngle: config?.minPolarAngle ?? 0,
+        maxPolarAngle: config?.maxPolarAngle ?? Math.PI,
+        pan: config?.pan ?? true,
+        rotateSpeed: config?.rotateSpeed ?? 0.6,
+        zoomSpeed: config?.zoomSpeed ?? 0.6,
+        dampingFactor: config?.dampingFactor ?? 0.08,
+    };
+}
+/** 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. */
+export function seedInspectionCamera(config) {
+    if (config.initialPosition !== null) {
+        return { camera: config.initialPosition, target: config.target };
+    }
+    return {
+        camera: {
+            x: config.target.x,
+            y: config.target.y + config.initialDistance * 0.4,
+            z: config.target.z - config.initialDistance,
+        },
+        target: config.target,
+    };
+}
+/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag. */
+export function resolveInspectionZoomToCursor(anchor) {
+    return anchor === "cursor";
+}

package/dist/camera/rigMath.d.ts

@@ -1,14 +1,17 @@
-import type { CameraKeyframe, ChaseCameraConfig, LockOnCameraConfig, ObserverCameraConfig, ShoulderCameraConfig, TopDownCameraConfig } from "@jgengine/core/game/playableGame";
+import type { CameraKeyframe, ChaseCameraConfig, CinematicCameraConfig, LockOnCameraConfig, ObserverCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig } from "@jgengine/core/game/playableGame";
+import type { ActionCodesMap } from "@jgengine/core/input/actionBindings";
 import { type Vec3 } from "./orbitCameraMath.js";
 export interface CameraPose {
     position: Vec3;
     lookAt: Vec3;
     fov: number;
 }
+export declare function rtsPanKeysConflict(input: ActionCodesMap | undefined): boolean;
 export declare function clamp(value: number, min: number, max: number): number;
 export declare function lerp(from: number, to: number, blend: number): number;
 export declare function smoothstep(t: number): number;
 export declare function forwardVector(yaw: number): Vec3;
+/** Screen-right of a yaw: `forward × up` with up = +Y. */
 export declare function rightVector(yaw: number): Vec3;
 export interface ResolvedTopDown {
     height: number;
@@ -27,6 +30,22 @@ export declare function resolveTopDown(config: TopDownCameraConfig | undefined):
 export declare function topDownPose(follow: Vec3, resolved: ResolvedTopDown, fov: number): CameraPose;
 /** Exponential spring-arm approach toward a desired point (frame-rate independent). */
 export declare function springArmStep(current: Vec3, desired: Vec3, damping: number, dt: number): Vec3;
+export interface ResolvedSideScroll {
+    axis: "x" | "z";
+    distance: number;
+    height: number;
+    lookHeight: number;
+    followSmoothing: number;
+}
+export declare function resolveSideScroll(config: SideScrollCameraConfig | undefined): ResolvedSideScroll;
+/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing. */
+export declare function sideScrollFollowBlend(followSmoothing: number, dt: number): number;
+/**
+ * Fixed lateral 2.5D follow pose: the camera sits perpendicular to the travel
+ * axis at `distance`, above the entity by `height`, and looks at the entity
+ * raised by `lookHeight`. Axis "x" watches from +z; axis "z" watches from +x.
+ */
+export declare function resolveSideScrollPose(entityPos: Vec3, resolved: ResolvedSideScroll, fov: number): CameraPose;
 /** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`. */
 export declare function speedToFov(speed: number, curve: {
     base?: number;
@@ -69,8 +88,17 @@ export interface ResolvedChase {
     lookHeight: number;
     springDamping: number;
     shakePerSpeed: number;
+    leadTime: number;
+    leadMax: number;
+    bankPerYawRate: number;
+    bankMax: number;
+    bankDamping: number;
 }
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+export declare function leadFollowPoint(follow: Vec3, previous: Vec3, dt: number, resolved: ResolvedChase): Vec3;
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+export declare function bankRollStep(currentRoll: number, yaw: number, previousYaw: number, dt: number, resolved: ResolvedChase): number;
 export interface ResolvedObserver {
     distance: number;
     height: number;
@@ -117,6 +145,27 @@ export declare function shakeOffset(state: TraumaState, config: {
 } | undefined): ShakeOffset;
 /** Linear cross-fade between two full camera poses (position, lookAt, fov). */
 export declare function crossfadePose(from: CameraPose, to: CameraPose, t: number): CameraPose;
+export interface DirectorCameraValues {
+    /** `undefined` = no runtime override (fall back to static); `null` = explicitly follow nothing. */
+    followEntityId?: string | null;
+    /** `null` = no runtime cinematic active (fall back to static). */
+    cinematic?: CinematicCameraConfig | null;
+}
+export interface StaticCameraValues {
+    followEntityId?: string | null;
+    cinematic?: CinematicCameraConfig;
+}
+export interface ResolvedDirectedCamera {
+    followEntityId: string | null | undefined;
+    cinematic: CinematicCameraConfig | undefined;
+}
+/**
+ * Merges a `CameraDirector` runtime snapshot over the static `GameCameraConfig`
+ * (#196.2). `director` omitted, or its fields `undefined`/`null`, is a pure
+ * passthrough to `staticConfig` so mounting a director with no active override
+ * changes nothing.
+ */
+export declare function resolveDirectedCamera(director: DirectorCameraValues | undefined, staticConfig: StaticCameraValues): ResolvedDirectedCamera;
 export interface CinematicSample {
     pose: CameraPose;
     done: boolean;

package/dist/camera/rigMath.js

@@ -1,4 +1,16 @@
 import { lerpVec3, smoothBlend } from "./orbitCameraMath.js";
+const RTS_WASD_CODES = ["KeyW", "KeyA", "KeyS", "KeyD"];
+function actionCodeList(codes) {
+    if (Array.isArray(codes))
+        return codes;
+    const modes = codes;
+    return [...(modes.hold ?? []), ...(modes.toggle ?? [])];
+}
+export function rtsPanKeysConflict(input) {
+    if (input === undefined)
+        return false;
+    return Object.values(input).some((codes) => actionCodeList(codes).some((code) => RTS_WASD_CODES.includes(code)));
+}
 export function clamp(value, min, max) {
     return value < min ? min : value > max ? max : value;
 }
@@ -12,8 +24,9 @@ export function smoothstep(t) {
 export function forwardVector(yaw) {
     return { x: Math.sin(yaw), y: 0, z: Math.cos(yaw) };
 }
+/** Screen-right of a yaw: `forward × up` with up = +Y. */
 export function rightVector(yaw) {
-    return { x: Math.cos(yaw), y: 0, z: -Math.sin(yaw) };
+    return { x: -Math.cos(yaw), y: 0, z: Math.sin(yaw) };
 }
 export function resolveTopDown(config) {
     return {
@@ -56,6 +69,36 @@ export function topDownPose(follow, resolved, fov) {
 export function springArmStep(current, desired, damping, dt) {
     return lerpVec3(current, desired, smoothBlend(dt, damping));
 }
+export function resolveSideScroll(config) {
+    return {
+        axis: config?.axis ?? "x",
+        distance: config?.distance ?? 10,
+        height: config?.height ?? 3,
+        lookHeight: config?.lookHeight ?? 1,
+        followSmoothing: config?.followSmoothing ?? 8,
+    };
+}
+/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing. */
+export function sideScrollFollowBlend(followSmoothing, dt) {
+    return followSmoothing <= 0 ? 1 : smoothBlend(dt, followSmoothing);
+}
+/**
+ * Fixed lateral 2.5D follow pose: the camera sits perpendicular to the travel
+ * axis at `distance`, above the entity by `height`, and looks at the entity
+ * raised by `lookHeight`. Axis "x" watches from +z; axis "z" watches from +x.
+ */
+export function resolveSideScrollPose(entityPos, resolved, fov) {
+    const perpendicular = resolved.axis === "x" ? { x: 0, y: 0, z: 1 } : { x: 1, y: 0, z: 0 };
+    return {
+        position: {
+            x: entityPos.x + perpendicular.x * resolved.distance,
+            y: entityPos.y + resolved.height,
+            z: entityPos.z + perpendicular.z * resolved.distance,
+        },
+        lookAt: { x: entityPos.x, y: entityPos.y + resolved.lookHeight, z: entityPos.z },
+        fov,
+    };
+}
 /** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`. */
 export function speedToFov(speed, curve) {
     const base = curve?.base ?? 55;
@@ -165,8 +208,42 @@ export function resolveChase(config) {
         lookHeight: config?.lookHeight ?? 1.2,
         springDamping: config?.springDamping ?? 6,
         shakePerSpeed: config?.shakePerSpeed ?? 0,
+        leadTime: config?.lead?.time ?? 0,
+        leadMax: config?.lead?.max ?? 4,
+        bankPerYawRate: config?.bank?.perYawRate ?? 0,
+        bankMax: config?.bank?.max ?? 0.35,
+        bankDamping: config?.bank?.damping ?? 8,
     };
 }
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+export function leadFollowPoint(follow, previous, dt, resolved) {
+    if (resolved.leadTime <= 0 || dt <= 0)
+        return follow;
+    let leadX = ((follow.x - previous.x) / dt) * resolved.leadTime;
+    let leadZ = ((follow.z - previous.z) / dt) * resolved.leadTime;
+    const magnitude = Math.hypot(leadX, leadZ);
+    if (magnitude > resolved.leadMax) {
+        leadX *= resolved.leadMax / magnitude;
+        leadZ *= resolved.leadMax / magnitude;
+    }
+    return { x: follow.x + leadX, y: follow.y, z: follow.z + leadZ };
+}
+function wrapAngle(angle) {
+    let wrapped = angle;
+    while (wrapped > Math.PI)
+        wrapped -= Math.PI * 2;
+    while (wrapped < -Math.PI)
+        wrapped += Math.PI * 2;
+    return wrapped;
+}
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+export function bankRollStep(currentRoll, yaw, previousYaw, dt, resolved) {
+    if (resolved.bankPerYawRate <= 0)
+        return 0;
+    const yawRate = dt > 0 ? wrapAngle(yaw - previousYaw) / dt : 0;
+    const target = clamp(-yawRate * resolved.bankPerYawRate, -resolved.bankMax, resolved.bankMax);
+    return currentRoll + (target - currentRoll) * Math.min(1, resolved.bankDamping * dt);
+}
 export function resolveObserver(config) {
     return {
         distance: config?.distance ?? 8,
@@ -268,6 +345,19 @@ export function crossfadePose(from, to, t) {
         fov: lerp(from.fov, to.fov, blend),
     };
 }
+/**
+ * Merges a `CameraDirector` runtime snapshot over the static `GameCameraConfig`
+ * (#196.2). `director` omitted, or its fields `undefined`/`null`, is a pure
+ * passthrough to `staticConfig` so mounting a director with no active override
+ * changes nothing.
+ */
+export function resolveDirectedCamera(director, staticConfig) {
+    const directedFollow = director?.followEntityId;
+    const followEntityId = directedFollow === undefined ? staticConfig.followEntityId : directedFollow;
+    const directedCinematic = director?.cinematic;
+    const cinematic = directedCinematic === undefined || directedCinematic === null ? staticConfig.cinematic : directedCinematic;
+    return { followEntityId, cinematic };
+}
 /**
  * Sample a keyframe path at `elapsed` seconds. Each keyframe's `duration` is the
  * travel time from the previous keyframe into it; segment easing is per the

package/dist/camera/rigResolve.d.ts

@@ -0,0 +1,15 @@
+import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playableGame";
+/**
+ * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
+ * specific: an explicit `rig` field always wins; then `perspective: "first"`
+ * (the historical shorthand for `rig: "orbit" | "first"`); then the mere presence
+ * of a rig's own config block selects that rig, checked in the fixed order below
+ * (#207.8) so a config carrying more than one block resolves deterministically
+ * instead of depending on object key order. Set `rig` explicitly to break a tie.
+ */
+export declare function resolveRigKind(config: GameCameraConfig | undefined): CameraRigKind;
+/**
+ * The turntable rig is a flat facade over the observer's point-orbit mode: map
+ * its `target`/`distance`/… onto an observer block so ObserverRig runs unchanged.
+ */
+export declare function turntableAsObserver(config: GameCameraConfig | undefined): GameCameraConfig;