@jgengine/shell 0.7.0 → 0.8.0

package/dist/behaviour.d.ts

@@ -0,0 +1,31 @@
+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;
+/**
+ * Bootstraps `world` on mount and dispatches `world.update` every frame at
+ * simulation priority. `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 declare function useBehaviourWorld(world: BehaviourWorld, scaleDt?: (rawDt: number) => number): void;

package/dist/behaviour.js

@@ -0,0 +1,63 @@
+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;
+}
+/**
+ * Bootstraps `world` on mount and dispatches `world.update` every frame at
+ * simulation priority. `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) {
+    useEffect(() => {
+        world.start();
+    }, [world]);
+    useFrame((_state, rawDt) => {
+        world.update(scaleDt === undefined ? rawDt : scaleDt(rawDt));
+    });
+}

package/dist/camera/GameCameraRig.d.ts

@@ -1,11 +1,16 @@
 import { type MutableRefObject } from "react";
-import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playableGame";
+import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+import type { CameraDirector } from "@jgengine/core/runtime/cameraDirector";
+export { resolveRigKind } from "./rigResolve.js";
 export interface GameCameraRigProps {
     yawRef: MutableRefObject<number>;
     pitchRef: MutableRefObject<number>;
     config?: GameCameraConfig;
     onDragChange?: (dragging: boolean) => void;
     pointerControls?: boolean;
+    /** False when the game's own input map already claims WASD, so the RTS rig should stop panning on those keys. */
+    panKeysEnabled?: boolean;
+    /** Runtime follow/cinematic override (#196.2). While present it wins over the static `config` for any field it reports non-`undefined`/non-`null`; absent (or an all-`undefined` snapshot) is a no-op. */
+    director?: CameraDirector;
 }
-export declare function resolveRigKind(config: GameCameraConfig | undefined): CameraRigKind;
-export declare function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls }: GameCameraRigProps): import("react").JSX.Element;
+export declare function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, }: GameCameraRigProps): import("react").JSX.Element;

package/dist/camera/GameCameraRig.js

@@ -1,22 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from "react";
-import { ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, TopDownRig, } from "./cameraRigs.js";
+import { useEffect, useMemo, useReducer } from "react";
+import { ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, SideScrollRig, TopDownRig, } from "./cameraRigs.js";
 import { GameFirstPersonCamera } from "./GameFirstPersonCamera.js";
+import { GameInspectionCamera } from "./GameInspectionCamera.js";
 import { GameOrbitCamera } from "./GameOrbitCamera.js";
+import { resolveDirectedCamera } from "./rigMath.js";
+import { resolveRigKind, turntableAsObserver } from "./rigResolve.js";
 import { CameraShakeContext, createCameraShakeChannel } from "./shakeChannel.js";
-export function resolveRigKind(config) {
-    if (config?.rig !== undefined)
-        return config.rig;
-    if (config?.perspective === "first")
-        return "first";
-    return "orbit";
-}
-export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls }) {
+export { resolveRigKind } from "./rigResolve.js";
+export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, }) {
     const channel = useMemo(() => createCameraShakeChannel(config?.shake?.decayPerSecond), [config?.shake?.decayPerSecond]);
-    const followEntityId = config?.followEntityId;
+    const [, notifyDirectorChange] = useReducer((count) => count + 1, 0);
+    useEffect(() => {
+        if (director === undefined)
+            return undefined;
+        return director.subscribe(notifyDirectorChange);
+    }, [director]);
+    const directed = resolveDirectedCamera(director === undefined
+        ? undefined
+        : { followEntityId: director.followedEntityId(), cinematic: director.cinematic() }, { followEntityId: config?.followEntityId, cinematic: config?.cinematic });
+    const followEntityId = directed.followEntityId;
     const rig = (() => {
-        if (config?.cinematic !== undefined) {
-            return _jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
+        if (directed.cinematic !== undefined) {
+            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId }));
         }
         const kind = resolveRigKind(config);
         switch (kind) {
@@ -25,7 +31,7 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
             case "topDown":
                 return _jsx(TopDownRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
             case "rts":
-                return _jsx(RtsRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
+                return (_jsx(RtsRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId, panKeysEnabled: panKeysEnabled }));
             case "shoulder":
                 return _jsx(ShoulderRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
             case "lockOn":
@@ -34,6 +40,14 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
                 return _jsx(ChaseRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
             case "observer":
                 return _jsx(ObserverRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
+            case "turntable":
+                return (_jsx(ObserverRig, { yawRef: yawRef, pitchRef: pitchRef, config: turntableAsObserver(config), followEntityId: followEntityId }));
+            case "sideScroll":
+                return _jsx(SideScrollRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
+            case "inspection":
+                return _jsx(GameInspectionCamera, { config: config?.inspection });
+            case "none":
+                return null;
             default:
                 return (_jsx(GameOrbitCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId ?? undefined, onCameraFollow: config?.onCameraFollow, onDragChange: onDragChange, pointerControls: pointerControls }));
         }

package/dist/camera/GameFirstPersonCamera.js

@@ -19,6 +19,8 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     const followId = followEntityId ?? userId;
     useEffect(() => {
         const requestLock = () => {
+            if (window.matchMedia?.("(pointer: coarse)").matches)
+                return;
             if (document.pointerLockElement !== domElement)
                 void domElement.requestPointerLock?.();
         };

package/dist/camera/GameInspectionCamera.d.ts

@@ -0,0 +1,6 @@
+import { type InspectionCameraConfig } from "./inspectionCameraMath.js";
+export interface GameInspectionCameraProps {
+    config?: InspectionCameraConfig;
+}
+/** 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. */
+export declare function GameInspectionCamera({ config: configPatch }: GameInspectionCameraProps): import("react").JSX.Element;

package/dist/camera/GameInspectionCamera.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { OrbitControls } from "@react-three/drei";
+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. */
+export function GameInspectionCamera({ config: configPatch }) {
+    const config = resolveInspectionCameraConfig(configPatch);
+    const controlsRef = useRef(null);
+    const camera = useThree((state) => state.camera);
+    const seededRef = useRef(false);
+    useEffect(() => {
+        if (seededRef.current)
+            return;
+        const seeded = seedInspectionCamera(config);
+        camera.position.set(seeded.camera.x, seeded.camera.y, seeded.camera.z);
+        camera.lookAt(seeded.target.x, seeded.target.y, seeded.target.z);
+        controlsRef.current?.target.set(seeded.target.x, seeded.target.y, seeded.target.z);
+        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 } }));
+}

package/dist/camera/cameraRigs.d.ts

@@ -9,7 +9,11 @@ export interface RigProps {
     followEntityId?: string | null;
 }
 export declare function TopDownRig(props: RigProps): null;
-export declare function RtsRig(props: RigProps): null;
+/** Fixed side-on 2.5D follow rig: watches the followed entity from the perpendicular axis, never reading WASD/mouse-look. */
+export declare function SideScrollRig(props: RigProps): null;
+export declare function RtsRig(props: RigProps & {
+    panKeysEnabled?: boolean;
+}): null;
 export declare function ShoulderRig(props: RigProps): null;
 export declare function LockOnRig(props: RigProps): null;
 export declare function ChaseRig(props: RigProps): null;

package/dist/camera/cameraRigs.js

@@ -4,7 +4,7 @@ import { PerspectiveCamera, Quaternion, Vector3 } from "three";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useGameContext } from "@jgengine/react/provider";
 import { ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
-import { chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveTopDown, seatPose, shoulderPose, smoothstep, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
+import { chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothstep, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
 import { useCameraShake } from "./shakeChannel.js";
 export const CAMERA_RIG_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY;
 export const CAMERA_POST_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY + 0.5;
@@ -51,6 +51,7 @@ function useCameraCommit(props, followId) {
     const transitionSeconds = props.config?.transitionSeconds ?? 0.6;
     const blendRef = useRef(null);
     const lastPoseRef = useRef(null);
+    const farWarnedRef = useRef(false);
     const beginTransition = () => {
         if (transitionSeconds <= 0)
             return;
@@ -65,6 +66,11 @@ function useCameraCommit(props, followId) {
     const commit = (pose, dt) => {
         lastPoseRef.current = pose;
         applyPose(camera, pose);
+        const lookDistance = Math.hypot(pose.position.x - pose.lookAt.x, pose.position.y - pose.lookAt.y, pose.position.z - pose.lookAt.z);
+        if (!farWarnedRef.current && isPerspective(camera) && lookDistance > camera.far) {
+            farWarnedRef.current = true;
+            console.warn(`[jgengine:camera] the "${props.config?.rig ?? "orbit"}" rig placed the camera ${Math.round(lookDistance)} world units from its look target, beyond the far plane (${camera.far}) — everything near the target is frustum-culled and the world renders empty. Check the rig config (topDown pitch is elevation: PI/2 = straight down, near 0 = grazing) or raise camera.frustum.far.`);
+        }
         const blend = blendRef.current;
         if (blend !== null) {
             blend.elapsed += dt;
@@ -141,6 +147,32 @@ export function TopDownRig(props) {
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }
+/** Fixed side-on 2.5D follow rig: watches the followed entity from the perpendicular axis, never reading WASD/mouse-look. */
+export function SideScrollRig(props) {
+    const { userId } = usePlayer();
+    const ctx = useGameContext();
+    const followId = resolveFollowId(props.followEntityId, userId);
+    const config = props.config?.sideScroll;
+    const resolved = useMemo(() => resolveSideScroll(config), [config]);
+    const { camera, commit, beginTransition } = useCameraCommit(props, followId);
+    const followRef = useRef(null);
+    useEffect(beginTransition, []);
+    useFrame((_, dt) => {
+        const sample = readFollow(ctx, followId);
+        const desired = sample?.pos ?? { x: 0, y: 0, z: 0 };
+        const prev = followRef.current ?? desired;
+        const blend = sideScrollFollowBlend(resolved.followSmoothing, dt);
+        const follow = {
+            x: prev.x + (desired.x - prev.x) * blend,
+            y: prev.y + (desired.y - prev.y) * blend,
+            z: prev.z + (desired.z - prev.z) * blend,
+        };
+        followRef.current = follow;
+        const pose = resolveSideScrollPose(follow, resolved, config?.fov ?? currentFov(camera));
+        commit(pose, dt);
+    }, CAMERA_RIG_FRAME_PRIORITY);
+    return null;
+}
 function useHeldKeys(codes) {
     const held = useRef(new Set());
     useEffect(() => {
@@ -163,6 +195,7 @@ function useHeldKeys(codes) {
     return held;
 }
 const RTS_PAN_KEYS = ["KeyW", "KeyA", "KeyS", "KeyD", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "KeyQ", "KeyE"];
+const RTS_WASD_KEYS = new Set(["KeyW", "KeyA", "KeyS", "KeyD"]);
 export function RtsRig(props) {
     const { userId } = usePlayer();
     const ctx = useGameContext();
@@ -170,7 +203,9 @@ export function RtsRig(props) {
     const config = props.config?.rts;
     const resolved = useMemo(() => resolveTopDown(config), [config]);
     const { camera, commit, beginTransition } = useCameraCommit(props, followId);
-    const held = useHeldKeys(RTS_PAN_KEYS);
+    const wasdPanEnabled = followId === null && props.panKeysEnabled !== false;
+    const heldCodes = useMemo(() => (wasdPanEnabled ? RTS_PAN_KEYS : RTS_PAN_KEYS.filter((code) => !RTS_WASD_KEYS.has(code))), [wasdPanEnabled]);
+    const held = useHeldKeys(heldCodes);
     const centerRef = useRef({
         x: config?.start?.x ?? 0,
         y: 0,
@@ -431,8 +466,8 @@ export function ChaseRig(props) {
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }
-function observerSubject(ctx, config) {
-    const bind = config?.bind;
+function observerSubject(ctx, config, followId) {
+    const bind = config?.bind ?? (followId !== null ? { kind: "entity", entityId: followId } : undefined);
     if (bind?.kind === "entity") {
         const entity = ctx.scene.entity.get(bind.entityId);
         if (entity !== null) {
@@ -450,15 +485,17 @@ function observerSubject(ctx, config) {
  * kill-cam rig. Distinct from every other rig, which drives from mouse/keys.
  */
 export function ObserverRig(props) {
+    const { userId } = usePlayer();
     const ctx = useGameContext();
     const config = props.config?.observer;
+    const followId = resolveFollowId(props.followEntityId, userId);
     const resolved = useMemo(() => resolveObserver(config), [config]);
     const angleRef = useRef(config?.startAngle ?? 0);
-    const { camera, commit, beginTransition } = useCameraCommit(props, observerSubject(ctx, config).boundEntityId);
+    const { camera, commit, beginTransition } = useCameraCommit(props, observerSubject(ctx, config, followId).boundEntityId);
     useEffect(beginTransition, []);
     useFrame((_, dt) => {
         angleRef.current += resolved.orbitSpeed * dt;
-        const { subject } = observerSubject(ctx, config);
+        const { subject } = observerSubject(ctx, config, followId);
         const pose = observerPose(subject, angleRef.current, resolved, config?.fov ?? currentFov(camera));
         commit(pose, dt);
     }, CAMERA_RIG_FRAME_PRIORITY);

package/dist/camera/index.d.ts

@@ -1,7 +1,9 @@
 export { GameOrbitCamera, type CameraFollowListener, type GameOrbitCameraProps } from "./GameOrbitCamera.js";
 export { GameFirstPersonCamera, type GameFirstPersonCameraProps } from "./GameFirstPersonCamera.js";
+export { GameInspectionCamera, type GameInspectionCameraProps } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind, type GameCameraRigProps } from "./GameCameraRig.js";
-export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, TopDownRig, type RigProps, } from "./cameraRigs.js";
+export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, SideScrollRig, TopDownRig, type RigProps, } from "./cameraRigs.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, resolveObserver, resolveShoulder, resolveTopDown, rightVector, seatPose, shakeOffset, shoulderPose, smoothstep, smoothYaw, speedToFov, springArmStep, stepTrauma, topDownPose, yawTo, type CameraPose, type ResolvedChase, type ResolvedObserver, type ResolvedShoulder, type ResolvedTopDown, type ShakeOffset, type TraumaState, } from "./rigMath.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";

package/dist/camera/index.js

@@ -1,7 +1,9 @@
 export { GameOrbitCamera } from "./GameOrbitCamera.js";
 export { GameFirstPersonCamera } from "./GameFirstPersonCamera.js";
+export { GameInspectionCamera } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind } from "./GameCameraRig.js";
-export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, TopDownRig, } from "./cameraRigs.js";
+export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, SideScrollRig, TopDownRig, } from "./cameraRigs.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, resolveObserver, resolveShoulder, resolveTopDown, rightVector, seatPose, shakeOffset, shoulderPose, smoothstep, smoothYaw, speedToFov, springArmStep, stepTrauma, topDownPose, yawTo, } from "./rigMath.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";

package/dist/camera/inspectionCameraMath.d.ts

@@ -0,0 +1,25 @@
+import type { InspectionCameraConfig, InspectionZoomAnchor } from "@jgengine/core/game/playableGame";
+import type { Vec3 } from "./orbitCameraMath.js";
+export type { InspectionCameraConfig, InspectionZoomAnchor };
+export interface ResolvedInspectionCameraConfig {
+    anchor: InspectionZoomAnchor;
+    target: Vec3;
+    initialDistance: number;
+    initialPosition: Vec3 | null;
+    minDistance: number;
+    maxDistance: number;
+    minPolarAngle: number;
+    maxPolarAngle: number;
+    pan: boolean;
+    rotateSpeed: number;
+    zoomSpeed: number;
+    dampingFactor: number;
+}
+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. */
+export declare function seedInspectionCamera(config: ResolvedInspectionCameraConfig): {
+    camera: Vec3;
+    target: Vec3;
+};
+/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag. */
+export declare function resolveInspectionZoomToCursor(anchor: InspectionZoomAnchor): boolean;

package/dist/camera/inspectionCameraMath.js

@@ -0,0 +1,44 @@
+export function resolveInspectionCameraConfig(config) {
+    return {
+        anchor: config?.anchor ?? "target",
+        target: {
+            x: config?.target?.x ?? 0,
+            y: config?.target?.y ?? 0,
+            z: config?.target?.z ?? 0,
+        },
+        initialDistance: config?.initialDistance ?? 6,
+        initialPosition: config?.initialPosition === undefined
+            ? null
+            : {
+                x: config.initialPosition.x ?? 0,
+                y: config.initialPosition.y ?? 0,
+                z: config.initialPosition.z ?? 0,
+            },
+        minDistance: config?.minDistance ?? 2,
+        maxDistance: config?.maxDistance ?? 20,
+        minPolarAngle: config?.minPolarAngle ?? 0,
+        maxPolarAngle: config?.maxPolarAngle ?? Math.PI,
+        pan: config?.pan ?? true,
+        rotateSpeed: config?.rotateSpeed ?? 0.6,
+        zoomSpeed: config?.zoomSpeed ?? 0.6,
+        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. */
+export function seedInspectionCamera(config) {
+    if (config.initialPosition !== null) {
+        return { camera: config.initialPosition, target: config.target };
+    }
+    return {
+        camera: {
+            x: config.target.x,
+            y: config.target.y + config.initialDistance * 0.4,
+            z: config.target.z - config.initialDistance,
+        },
+        target: config.target,
+    };
+}
+/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag. */
+export function resolveInspectionZoomToCursor(anchor) {
+    return anchor === "cursor";
+}

package/dist/camera/rigMath.d.ts

@@ -1,10 +1,12 @@
-import type { CameraKeyframe, ChaseCameraConfig, LockOnCameraConfig, ObserverCameraConfig, ShoulderCameraConfig, TopDownCameraConfig } from "@jgengine/core/game/playableGame";
+import type { CameraKeyframe, ChaseCameraConfig, CinematicCameraConfig, LockOnCameraConfig, ObserverCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig } from "@jgengine/core/game/playableGame";
+import type { ActionCodesMap } from "@jgengine/core/input/actionBindings";
 import { type Vec3 } from "./orbitCameraMath.js";
 export interface CameraPose {
     position: Vec3;
     lookAt: Vec3;
     fov: number;
 }
+export declare function rtsPanKeysConflict(input: ActionCodesMap | undefined): boolean;
 export declare function clamp(value: number, min: number, max: number): number;
 export declare function lerp(from: number, to: number, blend: number): number;
 export declare function smoothstep(t: number): number;
@@ -27,6 +29,22 @@ export declare function resolveTopDown(config: TopDownCameraConfig | undefined):
 export declare function topDownPose(follow: Vec3, resolved: ResolvedTopDown, fov: number): CameraPose;
 /** Exponential spring-arm approach toward a desired point (frame-rate independent). */
 export declare function springArmStep(current: Vec3, desired: Vec3, damping: number, dt: number): Vec3;
+export interface ResolvedSideScroll {
+    axis: "x" | "z";
+    distance: number;
+    height: number;
+    lookHeight: number;
+    followSmoothing: number;
+}
+export declare function resolveSideScroll(config: SideScrollCameraConfig | undefined): ResolvedSideScroll;
+/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing. */
+export declare function sideScrollFollowBlend(followSmoothing: number, dt: number): number;
+/**
+ * Fixed lateral 2.5D follow pose: the camera sits perpendicular to the travel
+ * axis at `distance`, above the entity by `height`, and looks at the entity
+ * raised by `lookHeight`. Axis "x" watches from +z; axis "z" watches from +x.
+ */
+export declare function resolveSideScrollPose(entityPos: Vec3, resolved: ResolvedSideScroll, fov: number): CameraPose;
 /** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`. */
 export declare function speedToFov(speed: number, curve: {
     base?: number;
@@ -117,6 +135,27 @@ export declare function shakeOffset(state: TraumaState, config: {
 } | undefined): ShakeOffset;
 /** Linear cross-fade between two full camera poses (position, lookAt, fov). */
 export declare function crossfadePose(from: CameraPose, to: CameraPose, t: number): CameraPose;
+export interface DirectorCameraValues {
+    /** `undefined` = no runtime override (fall back to static); `null` = explicitly follow nothing. */
+    followEntityId?: string | null;
+    /** `null` = no runtime cinematic active (fall back to static). */
+    cinematic?: CinematicCameraConfig | null;
+}
+export interface StaticCameraValues {
+    followEntityId?: string | null;
+    cinematic?: CinematicCameraConfig;
+}
+export interface ResolvedDirectedCamera {
+    followEntityId: string | null | undefined;
+    cinematic: CinematicCameraConfig | undefined;
+}
+/**
+ * Merges a `CameraDirector` runtime snapshot over the static `GameCameraConfig`
+ * (#196.2). `director` omitted, or its fields `undefined`/`null`, is a pure
+ * passthrough to `staticConfig` so mounting a director with no active override
+ * changes nothing.
+ */
+export declare function resolveDirectedCamera(director: DirectorCameraValues | undefined, staticConfig: StaticCameraValues): ResolvedDirectedCamera;
 export interface CinematicSample {
     pose: CameraPose;
     done: boolean;

package/dist/camera/rigMath.js

@@ -1,4 +1,16 @@
 import { lerpVec3, smoothBlend } from "./orbitCameraMath.js";
+const RTS_WASD_CODES = ["KeyW", "KeyA", "KeyS", "KeyD"];
+function actionCodeList(codes) {
+    if (Array.isArray(codes))
+        return codes;
+    const modes = codes;
+    return [...(modes.hold ?? []), ...(modes.toggle ?? [])];
+}
+export function rtsPanKeysConflict(input) {
+    if (input === undefined)
+        return false;
+    return Object.values(input).some((codes) => actionCodeList(codes).some((code) => RTS_WASD_CODES.includes(code)));
+}
 export function clamp(value, min, max) {
     return value < min ? min : value > max ? max : value;
 }
@@ -56,6 +68,36 @@ export function topDownPose(follow, resolved, fov) {
 export function springArmStep(current, desired, damping, dt) {
     return lerpVec3(current, desired, smoothBlend(dt, damping));
 }
+export function resolveSideScroll(config) {
+    return {
+        axis: config?.axis ?? "x",
+        distance: config?.distance ?? 10,
+        height: config?.height ?? 3,
+        lookHeight: config?.lookHeight ?? 1,
+        followSmoothing: config?.followSmoothing ?? 8,
+    };
+}
+/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing. */
+export function sideScrollFollowBlend(followSmoothing, dt) {
+    return followSmoothing <= 0 ? 1 : smoothBlend(dt, followSmoothing);
+}
+/**
+ * Fixed lateral 2.5D follow pose: the camera sits perpendicular to the travel
+ * axis at `distance`, above the entity by `height`, and looks at the entity
+ * raised by `lookHeight`. Axis "x" watches from +z; axis "z" watches from +x.
+ */
+export function resolveSideScrollPose(entityPos, resolved, fov) {
+    const perpendicular = resolved.axis === "x" ? { x: 0, y: 0, z: 1 } : { x: 1, y: 0, z: 0 };
+    return {
+        position: {
+            x: entityPos.x + perpendicular.x * resolved.distance,
+            y: entityPos.y + resolved.height,
+            z: entityPos.z + perpendicular.z * resolved.distance,
+        },
+        lookAt: { x: entityPos.x, y: entityPos.y + resolved.lookHeight, z: entityPos.z },
+        fov,
+    };
+}
 /** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`. */
 export function speedToFov(speed, curve) {
     const base = curve?.base ?? 55;
@@ -268,6 +310,19 @@ export function crossfadePose(from, to, t) {
         fov: lerp(from.fov, to.fov, blend),
     };
 }
+/**
+ * Merges a `CameraDirector` runtime snapshot over the static `GameCameraConfig`
+ * (#196.2). `director` omitted, or its fields `undefined`/`null`, is a pure
+ * passthrough to `staticConfig` so mounting a director with no active override
+ * changes nothing.
+ */
+export function resolveDirectedCamera(director, staticConfig) {
+    const directedFollow = director?.followEntityId;
+    const followEntityId = directedFollow === undefined ? staticConfig.followEntityId : directedFollow;
+    const directedCinematic = director?.cinematic;
+    const cinematic = directedCinematic === undefined || directedCinematic === null ? staticConfig.cinematic : directedCinematic;
+    return { followEntityId, cinematic };
+}
 /**
  * Sample a keyframe path at `elapsed` seconds. Each keyframe's `duration` is the
  * travel time from the previous keyframe into it; segment easing is per the

package/dist/camera/rigResolve.d.ts

@@ -0,0 +1,15 @@
+import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playableGame";
+/**
+ * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
+ * specific: an explicit `rig` field always wins; then `perspective: "first"`
+ * (the historical shorthand for `rig: "orbit" | "first"`); then the mere presence
+ * of a rig's own config block selects that rig, checked in the fixed order below
+ * (#207.8) so a config carrying more than one block resolves deterministically
+ * instead of depending on object key order. Set `rig` explicitly to break a tie.
+ */
+export declare function resolveRigKind(config: GameCameraConfig | undefined): CameraRigKind;
+/**
+ * The turntable rig is a flat facade over the observer's point-orbit mode: map
+ * its `target`/`distance`/… onto an observer block so ObserverRig runs unchanged.
+ */
+export declare function turntableAsObserver(config: GameCameraConfig | undefined): GameCameraConfig;