@jgengine/shell 0.6.0 → 0.8.0

package/dist/camera/rigMath.d.ts

@@ -0,0 +1,169 @@
+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;
+export declare function forwardVector(yaw: number): Vec3;
+export declare function rightVector(yaw: number): Vec3;
+export interface ResolvedTopDown {
+    height: number;
+    pitch: number;
+    yaw: number;
+    offset: Vec3;
+    followSmoothing: number;
+}
+export declare function resolveTopDown(config: TopDownCameraConfig | undefined): ResolvedTopDown;
+/**
+ * Camera pose for a fixed top-down / isometric rig. `pitch` is the elevation of
+ * the camera→target ray above the ground (PI/2 = straight down); `yaw` is the
+ * fixed azimuth (PI/4 reads isometric). Height sets zoom; horizontal boom is
+ * derived so the look angle stays constant as height changes.
+ */
+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;
+    max?: number;
+    speedForMax?: number;
+} | undefined): number;
+/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)). */
+export declare function yawTo(from: Vec3, to: Vec3): number;
+/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI]. */
+export declare function angleDelta(a: number, b: number): number;
+/** Exponential yaw smoothing that respects wrap-around. */
+export declare function smoothYaw(current: number, desired: number, speed: number, dt: number): number;
+export interface ResolvedShoulder {
+    shoulderOffset: number;
+    heightOffset: number;
+    distance: number;
+    fov: number;
+}
+export declare function resolveShoulder(config: ShoulderCameraConfig | undefined, aiming: boolean): ResolvedShoulder;
+/** Blend two shoulder framings by an ADS factor in [0,1]. */
+export declare function blendShoulder(hip: ResolvedShoulder, ads: ResolvedShoulder, t: number): ResolvedShoulder;
+/**
+ * Over-the-shoulder camera pose. The boom sits behind the follow point along
+ * `yaw`, raised by `heightOffset`, and pushed sideways by `shoulderOffset`
+ * (sign set by `sideSign`: +1 right, -1 left). `pitch` tilts the look point.
+ */
+export declare function shoulderPose(follow: Vec3, yaw: number, pitch: number, sideSign: number, shoulder: ResolvedShoulder): CameraPose;
+/**
+ * Lock-on pose: camera sits behind the player along the player→target vector so
+ * the target stays framed. The look point is biased between player and target
+ * by `framingBias`.
+ */
+export declare function lockOnPose(player: Vec3, target: Vec3, config: LockOnCameraConfig | undefined, fov: number): {
+    pose: CameraPose;
+    yaw: number;
+};
+export interface ResolvedChase {
+    distance: number;
+    height: number;
+    lookHeight: number;
+    springDamping: number;
+    shakePerSpeed: number;
+}
+export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
+export interface ResolvedObserver {
+    distance: number;
+    height: number;
+    lookHeight: number;
+    orbitSpeed: number;
+}
+export declare function resolveObserver(config: ObserverCameraConfig | undefined): ResolvedObserver;
+/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input. */
+export declare function observerPose(subject: Vec3, angle: number, resolved: ResolvedObserver, fov: number): CameraPose;
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). */
+export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
+/** Look point ahead of / above a chased vehicle. */
+export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
+/** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle. */
+export declare function seatPose(follow: Vec3, yaw: number, local: {
+    x?: number;
+    y?: number;
+    z?: number;
+}, fov: number): CameraPose;
+export interface TraumaState {
+    trauma: number;
+    time: number;
+}
+export declare function createTrauma(): TraumaState;
+/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1. */
+export declare function addTrauma(state: TraumaState, amount: number): void;
+/** Decay trauma linearly toward 0 and advance the shake clock. */
+export declare function stepTrauma(state: TraumaState, decayPerSecond: number, dt: number): void;
+export interface ShakeOffset {
+    x: number;
+    y: number;
+    roll: number;
+}
+/**
+ * Positional + roll shake for the current trauma. Shake magnitude is
+ * `trauma^exponent` so small hits stay subtle; the oscillation is deterministic
+ * per-seed pseudo-noise (no per-frame RNG, so identical inputs reproduce).
+ */
+export declare function shakeOffset(state: TraumaState, config: {
+    maxOffset?: number;
+    maxRoll?: number;
+    exponent?: number;
+    frequency?: number;
+} | 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;
+}
+/**
+ * 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
+ * destination keyframe. Reports `done` once past the final keyframe (unless
+ * looping, which wraps `elapsed` into the total path duration).
+ */
+export declare function cinematicSample(keyframes: readonly CameraKeyframe[], elapsed: number, loop: boolean, fallbackFov: number): CinematicSample;

package/dist/camera/rigMath.js

@@ -0,0 +1,393 @@
+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;
+}
+export function lerp(from, to, blend) {
+    return from + (to - from) * blend;
+}
+export function smoothstep(t) {
+    const clamped = clamp(t, 0, 1);
+    return clamped * clamped * (3 - 2 * clamped);
+}
+export function forwardVector(yaw) {
+    return { x: Math.sin(yaw), y: 0, z: Math.cos(yaw) };
+}
+export function rightVector(yaw) {
+    return { x: Math.cos(yaw), y: 0, z: -Math.sin(yaw) };
+}
+export function resolveTopDown(config) {
+    return {
+        height: config?.height ?? 18,
+        pitch: config?.pitch ?? 1.02,
+        yaw: config?.yaw ?? Math.PI / 4,
+        offset: {
+            x: config?.targetOffset?.x ?? 0,
+            y: config?.targetOffset?.y ?? 0,
+            z: config?.targetOffset?.z ?? 0,
+        },
+        followSmoothing: config?.followSmoothing ?? 8,
+    };
+}
+/**
+ * Camera pose for a fixed top-down / isometric rig. `pitch` is the elevation of
+ * the camera→target ray above the ground (PI/2 = straight down); `yaw` is the
+ * fixed azimuth (PI/4 reads isometric). Height sets zoom; horizontal boom is
+ * derived so the look angle stays constant as height changes.
+ */
+export function topDownPose(follow, resolved, fov) {
+    const lookAt = {
+        x: follow.x + resolved.offset.x,
+        y: follow.y + resolved.offset.y,
+        z: follow.z + resolved.offset.z,
+    };
+    const pitch = clamp(resolved.pitch, 0.05, Math.PI / 2);
+    const horizontal = resolved.height / Math.tan(pitch);
+    return {
+        position: {
+            x: lookAt.x - Math.sin(resolved.yaw) * horizontal,
+            y: lookAt.y + resolved.height,
+            z: lookAt.z - Math.cos(resolved.yaw) * horizontal,
+        },
+        lookAt,
+        fov,
+    };
+}
+/** Exponential spring-arm approach toward a desired point (frame-rate independent). */
+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;
+    const max = curve?.max ?? 78;
+    const speedForMax = curve?.speedForMax ?? 24;
+    if (speedForMax <= 0)
+        return base;
+    return lerp(base, max, clamp(speed / speedForMax, 0, 1));
+}
+/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)). */
+export function yawTo(from, to) {
+    return Math.atan2(to.x - from.x, to.z - from.z);
+}
+/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI]. */
+export function angleDelta(a, b) {
+    let delta = (b - a) % (Math.PI * 2);
+    if (delta > Math.PI)
+        delta -= Math.PI * 2;
+    if (delta < -Math.PI)
+        delta += Math.PI * 2;
+    return delta;
+}
+/** Exponential yaw smoothing that respects wrap-around. */
+export function smoothYaw(current, desired, speed, dt) {
+    return current + angleDelta(current, desired) * smoothBlend(dt, speed);
+}
+export function resolveShoulder(config, aiming) {
+    const hip = {
+        shoulderOffset: config?.shoulderOffset ?? 0.6,
+        heightOffset: config?.heightOffset ?? 1.6,
+        distance: config?.distance ?? 3.2,
+        fov: config?.fov ?? 55,
+    };
+    if (!aiming)
+        return hip;
+    const ads = config?.ads;
+    return {
+        shoulderOffset: ads?.shoulderOffset ?? hip.shoulderOffset * 0.4,
+        heightOffset: ads?.heightOffset ?? hip.heightOffset,
+        distance: ads?.distance ?? hip.distance * 0.55,
+        fov: ads?.fov ?? hip.fov * 0.75,
+    };
+}
+/** Blend two shoulder framings by an ADS factor in [0,1]. */
+export function blendShoulder(hip, ads, t) {
+    return {
+        shoulderOffset: lerp(hip.shoulderOffset, ads.shoulderOffset, t),
+        heightOffset: lerp(hip.heightOffset, ads.heightOffset, t),
+        distance: lerp(hip.distance, ads.distance, t),
+        fov: lerp(hip.fov, ads.fov, t),
+    };
+}
+/**
+ * Over-the-shoulder camera pose. The boom sits behind the follow point along
+ * `yaw`, raised by `heightOffset`, and pushed sideways by `shoulderOffset`
+ * (sign set by `sideSign`: +1 right, -1 left). `pitch` tilts the look point.
+ */
+export function shoulderPose(follow, yaw, pitch, sideSign, shoulder) {
+    const forward = forwardVector(yaw);
+    const right = rightVector(yaw);
+    const anchor = {
+        x: follow.x + right.x * shoulder.shoulderOffset * sideSign,
+        y: follow.y + shoulder.heightOffset,
+        z: follow.z + right.z * shoulder.shoulderOffset * sideSign,
+    };
+    const cosPitch = Math.cos(pitch);
+    const position = {
+        x: anchor.x - forward.x * shoulder.distance * cosPitch,
+        y: anchor.y + Math.sin(pitch) * shoulder.distance,
+        z: anchor.z - forward.z * shoulder.distance * cosPitch,
+    };
+    const lookAt = {
+        x: anchor.x + forward.x * 4 * cosPitch,
+        y: anchor.y - Math.sin(pitch) * 4,
+        z: anchor.z + forward.z * 4 * cosPitch,
+    };
+    return { position, lookAt, fov: shoulder.fov };
+}
+/**
+ * Lock-on pose: camera sits behind the player along the player→target vector so
+ * the target stays framed. The look point is biased between player and target
+ * by `framingBias`.
+ */
+export function lockOnPose(player, target, config, fov) {
+    const distance = config?.distance ?? 5;
+    const height = config?.height ?? 2.4;
+    const lookHeight = config?.lookHeight ?? 1.2;
+    const bias = clamp(config?.framingBias ?? 0.5, 0, 1);
+    const yaw = yawTo(player, target);
+    const back = forwardVector(yaw);
+    const focus = {
+        x: lerp(player.x, target.x, bias),
+        y: lerp(player.y, target.y, bias) + lookHeight,
+        z: lerp(player.z, target.z, bias),
+    };
+    const position = {
+        x: player.x - back.x * distance,
+        y: player.y + height,
+        z: player.z - back.z * distance,
+    };
+    return { pose: { position, lookAt: focus, fov }, yaw };
+}
+export function resolveChase(config) {
+    return {
+        distance: config?.distance ?? 6,
+        height: config?.height ?? 2.6,
+        lookHeight: config?.lookHeight ?? 1.2,
+        springDamping: config?.springDamping ?? 6,
+        shakePerSpeed: config?.shakePerSpeed ?? 0,
+    };
+}
+export function resolveObserver(config) {
+    return {
+        distance: config?.distance ?? 8,
+        height: config?.height ?? 3,
+        lookHeight: config?.lookHeight ?? 1.2,
+        orbitSpeed: config?.orbitSpeed ?? 0.2,
+    };
+}
+/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input. */
+export function observerPose(subject, angle, resolved, fov) {
+    const position = {
+        x: subject.x + Math.sin(angle) * resolved.distance,
+        y: subject.y + resolved.height,
+        z: subject.z + Math.cos(angle) * resolved.distance,
+    };
+    return {
+        position,
+        lookAt: { x: subject.x, y: subject.y + resolved.lookHeight, z: subject.z },
+        fov,
+    };
+}
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). */
+export function chaseDesiredPosition(follow, yaw, resolved) {
+    const back = forwardVector(yaw);
+    return {
+        x: follow.x - back.x * resolved.distance,
+        y: follow.y + resolved.height,
+        z: follow.z - back.z * resolved.distance,
+    };
+}
+/** Look point ahead of / above a chased vehicle. */
+export function chaseLookAt(follow, yaw, resolved) {
+    const forward = forwardVector(yaw);
+    return {
+        x: follow.x + forward.x * 2,
+        y: follow.y + resolved.lookHeight,
+        z: follow.z + forward.z * 2,
+    };
+}
+/** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle. */
+export function seatPose(follow, yaw, local, fov) {
+    const forward = forwardVector(yaw);
+    const right = rightVector(yaw);
+    const lx = local.x ?? 0;
+    const ly = local.y ?? 1.1;
+    const lz = local.z ?? 0.2;
+    const position = {
+        x: follow.x + right.x * lx + forward.x * lz,
+        y: follow.y + ly,
+        z: follow.z + right.z * lx + forward.z * lz,
+    };
+    return {
+        position,
+        lookAt: { x: position.x + forward.x * 6, y: position.y, z: position.z + forward.z * 6 },
+        fov,
+    };
+}
+export function createTrauma() {
+    return { trauma: 0, time: 0 };
+}
+/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1. */
+export function addTrauma(state, amount) {
+    state.trauma = clamp(state.trauma + amount, 0, 1);
+}
+/** Decay trauma linearly toward 0 and advance the shake clock. */
+export function stepTrauma(state, decayPerSecond, dt) {
+    state.time += dt;
+    state.trauma = clamp(state.trauma - decayPerSecond * dt, 0, 1);
+}
+function hashNoise(seed, time, frequency) {
+    const phase = time * frequency + seed * 12.9898;
+    return Math.sin(phase) * 0.5 + Math.sin(phase * 2.137 + 1.7) * 0.5;
+}
+/**
+ * Positional + roll shake for the current trauma. Shake magnitude is
+ * `trauma^exponent` so small hits stay subtle; the oscillation is deterministic
+ * per-seed pseudo-noise (no per-frame RNG, so identical inputs reproduce).
+ */
+export function shakeOffset(state, config) {
+    const maxOffset = config?.maxOffset ?? 0.5;
+    const maxRoll = config?.maxRoll ?? 0.06;
+    const exponent = config?.exponent ?? 2;
+    const frequency = config?.frequency ?? 24;
+    const shake = Math.pow(state.trauma, exponent);
+    if (shake <= 0)
+        return { x: 0, y: 0, roll: 0 };
+    return {
+        x: maxOffset * shake * hashNoise(1, state.time, frequency),
+        y: maxOffset * shake * hashNoise(2, state.time, frequency),
+        roll: maxRoll * shake * hashNoise(3, state.time, frequency),
+    };
+}
+/** Linear cross-fade between two full camera poses (position, lookAt, fov). */
+export function crossfadePose(from, to, t) {
+    const blend = clamp(t, 0, 1);
+    return {
+        position: lerpVec3(from.position, to.position, blend),
+        lookAt: lerpVec3(from.lookAt, to.lookAt, blend),
+        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
+ * destination keyframe. Reports `done` once past the final keyframe (unless
+ * looping, which wraps `elapsed` into the total path duration).
+ */
+export function cinematicSample(keyframes, elapsed, loop, fallbackFov) {
+    if (keyframes.length === 0) {
+        const zero = { x: 0, y: 0, z: 0 };
+        return { pose: { position: zero, lookAt: zero, fov: fallbackFov }, done: true };
+    }
+    const first = keyframes[0];
+    const firstPose = {
+        position: { ...first.position },
+        lookAt: { ...first.lookAt },
+        fov: first.fov ?? fallbackFov,
+    };
+    if (keyframes.length === 1)
+        return { pose: firstPose, done: true };
+    let total = 0;
+    for (let i = 1; i < keyframes.length; i += 1)
+        total += keyframes[i].duration ?? 1;
+    if (total <= 0)
+        return { pose: firstPose, done: true };
+    let time = elapsed;
+    let done = false;
+    if (loop) {
+        time = ((elapsed % total) + total) % total;
+    }
+    else if (elapsed >= total) {
+        const last = keyframes[keyframes.length - 1];
+        return {
+            pose: { position: { ...last.position }, lookAt: { ...last.lookAt }, fov: last.fov ?? fallbackFov },
+            done: true,
+        };
+    }
+    else if (elapsed <= 0) {
+        return { pose: firstPose, done: false };
+    }
+    let acc = 0;
+    for (let i = 1; i < keyframes.length; i += 1) {
+        const to = keyframes[i];
+        const from = keyframes[i - 1];
+        const duration = to.duration ?? 1;
+        if (time <= acc + duration || i === keyframes.length - 1) {
+            const localT = duration <= 0 ? 1 : clamp((time - acc) / duration, 0, 1);
+            const eased = to.ease === "linear" ? localT : smoothstep(localT);
+            const fromPose = {
+                position: { ...from.position },
+                lookAt: { ...from.lookAt },
+                fov: from.fov ?? fallbackFov,
+            };
+            const toPose = {
+                position: { ...to.position },
+                lookAt: { ...to.lookAt },
+                fov: to.fov ?? fallbackFov,
+            };
+            return { pose: crossfadePose(fromPose, toPose, eased), done };
+        }
+        acc += duration;
+    }
+    done = true;
+    const last = keyframes[keyframes.length - 1];
+    return {
+        pose: { position: { ...last.position }, lookAt: { ...last.lookAt }, fov: last.fov ?? fallbackFov },
+        done,
+    };
+}

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;

package/dist/camera/rigResolve.js

@@ -0,0 +1,52 @@
+/**
+ * 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 function resolveRigKind(config) {
+    if (config?.rig !== undefined)
+        return config.rig;
+    if (config?.perspective === "first")
+        return "first";
+    if (config?.topDown !== undefined)
+        return "topDown";
+    if (config?.rts !== undefined)
+        return "rts";
+    if (config?.shoulder !== undefined)
+        return "shoulder";
+    if (config?.lockOn !== undefined)
+        return "lockOn";
+    if (config?.chase !== undefined)
+        return "chase";
+    if (config?.observer !== undefined)
+        return "observer";
+    if (config?.turntable !== undefined)
+        return "turntable";
+    if (config?.sideScroll !== undefined)
+        return "sideScroll";
+    if (config?.inspection !== undefined)
+        return "inspection";
+    return "orbit";
+}
+/**
+ * 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 function turntableAsObserver(config) {
+    const t = config?.turntable;
+    if (t === undefined)
+        return config ?? {};
+    const observer = {
+        ...(t.target !== undefined ? { bind: { kind: "point", position: t.target } } : {}),
+        ...(t.distance !== undefined ? { distance: t.distance } : {}),
+        ...(t.height !== undefined ? { height: t.height } : {}),
+        ...(t.lookHeight !== undefined ? { lookHeight: t.lookHeight } : {}),
+        ...(t.orbitSpeed !== undefined ? { orbitSpeed: t.orbitSpeed } : {}),
+        ...(t.startAngle !== undefined ? { startAngle: t.startAngle } : {}),
+        ...(t.fov !== undefined ? { fov: t.fov } : {}),
+    };
+    return { ...config, observer };
+}

package/dist/camera/shakeChannel.d.ts

@@ -0,0 +1,29 @@
+import { shakeOffset, type ShakeOffset } from "./rigMath.js";
+export interface CameraShakeChannel {
+    /**
+     * Add a trauma impulse. `amplitude` is a 0..1 fraction (1 = a full boss slam);
+     * `decayPerSecond` optionally overrides how fast this and subsequent trauma
+     * bleed off. Any gameplay system (combat hitstop, explosions, vehicle crashes)
+     * can call this — the active rig reads the resulting shake every frame.
+     */
+    shake(amplitude: number, decayPerSecond?: number): void;
+    /** Advance decay + the shake clock (called once per frame by the mounted rig). */
+    step(dt: number): void;
+    /** Current positional + roll shake for the given tuning. */
+    sample(config?: Parameters<typeof shakeOffset>[1]): ShakeOffset;
+    /** Live trauma in [0,1] (for HUD/debug). */
+    trauma(): number;
+}
+export declare function createCameraShakeChannel(defaultDecayPerSecond?: number): CameraShakeChannel;
+/**
+ * Process-wide default channel. A shell mounts its own channel via
+ * `CameraShakeContext`, but game systems that have no React context (e.g. a
+ * `loop.onTick` reacting to `entity.died`) can import `cameraShake` and feed the
+ * default channel directly.
+ */
+export declare const defaultCameraShakeChannel: CameraShakeChannel;
+/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut). */
+export declare function cameraShake(amplitude: number, decayPerSecond?: number): void;
+export declare const CameraShakeContext: import("react").Context<CameraShakeChannel>;
+/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI. */
+export declare function useCameraShake(): CameraShakeChannel;