@jgengine/shell 0.8.0 → 0.9.0

package/dist/camera/cameraRigs.js

@@ -4,8 +4,11 @@ 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, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothstep, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
+import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
+import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
+import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.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;
 function isPerspective(camera) {
@@ -47,45 +50,35 @@ function readFollow(ctx, followId) {
 function useCameraCommit(props, followId) {
     const camera = useThree((state) => state.camera);
     const shake = useCameraShake();
+    const playerFov = usePlayerFov();
     const shakeConfig = props.config?.shake;
     const transitionSeconds = props.config?.transitionSeconds ?? 0.6;
-    const blendRef = useRef(null);
+    const blendScratchRef = useRef(createCameraBlendScratch(Vector3, Quaternion));
+    const blendingRef = useRef(false);
     const lastPoseRef = useRef(null);
     const farWarnedRef = useRef(false);
     const beginTransition = () => {
         if (transitionSeconds <= 0)
             return;
-        blendRef.current = {
-            position: camera.position.clone(),
-            quaternion: camera.quaternion.clone(),
-            fov: currentFov(camera),
-            elapsed: 0,
-            duration: transitionSeconds,
-        };
+        captureCameraBlendFrom(blendScratchRef.current, camera.position, camera.quaternion, currentFov(camera), transitionSeconds);
+        blendingRef.current = true;
     };
     const commit = (pose, dt) => {
-        lastPoseRef.current = pose;
-        applyPose(camera, pose);
+        const composed = {
+            ...pose,
+            fov: playerFov.compose(pose.fov, props.absoluteFov === true ? "absolute" : "relative"),
+        };
+        lastPoseRef.current = composed;
+        applyPose(camera, composed);
         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;
-            const t = blend.duration <= 0 ? 1 : Math.min(blend.elapsed / blend.duration, 1);
-            const eased = smoothstep(t);
-            const targetPos = camera.position.clone();
-            const targetQuat = camera.quaternion.clone();
-            camera.position.lerpVectors(blend.position, targetPos, eased);
-            camera.quaternion.slerpQuaternions(blend.quaternion, targetQuat, eased);
-            if (isPerspective(camera)) {
-                camera.fov = blend.fov + (pose.fov - blend.fov) * eased;
-                camera.updateProjectionMatrix();
-            }
-            if (t >= 1)
-                blendRef.current = null;
+        if (blendingRef.current) {
+            const done = applyCameraBlendStep(blendScratchRef.current, camera, composed.fov, dt);
+            if (done)
+                blendingRef.current = false;
         }
         shake.step(dt);
         const offset = shake.sample(shakeConfig);
@@ -96,9 +89,9 @@ function useCameraCommit(props, followId) {
         }
         props.config?.onCameraFollow?.({
             entityId: followId ?? "",
-            target: pose.lookAt,
+            target: composed.lookAt,
             camera: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
-            distance: Math.hypot(camera.position.x - pose.lookAt.x, camera.position.y - pose.lookAt.y, camera.position.z - pose.lookAt.z),
+            distance: Math.hypot(camera.position.x - composed.lookAt.x, camera.position.y - composed.lookAt.y, camera.position.z - composed.lookAt.z),
         });
     };
     return { camera, commit, beginTransition };
@@ -425,21 +418,28 @@ export function ChaseRig(props) {
     const ctx = useGameContext();
     const followId = resolveFollowId(props.followEntityId, userId);
     const config = props.config?.chase;
-    const resolved = useMemo(() => resolveChase(config), [config]);
-    const { commit, beginTransition } = useCameraCommit(props, followId);
+    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 rollRef = useRef(0);
     const view = config?.view ?? "chase";
     useEffect(beginTransition, [view]);
     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 fov = speedToFov(speed, config?.fov);
+        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);
         if (view !== "chase") {
             const seat = view === "cockpit"
                 ? config?.seatOffsets?.cockpit ?? { x: 0, y: 1.2, z: 0.1 }
@@ -454,15 +454,18 @@ export function ChaseRig(props) {
             commit(pose, dt);
             return;
         }
-        const desired = chaseDesiredPosition(follow, yaw, resolved);
+        const led = leadFollowPoint(follow, last, dt, resolved);
+        const desired = chaseDesiredPosition(led, yaw, 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(follow, yaw, resolved), fov };
+        const pose = { position: smoothed, lookAt: chaseLookAt(led, yaw, resolved), fov };
         commit(pose, dt);
+        if (rollRef.current !== 0)
+            camera.rotateZ(rollRef.current);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }

package/dist/camera/fovPreference.d.ts

@@ -0,0 +1,25 @@
+export declare const PLAYER_FOV_DEFAULT: 55;
+export declare const PLAYER_FOV_MIN = 40;
+export declare const PLAYER_FOV_MAX = 120;
+export declare const PLAYER_FOV_STORAGE_KEY = "jgengine:player-fov";
+export interface PlayerFovBounds {
+    min: number;
+    max: number;
+    defaultFov: number;
+}
+export declare function resolvePlayerFovBounds(options?: {
+    min?: number;
+    max?: number;
+    default?: number;
+}): PlayerFovBounds;
+export declare function clampPlayerFov(value: unknown, min?: number, max?: number): number;
+export declare function loadPlayerFov(bounds?: PlayerFovBounds, storage?: Pick<Storage, "getItem"> | null | undefined): number;
+export declare function savePlayerFov(value: number, bounds?: PlayerFovBounds, storage?: Pick<Storage, "setItem"> | null | undefined): number;
+/**
+ * Composition model for perspective rigs:
+ * - preference is the player base FOV
+ * - poseFov is the rig's authored FOV (includes chase-speed modulation, ADS zoom, transitions)
+ * - relative mode shifts the authored FOV by (preference − default) so mods still stack
+ * - absolute mode (cinematic keyframes) keeps the authored FOV as-is
+ */
+export declare function composePlayerFov(preference: number, poseFov: number, mode?: "relative" | "absolute", bounds?: PlayerFovBounds): number;

package/dist/camera/fovPreference.js

@@ -0,0 +1,73 @@
+import { CAMERA_FRUSTUM_DEFAULTS } from "@jgengine/core/game/playableGame";
+export const PLAYER_FOV_DEFAULT = CAMERA_FRUSTUM_DEFAULTS.fov;
+export const PLAYER_FOV_MIN = 40;
+export const PLAYER_FOV_MAX = 120;
+export const PLAYER_FOV_STORAGE_KEY = "jgengine:player-fov";
+export function resolvePlayerFovBounds(options) {
+    const min = Number.isFinite(options?.min) ? options.min : PLAYER_FOV_MIN;
+    const max = Number.isFinite(options?.max) ? options.max : PLAYER_FOV_MAX;
+    const lo = Math.min(min, max);
+    const hi = Math.max(min, max);
+    const defaultFov = clampPlayerFov(options?.default ?? PLAYER_FOV_DEFAULT, lo, hi);
+    return { min: lo, max: hi, defaultFov };
+}
+export function clampPlayerFov(value, min = PLAYER_FOV_MIN, max = PLAYER_FOV_MAX) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return clampPlayerFov(PLAYER_FOV_DEFAULT, min, max);
+    if (value < min)
+        return min;
+    if (value > max)
+        return max;
+    return value;
+}
+export function loadPlayerFov(bounds = resolvePlayerFovBounds(), storage = defaultStorage()) {
+    if (storage == null)
+        return bounds.defaultFov;
+    try {
+        const raw = storage.getItem(PLAYER_FOV_STORAGE_KEY);
+        if (raw === null)
+            return bounds.defaultFov;
+        return clampPlayerFov(Number(raw), bounds.min, bounds.max);
+    }
+    catch {
+        return bounds.defaultFov;
+    }
+}
+export function savePlayerFov(value, bounds = resolvePlayerFovBounds(), storage = defaultStorage()) {
+    const next = clampPlayerFov(value, bounds.min, bounds.max);
+    if (storage == null)
+        return next;
+    try {
+        storage.setItem(PLAYER_FOV_STORAGE_KEY, String(next));
+    }
+    catch {
+        /* ignore quota / private-mode failures */
+    }
+    return next;
+}
+/**
+ * Composition model for perspective rigs:
+ * - preference is the player base FOV
+ * - poseFov is the rig's authored FOV (includes chase-speed modulation, ADS zoom, transitions)
+ * - relative mode shifts the authored FOV by (preference − default) so mods still stack
+ * - absolute mode (cinematic keyframes) keeps the authored FOV as-is
+ */
+export function composePlayerFov(preference, poseFov, mode = "relative", bounds = resolvePlayerFovBounds()) {
+    if (mode === "absolute")
+        return clampPlayerFov(poseFov, bounds.min, bounds.max);
+    const pref = clampPlayerFov(preference, bounds.min, bounds.max);
+    if (!Number.isFinite(poseFov))
+        return pref;
+    return clampPlayerFov(pref + (poseFov - PLAYER_FOV_DEFAULT), bounds.min, bounds.max);
+}
+function defaultStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}

package/dist/camera/index.d.ts

@@ -2,7 +2,10 @@ export { GameOrbitCamera, type CameraFollowListener, type GameOrbitCameraProps }
 export { GameFirstPersonCamera, type GameFirstPersonCameraProps } from "./GameFirstPersonCamera.js";
 export { GameInspectionCamera, type GameInspectionCameraProps } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind, type GameCameraRigProps } from "./GameCameraRig.js";
+export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, type PlayerFovState, } from "./PlayerFov.js";
+export { PLAYER_FOV_DEFAULT, PLAYER_FOV_MAX, PLAYER_FOV_MIN, PLAYER_FOV_STORAGE_KEY, clampPlayerFov, composePlayerFov, loadPlayerFov, resolvePlayerFovBounds, savePlayerFov, type PlayerFovBounds, } from "./fovPreference.js";
 export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, SideScrollRig, TopDownRig, type RigProps, } from "./cameraRigs.js";
+export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, type CameraBlendScratch, } from "./cameraBlendMath.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, 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";

package/dist/camera/index.js

@@ -2,7 +2,10 @@ export { GameOrbitCamera } from "./GameOrbitCamera.js";
 export { GameFirstPersonCamera } from "./GameFirstPersonCamera.js";
 export { GameInspectionCamera } from "./GameInspectionCamera.js";
 export { GameCameraRig, resolveRigKind } from "./GameCameraRig.js";
+export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, } from "./PlayerFov.js";
+export { PLAYER_FOV_DEFAULT, PLAYER_FOV_MAX, PLAYER_FOV_MIN, PLAYER_FOV_STORAGE_KEY, clampPlayerFov, composePlayerFov, loadPlayerFov, resolvePlayerFovBounds, savePlayerFov, } from "./fovPreference.js";
 export { CAMERA_POST_FRAME_PRIORITY, CAMERA_RIG_FRAME_PRIORITY, ChaseRig, CinematicRig, LockOnRig, ObserverRig, RtsRig, ShoulderRig, SideScrollRig, TopDownRig, } from "./cameraRigs.js";
+export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.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, 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";

package/dist/camera/rigMath.d.ts

@@ -11,6 +11,7 @@ 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;
+/** Screen-right of a yaw: `forward × up` with up = +Y. */
 export declare function rightVector(yaw: number): Vec3;
 export interface ResolvedTopDown {
     height: number;
@@ -87,8 +88,17 @@ export interface ResolvedChase {
     lookHeight: number;
     springDamping: number;
     shakePerSpeed: number;
+    leadTime: number;
+    leadMax: number;
+    bankPerYawRate: number;
+    bankMax: number;
+    bankDamping: number;
 }
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+export declare function leadFollowPoint(follow: Vec3, previous: Vec3, dt: number, resolved: ResolvedChase): Vec3;
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+export declare function bankRollStep(currentRoll: number, yaw: number, previousYaw: number, dt: number, resolved: ResolvedChase): number;
 export interface ResolvedObserver {
     distance: number;
     height: number;

package/dist/camera/rigMath.js

@@ -24,8 +24,9 @@ export function smoothstep(t) {
 export function forwardVector(yaw) {
     return { x: Math.sin(yaw), y: 0, z: Math.cos(yaw) };
 }
+/** Screen-right of a yaw: `forward × up` with up = +Y. */
 export function rightVector(yaw) {
-    return { x: Math.cos(yaw), y: 0, z: -Math.sin(yaw) };
+    return { x: -Math.cos(yaw), y: 0, z: Math.sin(yaw) };
 }
 export function resolveTopDown(config) {
     return {
@@ -207,8 +208,42 @@ export function resolveChase(config) {
         lookHeight: config?.lookHeight ?? 1.2,
         springDamping: config?.springDamping ?? 6,
         shakePerSpeed: config?.shakePerSpeed ?? 0,
+        leadTime: config?.lead?.time ?? 0,
+        leadMax: config?.lead?.max ?? 4,
+        bankPerYawRate: config?.bank?.perYawRate ?? 0,
+        bankMax: config?.bank?.max ?? 0.35,
+        bankDamping: config?.bank?.damping ?? 8,
     };
 }
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+export function leadFollowPoint(follow, previous, dt, resolved) {
+    if (resolved.leadTime <= 0 || dt <= 0)
+        return follow;
+    let leadX = ((follow.x - previous.x) / dt) * resolved.leadTime;
+    let leadZ = ((follow.z - previous.z) / dt) * resolved.leadTime;
+    const magnitude = Math.hypot(leadX, leadZ);
+    if (magnitude > resolved.leadMax) {
+        leadX *= resolved.leadMax / magnitude;
+        leadZ *= resolved.leadMax / magnitude;
+    }
+    return { x: follow.x + leadX, y: follow.y, z: follow.z + leadZ };
+}
+function wrapAngle(angle) {
+    let wrapped = angle;
+    while (wrapped > Math.PI)
+        wrapped -= Math.PI * 2;
+    while (wrapped < -Math.PI)
+        wrapped += Math.PI * 2;
+    return wrapped;
+}
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+export function bankRollStep(currentRoll, yaw, previousYaw, dt, resolved) {
+    if (resolved.bankPerYawRate <= 0)
+        return 0;
+    const yawRate = dt > 0 ? wrapAngle(yaw - previousYaw) / dt : 0;
+    const target = clamp(-yawRate * resolved.bankPerYawRate, -resolved.bankMax, resolved.bankMax);
+    return currentRoll + (target - currentRoll) * Math.min(1, resolved.bankDamping * dt);
+}
 export function resolveObserver(config) {
     return {
         distance: config?.distance ?? 8,

package/dist/camera/shakeChannel.d.ts

@@ -1,20 +1,6 @@
-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;
+import { type CameraShakeChannel } from "./shakeChannelMath.js";
+export type { CameraShakeChannel } from "./shakeChannelMath.js";
+export { createCameraShakeChannel } from "./shakeChannelMath.js";
 /**
  * Process-wide default channel. A shell mounts its own channel via
  * `CameraShakeContext`, but game systems that have no React context (e.g. a

package/dist/camera/shakeChannel.js

@@ -1,25 +1,6 @@
 import { createContext, useContext } from "react";
-import { addTrauma, createTrauma, shakeOffset, stepTrauma } from "./rigMath.js";
-export function createCameraShakeChannel(defaultDecayPerSecond = 1.6) {
-    const state = createTrauma();
-    let decay = defaultDecayPerSecond;
-    return {
-        shake(amplitude, decayPerSecond) {
-            if (decayPerSecond !== undefined)
-                decay = decayPerSecond;
-            addTrauma(state, amplitude);
-        },
-        step(dt) {
-            stepTrauma(state, decay, dt);
-        },
-        sample(config) {
-            return shakeOffset(state, config);
-        },
-        trauma() {
-            return state.trauma;
-        },
-    };
-}
+import { createCameraShakeChannel, } from "./shakeChannelMath.js";
+export { createCameraShakeChannel } from "./shakeChannelMath.js";
 /**
  * Process-wide default channel. A shell mounts its own channel via
  * `CameraShakeContext`, but game systems that have no React context (e.g. a

package/dist/camera/shakeChannelMath.d.ts

@@ -0,0 +1,8 @@
+import { shakeOffset, type ShakeOffset } from "./rigMath.js";
+export interface CameraShakeChannel {
+    shake(amplitude: number, decayPerSecond?: number): void;
+    step(dt: number): void;
+    sample(config?: Parameters<typeof shakeOffset>[1]): ShakeOffset;
+    trauma(): number;
+}
+export declare function createCameraShakeChannel(defaultDecayPerSecond?: number): CameraShakeChannel;

package/dist/camera/shakeChannelMath.js

@@ -0,0 +1,21 @@
+import { addTrauma, createTrauma, shakeOffset, stepTrauma } from "./rigMath.js";
+export function createCameraShakeChannel(defaultDecayPerSecond = 1.6) {
+    const state = createTrauma();
+    let decay = defaultDecayPerSecond;
+    return {
+        shake(amplitude, decayPerSecond) {
+            if (decayPerSecond !== undefined)
+                decay = decayPerSecond;
+            addTrauma(state, amplitude);
+        },
+        step(dt) {
+            stepTrauma(state, decay, dt);
+        },
+        sample(config) {
+            return shakeOffset(state, config);
+        },
+        trauma() {
+            return state.trauma;
+        },
+    };
+}

package/dist/cartridge.d.ts

@@ -0,0 +1,145 @@
+import { type ComponentType } from "react";
+import { type CartridgeSpec } from "@jgengine/core/cartridge/spec";
+import type { AbilitySlotState } from "@jgengine/core/combat/abilityKit";
+import type { HudAnchor } from "@jgengine/core/ui/hudLayout";
+import { type GameConfig } from "./defineGame.js";
+import type { PlayableGame } from "./registry.js";
+export type CartridgePanelItem = {
+    kind: "vital";
+    stat: string;
+    label: string;
+    tone?: string;
+    width?: number;
+} | {
+    kind: "xp";
+    width?: number;
+} | {
+    kind: "timer";
+    label: string;
+} | {
+    kind: "score";
+    source: "kills";
+    label: string;
+    digits?: number;
+} | {
+    kind: "abilityBar";
+    icons: Record<string, string>;
+} | {
+    kind: "component";
+    Component: ComponentType;
+};
+export interface CartridgeHudPanelSpec {
+    id: string;
+    anchor: HudAnchor;
+    inset?: {
+        x: number;
+        y: number;
+    };
+    items: readonly CartridgePanelItem[];
+}
+export type CartridgeResultLine = {
+    label: string;
+    accent?: boolean;
+} & ({
+    source: "kills" | "level";
+} | {
+    value: string | number;
+});
+export interface CartridgeScreens {
+    start?: {
+        title: string;
+        subtitle?: string;
+        buttonLabel?: string;
+    };
+    win?: {
+        title: string;
+        lines: readonly CartridgeResultLine[];
+    };
+    lose?: {
+        title: string;
+        subtitle?: string;
+    };
+}
+export interface CartridgeAbilitySlot {
+    id: string;
+    icon: string;
+    state: AbilitySlotState;
+    cooldownFraction: number;
+    justCast: boolean;
+}
+export interface CartridgePanels {
+    Vital: ComponentType<{
+        value: {
+            current: number;
+            max: number;
+            min?: number;
+        };
+        label: string;
+        tone?: string;
+        width?: number;
+    }>;
+    Xp: ComponentType<{
+        fraction: number;
+        level?: number;
+        width?: number;
+    }>;
+    Timer: ComponentType<{
+        seconds: number;
+        label: string;
+    }>;
+    Score: ComponentType<{
+        value: number;
+        label: string;
+        digits?: number;
+    }>;
+    AbilityBar: ComponentType<{
+        slots: readonly CartridgeAbilitySlot[];
+    }>;
+    DraftModal: ComponentType<{
+        offers: readonly {
+            id: string;
+            label: string;
+        }[];
+        choose(id: string): void;
+    }>;
+    StartScreen: ComponentType<{
+        title: string;
+        subtitle?: string;
+        buttonLabel?: string;
+        begin(): void;
+    }>;
+    Countdown: ComponentType<{
+        seconds: number;
+    }>;
+    WinScreen: ComponentType<{
+        title: string;
+        lines: readonly {
+            label: string;
+            value: string | number;
+            accent?: boolean;
+        }[];
+    }>;
+    LoseScreen: ComponentType<{
+        title: string;
+        subtitle?: string;
+    }>;
+}
+export type CartridgeConfig = CartridgeSpec & {
+    name: string;
+    panels: CartridgePanels;
+    hud: {
+        storageKey?: string;
+        panels: readonly CartridgeHudPanelSpec[];
+    };
+    screens: CartridgeScreens;
+    theme?: Record<string, string>;
+    world?: GameConfig["world"];
+    physics?: GameConfig["physics"];
+    assets?: GameConfig["assets"];
+    save?: GameConfig["save"];
+    camera?: GameConfig["camera"];
+    entitySprites?: GameConfig["entitySprites"];
+    worldItem?: GameConfig["worldItem"];
+    settings?: GameConfig["settings"];
+};
+export declare function cartridge(config: CartridgeConfig): PlayableGame;