@jgengine/shell 0.6.0 → 0.8.0

package/dist/camera/cameraRigs.js

@@ -0,0 +1,522 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+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 { useCameraShake } from "./shakeChannel.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) {
+    return camera.isPerspectiveCamera === true;
+}
+function currentFov(camera) {
+    return isPerspective(camera) ? camera.fov : 55;
+}
+function applyPose(camera, pose) {
+    camera.position.set(pose.position.x, pose.position.y, pose.position.z);
+    camera.lookAt(pose.lookAt.x, pose.lookAt.y, pose.lookAt.z);
+    if (isPerspective(camera) && Math.abs(camera.fov - pose.fov) > 0.001) {
+        camera.fov = pose.fov;
+        camera.updateProjectionMatrix();
+    }
+}
+function resolveFollowId(explicit, userId) {
+    if (explicit === null)
+        return null;
+    return explicit ?? userId;
+}
+function readFollow(ctx, followId) {
+    if (followId === null)
+        return null;
+    const entity = ctx.scene.entity.get(followId);
+    if (entity === null)
+        return null;
+    return {
+        pos: { x: entity.position[0], y: entity.position[1], z: entity.position[2] },
+        yaw: entity.rotationY,
+    };
+}
+/**
+ * Shared per-frame finalizer every rig funnels through: applies the crossfade
+ * blend captured on a rig swap, layers the trauma-channel shake, advances the
+ * shake clock, and reports `onCameraFollow`. Rigs compute a clean pose; this
+ * hook owns shake + transitions so they behave identically across rigs.
+ */
+function useCameraCommit(props, followId) {
+    const camera = useThree((state) => state.camera);
+    const shake = useCameraShake();
+    const shakeConfig = props.config?.shake;
+    const transitionSeconds = props.config?.transitionSeconds ?? 0.6;
+    const blendRef = useRef(null);
+    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,
+        };
+    };
+    const commit = (pose, dt) => {
+        lastPoseRef.current = pose;
+        applyPose(camera, pose);
+        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;
+        }
+        shake.step(dt);
+        const offset = shake.sample(shakeConfig);
+        if (offset.x !== 0 || offset.y !== 0 || offset.roll !== 0) {
+            camera.translateX(offset.x);
+            camera.translateY(offset.y);
+            camera.rotateZ(offset.roll);
+        }
+        props.config?.onCameraFollow?.({
+            entityId: followId ?? "",
+            target: pose.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),
+        });
+    };
+    return { camera, commit, beginTransition };
+}
+function useWheelZoom(initial, min, max, speed) {
+    const domElement = useThree((state) => state.gl.domElement);
+    const zoomRef = useRef(initial);
+    useEffect(() => {
+        zoomRef.current = initial;
+    }, [initial]);
+    useEffect(() => {
+        const onWheel = (event) => {
+            if (event.shiftKey)
+                return;
+            zoomRef.current = clamp(zoomRef.current + Math.sign(event.deltaY) * speed, min, max);
+        };
+        domElement.addEventListener("wheel", onWheel, { passive: true });
+        return () => domElement.removeEventListener("wheel", onWheel);
+    }, [domElement, min, max, speed]);
+    return zoomRef;
+}
+export function TopDownRig(props) {
+    const { userId } = usePlayer();
+    const ctx = useGameContext();
+    const followId = resolveFollowId(props.followEntityId, userId);
+    const config = props.config?.topDown;
+    const resolved = useMemo(() => resolveTopDown(config), [config]);
+    const { camera, commit, beginTransition } = useCameraCommit(props, followId);
+    const followRef = useRef(null);
+    const zoomRef = useWheelZoom(resolved.height, (config?.zoom?.min ?? 0.6) * resolved.height, (config?.zoom?.max ?? 1.8) * resolved.height, config?.zoom?.speed ?? resolved.height * 0.08);
+    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 = 1 - Math.exp(-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;
+        props.yawRef.current = resolved.yaw;
+        const pose = topDownPose(follow, { ...resolved, height: zoomRef.current }, currentFov(camera));
+        commit(pose, dt);
+    }, 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(() => {
+        const set = new Set(codes);
+        const down = (event) => {
+            if (set.has(event.code))
+                held.current.add(event.code);
+        };
+        const up = (event) => {
+            held.current.delete(event.code);
+        };
+        window.addEventListener("keydown", down);
+        window.addEventListener("keyup", up);
+        return () => {
+            window.removeEventListener("keydown", down);
+            window.removeEventListener("keyup", up);
+            held.current.clear();
+        };
+    }, [codes.join(",")]);
+    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();
+    const followId = resolveFollowId(props.followEntityId, userId);
+    const config = props.config?.rts;
+    const resolved = useMemo(() => resolveTopDown(config), [config]);
+    const { camera, commit, beginTransition } = useCameraCommit(props, followId);
+    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,
+        z: config?.start?.z ?? 0,
+    });
+    const yawRef = useRef(resolved.yaw);
+    const pointerRef = useRef(null);
+    const domElement = useThree((state) => state.gl.domElement);
+    const zoomRef = useWheelZoom(resolved.height, (config?.zoom?.min ?? 0.5) * resolved.height, (config?.zoom?.max ?? 2.2) * resolved.height, config?.zoom?.speed ?? resolved.height * 0.09);
+    const edgeScroll = config?.edgeScroll ?? true;
+    const edgeMargin = typeof edgeScroll === "object" ? edgeScroll.margin ?? 0.04 : 0.04;
+    const panSpeed = config?.panSpeed ?? 24;
+    const rotateSpeed = config?.rotateSpeed ?? 1.4;
+    useEffect(beginTransition, []);
+    useEffect(() => {
+        if (edgeScroll === false)
+            return;
+        const onMove = (event) => {
+            const rect = domElement.getBoundingClientRect();
+            pointerRef.current = {
+                nx: (event.clientX - rect.left) / rect.width,
+                ny: (event.clientY - rect.top) / rect.height,
+            };
+        };
+        const onLeave = () => {
+            pointerRef.current = null;
+        };
+        domElement.addEventListener("pointermove", onMove);
+        domElement.addEventListener("pointerleave", onLeave);
+        return () => {
+            domElement.removeEventListener("pointermove", onMove);
+            domElement.removeEventListener("pointerleave", onLeave);
+        };
+    }, [domElement, edgeScroll]);
+    useFrame((_, dt) => {
+        const keys = held.current;
+        if (keys.has("KeyQ"))
+            yawRef.current += rotateSpeed * dt;
+        if (keys.has("KeyE"))
+            yawRef.current -= rotateSpeed * dt;
+        let panX = 0;
+        let panZ = 0;
+        if (keys.has("KeyW") || keys.has("ArrowUp"))
+            panZ += 1;
+        if (keys.has("KeyS") || keys.has("ArrowDown"))
+            panZ -= 1;
+        if (keys.has("KeyD") || keys.has("ArrowRight"))
+            panX += 1;
+        if (keys.has("KeyA") || keys.has("ArrowLeft"))
+            panX -= 1;
+        const pointer = pointerRef.current;
+        if (edgeScroll !== false && pointer !== null) {
+            if (pointer.nx < edgeMargin)
+                panX -= 1;
+            else if (pointer.nx > 1 - edgeMargin)
+                panX += 1;
+            if (pointer.ny < edgeMargin)
+                panZ += 1;
+            else if (pointer.ny > 1 - edgeMargin)
+                panZ -= 1;
+        }
+        const center = centerRef.current;
+        if (panX !== 0 || panZ !== 0) {
+            const cos = Math.cos(yawRef.current);
+            const sin = Math.sin(yawRef.current);
+            const worldX = panX * cos + panZ * sin;
+            const worldZ = panZ * cos - panX * sin;
+            const len = Math.hypot(worldX, worldZ) || 1;
+            center.x += (worldX / len) * panSpeed * dt;
+            center.z += (worldZ / len) * panSpeed * dt;
+        }
+        else {
+            const follow = readFollow(ctx, followId);
+            if (follow !== null) {
+                center.x += (follow.pos.x - center.x) * (1 - Math.exp(-resolved.followSmoothing * dt));
+                center.z += (follow.pos.z - center.z) * (1 - Math.exp(-resolved.followSmoothing * dt));
+            }
+        }
+        const bounds = config?.bounds;
+        if (bounds !== undefined) {
+            center.x = clamp(center.x, bounds.minX ?? -Infinity, bounds.maxX ?? Infinity);
+            center.z = clamp(center.z, bounds.minZ ?? -Infinity, bounds.maxZ ?? Infinity);
+        }
+        props.yawRef.current = yawRef.current;
+        const pose = topDownPose(center, { ...resolved, yaw: yawRef.current, height: zoomRef.current }, currentFov(camera));
+        commit(pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}
+export function ShoulderRig(props) {
+    const { userId } = usePlayer();
+    const ctx = useGameContext();
+    const followId = resolveFollowId(props.followEntityId, userId);
+    const config = props.config?.shoulder;
+    const { commit, beginTransition } = useCameraCommit(props, followId);
+    const domElement = useThree((state) => state.gl.domElement);
+    const sideRef = useRef(config?.side === "left" ? -1 : 1);
+    const aimRef = useRef(0);
+    const aimingRef = useRef(false);
+    const sensitivity = config?.sensitivity ?? 0.0025;
+    useEffect(beginTransition, []);
+    useEffect(() => {
+        const requestLock = () => {
+            if (document.pointerLockElement !== domElement)
+                void domElement.requestPointerLock?.();
+        };
+        const onMove = (event) => {
+            if (document.pointerLockElement !== domElement)
+                return;
+            props.yawRef.current -= event.movementX * sensitivity;
+            props.pitchRef.current = clamp(props.pitchRef.current - event.movementY * sensitivity, -1.2, 1.2);
+        };
+        const onDown = (event) => {
+            if (event.button === 2)
+                aimingRef.current = true;
+        };
+        const onUp = (event) => {
+            if (event.button === 2)
+                aimingRef.current = false;
+        };
+        const onKey = (event) => {
+            if (event.code === "KeyV")
+                sideRef.current *= -1;
+        };
+        const onContext = (event) => event.preventDefault();
+        domElement.addEventListener("click", requestLock);
+        window.addEventListener("mousemove", onMove);
+        window.addEventListener("mousedown", onDown);
+        window.addEventListener("mouseup", onUp);
+        window.addEventListener("keydown", onKey);
+        domElement.addEventListener("contextmenu", onContext);
+        return () => {
+            domElement.removeEventListener("click", requestLock);
+            window.removeEventListener("mousemove", onMove);
+            window.removeEventListener("mousedown", onDown);
+            window.removeEventListener("mouseup", onUp);
+            window.removeEventListener("keydown", onKey);
+            domElement.removeEventListener("contextmenu", onContext);
+        };
+    }, [domElement, sensitivity, props.yawRef, props.pitchRef]);
+    useFrame((_, dt) => {
+        const sample = readFollow(ctx, followId);
+        const follow = sample?.pos ?? { x: 0, y: 0, z: 0 };
+        const adsTarget = aimingRef.current ? 1 : 0;
+        aimRef.current += (adsTarget - aimRef.current) * (1 - Math.exp(-(config?.adsTransitionSpeed ?? 10) * dt));
+        const hip = resolveShoulder(config, false);
+        const ads = resolveShoulder(config, true);
+        const blended = {
+            shoulderOffset: hip.shoulderOffset + (ads.shoulderOffset - hip.shoulderOffset) * aimRef.current,
+            heightOffset: hip.heightOffset + (ads.heightOffset - hip.heightOffset) * aimRef.current,
+            distance: hip.distance + (ads.distance - hip.distance) * aimRef.current,
+            fov: hip.fov + (ads.fov - hip.fov) * aimRef.current,
+        };
+        const pose = shoulderPose(follow, props.yawRef.current, props.pitchRef.current, sideRef.current, blended);
+        commit(pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}
+function pickLockTarget(ctx, followId, config) {
+    if (config?.targetEntityId !== undefined)
+        return config.targetEntityId;
+    if (followId !== null) {
+        const explicit = ctx.scene.entity.getTarget(followId);
+        if (explicit !== null)
+            return explicit;
+    }
+    let nearest = null;
+    let best = Infinity;
+    const origin = followId === null ? null : ctx.scene.entity.get(followId);
+    if (origin === null)
+        return null;
+    for (const entity of ctx.scene.entity.list()) {
+        if (entity.id === followId)
+            continue;
+        const dx = entity.position[0] - origin.position[0];
+        const dz = entity.position[2] - origin.position[2];
+        const d = dx * dx + dz * dz;
+        if (d < best) {
+            best = d;
+            nearest = entity.id;
+        }
+    }
+    return nearest;
+}
+export function LockOnRig(props) {
+    const { userId } = usePlayer();
+    const ctx = useGameContext();
+    const followId = resolveFollowId(props.followEntityId, userId);
+    const config = props.config?.lockOn;
+    const { camera, commit, beginTransition } = useCameraCommit(props, followId);
+    const yawRef = useRef(0);
+    const seeded = useRef(false);
+    useEffect(beginTransition, []);
+    useFrame((_, dt) => {
+        const sample = readFollow(ctx, followId);
+        const player = sample?.pos ?? { x: 0, y: 0, z: 0 };
+        const targetId = pickLockTarget(ctx, followId, config);
+        const targetEntity = targetId === null ? null : ctx.scene.entity.get(targetId);
+        const target = targetEntity === null
+            ? { x: player.x, y: player.y, z: player.z + 1 }
+            : { x: targetEntity.position[0], y: targetEntity.position[1], z: targetEntity.position[2] };
+        const { pose, yaw } = lockOnPose(player, target, config, currentFov(camera));
+        if (!seeded.current) {
+            yawRef.current = yaw;
+            seeded.current = true;
+        }
+        else {
+            yawRef.current = smoothYaw(yawRef.current, yaw, config?.yawSmoothing ?? 9, dt);
+        }
+        props.yawRef.current = yawRef.current;
+        commit(pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}
+export function ChaseRig(props) {
+    const { userId } = usePlayer();
+    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 shake = useCameraShake();
+    const posRef = useRef(null);
+    const lastFollowRef = useRef(null);
+    const view = config?.view ?? "chase";
+    useEffect(beginTransition, [view]);
+    useFrame((_, dt) => {
+        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);
+        if (view !== "chase") {
+            const seat = view === "cockpit"
+                ? config?.seatOffsets?.cockpit ?? { x: 0, y: 1.2, z: 0.1 }
+                : view === "hood"
+                    ? config?.seatOffsets?.hood ?? { x: 0, y: 1, z: 1.4 }
+                    : config?.seatOffsets?.rear ?? { x: 0, y: 1.6, z: -1.5 };
+            const lookBack = view === "rear";
+            const pose = seatPose(follow, lookBack ? yaw + Math.PI : yaw, seat, fov);
+            if (lookBack) {
+                pose.position = seatPose(follow, yaw, seat, fov).position;
+            }
+            commit(pose, dt);
+            return;
+        }
+        const desired = chaseDesiredPosition(follow, 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 };
+        commit(pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}
+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) {
+            return { subject: { x: entity.position[0], y: entity.position[1], z: entity.position[2] }, boundEntityId: bind.entityId };
+        }
+        return { subject: { x: 0, y: 0, z: 0 }, boundEntityId: bind.entityId };
+    }
+    if (bind?.kind === "point")
+        return { subject: { ...bind.position }, boundEntityId: null };
+    return { subject: { x: 0, y: 0, z: 0 }, boundEntityId: null };
+}
+/**
+ * Detached spectator/photo cam (#120): binds to any entity or fixed point and
+ * auto-orbits it, reading no player input at all — the van CCTV / photo-mode /
+ * 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, followId).boundEntityId);
+    useEffect(beginTransition, []);
+    useFrame((_, dt) => {
+        angleRef.current += resolved.orbitSpeed * dt;
+        const { subject } = observerSubject(ctx, config, followId);
+        const pose = observerPose(subject, angleRef.current, resolved, config?.fov ?? currentFov(camera));
+        commit(pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}
+export function CinematicRig(props) {
+    const { userId } = usePlayer();
+    const followId = resolveFollowId(props.followEntityId, userId);
+    const cinematic = props.config?.cinematic;
+    const { camera, commit, beginTransition } = useCameraCommit(props, followId);
+    const elapsedRef = useRef(0);
+    useEffect(() => {
+        elapsedRef.current = 0;
+        beginTransition();
+    }, [cinematic]);
+    useFrame((_, dt) => {
+        if (cinematic === undefined)
+            return;
+        elapsedRef.current += dt;
+        const sample = cinematicSample(cinematic.keyframes, elapsedRef.current, cinematic.loop ?? false, currentFov(camera));
+        commit(sample.pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}

package/dist/camera/index.d.ts

@@ -1,2 +1,9 @@
 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, SideScrollRig, TopDownRig, type RigProps, } from "./cameraRigs.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";

package/dist/camera/index.js

@@ -1,2 +1,9 @@
 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, SideScrollRig, TopDownRig, } from "./cameraRigs.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";

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";
+}