@jgengine/shell 0.8.0 → 0.9.0

package/dist/GameUiPreview.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { createGameContext } from "@jgengine/core/runtime/gameContext";
 import { GameProvider } from "@jgengine/react/provider";
+import { HudViewportProvider } from "@jgengine/react/hudViewport";
 const PREVIEW_USER_ID = "ui-preview";
 const TICK_STEP = 1 / 60;
 function runTicks(ctx, playable, seconds) {
@@ -59,5 +60,5 @@ export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
     if (ctx === null)
         return _jsx("div", { className: "h-full w-full bg-neutral-900" });
     const GameUI = playable.GameUI;
-    return (_jsx("div", { "data-ui-preview-ready": true, className: "relative h-full w-full overflow-hidden", style: { background: "linear-gradient(180deg, #2a3d33 0%, #1a2320 55%, #141b18 100%)" }, children: _jsx(GameProvider, { context: ctx, children: _jsx(GameUI, {}) }) }));
+    return (_jsx("div", { "data-ui-preview-ready": true, className: "relative h-full w-full overflow-hidden", style: { background: "linear-gradient(180deg, #2a3d33 0%, #1a2320 55%, #141b18 100%)" }, children: _jsx(GameProvider, { context: ctx, children: _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, children: _jsx(GameUI, {}) }) }) }));
 }

package/dist/audio/AudioComponents.js

@@ -1,6 +1,6 @@
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
-import { useSceneEntities, useSceneObjects } from "@jgengine/react/hooks";
+import { useGameContext } from "@jgengine/react/provider";
 export function AudioListener({ engine }) {
     const camera = useThree((state) => state.camera);
     useFrame(() => {
@@ -8,18 +8,20 @@ export function AudioListener({ engine }) {
     });
     return null;
 }
-function useTrackedEmitters(engine, soundByKey, entries) {
+function useTrackedEmitters(engine, soundByKey, readEntries) {
     const handles = useRef(new Map());
+    const lastPose = useRef(new Map());
     useEffect(() => () => {
         for (const handle of handles.current.values())
             handle.stop();
         handles.current.clear();
+        lastPose.current.clear();
     }, [engine]);
     useFrame(() => {
         if (soundByKey === undefined)
             return;
         const live = new Set();
-        for (const entry of entries) {
+        for (const entry of readEntries()) {
             const soundId = soundByKey[entry.key];
             if (soundId === undefined)
                 continue;
@@ -27,27 +29,42 @@ function useTrackedEmitters(engine, soundByKey, entries) {
             let handle = handles.current.get(entry.id);
             if (handle === undefined) {
                 handle = engine.playLoop(soundId, { x: entry.position[0], y: entry.position[1], z: entry.position[2] }) ?? undefined;
-                if (handle !== undefined)
+                if (handle !== undefined) {
                     handles.current.set(entry.id, handle);
+                    lastPose.current.set(entry.id, entry.position);
+                }
+                continue;
+            }
+            const prev = lastPose.current.get(entry.id);
+            if (prev !== undefined &&
+                prev[0] === entry.position[0] &&
+                prev[1] === entry.position[1] &&
+                prev[2] === entry.position[2]) {
                 continue;
             }
             handle.setPosition({ x: entry.position[0], y: entry.position[1], z: entry.position[2] });
+            lastPose.current.set(entry.id, entry.position);
         }
         for (const [id, handle] of handles.current) {
             if (!live.has(id)) {
                 handle.stop();
                 handles.current.delete(id);
+                lastPose.current.delete(id);
             }
         }
     });
 }
 export function EntityAudioEmitters({ engine, entitySounds, }) {
-    const entities = useSceneEntities();
-    useTrackedEmitters(engine, entitySounds, entities.map((entity) => ({ id: entity.id, key: entity.name, position: entity.position })));
+    const ctx = useGameContext();
+    useTrackedEmitters(engine, entitySounds, () => ctx.scene.entity.list().map((entity) => ({ id: entity.id, key: entity.name, position: entity.position })));
     return null;
 }
 export function ObjectAudioEmitters({ engine, objectSounds, }) {
-    const objects = useSceneObjects();
-    useTrackedEmitters(engine, objectSounds, objects.map((object) => ({ id: object.instanceId, key: object.catalogId, position: object.position })));
+    const ctx = useGameContext();
+    useTrackedEmitters(engine, objectSounds, () => ctx.scene.object.list().map((object) => ({
+        id: object.instanceId,
+        key: object.catalogId,
+        position: object.position,
+    })));
     return null;
 }

package/dist/audio/audioEngine.d.ts

@@ -17,6 +17,7 @@ export interface AudioEngine {
     playOneShot(soundId: string, position?: Vec3): void;
     playLoop(soundId: string, position?: Vec3): AudioEmitterHandle | null;
     setBusGain(busId: string, gain: number): void;
+    setMasterGain(gain: number): void;
     resume(): void;
     dispose(): void;
 }

package/dist/audio/audioEngine.js

@@ -5,6 +5,7 @@ function createNoopEngine() {
         playOneShot: () => undefined,
         playLoop: () => null,
         setBusGain: () => undefined,
+        setMasterGain: () => undefined,
         resume: () => undefined,
         dispose: () => undefined,
     };
@@ -100,6 +101,9 @@ export function createAudioEngine(config = {}) {
         setBusGain(busId, gain) {
             busGainNode(busId).gain.value = gain;
         },
+        setMasterGain(gain) {
+            masterGain.gain.value = gain;
+        },
         resume() {
             void context.resume().catch(() => undefined);
         },

package/dist/behaviour.d.ts

@@ -1,29 +1,10 @@
-import type { Object3D } from "three";
-import { Behaviour, type BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
-/**
- * A core `Behaviour` bound to a three.js object. `onBeforeRender`/`onAfterRender`
- * ride the object's own three.js render callbacks, so they only fire for renderable
- * objects (Mesh, Line, Points, Sprite) that are visible and in frustum — attach to
- * the mesh itself, not a parent Group, when you need them.
- */
-export declare class Object3DBehaviour extends Behaviour {
-    /** @internal */ _object: Object3D | null;
-    /** The bound three.js object; available from `onAwake` onward. */
-    get object(): Object3D;
-    onBeforeRender(): void;
-    onAfterRender(): void;
-}
-/**
- * Binds `behaviour` to `object` and attaches it to `world` under `nodeId`
- * (default: the object's uuid). Render hooks are chained onto the object's
- * existing `onBeforeRender`/`onAfterRender` only when actually overridden, and
- * are gated on the behaviour being active; the update lifecycle still flows
- * through `world.update`.
- */
-export declare function attachObject3D<T extends Object3DBehaviour>(world: BehaviourWorld, object: Object3D, behaviour: T, nodeId?: string): T;
+import type { BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+export { createBehaviourWorldDriver } from "./behaviourDriver.js";
+export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
 /**
  * Bootstraps `world` on mount and dispatches `world.update` every frame at
- * simulation priority. `scaleDt` maps the raw frame delta to the dt behaviours
+ * simulation priority. Stops driving updates on unmount so remount does not
+ * double-step. `scaleDt` maps the raw frame delta to the dt behaviours
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.

package/dist/behaviour.js

@@ -1,63 +1,27 @@
 import { useFrame } from "@react-three/fiber";
-import { useEffect } from "react";
-import { Behaviour } from "@jgengine/core/behaviour/behaviour";
-/**
- * A core `Behaviour` bound to a three.js object. `onBeforeRender`/`onAfterRender`
- * ride the object's own three.js render callbacks, so they only fire for renderable
- * objects (Mesh, Line, Points, Sprite) that are visible and in frustum — attach to
- * the mesh itself, not a parent Group, when you need them.
- */
-export class Object3DBehaviour extends Behaviour {
-    /** @internal */ _object = null;
-    /** The bound three.js object; available from `onAwake` onward. */
-    get object() {
-        if (this._object === null)
-            throw new Error("behaviour is not bound to an Object3D");
-        return this._object;
-    }
-    onBeforeRender() { }
-    onAfterRender() { }
-}
-/**
- * Binds `behaviour` to `object` and attaches it to `world` under `nodeId`
- * (default: the object's uuid). Render hooks are chained onto the object's
- * existing `onBeforeRender`/`onAfterRender` only when actually overridden, and
- * are gated on the behaviour being active; the update lifecycle still flows
- * through `world.update`.
- */
-export function attachObject3D(world, object, behaviour, nodeId = object.uuid) {
-    behaviour._object = object;
-    world.attach(nodeId, behaviour);
-    if (behaviour.onBeforeRender !== Object3DBehaviour.prototype.onBeforeRender) {
-        const previous = object.onBeforeRender;
-        object.onBeforeRender = function chainedBeforeRender(...args) {
-            previous.apply(this, args);
-            if (behaviour.isActive)
-                behaviour.onBeforeRender();
-        };
-    }
-    if (behaviour.onAfterRender !== Object3DBehaviour.prototype.onAfterRender) {
-        const previous = object.onAfterRender;
-        object.onAfterRender = function chainedAfterRender(...args) {
-            previous.apply(this, args);
-            if (behaviour.isActive)
-                behaviour.onAfterRender();
-        };
-    }
-    return behaviour;
-}
+import { useEffect, useRef } from "react";
+import { createBehaviourWorldDriver } from "./behaviourDriver.js";
+export { createBehaviourWorldDriver } from "./behaviourDriver.js";
+export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
 /**
  * Bootstraps `world` on mount and dispatches `world.update` every frame at
- * simulation priority. `scaleDt` maps the raw frame delta to the dt behaviours
+ * simulation priority. Stops driving updates on unmount so remount does not
+ * double-step. `scaleDt` maps the raw frame delta to the dt behaviours
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.
  */
 export function useBehaviourWorld(world, scaleDt) {
+    const driverRef = useRef(createBehaviourWorldDriver(world));
     useEffect(() => {
-        world.start();
+        const driver = createBehaviourWorldDriver(world);
+        driverRef.current = driver;
+        driver.start();
+        return () => {
+            driver.stop();
+        };
     }, [world]);
     useFrame((_state, rawDt) => {
-        world.update(scaleDt === undefined ? rawDt : scaleDt(rawDt));
+        driverRef.current.step(scaleDt === undefined ? rawDt : scaleDt(rawDt));
     });
 }

package/dist/behaviourAttach.d.ts

@@ -0,0 +1,9 @@
+import type { Object3D } from "three";
+import { Behaviour, type BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+export declare class Object3DBehaviour extends Behaviour {
+    /** @internal */ _object: Object3D | null;
+    get object(): Object3D;
+    onBeforeRender(): void;
+    onAfterRender(): void;
+}
+export declare function attachObject3D<T extends Object3DBehaviour>(world: BehaviourWorld, object: Object3D, behaviour: T, nodeId?: string): T;

package/dist/behaviourAttach.js

@@ -0,0 +1,32 @@
+import { Behaviour } from "@jgengine/core/behaviour/behaviour";
+export class Object3DBehaviour extends Behaviour {
+    /** @internal */ _object = null;
+    get object() {
+        if (this._object === null)
+            throw new Error("behaviour is not bound to an Object3D");
+        return this._object;
+    }
+    onBeforeRender() { }
+    onAfterRender() { }
+}
+export function attachObject3D(world, object, behaviour, nodeId = object.uuid) {
+    behaviour._object = object;
+    world.attach(nodeId, behaviour);
+    if (behaviour.onBeforeRender !== Object3DBehaviour.prototype.onBeforeRender) {
+        const previous = object.onBeforeRender;
+        object.onBeforeRender = function chainedBeforeRender(...args) {
+            previous.apply(this, args);
+            if (behaviour.isActive)
+                behaviour.onBeforeRender();
+        };
+    }
+    if (behaviour.onAfterRender !== Object3DBehaviour.prototype.onAfterRender) {
+        const previous = object.onAfterRender;
+        object.onAfterRender = function chainedAfterRender(...args) {
+            previous.apply(this, args);
+            if (behaviour.isActive)
+                behaviour.onAfterRender();
+        };
+    }
+    return behaviour;
+}

package/dist/behaviourDriver.d.ts

@@ -0,0 +1,7 @@
+import type { BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+export declare function createBehaviourWorldDriver(world: BehaviourWorld): {
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    step(dt: number): void;
+};

package/dist/behaviourDriver.js

@@ -0,0 +1,21 @@
+export function createBehaviourWorldDriver(world) {
+    let running = false;
+    return {
+        start() {
+            if (!world.started())
+                world.start();
+            running = true;
+        },
+        stop() {
+            running = false;
+        },
+        isRunning() {
+            return running;
+        },
+        step(dt) {
+            if (!running)
+                return;
+            world.update(dt);
+        },
+    };
+}

package/dist/camera/GameCameraRig.js

@@ -22,7 +22,7 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
     const followEntityId = directed.followEntityId;
     const rig = (() => {
         if (directed.cinematic !== undefined) {
-            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId }));
+            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true }));
         }
         const kind = resolveRigKind(config);
         switch (kind) {

package/dist/camera/GameFirstPersonCamera.js

@@ -4,6 +4,7 @@ import { useEffect, useRef } from "react";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
+import { usePlayerFov } from "./PlayerFov.js";
 import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
 const DEFAULT_EYE_HEIGHT = 1.6;
 const DEFAULT_SENSITIVITY = 0.0025;
@@ -14,9 +15,11 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     const maxPitch = config?.maxPitch ?? DEFAULT_MAX_PITCH;
     const { userId } = usePlayer();
     const ctx = useGameContext();
+    const playerFov = usePlayerFov();
     const camera = useThree((state) => state.camera);
     const domElement = useThree((state) => state.gl.domElement);
     const followId = followEntityId ?? userId;
+    const seededRef = useRef(false);
     useEffect(() => {
         const requestLock = () => {
             if (window.matchMedia?.("(pointer: coarse)").matches)
@@ -41,9 +44,20 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
         const entity = ctx.scene.entity.get(followId);
         if (entity === null)
             return;
+        if (!seededRef.current) {
+            seededRef.current = true;
+            yawRef.current = entity.rotationY;
+        }
         const cosPitch = Math.cos(pitchRef.current);
         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);
+        if (camera.isPerspectiveCamera === true) {
+            const perspective = camera;
+            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
+                perspective.fov = playerFov.fov;
+                perspective.updateProjectionMatrix();
+            }
+        }
     }, ORBIT_CAMERA_FRAME_PRIORITY);
     if (config?.viewmodel === false)
         return null;

package/dist/camera/GameOrbitCamera.js

@@ -2,10 +2,11 @@ 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, Vector3 } from "three";
+import { MOUSE, PerspectiveCamera, 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 { usePlayerFov } from "./PlayerFov.js";
 export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followEntityId, resolveFollowTarget, onDragChange, onCameraFollow, pointerControls = false, }) {
     const config = resolveOrbitCameraConfig(configPatch);
     const controlsRef = useRef(null);
@@ -13,6 +14,7 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
     const draggingRef = useRef(false);
     const { userId } = usePlayer();
     const ctx = useGameContext();
+    const playerFov = usePlayerFov();
     const camera = useThree((state) => state.camera);
     const followId = followEntityId ?? userId;
     useEffect(() => {
@@ -64,6 +66,13 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
         if (pitchRef !== undefined) {
             pitchRef.current = cameraLookPitch({ x: camera.position.x, y: camera.position.y, z: camera.position.z }, stepped.target);
         }
+        if (camera.isPerspectiveCamera === true) {
+            const perspective = camera;
+            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
+                perspective.fov = playerFov.fov;
+                perspective.updateProjectionMatrix();
+            }
+        }
         onCameraFollow?.({
             entityId: followId,
             target: stepped.target,

package/dist/camera/PlayerFov.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+import { type PlayerFovBounds } from "./fovPreference.js";
+export interface PlayerFovState {
+    fov: number;
+    bounds: PlayerFovBounds;
+    enabled: boolean;
+    persist: boolean;
+    setFov: (value: number) => void;
+    compose: (poseFov: number, mode?: "relative" | "absolute") => number;
+}
+export declare function PlayerFovProvider({ config, orthographic, children, }: {
+    config?: GameCameraConfig;
+    orthographic: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function usePlayerFov(): PlayerFovState;
+export declare function PlayerFovSlider(): import("react").JSX.Element | null;

package/dist/camera/PlayerFov.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useState, } from "react";
+import { composePlayerFov, loadPlayerFov, resolvePlayerFovBounds, savePlayerFov, } from "./fovPreference.js";
+const PlayerFovContext = createContext(null);
+export function PlayerFovProvider({ config, orthographic, children, }) {
+    const bounds = useMemo(() => resolvePlayerFovBounds({
+        min: config?.playerFov?.min,
+        max: config?.playerFov?.max,
+        default: config?.playerFov?.default ?? config?.frustum?.fov,
+    }), [config?.playerFov?.min, config?.playerFov?.max, config?.playerFov?.default, config?.frustum?.fov]);
+    const persist = config?.playerFov?.persist !== false;
+    const showControl = !orthographic && config?.playerFov?.control !== false;
+    const [fov, setFovState] = useState(() => persist ? loadPlayerFov(bounds) : bounds.defaultFov);
+    const setFov = useCallback((value) => {
+        setFovState(persist ? savePlayerFov(value, bounds) : savePlayerFov(value, bounds, null));
+    }, [bounds, persist]);
+    const compose = useCallback((poseFov, mode = "relative") => orthographic ? poseFov : composePlayerFov(fov, poseFov, mode, bounds), [bounds, fov, orthographic]);
+    const value = useMemo(() => ({
+        fov,
+        bounds,
+        enabled: showControl,
+        persist,
+        setFov,
+        compose,
+    }), [bounds, compose, fov, persist, setFov, showControl]);
+    return _jsx(PlayerFovContext.Provider, { value: value, children: children });
+}
+export function usePlayerFov() {
+    const value = useContext(PlayerFovContext);
+    if (value === null) {
+        const bounds = resolvePlayerFovBounds();
+        return {
+            fov: bounds.defaultFov,
+            bounds,
+            enabled: false,
+            persist: false,
+            setFov: () => undefined,
+            compose: (poseFov) => poseFov,
+        };
+    }
+    return value;
+}
+export function PlayerFovSlider() {
+    const { fov, setFov, bounds, enabled } = usePlayerFov();
+    if (!enabled)
+        return null;
+    return (_jsxs("label", { className: "pointer-events-auto absolute bottom-3 right-3 z-20 flex items-center gap-2 rounded-md bg-neutral-950/75 px-2.5 py-1.5 text-[11px] font-medium tracking-wide text-neutral-200 shadow-lg ring-1 ring-white/10 backdrop-blur-sm", children: [_jsx("span", { className: "text-neutral-400", children: "FOV" }), _jsx("input", { type: "range", min: bounds.min, max: bounds.max, step: 1, value: fov, "aria-label": "Field of view", className: "h-1 w-24 cursor-pointer accent-emerald-400", onChange: (event) => setFov(Number(event.target.value)) }), _jsx("span", { className: "w-7 tabular-nums text-neutral-100", children: Math.round(fov) })] }));
+}

package/dist/camera/cameraBlendMath.d.ts

@@ -0,0 +1,13 @@
+import type { Camera, Quaternion, Vector3 } from "three";
+export interface CameraBlendScratch {
+    fromPos: Vector3;
+    fromQuat: Quaternion;
+    toPos: Vector3;
+    toQuat: Quaternion;
+    fov: number;
+    elapsed: number;
+    duration: number;
+}
+export declare function createCameraBlendScratch(Vector3Ctor: new () => Vector3, QuaternionCtor: new () => Quaternion): CameraBlendScratch;
+export declare function captureCameraBlendFrom(scratch: CameraBlendScratch, position: Vector3, quaternion: Quaternion, fov: number, duration: number): void;
+export declare function applyCameraBlendStep(scratch: CameraBlendScratch, camera: Camera, targetFov: number, dt: number): boolean;

package/dist/camera/cameraBlendMath.js

@@ -0,0 +1,36 @@
+import { smoothstep } from "./rigMath.js";
+export function createCameraBlendScratch(Vector3Ctor, QuaternionCtor) {
+    return {
+        fromPos: new Vector3Ctor(),
+        fromQuat: new QuaternionCtor(),
+        toPos: new Vector3Ctor(),
+        toQuat: new QuaternionCtor(),
+        fov: 55,
+        elapsed: 0,
+        duration: 0,
+    };
+}
+export function captureCameraBlendFrom(scratch, position, quaternion, fov, duration) {
+    scratch.fromPos.copy(position);
+    scratch.fromQuat.copy(quaternion);
+    scratch.fov = fov;
+    scratch.elapsed = 0;
+    scratch.duration = duration;
+}
+function isPerspective(camera) {
+    return camera.isPerspectiveCamera === true;
+}
+export function applyCameraBlendStep(scratch, camera, targetFov, dt) {
+    scratch.elapsed += dt;
+    const t = scratch.duration <= 0 ? 1 : Math.min(scratch.elapsed / scratch.duration, 1);
+    const eased = smoothstep(t);
+    scratch.toPos.copy(camera.position);
+    scratch.toQuat.copy(camera.quaternion);
+    camera.position.lerpVectors(scratch.fromPos, scratch.toPos, eased);
+    camera.quaternion.slerpQuaternions(scratch.fromQuat, scratch.toQuat, eased);
+    if (isPerspective(camera)) {
+        camera.fov = scratch.fov + (targetFov - scratch.fov) * eased;
+        camera.updateProjectionMatrix();
+    }
+    return t >= 1;
+}

package/dist/camera/cameraRigs.d.ts

@@ -1,5 +1,6 @@
 import { type MutableRefObject } from "react";
 import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, type CameraBlendScratch, } from "./cameraBlendMath.js";
 export declare const CAMERA_RIG_FRAME_PRIORITY = -1;
 export declare const CAMERA_POST_FRAME_PRIORITY: number;
 export interface RigProps {
@@ -7,6 +8,8 @@ export interface RigProps {
     pitchRef: MutableRefObject<number>;
     config?: GameCameraConfig;
     followEntityId?: string | null;
+    /** When true, pose FOV is treated as absolute (cinematic keyframes). */
+    absoluteFov?: boolean;
 }
 export declare function TopDownRig(props: RigProps): null;
 /** Fixed side-on 2.5D follow rig: watches the followed entity from the perpendicular axis, never reading WASD/mouse-look. */