@jgengine/shell 0.18.1 → 0.21.0

package/dist/camera/cameraRigs.js

@@ -5,10 +5,12 @@ import { snapPixelPerfectPosition } from "@jgengine/core/game/pixelPerfect";
 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, rtsPanWorldDir, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, velocityYawTarget, } from "./rigMath.js";
+import { cinematicSample, clamp, clampBoomToHit, createChaseRigState, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, rtsPanWorldDir, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, stepChase, topDownPose, } from "./rigMath.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
 import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
+import { requestRawPointerLock } from "../input/pointerLock.js";
+import { resolveChaseHeading } from "./chaseHeading.js";
 export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
 export const CAMERA_RIG_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY;
 export const CAMERA_POST_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY + 0.5;
@@ -306,7 +308,7 @@ export function ShoulderRig(props) {
     useEffect(() => {
         const requestLock = () => {
             if (document.pointerLockElement !== domElement)
-                void domElement.requestPointerLock?.();
+                requestRawPointerLock(domElement);
         };
         const onMove = (event) => {
             if (document.pointerLockElement !== domElement)
@@ -345,8 +347,13 @@ export function ShoulderRig(props) {
     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 weapon = followId === null ? null : (props.config?.weapon?.(followId) ?? null);
+        if (weapon === null) {
+            const adsTarget = aimingRef.current ? 1 : 0;
+            aimRef.current += (adsTarget - aimRef.current) * (1 - Math.exp(-(config?.adsTransitionSpeed ?? 10) * dt));
+        }
+        else
+            aimRef.current = weapon.handling.adsProgress;
         const hip = resolveShoulder(config, false);
         const ads = resolveShoulder(config, true);
         const blended = {
@@ -355,7 +362,11 @@ export function ShoulderRig(props) {
             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);
+        const handling = weapon?.handling;
+        const yaw = props.yawRef.current - (handling === undefined ? 0 : handling.aimYaw + handling.cameraYaw);
+        // This rig's pitch is camera elevation, so a muzzle climb lowers it.
+        const pitch = props.pitchRef.current - (handling === undefined ? 0 : handling.aimPitch + handling.cameraPitch);
+        const pose = shoulderPose(follow, yaw, pitch, sideRef.current, blended);
         commit(pose, dt);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
@@ -424,73 +435,76 @@ export function ChaseRig(props) {
     const staticResolved = useMemo(() => resolveChase(config), [config]);
     const { camera, commit, beginTransition } = useCameraCommit(props, followId);
     const shake = useCameraShake();
-    const posRef = useRef(null);
-    const lastFollowRef = useRef(null);
-    const lastYawRef = useRef(null);
-    const anchorYawRef = useRef(null);
-    const rollRef = useRef(0);
-    const view = config?.view ?? "chase";
-    useEffect(beginTransition, [view]);
+    const stateRef = useRef(createChaseRigState());
+    const viewRef = useRef(null);
+    const inputSeededRef = useRef(false);
     useFrame((_, dt) => {
         const tuning = ctx.camera.chaseTuning();
-        const resolved = tuning === null ? staticResolved : resolveChase({ ...config, ...tuning });
-        const sample = readFollow(ctx, followId);
-        const follow = sample?.pos ?? { x: 0, y: 0, z: 0 };
-        const yaw = sample?.yaw ?? 0;
-        const last = lastFollowRef.current ?? follow;
-        const speed = dt > 0 ? Math.hypot(follow.x - last.x, follow.z - last.z) / dt : 0;
-        lastFollowRef.current = follow;
-        const lastYaw = lastYawRef.current ?? yaw;
-        lastYawRef.current = yaw;
-        rollRef.current = bankRollStep(rollRef.current, yaw, lastYaw, dt, resolved);
-        const fov = speedToFov(speed, tuning?.fov ?? config?.fov);
+        const merged = tuning === null ? config : { ...config, ...tuning };
+        const resolved = tuning === null ? staticResolved : resolveChase(merged);
+        const view = merged?.view ?? "chase";
+        if (viewRef.current !== view) {
+            beginTransition();
+            viewRef.current = view;
+            stateRef.current.offset = null;
+        }
+        const entity = followId === null ? null : ctx.scene.entity.get(followId);
+        const follow = entity === null ? { x: 0, y: 0, z: 0 } : { x: entity.position[0], y: entity.position[1], z: entity.position[2] };
+        if (!inputSeededRef.current && merged?.headingSource === "input" && view === "chase" && (entity !== null || props.config?.initialYaw !== undefined)) {
+            props.yawRef.current = resolveChaseHeading(merged, entity?.rotationY ?? 0, undefined, props.config?.initialYaw);
+            inputSeededRef.current = true;
+        }
+        const yaw = resolveChaseHeading(merged, entity?.rotationY ?? 0, props.yawRef.current);
+        const v = entity?.velocity;
+        const published = v !== undefined && (v[0] !== 0 || v[1] !== 0 || v[2] !== 0);
+        const lookBack = resolved.lookBackAction !== null && ctx.input.isDown(resolved.lookBackAction);
+        const clampBoom = resolved.collision
+            ? (pivot, desired) => {
+                const dx = desired.x - pivot.x;
+                const dy = desired.y - pivot.y;
+                const dz = desired.z - pivot.z;
+                const length = Math.hypot(dx, dy, dz);
+                if (length <= 1e-6)
+                    return desired;
+                const hit = ctx.scene.raycast({
+                    origin: [pivot.x, pivot.y, pivot.z],
+                    direction: [dx / length, dy / length, dz / length],
+                    maxDistance: length + resolved.collisionRadius,
+                    excludeInstanceIds: followId === null ? undefined : [followId],
+                    filter: { entities: false },
+                });
+                return clampBoomToHit(pivot, desired, hit?.distance ?? null, resolved.collisionRadius, resolved.collisionMinDistance);
+            }
+            : undefined;
+        const step = stepChase(stateRef.current, {
+            follow,
+            yaw,
+            bodyPitch: entity?.rotationX ?? 0,
+            velocity: published ? { x: v[0], y: v[1], z: v[2] } : null,
+            lookBack: lookBack && view === "chase",
+            fovKick: ctx.camera.takeFovKick(),
+        }, resolved, dt, view === "chase" ? clampBoom : undefined);
+        props.yawRef.current = resolveChaseHeading(merged, step.anchorYaw, props.yawRef.current);
         if (view !== "chase") {
             const seat = view === "cockpit"
-                ? config?.seatOffsets?.cockpit ?? { x: 0, y: 1.2, z: 0.1 }
+                ? merged?.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;
-            }
+                    ? merged?.seatOffsets?.hood ?? { x: 0, y: 1, z: 1.4 }
+                    : merged?.seatOffsets?.rear ?? { x: 0, y: 1.6, z: -1.5 };
+            const seatLooksBack = view === "rear" || lookBack;
+            const pose = seatPose(follow, seatLooksBack ? yaw + Math.PI : yaw, seat, step.pose.fov);
+            if (seatLooksBack)
+                pose.position = seatPose(follow, yaw, seat, step.pose.fov).position;
             props.yawRef.current = yaw;
             commit(pose, dt);
             return;
         }
-        // Anchor yaw always eases toward its target (#1370): with drift-lag configured the target is
-        // the velocity-blended yaw at velocityYawResponse, otherwise the raw body facing at
-        // yawResponse — so a strafe-flipped facing arcs the boom around the character instead of
-        // teleporting it to the far side. yawResponse: Infinity restores the legacy rigid follow.
-        let targetYaw = yaw;
-        let response = resolved.yawResponse;
-        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 };
-            targetYaw = velocityYawTarget(yaw, velocity, resolved);
-            response = resolved.velocityYawResponse;
+        if (resolved.shakePerSpeed > 0 && step.speed > 0) {
+            shake.shake(Math.min(resolved.shakePerSpeed * step.speed * dt, 0.1));
         }
-        const anchorYaw = Number.isFinite(response)
-            ? smoothYaw(anchorYawRef.current ?? targetYaw, targetYaw, response, dt)
-            : targetYaw;
-        anchorYawRef.current = anchorYaw;
-        // Report camera yaw back to the shell like every other player-facing rig, so
-        // on-foot movement and aim stay camera-relative instead of frozen at yaw 0.
-        props.yawRef.current = anchorYaw;
-        const led = leadFollowPoint(follow, last, dt, 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, anchorYaw, resolved), fov };
-        commit(pose, dt);
-        if (rollRef.current !== 0)
-            camera.rotateZ(rollRef.current);
+        commit(step.pose, dt);
+        if (step.roll !== 0)
+            camera.rotateZ(step.roll);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }

package/dist/camera/chaseHeading.d.ts

@@ -0,0 +1,9 @@
+import type { ChaseCameraConfig } from "@jgengine/core/game/playableGame";
+/**
+ * Select a chase heading without feeding target facing or camera smoothing back into input-owned yaw.
+ * An undefined input yaw seeds from `initialYaw`, or the acquired target's body heading.
+ * Seat views always use body heading; omitting `headingSource` preserves body follow.
+ *
+ * @capability chase-heading keep camera-relative input heading independent of body facing while retaining vehicle and seat camera follow
+ */
+export declare function resolveChaseHeading(config: Pick<ChaseCameraConfig, "headingSource" | "view"> | undefined, bodyYaw: number, inputYaw: number | undefined, initialYaw?: number): number;

package/dist/camera/chaseHeading.js

@@ -0,0 +1,10 @@
+/**
+ * Select a chase heading without feeding target facing or camera smoothing back into input-owned yaw.
+ * An undefined input yaw seeds from `initialYaw`, or the acquired target's body heading.
+ * Seat views always use body heading; omitting `headingSource` preserves body follow.
+ *
+ * @capability chase-heading keep camera-relative input heading independent of body facing while retaining vehicle and seat camera follow
+ */
+export function resolveChaseHeading(config, bodyYaw, inputYaw, initialYaw) {
+    return config?.headingSource === "input" && (config.view ?? "chase") === "chase" ? inputYaw ?? initialYaw ?? bodyYaw : bodyYaw;
+}

package/dist/camera/customMuzzle.d.ts

@@ -0,0 +1,14 @@
+import { Camera, Vector3 } from "three";
+/** Writes a live presentation muzzle in world space; false means this rig has no muzzle available. */
+export type FirstPersonMuzzleReader = (target: Vector3) => boolean;
+/**
+ * Register a custom rig's presentation muzzle for its Three.js camera. Newest available custom
+ * reader wins over that camera's stock muzzle; call the returned cleanup on unmount.
+ *
+ * @capability custom-viewmodel-muzzle align tracer origins with a custom viewmodel's live muzzle without changing authoritative shots
+ */
+export declare function registerFirstPersonMuzzle(camera: Camera, reader: FirstPersonMuzzleReader): () => void;
+/** @internal Stock rig registration shares camera isolation and owner-scoped cleanup. */
+export declare function registerTrackedFirstPersonMuzzle(camera: Camera, reader: FirstPersonMuzzleReader): () => void;
+/** @internal Unscoped legacy reads consider the newest 64 registrations per priority. */
+export declare function readRegisteredFirstPersonMuzzle(target: Vector3, camera?: Camera): boolean;

package/dist/camera/customMuzzle.js

@@ -0,0 +1,68 @@
+import { Camera, Vector3 } from "three";
+const MAX_READERS = 64;
+const custom = new WeakMap();
+const tracked = new WeakMap();
+const legacyCustom = [];
+const legacyTracked = [];
+function register(camera, reader, scoped, legacy) {
+    const readers = scoped.get(camera) ?? [];
+    if (readers.length >= MAX_READERS)
+        throw new RangeError("Too many muzzle readers for one camera");
+    const entry = { reader, scratch: new Vector3(), reading: false, disposed: false };
+    readers.push(entry);
+    scoped.set(camera, readers);
+    legacy.push(entry);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        entry.disposed = true;
+        readers.splice(readers.indexOf(entry), 1);
+        legacy.splice(legacy.indexOf(entry), 1);
+        if (readers.length === 0)
+            scoped.delete(camera);
+    };
+}
+/**
+ * Register a custom rig's presentation muzzle for its Three.js camera. Newest available custom
+ * reader wins over that camera's stock muzzle; call the returned cleanup on unmount.
+ *
+ * @capability custom-viewmodel-muzzle align tracer origins with a custom viewmodel's live muzzle without changing authoritative shots
+ */
+export function registerFirstPersonMuzzle(camera, reader) {
+    return register(camera, reader, custom, legacyCustom);
+}
+/** @internal Stock rig registration shares camera isolation and owner-scoped cleanup. */
+export function registerTrackedFirstPersonMuzzle(camera, reader) {
+    return register(camera, reader, tracked, legacyTracked);
+}
+function read(readers, target) {
+    if (readers === undefined)
+        return false;
+    const pending = readers.slice(-MAX_READERS);
+    for (let i = pending.length - 1; i >= 0; i--) {
+        const entry = pending[i];
+        if (entry.reading || entry.disposed)
+            continue;
+        entry.reading = true;
+        try {
+            if (!entry.reader(entry.scratch))
+                continue;
+            const { x, y, z } = entry.scratch;
+            if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+                continue;
+            target.copy(entry.scratch);
+            return true;
+        }
+        finally {
+            entry.reading = false;
+        }
+    }
+    return false;
+}
+/** @internal Unscoped legacy reads consider the newest 64 registrations per priority. */
+export function readRegisteredFirstPersonMuzzle(target, camera) {
+    return read(camera === undefined ? legacyCustom : custom.get(camera), target) ||
+        read(camera === undefined ? legacyTracked : tracked.get(camera), target);
+}

package/dist/camera/index.d.ts

@@ -9,3 +9,4 @@ export { ControllerCameraShake, type ControllerCameraShakeProps } from "./Contro
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
 export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, type CameraOccluder, } from "./cameraCollision.js";
+export { registerFirstPersonMuzzle, type FirstPersonMuzzleReader } from "./customMuzzle.js";

package/dist/camera/index.js

@@ -9,3 +9,4 @@ export { ControllerCameraShake } from "./ControllerCameraShake.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
 export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, } from "./cameraCollision.js";
+export { registerFirstPersonMuzzle } from "./customMuzzle.js";

package/dist/camera/orbitCameraMath.js

@@ -17,8 +17,8 @@ export const DEFAULT_ORBIT_CAMERA = {
     minDistance: 4,
     maxDistance: 28,
     targetHeight: 1.2,
-    initialDistance: 9,
-    initialHeight: 5.5,
+    initialDistance: 7,
+    initialHeight: 2.4,
     followLock: true,
     followEnabled: true,
     rotateSpeed: 0.22,

package/dist/camera/rigMath.d.ts

@@ -136,6 +136,23 @@ export interface ResolvedChase {
     velocityYawResponse: number;
     /** Exponential smoothing rate the anchor yaw follows the body's facing with (#1370). `Infinity` restores the legacy rigid follow. */
     yawResponse: number;
+    fovBase: number;
+    fovMax: number;
+    fovSpeedForMax: number;
+    /** Exponential FOV smoothing rate; `Infinity` applies the curve unsmoothed. */
+    fovResponse: number;
+    distanceExtra: number;
+    distanceSpeedForMax: number;
+    /** Fraction of body pitch the boom follows; 0 keeps a level boom. */
+    pitchBlend: number;
+    pitchMax: number;
+    pitchResponse: number;
+    fovKickDecay: number;
+    fovKickMax: number;
+    lookBackAction: string | null;
+    collision: boolean;
+    collisionRadius: number;
+    collisionMinDistance: number;
 }
 /** @internal */
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
@@ -143,6 +160,10 @@ export declare function resolveChase(config: ChaseCameraConfig | undefined): Res
  * @internal
  */
 export declare function leadFollowPoint(follow: Vec3, previous: Vec3, dt: number, resolved: ResolvedChase): Vec3;
+/** Velocity-lead the follow point along a known planar velocity, clamped to `leadMax`.
+ * @internal
+ */
+export declare function leadFromVelocity(follow: Vec3, velocity: Vec3, resolved: ResolvedChase): Vec3;
 /** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped.
  * @internal
  */
@@ -159,14 +180,71 @@ export declare function resolveObserver(config: ObserverCameraConfig | undefined
  * @internal
  */
 export declare function observerPose(subject: Vec3, angle: number, resolved: ResolvedObserver, fov: number): CameraPose;
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). `pitch` (nose-up positive) tilts the boom around the vehicle's right axis.
+ * @internal
+ */
+export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase, pitch?: number, distance?: number): Vec3;
+/** Camera offset from the follow point for a boom `distance` back and `height` up, tilted by `pitch` (nose-up positive).
+ * @internal
+ */
+export declare function chaseBoomOffset(yaw: number, pitch: number, distance: number, height: number): Vec3;
+/** Look point ahead of / above a chased vehicle, tilted by `pitch` like the boom.
  * @internal
  */
-export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
-/** Look point ahead of / above a chased vehicle.
+export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase, pitch?: number): Vec3;
+/** Mutable per-rig chase state; {@link stepChase} advances it in place. */
+export interface ChaseRigState {
+    /** Smoothed camera offset from the led follow point; springing the offset, not the world position, keeps the boom length at any constant speed. */
+    offset: Vec3 | null;
+    anchorYaw: number | null;
+    lastYaw: number | null;
+    lastFollow: Vec3 | null;
+    roll: number;
+    pitch: number;
+    fov: number | null;
+    kick: number;
+    lookingBack: boolean;
+}
+/** @internal */
+export declare function createChaseRigState(): ChaseRigState;
+/** What the chase rig reads from its target each frame. */
+export interface ChaseSample {
+    follow: Vec3;
+    /** Body heading (radians). */
+    yaw: number;
+    /** Body `rotationX` (three.js convention: positive = nose down). */
+    bodyPitch: number;
+    /** Sim velocity when the entity publishes one; `null` falls back to the frame-to-frame position delta. */
+    velocity: Vec3 | null;
+    lookBack: boolean;
+    /** FOV impulse (degrees) queued since the last frame. */
+    fovKick: number;
+}
+/** One frame of chase output from {@link stepChase}. */
+export interface ChaseStepResult {
+    pose: CameraPose;
+    /** Camera roll to apply after the pose, radians. */
+    roll: number;
+    /** Forward chase yaw to report to the shell; unaffected by look-back. */
+    anchorYaw: number;
+    /** Planar speed used for FOV, distance and shake. */
+    speed: number;
+}
+/** Pulls a desired camera position in toward `pivot` when something blocks the boom. */
+export type ChaseBoomClamp = (pivot: Vec3, desired: Vec3) => Vec3;
+/**
+ * One frame of the chase rig: speed from sim velocity, smoothed FOV plus decaying kicks, drift-lag
+ * anchor yaw, pitch follow, distance by speed, look-back, and a boom spring that eases the offset
+ * from the target rather than its world position, so the camera holds its distance at speed.
+ * @internal
+ */
+export declare function stepChase(state: ChaseRigState, sample: ChaseSample, resolved: ResolvedChase, dt: number, clampBoom?: ChaseBoomClamp): ChaseStepResult;
+/**
+ * Where a blocked boom should put the camera: `hitDistance` along the pivot→desired ray, less
+ * `radius`, but never nearer the pivot than `minDistance`. `null` hit returns `desired` unchanged.
  * @internal
  */
-export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
+export declare function clampBoomToHit(pivot: Vec3, desired: Vec3, hitDistance: number | null, radius: number, minDistance: number): Vec3;
 /**
  * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
  * smoothing. When the target slides, its planar `velocity` diverges from its

package/dist/camera/rigMath.js

@@ -253,6 +253,9 @@ export function lockOnPose(player, target, config, fov) {
 const DEFAULT_CHASE_YAW_RESPONSE = 5;
 /** @internal */
 export function resolveChase(config) {
+    const fovSpeedForMax = config?.fov?.speedForMax ?? 24;
+    const collision = config?.collision ?? true;
+    const collisionBlock = typeof collision === "object" ? collision : undefined;
     return {
         distance: config?.distance ?? 6,
         height: config?.height ?? 2.6,
@@ -268,16 +271,39 @@ export function resolveChase(config) {
         velocityYawMinSpeed: config?.velocityYaw?.minSpeed ?? 4,
         velocityYawResponse: config?.velocityYaw?.response ?? 6,
         yawResponse: config?.yawResponse ?? DEFAULT_CHASE_YAW_RESPONSE,
+        fovBase: config?.fov?.base ?? 55,
+        fovMax: config?.fov?.max ?? 78,
+        fovSpeedForMax,
+        fovResponse: config?.fov?.response ?? 6,
+        distanceExtra: config?.distanceBySpeed?.extra ?? 0,
+        distanceSpeedForMax: config?.distanceBySpeed?.speedForMax ?? fovSpeedForMax,
+        pitchBlend: config?.pitchFollow === undefined ? 0 : config.pitchFollow.blend ?? 1,
+        pitchMax: config?.pitchFollow?.max ?? 0.6,
+        pitchResponse: config?.pitchFollow?.response ?? 5,
+        fovKickDecay: config?.fovKick?.decay ?? 7,
+        fovKickMax: config?.fovKick?.max ?? 20,
+        lookBackAction: config?.lookBackAction ?? null,
+        collision: collision !== false,
+        collisionRadius: collisionBlock?.radius ?? 0.3,
+        collisionMinDistance: collisionBlock?.minDistance ?? 0.8,
     };
 }
 /** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
  * @internal
  */
 export function leadFollowPoint(follow, previous, dt, resolved) {
-    if (resolved.leadTime <= 0 || dt <= 0)
+    if (dt <= 0)
         return follow;
-    let leadX = ((follow.x - previous.x) / dt) * resolved.leadTime;
-    let leadZ = ((follow.z - previous.z) / dt) * resolved.leadTime;
+    return leadFromVelocity(follow, { x: (follow.x - previous.x) / dt, y: 0, z: (follow.z - previous.z) / dt }, resolved);
+}
+/** Velocity-lead the follow point along a known planar velocity, clamped to `leadMax`.
+ * @internal
+ */
+export function leadFromVelocity(follow, velocity, resolved) {
+    if (resolved.leadTime <= 0)
+        return follow;
+    let leadX = velocity.x * resolved.leadTime;
+    let leadZ = velocity.z * resolved.leadTime;
     const magnitude = Math.hypot(leadX, leadZ);
     if (magnitude > resolved.leadMax) {
         leadX *= resolved.leadMax / magnitude;
@@ -327,28 +353,120 @@ export function observerPose(subject, angle, resolved, fov) {
         fov,
     };
 }
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). `pitch` (nose-up positive) tilts the boom around the vehicle's right axis.
  * @internal
  */
-export function chaseDesiredPosition(follow, yaw, resolved) {
-    const back = forwardVector(yaw);
+export function chaseDesiredPosition(follow, yaw, resolved, pitch = 0, distance = resolved.distance) {
+    const offset = chaseBoomOffset(yaw, pitch, distance, resolved.height);
+    return { x: follow.x + offset.x, y: follow.y + offset.y, z: follow.z + offset.z };
+}
+/** Camera offset from the follow point for a boom `distance` back and `height` up, tilted by `pitch` (nose-up positive).
+ * @internal
+ */
+export function chaseBoomOffset(yaw, pitch, distance, height) {
+    const forward = forwardVector(yaw);
+    const cos = Math.cos(pitch);
+    const sin = Math.sin(pitch);
+    const along = -distance * cos - height * sin;
+    return { x: forward.x * along, y: -distance * sin + height * cos, z: forward.z * along };
+}
+/** Look point ahead of / above a chased vehicle, tilted by `pitch` like the boom.
+ * @internal
+ */
+export function chaseLookAt(follow, yaw, resolved, pitch = 0) {
+    const forward = forwardVector(yaw);
+    const cos = Math.cos(pitch);
+    const sin = Math.sin(pitch);
+    const along = 2 * cos - resolved.lookHeight * sin;
     return {
-        x: follow.x - back.x * resolved.distance,
-        y: follow.y + resolved.height,
-        z: follow.z - back.z * resolved.distance,
+        x: follow.x + forward.x * along,
+        y: follow.y + 2 * sin + resolved.lookHeight * cos,
+        z: follow.z + forward.z * along,
     };
 }
-/** Look point ahead of / above a chased vehicle.
+/** @internal */
+export function createChaseRigState() {
+    return { offset: null, anchorYaw: null, lastYaw: null, lastFollow: null, roll: 0, pitch: 0, fov: null, kick: 0, lookingBack: false };
+}
+/**
+ * One frame of the chase rig: speed from sim velocity, smoothed FOV plus decaying kicks, drift-lag
+ * anchor yaw, pitch follow, distance by speed, look-back, and a boom spring that eases the offset
+ * from the target rather than its world position, so the camera holds its distance at speed.
  * @internal
  */
-export function chaseLookAt(follow, yaw, resolved) {
-    const forward = forwardVector(yaw);
+export function stepChase(state, sample, resolved, dt, clampBoom) {
+    const { follow, yaw } = sample;
+    const last = state.lastFollow ?? follow;
+    const velocity = sample.velocity ?? (dt > 0 ? { x: (follow.x - last.x) / dt, y: 0, z: (follow.z - last.z) / dt } : { x: 0, y: 0, z: 0 });
+    state.lastFollow = follow;
+    const speed = Math.hypot(velocity.x, velocity.z);
+    const lastYaw = state.lastYaw ?? yaw;
+    state.lastYaw = yaw;
+    state.roll = bankRollStep(state.roll, yaw, lastYaw, dt, resolved);
+    const targetFov = speedToFov(speed, { base: resolved.fovBase, max: resolved.fovMax, speedForMax: resolved.fovSpeedForMax });
+    state.fov =
+        state.fov === null || !Number.isFinite(resolved.fovResponse)
+            ? targetFov
+            : state.fov + (targetFov - state.fov) * smoothBlend(dt, resolved.fovResponse);
+    state.kick = clamp(state.kick * Math.exp(-resolved.fovKickDecay * dt) + sample.fovKick, -resolved.fovKickMax, resolved.fovKickMax);
+    let targetYaw = yaw;
+    let response = resolved.yawResponse;
+    if (resolved.velocityYawBlend > 0) {
+        targetYaw = velocityYawTarget(yaw, velocity, resolved);
+        response = resolved.velocityYawResponse;
+    }
+    const anchorYaw = Number.isFinite(response)
+        ? smoothYaw(state.anchorYaw ?? targetYaw, targetYaw, response, dt)
+        : targetYaw;
+    state.anchorYaw = anchorYaw;
+    const pitchTarget = clamp(-sample.bodyPitch * resolved.pitchBlend, -resolved.pitchMax, resolved.pitchMax);
+    state.pitch =
+        resolved.pitchBlend <= 0 ? 0 : state.pitch + (pitchTarget - state.pitch) * smoothBlend(dt, resolved.pitchResponse);
+    const snap = state.offset === null || sample.lookBack !== state.lookingBack;
+    state.lookingBack = sample.lookBack;
+    const boomYaw = sample.lookBack ? anchorYaw + Math.PI : anchorYaw;
+    const boomPitch = sample.lookBack ? -state.pitch : state.pitch;
+    const extra = resolved.distanceSpeedForMax > 0 ? resolved.distanceExtra * clamp(speed / resolved.distanceSpeedForMax, 0, 1) : 0;
+    const led = sample.lookBack ? follow : leadFromVelocity(follow, velocity, resolved);
+    const desiredOffset = chaseBoomOffset(boomYaw, boomPitch, resolved.distance + extra, resolved.height);
+    let offset = snap || state.offset === null ? desiredOffset : springArmStep(state.offset, desiredOffset, resolved.springDamping, dt);
+    if (clampBoom !== undefined) {
+        const up = chaseLookAt(led, boomYaw, resolved, boomPitch);
+        const pivot = { x: led.x, y: up.y, z: led.z };
+        const wanted = { x: led.x + offset.x, y: led.y + offset.y, z: led.z + offset.z };
+        const allowed = clampBoom(pivot, wanted);
+        offset = { x: allowed.x - led.x, y: allowed.y - led.y, z: allowed.z - led.z };
+    }
+    state.offset = offset;
     return {
-        x: follow.x + forward.x * 2,
-        y: follow.y + resolved.lookHeight,
-        z: follow.z + forward.z * 2,
+        pose: {
+            position: { x: led.x + offset.x, y: led.y + offset.y, z: led.z + offset.z },
+            lookAt: chaseLookAt(led, boomYaw, resolved, boomPitch),
+            fov: state.fov + state.kick,
+        },
+        roll: sample.lookBack ? -state.roll : state.roll,
+        anchorYaw,
+        speed,
     };
 }
+/**
+ * Where a blocked boom should put the camera: `hitDistance` along the pivot→desired ray, less
+ * `radius`, but never nearer the pivot than `minDistance`. `null` hit returns `desired` unchanged.
+ * @internal
+ */
+export function clampBoomToHit(pivot, desired, hitDistance, radius, minDistance) {
+    if (hitDistance === null)
+        return desired;
+    const dx = desired.x - pivot.x;
+    const dy = desired.y - pivot.y;
+    const dz = desired.z - pivot.z;
+    const length = Math.hypot(dx, dy, dz);
+    if (length <= 1e-6)
+        return desired;
+    const allowed = clamp(hitDistance - radius, Math.min(minDistance, length), length);
+    const scale = allowed / length;
+    return { x: pivot.x + dx * scale, y: pivot.y + dy * scale, z: pivot.z + dz * scale };
+}
 /**
  * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
  * smoothing. When the target slides, its planar `velocity` diverges from its

package/dist/camera/rigResolve.d.ts

@@ -1,4 +1,7 @@
 import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playableGame";
+import type { CameraRigOverride } from "@jgengine/core/runtime/cameraDirector";
+/** @internal */
+export declare function resolveRuntimeCameraConfig(config: GameCameraConfig | undefined, override: CameraRigOverride | null | undefined): GameCameraConfig | undefined;
 /**
  * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
  * specific: an explicit `rig` field always wins; then `perspective: "first"`

package/dist/camera/rigResolve.js

@@ -1,3 +1,14 @@
+/** @internal */
+export function resolveRuntimeCameraConfig(config, override) {
+    if (override === null || override === undefined)
+        return config;
+    const merged = { ...config, ...override.config, rig: override.kind };
+    for (const key of ["firstPerson", "topDown", "rts", "shoulder", "lockOn", "chase", "observer", "turntable", "sideScroll", "inspection", "shake"]) {
+        if (override.config[key] !== undefined)
+            Object.assign(merged, { [key]: { ...config?.[key], ...override.config[key] } });
+    }
+    return merged;
+}
 /**
  * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
  * specific: an explicit `rig` field always wins; then `perspective: "first"`