@jgengine/shell 0.18.0 → 0.19.0

package/dist/audio/loopParams.js

@@ -26,3 +26,46 @@ export function clampLoopGain(gain) {
         return 0;
     return Math.min(1, Math.max(0, gain));
 }
+/** Lowest live filter cutoff, Hz. */
+export const MIN_LOOP_CUTOFF = 10;
+/** Highest live filter cutoff, Hz; the engine also caps it at the context's Nyquist frequency. */
+export const MAX_LOOP_CUTOFF = 22050;
+/**
+ * Clamp a loop filter cutoff into `MIN_LOOP_CUTOFF`–`min(MAX_LOOP_CUTOFF, nyquist)` Hz. Non-finite input
+ * falls back to `fallback` (the open, transparent end of that filter).
+ * @internal — the audio engine applies this; game code sets cutoffs through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopCutoff(hz, fallback, nyquist = MAX_LOOP_CUTOFF) {
+    const max = Math.min(MAX_LOOP_CUTOFF, nyquist);
+    if (!Number.isFinite(hz))
+        return Math.min(max, Math.max(MIN_LOOP_CUTOFF, fallback));
+    return Math.min(max, Math.max(MIN_LOOP_CUTOFF, hz));
+}
+/** @internal */
+export function createListenerVelocityTrack() {
+    return { last: null, velocity: { x: 0, y: 0, z: 0 } };
+}
+/** Camera jumps faster than this (world units/s) are cuts or teleports, not motion, and reset the estimate. */
+const MAX_LISTENER_SPEED = 400;
+/**
+ * Advance the listener velocity estimate by one frame: the position delta over `dt`, eased with a
+ * ~50 ms time constant so frame-time jitter does not warble doppler. A cut resets it to zero.
+ * @internal
+ */
+export function stepListenerVelocity(track, position, dt) {
+    const last = track.last;
+    track.last = { x: position.x, y: position.y, z: position.z };
+    if (last === null || !(dt > 0))
+        return track.velocity;
+    const vx = (position.x - last.x) / dt;
+    const vy = (position.y - last.y) / dt;
+    const vz = (position.z - last.z) / dt;
+    if (Math.hypot(vx, vy, vz) > MAX_LISTENER_SPEED) {
+        track.velocity = { x: 0, y: 0, z: 0 };
+        return track.velocity;
+    }
+    const blend = 1 - Math.exp(-dt / 0.05);
+    const v = track.velocity;
+    track.velocity = { x: v.x + (vx - v.x) * blend, y: v.y + (vy - v.y) * blend, z: v.z + (vz - v.z) * blend };
+    return track.velocity;
+}

package/dist/camera/GameCameraRig.js

@@ -37,7 +37,7 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
         const kind = resolveRigKind(config);
         switch (kind) {
             case "first":
-                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined, viewmodel: viewmodel }));
+                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined, viewmodel: viewmodel, weapon: config?.weapon }));
             case "topDown":
                 return _jsx(TopDownRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
             case "rts":

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -1,6 +1,6 @@
 import { type ComponentType, type MutableRefObject } from "react";
 import * as THREE from "three";
-import type { FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
+import type { CameraWeaponView, FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
 import type { EntityRenderCues } from "@jgengine/core/combat/renderCues";
 /** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
 export declare function readFirstPersonMuzzle(target: THREE.Vector3): boolean;
@@ -15,5 +15,7 @@ export interface GameFirstPersonCameraProps {
     followEntityId?: string;
     /** Custom viewmodel component replacing the built-in three-mesh gun, rendered inside the same camera-locked, muzzle-tracked anchor. Ignored when `config.viewmodel === false`. */
     viewmodel?: ComponentType<ViewmodelProps>;
+    /** Held-weapon source (`GameCameraConfig.weapon`): poses the viewmodel and adds recoil to the look. */
+    weapon?: (entityId: string) => CameraWeaponView | null;
 }
-export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;
+export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, weapon, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;

package/dist/camera/GameFirstPersonCamera.js

@@ -1,18 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { DEFAULT_EYE_HEIGHT } from "@jgengine/core/combat/shotOrigin";
+import { createWeaponPresentation, viewmodelFovScale, } from "@jgengine/core/combat/weaponPresentation";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useEntityRenderCues } from "../render/useEntityRenderCues.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
+import { requestRawPointerLock } from "../input/pointerLock.js";
 const DEFAULT_SENSITIVITY = 0.0025;
 const DEFAULT_MAX_PITCH = 1.45;
 const VIEWMODEL_ORIGIN = new THREE.Vector3(0.34, -0.26, -0.72);
 const MUZZLE_TIP_LOCAL = new THREE.Vector3(0, 0.03, -0.61);
-const MUZZLE_OFFSET = VIEWMODEL_ORIGIN.clone().add(MUZZLE_TIP_LOCAL);
 const muzzleWorld = new THREE.Vector3();
 let muzzleTracked = false;
 /** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
@@ -22,7 +23,7 @@ export function readFirstPersonMuzzle(target) {
     target.copy(muzzleWorld);
     return true;
 }
-export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }) {
+export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, weapon, }) {
     const eyeHeight = config?.eyeHeight ?? DEFAULT_EYE_HEIGHT;
     const sensitivity = config?.sensitivity ?? DEFAULT_SENSITIVITY;
     const maxPitch = config?.maxPitch ?? DEFAULT_MAX_PITCH;
@@ -34,12 +35,16 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     const followId = followEntityId ?? userId;
     const seededRef = useRef(false);
     const cuesRef = useEntityRenderCues(followId);
+    const presentation = useMemo(() => createWeaponPresentation(), []);
+    const tuningRef = useRef(undefined);
+    const lastLookRef = useRef(null);
+    const poseRef = useRef(null);
     useEffect(() => {
         const requestLock = () => {
             if (window.matchMedia?.("(pointer: coarse)").matches)
                 return;
             if (document.pointerLockElement !== domElement)
-                void domElement.requestPointerLock?.();
+                requestRawPointerLock(domElement);
         };
         const onMove = (event) => {
             if (document.pointerLockElement !== domElement)
@@ -54,7 +59,7 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
             window.removeEventListener("mousemove", onMove);
         };
     }, [domElement, sensitivity, maxPitch, yawRef, pitchRef]);
-    useFrame(() => {
+    useFrame((_, dt) => {
         const entity = ctx.scene.entity.get(followId);
         if (entity === null)
             return;
@@ -62,22 +67,45 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
             seededRef.current = true;
             yawRef.current = entity.rotationY;
         }
-        const cosPitch = Math.cos(pitchRef.current);
+        const view = weapon?.(followId) ?? null;
+        const last = (lastLookRef.current ??= { yaw: yawRef.current, pitch: pitchRef.current });
+        const step = Math.max(1e-4, dt);
+        let pose = null;
+        if (view !== null) {
+            if (view.presentation !== tuningRef.current) {
+                tuningRef.current = view.presentation;
+                presentation.retune(view.presentation ?? {});
+            }
+            pose = presentation.update(dt, {
+                lookYawRate: (yawRef.current - last.yaw) / step,
+                lookPitchRate: (pitchRef.current - last.pitch) / step,
+                speed: cuesRef.current.speed,
+                bobPhase: cuesRef.current.bobPhase,
+                handling: view.handling,
+            });
+        }
+        last.yaw = yawRef.current;
+        last.pitch = pitchRef.current;
+        poseRef.current = pose;
+        const yaw = yawRef.current - (pose?.lookYaw ?? 0);
+        const pitch = Math.max(-maxPitch, Math.min(maxPitch, pitchRef.current + (pose?.lookPitch ?? 0)));
+        const cosPitch = Math.cos(pitch);
         camera.position.set(entity.position[0], entity.position[1] + eyeHeight, entity.position[2]);
-        camera.lookAt(camera.position.x + Math.sin(yawRef.current) * cosPitch, camera.position.y + Math.sin(pitchRef.current), camera.position.z + Math.cos(yawRef.current) * cosPitch);
+        camera.lookAt(camera.position.x + Math.sin(yaw) * cosPitch, camera.position.y + Math.sin(pitch), camera.position.z + Math.cos(yaw) * cosPitch);
         if (camera.isPerspectiveCamera === true) {
             const perspective = camera;
-            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
-                perspective.fov = playerFov.fov;
+            const fov = playerFov.fov * (pose?.fovScale ?? 1);
+            if (Math.abs(perspective.fov - fov) > 0.001) {
+                perspective.fov = fov;
                 perspective.updateProjectionMatrix();
             }
         }
     }, ORBIT_CAMERA_FRAME_PRIORITY);
     if (config?.viewmodel === false)
         return null;
-    return _jsx(FirstPersonViewmodel, { camera: camera, viewmodel: viewmodel, cuesRef: cuesRef });
+    return _jsx(FirstPersonViewmodel, { camera: camera, viewmodel: viewmodel, cuesRef: cuesRef, poseRef: poseRef });
 }
-function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, }) {
+function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, poseRef, }) {
     const groupRef = useRef(null);
     useEffect(() => () => {
         muzzleTracked = false;
@@ -86,12 +114,21 @@ function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, }) {
         const group = groupRef.current;
         if (group === null)
             return;
+        const pose = poseRef.current;
+        const perspective = camera;
+        // Scaling camera-space x/y by this projects the viewmodel at its own FOV without a second render pass.
+        const squash = pose?.viewmodelFov == null || perspective.isPerspectiveCamera !== true ? 1 : viewmodelFovScale(perspective.fov, pose.viewmodelFov);
         group.position.copy(camera.position);
         group.quaternion.copy(camera.quaternion);
-        group.translateX(VIEWMODEL_ORIGIN.x);
-        group.translateY(VIEWMODEL_ORIGIN.y);
-        group.translateZ(VIEWMODEL_ORIGIN.z);
-        muzzleWorld.copy(MUZZLE_OFFSET).applyQuaternion(camera.quaternion).add(camera.position);
+        group.translateX((pose?.offset[0] ?? VIEWMODEL_ORIGIN.x) * squash);
+        group.translateY((pose?.offset[1] ?? VIEWMODEL_ORIGIN.y) * squash);
+        group.translateZ(pose?.offset[2] ?? VIEWMODEL_ORIGIN.z);
+        group.rotateX(pose?.pitch ?? 0);
+        group.rotateY(pose?.yaw ?? 0);
+        group.rotateZ(pose?.roll ?? 0);
+        group.scale.set(squash, squash, 1);
+        group.updateMatrixWorld();
+        group.localToWorld(muzzleWorld.copy(MUZZLE_TIP_LOCAL));
         muzzleTracked = true;
     }, GAME_SIM_FRAME_PRIORITY);
     if (Viewmodel !== undefined) {

package/dist/camera/Viewports.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+import { type ViewportDef, type ViewportsConfig } from "@jgengine/core/game/viewports";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import { type LocalPlayerSlot } from "@jgengine/core/runtime/localPlayers";
+/** Camera yaw the split-screen renderer last used for a seat's user, so the walk controller moves that seat camera-relative. @internal */
+export declare function seatCameraYaw(ctx: GameContext, userId: string): number | undefined;
+/**
+ * The viewports for the seats currently joined, re-resolved when a seat joins or leaves.
+ * @internal
+ */
+export declare function useSeatViewports(ctx: GameContext, config: ViewportsConfig | undefined): readonly ViewportDef[];
+/**
+ * Draws one scissored render per viewport. The primary seat keeps the main camera and its rig; every
+ * other seat gets a follow camera (chase or top-down) on its possessed entity. Mounted only while more
+ * than one viewport is drawn, since a render-priority frame callback takes over R3F's own render.
+ * @internal
+ */
+export declare function SplitScreenRenderer({ ctx, viewports, config, mainCamera, }: {
+    ctx: GameContext;
+    viewports: readonly ViewportDef[];
+    config: ViewportsConfig | undefined;
+    mainCamera: GameCameraConfig | undefined;
+}): null;
+/**
+ * One absolutely-positioned HUD root per viewport, laid over the canvas: render each seat's own
+ * health, prompts or score with `children(slot)`. Pass the same `viewports` config the game gave `defineGame`.
+ * @capability split-screen-hud Per-seat HUD roots positioned over each split-screen viewport.
+ */
+export declare function ViewportHuds({ ctx, config, children, }: {
+    ctx: GameContext;
+    config?: ViewportsConfig;
+    children: (slot: LocalPlayerSlot, viewport: ViewportDef) => ReactNode;
+}): import("react").JSX.Element;

package/dist/camera/Viewports.js

@@ -0,0 +1,123 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useMemo, useRef, useSyncExternalStore } from "react";
+import * as THREE from "three";
+import { resolveViewports, viewportPixels, } from "@jgengine/core/game/viewports";
+import { localPlayers } from "@jgengine/core/runtime/localPlayers";
+import { createChaseRigState, resolveChase, resolveTopDown, stepChase, topDownPose } from "./rigMath.js";
+const SEAT_YAW = new WeakMap();
+/** Camera yaw the split-screen renderer last used for a seat's user, so the walk controller moves that seat camera-relative. @internal */
+export function seatCameraYaw(ctx, userId) {
+    return SEAT_YAW.get(ctx)?.get(userId);
+}
+function seatSlotIds(ctx) {
+    return localPlayers(ctx).slots().map((slot) => slot.slotId);
+}
+/**
+ * The viewports for the seats currently joined, re-resolved when a seat joins or leaves.
+ * @internal
+ */
+export function useSeatViewports(ctx, config) {
+    const seats = localPlayers(ctx);
+    const key = useSyncExternalStore(seats.subscribe, () => seatSlotIds(ctx).join("|"), () => seatSlotIds(ctx).join("|"));
+    return useMemo(() => resolveViewports(config, key === "" ? [] : key.split("|")), [config, key]);
+}
+function seatRigKind(camera, main) {
+    return camera?.rig ?? (main?.rig === "topDown" ? "topDown" : "chase");
+}
+/**
+ * Draws one scissored render per viewport. The primary seat keeps the main camera and its rig; every
+ * other seat gets a follow camera (chase or top-down) on its possessed entity. Mounted only while more
+ * than one viewport is drawn, since a render-priority frame callback takes over R3F's own render.
+ * @internal
+ */
+export function SplitScreenRenderer({ ctx, viewports, config, mainCamera, }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    const camera = useThree((state) => state.camera);
+    const size = useThree((state) => state.size);
+    const rigs = useRef(new Map());
+    useFrame((_state, dt) => {
+        const seats = localPlayers(ctx);
+        let yaws = SEAT_YAW.get(ctx);
+        if (yaws === undefined) {
+            yaws = new Map();
+            SEAT_YAW.set(ctx, yaws);
+        }
+        gl.setScissorTest(true);
+        for (const def of viewports) {
+            const slot = seats.slot(def.slot);
+            if (slot === null)
+                continue;
+            const pixels = viewportPixels(def.rect, size.width, size.height);
+            const view = slot.index === 0 ? camera : seatCamera(slot, def.camera ?? config?.camera, dt, yaws);
+            if (view instanceof THREE.PerspectiveCamera) {
+                view.aspect = pixels.width / pixels.height;
+                view.updateProjectionMatrix();
+            }
+            gl.setViewport(pixels.x, pixels.y, pixels.width, pixels.height);
+            gl.setScissor(pixels.x, pixels.y, pixels.width, pixels.height);
+            gl.render(scene, view);
+        }
+        gl.setScissorTest(false);
+        gl.setViewport(0, 0, size.width, size.height);
+        if (camera instanceof THREE.PerspectiveCamera) {
+            camera.aspect = size.width / size.height;
+            camera.updateProjectionMatrix();
+        }
+    }, 1);
+    function seatCamera(slot, cameraConfig, dt, yaws) {
+        let rig = rigs.current.get(slot.slotId);
+        if (rig === undefined) {
+            const created = new THREE.PerspectiveCamera();
+            if (camera instanceof THREE.PerspectiveCamera) {
+                created.near = camera.near;
+                created.far = camera.far;
+            }
+            rig = { camera: created, chase: createChaseRigState() };
+            rigs.current.set(slot.slotId, rig);
+        }
+        const entity = ctx.scene.entity.get(ctx.player.possession.active(slot.userId));
+        const follow = entity === null ? { x: 0, y: 0, z: 0 } : { x: entity.position[0], y: entity.position[1], z: entity.position[2] };
+        let pose;
+        if (seatRigKind(cameraConfig, mainCamera) === "topDown") {
+            const resolved = resolveTopDown(cameraConfig?.topDown ?? mainCamera?.topDown);
+            pose = topDownPose(follow, resolved, rig.camera.fov);
+            yaws.set(slot.userId, resolved.yaw);
+        }
+        else {
+            const velocity = entity?.velocity;
+            const step = stepChase(rig.chase, {
+                follow,
+                yaw: entity?.rotationY ?? 0,
+                bodyPitch: entity?.rotationX ?? 0,
+                velocity: velocity === undefined ? null : { x: velocity[0], y: velocity[1], z: velocity[2] },
+                lookBack: false,
+                fovKick: 0,
+            }, resolveChase(cameraConfig?.chase ?? mainCamera?.chase), dt);
+            pose = step.pose;
+            yaws.set(slot.userId, step.anchorYaw);
+        }
+        rig.camera.position.set(pose.position.x, pose.position.y, pose.position.z);
+        rig.camera.fov = pose.fov;
+        rig.camera.lookAt(pose.lookAt.x, pose.lookAt.y, pose.lookAt.z);
+        return rig.camera;
+    }
+    return null;
+}
+/**
+ * One absolutely-positioned HUD root per viewport, laid over the canvas: render each seat's own
+ * health, prompts or score with `children(slot)`. Pass the same `viewports` config the game gave `defineGame`.
+ * @capability split-screen-hud Per-seat HUD roots positioned over each split-screen viewport.
+ */
+export function ViewportHuds({ ctx, config, children, }) {
+    const viewports = useSeatViewports(ctx, config);
+    const seats = localPlayers(ctx);
+    return (_jsx(_Fragment, { children: viewports.map((viewport) => {
+            const slot = seats.slot(viewport.slot);
+            if (slot === null)
+                return null;
+            const [x, y, width, height] = viewport.rect;
+            return (_jsx("div", { "data-jg-viewport": viewport.slot, className: "pointer-events-none absolute overflow-hidden", style: { left: `${x * 100}%`, top: `${y * 100}%`, width: `${width * 100}%`, height: `${height * 100}%` }, children: children(slot, viewport) }, viewport.slot));
+        }) }));
+}

package/dist/camera/cameraRigs.js

@@ -1,13 +1,15 @@
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import { PerspectiveCamera, Quaternion, Vector3 } from "three";
+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";
 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;
@@ -162,6 +164,12 @@ export function SideScrollRig(props) {
         };
         followRef.current = follow;
         const pose = resolveSideScrollPose(follow, resolved, config?.fov ?? currentFov(camera));
+        const pixelPerfect = props.config?.projection === "orthographic" ? props.config.pixelPerfect : undefined;
+        if (pixelPerfect !== undefined) {
+            const snapped = snapPixelPerfectPosition(pose.position, pixelPerfect.pixelsPerUnit);
+            pose.position = snapped;
+            pose.lookAt = snapPixelPerfectPosition(pose.lookAt, pixelPerfect.pixelsPerUnit);
+        }
         commit(pose, dt);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
@@ -299,7 +307,7 @@ export function ShoulderRig(props) {
     useEffect(() => {
         const requestLock = () => {
             if (document.pointerLockElement !== domElement)
-                void domElement.requestPointerLock?.();
+                requestRawPointerLock(domElement);
         };
         const onMove = (event) => {
             if (document.pointerLockElement !== domElement)
@@ -338,8 +346,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 = {
@@ -348,7 +361,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;
@@ -417,73 +434,71 @@ 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);
     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] };
+        const yaw = entity?.rotationY ?? 0;
+        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 = step.anchorYaw;
         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/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,