@jgengine/shell 0.9.0 → 0.11.0

package/dist/camera/GameInspectionCamera.js

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

package/dist/camera/GameOrbitCamera.js

@@ -2,10 +2,10 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { OrbitControls } from "@react-three/drei";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
-import { MOUSE, PerspectiveCamera, Vector3 } from "three";
+import { MOUSE, PerspectiveCamera, Raycaster, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
-import { cameraLookPitch, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
+import { 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);
@@ -16,6 +16,16 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
     const ctx = useGameContext();
     const playerFov = usePlayerFov();
     const camera = useThree((state) => state.camera);
+    const scene = useThree((state) => state.scene);
+    const raycasterRef = useRef(new Raycaster());
+    const collisionDirRef = useRef(new Vector3());
+    const collisionOriginRef = useRef(new Vector3());
+    const 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);
@@ -56,6 +66,40 @@ 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;
+                ray.set(collisionOriginRef.current.set(t.x, t.y, t.z), dir);
+                ray.near = config.collision.minTargetDistance;
+                ray.far = dist;
+                let blocked = 0;
+                for (const hit of ray.intersectObjects(scene.children, true)) {
+                    const obj = hit.object;
+                    if (!obj.visible)
+                        continue;
+                    if (obj.isSprite === true)
+                        continue;
+                    if (obj.userData.jgCameraTransparent === true)
+                        continue;
+                    blocked = hit.distance;
+                    break;
+                }
+                if (blocked > 0) {
+                    const pulled = Math.max(config.collision.minTargetDistance, blocked - config.collision.padding);
+                    camera.position.set(t.x + dir.x * pulled, t.y + dir.y * pulled, t.z + dir.z * pulled);
+                    pulledDistance = pulled;
+                }
+            }
+        }
         runtimeRef.current = {
             target: stepped.target,
             camera: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
@@ -68,17 +112,22 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
         }
         if (camera.isPerspectiveCamera === true) {
             const perspective = camera;
-            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
-                perspective.fov = playerFov.fov;
+            const targetFov = pulledDistance > 0 && pulledDistance < desiredDistance
+                ? compensatedFov(playerFov.fov, desiredDistance, pulledDistance)
+                : playerFov.fov;
+            if (Math.abs(perspective.fov - targetFov) > 0.001) {
+                perspective.fov = targetFov;
                 perspective.updateProjectionMatrix();
             }
         }
-        onCameraFollow?.({
-            entityId: followId,
-            target: stepped.target,
-            camera: runtimeRef.current.camera,
-            distance: runtimeRef.current.lockedDistance ?? stepped.distance,
-        });
+        if (onCameraFollow !== undefined) {
+            const payload = followPayloadRef.current;
+            payload.entityId = followId;
+            payload.target = stepped.target;
+            payload.camera = runtimeRef.current.camera;
+            payload.distance = runtimeRef.current.lockedDistance ?? stepped.distance;
+            onCameraFollow(payload);
+        }
     }, ORBIT_CAMERA_FRAME_PRIORITY);
     return (_jsx(OrbitControls, { ref: controlsRef, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, enablePan: false, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, maxPolarAngle: config.maxPolarAngle, minPolarAngle: config.minPolarAngle, screenSpacePanning: false, mouseButtons: pointerControls
             ? { LEFT: undefined, MIDDLE: MOUSE.ROTATE, RIGHT: undefined }

package/dist/camera/cameraBlendMath.d.ts

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

package/dist/camera/cameraBlendMath.js

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

package/dist/camera/fovPreference.d.ts

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

package/dist/camera/fovPreference.js

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

package/dist/camera/index.d.ts

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

package/dist/camera/index.js

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

package/dist/camera/inspectionCameraMath.d.ts

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

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. */
@@ -39,6 +49,23 @@ export interface OrbitCameraConfig {
     /** Vertical clamp (three.js polar angle, radians): 0 = top-down over the head, PI/2 = level, >PI/2 = look up from below the target. Widen to allow top-down or vertical aim; leave unset for the standard chase feel. */
     minPolarAngle?: number;
     maxPolarAngle?: number;
+    /** Spring-arm collision: raycast target→camera each frame and pull the boom in past occluders (walls, terrain) so the camera never clips inside geometry. */
+    collision?: OrbitCollisionConfig;
+}
+/** Spring-arm occlusion config for the orbit rig. */
+export interface OrbitCollisionConfig {
+    /** Enable the pull-in raycast. Default false (unchanged chase camera). */
+    enabled?: boolean;
+    /** Gap kept between the camera and the hit surface, world units. Default 0.35. */
+    padding?: number;
+    /** Ignore hits closer than this to the target — the player's own body. Default 1.2. */
+    minTargetDistance?: number;
+}
+/** An {@link OrbitCollisionConfig} with every field resolved to a concrete value. */
+export interface ResolvedOrbitCollision {
+    enabled: boolean;
+    padding: number;
+    minTargetDistance: number;
 }
 /** Fully resolved shell config after merging with DEFAULT_ORBIT_CAMERA. */
 export interface ResolvedOrbitCameraConfig {
@@ -47,6 +74,8 @@ export interface ResolvedOrbitCameraConfig {
     targetHeight: number;
     initialDistance: number;
     initialHeight: number;
+    initialYaw?: number;
+    initialPitch?: number;
     targetOffset?: Partial<Vec3>;
     followLock: boolean;
     followEnabled: boolean;
@@ -58,6 +87,7 @@ export interface ResolvedOrbitCameraConfig {
     distanceSmoothing: number;
     minPolarAngle: number;
     maxPolarAngle: number;
+    collision: ResolvedOrbitCollision;
 }
 export declare const DEFAULT_ORBIT_CAMERA: ResolvedOrbitCameraConfig;
 /** Run simulation/movement before orbit follow so poses are current. */
@@ -69,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;
@@ -94,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);
@@ -25,24 +29,54 @@ export const DEFAULT_ORBIT_CAMERA = {
     distanceSmoothing: 5,
     minPolarAngle: 0.12,
     maxPolarAngle: Math.PI / 2.05,
+    collision: { enabled: false, padding: 0.35, minTargetDistance: 1.2 },
 };
 /** Run simulation/movement before orbit follow so poses are current. */
 export const GAME_SIM_FRAME_PRIORITY = 0;
 /** 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 { ...DEFAULT_ORBIT_CAMERA, ...patch };
+    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 {
@@ -51,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,
@@ -58,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: {
@@ -80,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 };
@@ -119,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,