@jgengine/shell 0.10.0 → 0.12.0

package/dist/camera/GameOrbitCamera.js

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

package/dist/camera/cameraBlendMath.d.ts

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

package/dist/camera/cameraBlendMath.js

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

package/dist/camera/cameraRigs.d.ts

@@ -26,4 +26,6 @@ export declare function ChaseRig(props: RigProps): null;
  * kill-cam rig. Distinct from every other rig, which drives from mouse/keys.
  */
 export declare function ObserverRig(props: RigProps): null;
-export declare function CinematicRig(props: RigProps): null;
+export declare function CinematicRig(props: RigProps & {
+    onComplete?: () => void;
+}): null;

package/dist/camera/cameraRigs.js

@@ -4,7 +4,7 @@ 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 { 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 { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, velocityYawTarget, } from "./rigMath.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
 import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
@@ -424,6 +424,7 @@ export function ChaseRig(props) {
     const posRef = useRef(null);
     const lastFollowRef = useRef(null);
     const lastYawRef = useRef(null);
+    const anchorYawRef = useRef(null);
     const rollRef = useRef(0);
     const view = config?.view ?? "chase";
     useEffect(beginTransition, [view]);
@@ -454,15 +455,24 @@ export function ChaseRig(props) {
             commit(pose, dt);
             return;
         }
+        let anchorYaw = yaw;
+        if (resolved.velocityYawBlend > 0) {
+            const velocity = dt > 0
+                ? { x: (follow.x - last.x) / dt, y: 0, z: (follow.z - last.z) / dt }
+                : { x: 0, y: 0, z: 0 };
+            const targetYaw = velocityYawTarget(yaw, velocity, resolved);
+            anchorYaw = smoothYaw(anchorYawRef.current ?? targetYaw, targetYaw, resolved.velocityYawResponse, dt);
+            anchorYawRef.current = anchorYaw;
+        }
         const led = leadFollowPoint(follow, last, dt, resolved);
-        const desired = chaseDesiredPosition(led, yaw, resolved);
+        const desired = chaseDesiredPosition(led, anchorYaw, 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(led, yaw, resolved), fov };
+        const pose = { position: smoothed, lookAt: chaseLookAt(led, anchorYaw, resolved), fov };
         commit(pose, dt);
         if (rollRef.current !== 0)
             camera.rotateZ(rollRef.current);
@@ -510,8 +520,12 @@ export function CinematicRig(props) {
     const cinematic = props.config?.cinematic;
     const { camera, commit, beginTransition } = useCameraCommit(props, followId);
     const elapsedRef = useRef(0);
+    const completedRef = useRef(false);
+    const onCompleteRef = useRef(props.onComplete);
+    onCompleteRef.current = props.onComplete;
     useEffect(() => {
         elapsedRef.current = 0;
+        completedRef.current = false;
         beginTransition();
     }, [cinematic]);
     useFrame((_, dt) => {
@@ -520,6 +534,10 @@ export function CinematicRig(props) {
         elapsedRef.current += dt;
         const sample = cinematicSample(cinematic.keyframes, elapsedRef.current, cinematic.loop ?? false, currentFov(camera));
         commit(sample.pose, dt);
+        if (sample.done && !completedRef.current) {
+            completedRef.current = true;
+            onCompleteRef.current?.();
+        }
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }

package/dist/camera/fovPreference.d.ts

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

package/dist/camera/fovPreference.js

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

package/dist/camera/index.d.ts

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

package/dist/camera/index.js

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

package/dist/camera/inspectionCameraMath.d.ts

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

package/dist/camera/inspectionCameraMath.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function resolveInspectionCameraConfig(config) {
     return {
         anchor: config?.anchor ?? "target",
@@ -24,7 +25,9 @@ export function resolveInspectionCameraConfig(config) {
         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. */
+/** Seeds the camera/target world position before OrbitControls mounts. Falls back to `initialDistance` behind `target` on the -Z axis, raised by 40% of that distance, when `initialPosition` is unset.
+ * @internal
+ */
 export function seedInspectionCamera(config) {
     if (config.initialPosition !== null) {
         return { camera: config.initialPosition, target: config.target };
@@ -38,7 +41,9 @@ export function seedInspectionCamera(config) {
         target: config.target,
     };
 }
-/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag. */
+/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag.
+ * @internal
+ */
 export function resolveInspectionZoomToCursor(anchor) {
     return anchor === "cursor";
 }

package/dist/camera/orbitCameraMath.d.ts

@@ -1,6 +1,10 @@
-/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane. */
+/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane.
+ * @internal
+ */
 export declare function orbitYawFromCamera(cameraX: number, cameraZ: number, targetX: number, targetZ: number): number;
-/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera. */
+/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera.
+ * @internal
+ */
 export declare function cameraLookPitch(camera: Vec3, target: Vec3): number;
 export interface Vec3 {
     x: number;
@@ -19,6 +23,12 @@ export interface OrbitCameraConfig {
     targetHeight?: number;
     initialDistance?: number;
     initialHeight?: number;
+    /** Initial horizontal facing of the boom (radians): 0 = camera behind on -Z, PI = camera on +Z. Seeds the rig when set; unset keeps the legacy -Z placement. */
+    initialYaw?: number;
+    /** Initial boom elevation (radians): 0 = level, positive = camera above the target looking down. Seeds the rig when set; unset derives elevation from `initialHeight`/`initialDistance`. */
+    initialPitch?: number;
+    /** Signed boom-elevation clamp `[min, max]` (radians): min < 0 dips below the target, max > 0 rises overhead. Maps onto `minPolarAngle`/`maxPolarAngle` (polar = PI/2 − pitch); explicit polar fields win. */
+    pitchClamp?: readonly [number, number];
     /** Extra offset applied on top of entity position for the orbit target. */
     targetOffset?: Partial<Vec3>;
     /** Keep orbit radius locked while the follow target moves. */
@@ -64,6 +74,8 @@ export interface ResolvedOrbitCameraConfig {
     targetHeight: number;
     initialDistance: number;
     initialHeight: number;
+    initialYaw?: number;
+    initialPitch?: number;
     targetOffset?: Partial<Vec3>;
     followLock: boolean;
     followEnabled: boolean;
@@ -87,22 +99,38 @@ export interface OrbitFollowRuntimeState {
     camera: Vec3;
     lockedDistance: number | null;
 }
-/** Frame-rate independent exponential smoothing factor in [0, 1]. */
+/** Frame-rate independent exponential smoothing factor in [0, 1].
+ * @internal
+ */
 export declare function smoothBlend(deltaSeconds: number, speed: number): number;
+/** @internal */
 export declare function resolveOrbitCameraConfig(patch?: OrbitCameraConfig): ResolvedOrbitCameraConfig;
+/**
+ * FOV that keeps a target's on-screen size constant as the spring-arm pulls the
+ * camera in. Widens the base FOV by the desired/pulled distance ratio; a no-op
+ * (returns the base) whenever the camera sits at or beyond its desired distance.
+  * @internal
+  */
+export declare function compensatedFov(baseFovDegrees: number, desiredDistance: number, pulledDistance: number): number;
+/** @internal */
 export declare function resolveTargetSmoothing(config: ResolvedOrbitCameraConfig, dragging: boolean): number;
+/** @internal */
 export declare function resolveFollowTargetFromPosition(position: readonly [number, number, number], config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset">): Vec3;
+/** @internal */
 export declare function lerpVec3(from: Vec3, to: Vec3, blend: number): Vec3;
+/** @internal */
 export declare function distanceBetween(a: Vec3, b: Vec3): number;
+/** @internal */
 export declare function seedOrbitFollowState(input: {
     entityPosition: readonly [number, number, number];
-    config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset" | "initialDistance" | "initialHeight">;
+    config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset" | "initialDistance" | "initialHeight" | "initialYaw" | "initialPitch">;
 }): OrbitFollowRuntimeState;
 /**
  * Pure orbit follow step — smooth target tracking, camera carries target delta
  * (OrbitControls alone keeps camera fixed when only target moves), optional
  * distance lock. Call each frame before OrbitControls.update() in the shell.
- */
+  * @internal
+  */
 export declare function orbitFollowStep(input: {
     state: OrbitFollowRuntimeState;
     desiredTarget: Vec3;
@@ -112,7 +140,9 @@ export declare function orbitFollowStep(input: {
 }): OrbitFollowRuntimeState & {
     distance: number;
 };
-/** @deprecated Use orbitFollowStep — kept for older call sites. */
+/** @deprecated Use orbitFollowStep — kept for older call sites.
+ * @internal
+ */
 export declare function cameraFollowStep(input: {
     camera: Vec3;
     target: Vec3;

package/dist/camera/orbitCameraMath.js

@@ -1,10 +1,14 @@
-/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane. */
+/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane.
+ * @internal
+ */
 export function orbitYawFromCamera(cameraX, cameraZ, targetX, targetZ) {
     const dx = targetX - cameraX;
     const dz = targetZ - cameraZ;
     return Math.atan2(dx, dz);
 }
-/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera. */
+/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera.
+ * @internal
+ */
 export function cameraLookPitch(camera, target) {
     const horizontal = Math.hypot(target.x - camera.x, target.z - camera.z);
     return Math.atan2(target.y - camera.y, horizontal);
@@ -31,23 +35,48 @@ export const DEFAULT_ORBIT_CAMERA = {
 export const GAME_SIM_FRAME_PRIORITY = 0;
 /** Orbit follow reads the latest entity pose after GAME_SIM_FRAME_PRIORITY. */
 export const ORBIT_CAMERA_FRAME_PRIORITY = -1;
-/** Frame-rate independent exponential smoothing factor in [0, 1]. */
+/** Frame-rate independent exponential smoothing factor in [0, 1].
+ * @internal
+ */
 export function smoothBlend(deltaSeconds, speed) {
     return 1 - Math.exp(-speed * deltaSeconds);
 }
+/** @internal */
 export function resolveOrbitCameraConfig(patch) {
-    return {
+    const resolved = {
         ...DEFAULT_ORBIT_CAMERA,
         ...patch,
         collision: { ...DEFAULT_ORBIT_CAMERA.collision, ...patch?.collision },
     };
+    if (patch?.pitchClamp !== undefined) {
+        const [minPitch, maxPitch] = patch.pitchClamp;
+        resolved.minPolarAngle = patch.minPolarAngle ?? Math.PI / 2 - maxPitch;
+        resolved.maxPolarAngle = patch.maxPolarAngle ?? Math.PI / 2 - minPitch;
+    }
+    return resolved;
 }
+/**
+ * FOV that keeps a target's on-screen size constant as the spring-arm pulls the
+ * camera in. Widens the base FOV by the desired/pulled distance ratio; a no-op
+ * (returns the base) whenever the camera sits at or beyond its desired distance.
+  * @internal
+  */
+export function compensatedFov(baseFovDegrees, desiredDistance, pulledDistance) {
+    if (pulledDistance <= 0 || desiredDistance <= 0 || pulledDistance >= desiredDistance) {
+        return baseFovDegrees;
+    }
+    const half = (baseFovDegrees * Math.PI) / 360;
+    const widened = 2 * Math.atan(Math.tan(half) * (desiredDistance / pulledDistance));
+    return Math.min((widened * 180) / Math.PI, 170);
+}
+/** @internal */
 export function resolveTargetSmoothing(config, dragging) {
     if (dragging) {
         return config.dragTargetSmoothing;
     }
     return config.targetSmoothing;
 }
+/** @internal */
 export function resolveFollowTargetFromPosition(position, config) {
     const offset = config.targetOffset;
     return {
@@ -56,6 +85,7 @@ export function resolveFollowTargetFromPosition(position, config) {
         z: position[2] + (offset?.z ?? 0),
     };
 }
+/** @internal */
 export function lerpVec3(from, to, blend) {
     return {
         x: from.x + (to.x - from.x) * blend,
@@ -63,14 +93,31 @@ export function lerpVec3(from, to, blend) {
         z: from.z + (to.z - from.z) * blend,
     };
 }
+/** @internal */
 export function distanceBetween(a, b) {
     const dx = a.x - b.x;
     const dy = a.y - b.y;
     const dz = a.z - b.z;
     return Math.sqrt(dx * dx + dy * dy + dz * dz);
 }
+/** @internal */
 export function seedOrbitFollowState(input) {
     const target = resolveFollowTargetFromPosition(input.entityPosition, input.config);
+    const { initialDistance, initialYaw, initialPitch } = input.config;
+    if (initialYaw !== undefined || initialPitch !== undefined) {
+        const yaw = initialYaw ?? 0;
+        const pitch = initialPitch ?? Math.atan2(input.config.initialHeight - input.config.targetHeight, initialDistance);
+        const horizontal = initialDistance * Math.cos(pitch);
+        return {
+            target,
+            camera: {
+                x: target.x - horizontal * Math.sin(yaw),
+                y: target.y + initialDistance * Math.sin(pitch),
+                z: target.z - horizontal * Math.cos(yaw),
+            },
+            lockedDistance: initialDistance,
+        };
+    }
     return {
         target,
         camera: {
@@ -85,7 +132,8 @@ export function seedOrbitFollowState(input) {
  * Pure orbit follow step — smooth target tracking, camera carries target delta
  * (OrbitControls alone keeps camera fixed when only target moves), optional
  * distance lock. Call each frame before OrbitControls.update() in the shell.
- */
+  * @internal
+  */
 export function orbitFollowStep(input) {
     const target = { ...input.state.target };
     const camera = { ...input.state.camera };
@@ -124,7 +172,9 @@ export function orbitFollowStep(input) {
     }
     return { target, camera, lockedDistance, distance: distanceBetween(camera, target) };
 }
-/** @deprecated Use orbitFollowStep — kept for older call sites. */
+/** @deprecated Use orbitFollowStep — kept for older call sites.
+ * @internal
+ */
 export function cameraFollowStep(input) {
     const state = {
         target: input.previousTarget ?? input.target,