@jgengine/shell 0.10.0 → 0.11.0

package/dist/camera/inspectionCameraMath.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function resolveInspectionCameraConfig(config) {
     return {
         anchor: config?.anchor ?? "target",
@@ -24,7 +25,9 @@ export function resolveInspectionCameraConfig(config) {
         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. */
+/** 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.
+ * @internal
+ */
 export function seedInspectionCamera(config) {
     if (config.initialPosition !== null) {
         return { camera: config.initialPosition, target: config.target };
@@ -38,7 +41,9 @@ export function seedInspectionCamera(config) {
         target: config.target,
     };
 }
-/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag. */
+/** Maps the anchor mode onto three-stdlib OrbitControls' native `zoomToCursor` flag.
+ * @internal
+ */
 export function resolveInspectionZoomToCursor(anchor) {
     return anchor === "cursor";
 }

package/dist/camera/orbitCameraMath.d.ts

@@ -1,6 +1,10 @@
-/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane. */
+/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane.
+ * @internal
+ */
 export declare function orbitYawFromCamera(cameraX: number, cameraZ: number, targetX: number, targetZ: number): number;
-/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera. */
+/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera.
+ * @internal
+ */
 export declare function cameraLookPitch(camera: Vec3, target: Vec3): number;
 export interface Vec3 {
     x: number;
@@ -19,6 +23,12 @@ export interface OrbitCameraConfig {
     targetHeight?: number;
     initialDistance?: number;
     initialHeight?: number;
+    /** Initial horizontal facing of the boom (radians): 0 = camera behind on -Z, PI = camera on +Z. Seeds the rig when set; unset keeps the legacy -Z placement. */
+    initialYaw?: number;
+    /** Initial boom elevation (radians): 0 = level, positive = camera above the target looking down. Seeds the rig when set; unset derives elevation from `initialHeight`/`initialDistance`. */
+    initialPitch?: number;
+    /** Signed boom-elevation clamp `[min, max]` (radians): min < 0 dips below the target, max > 0 rises overhead. Maps onto `minPolarAngle`/`maxPolarAngle` (polar = PI/2 − pitch); explicit polar fields win. */
+    pitchClamp?: readonly [number, number];
     /** Extra offset applied on top of entity position for the orbit target. */
     targetOffset?: Partial<Vec3>;
     /** Keep orbit radius locked while the follow target moves. */
@@ -64,6 +74,8 @@ export interface ResolvedOrbitCameraConfig {
     targetHeight: number;
     initialDistance: number;
     initialHeight: number;
+    initialYaw?: number;
+    initialPitch?: number;
     targetOffset?: Partial<Vec3>;
     followLock: boolean;
     followEnabled: boolean;
@@ -87,22 +99,38 @@ export interface OrbitFollowRuntimeState {
     camera: Vec3;
     lockedDistance: number | null;
 }
-/** Frame-rate independent exponential smoothing factor in [0, 1]. */
+/** Frame-rate independent exponential smoothing factor in [0, 1].
+ * @internal
+ */
 export declare function smoothBlend(deltaSeconds: number, speed: number): number;
+/** @internal */
 export declare function resolveOrbitCameraConfig(patch?: OrbitCameraConfig): ResolvedOrbitCameraConfig;
+/**
+ * FOV that keeps a target's on-screen size constant as the spring-arm pulls the
+ * camera in. Widens the base FOV by the desired/pulled distance ratio; a no-op
+ * (returns the base) whenever the camera sits at or beyond its desired distance.
+  * @internal
+  */
+export declare function compensatedFov(baseFovDegrees: number, desiredDistance: number, pulledDistance: number): number;
+/** @internal */
 export declare function resolveTargetSmoothing(config: ResolvedOrbitCameraConfig, dragging: boolean): number;
+/** @internal */
 export declare function resolveFollowTargetFromPosition(position: readonly [number, number, number], config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset">): Vec3;
+/** @internal */
 export declare function lerpVec3(from: Vec3, to: Vec3, blend: number): Vec3;
+/** @internal */
 export declare function distanceBetween(a: Vec3, b: Vec3): number;
+/** @internal */
 export declare function seedOrbitFollowState(input: {
     entityPosition: readonly [number, number, number];
-    config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset" | "initialDistance" | "initialHeight">;
+    config: Pick<ResolvedOrbitCameraConfig, "targetHeight" | "targetOffset" | "initialDistance" | "initialHeight" | "initialYaw" | "initialPitch">;
 }): OrbitFollowRuntimeState;
 /**
  * Pure orbit follow step — smooth target tracking, camera carries target delta
  * (OrbitControls alone keeps camera fixed when only target moves), optional
  * distance lock. Call each frame before OrbitControls.update() in the shell.
- */
+  * @internal
+  */
 export declare function orbitFollowStep(input: {
     state: OrbitFollowRuntimeState;
     desiredTarget: Vec3;
@@ -112,7 +140,9 @@ export declare function orbitFollowStep(input: {
 }): OrbitFollowRuntimeState & {
     distance: number;
 };
-/** @deprecated Use orbitFollowStep — kept for older call sites. */
+/** @deprecated Use orbitFollowStep — kept for older call sites.
+ * @internal
+ */
 export declare function cameraFollowStep(input: {
     camera: Vec3;
     target: Vec3;

package/dist/camera/orbitCameraMath.js

@@ -1,10 +1,14 @@
-/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane. */
+/** Horizontal facing derived from an orbit camera orbiting a target on the XZ plane.
+ * @internal
+ */
 export function orbitYawFromCamera(cameraX, cameraZ, targetX, targetZ) {
     const dx = targetX - cameraX;
     const dz = targetZ - cameraZ;
     return Math.atan2(dx, dz);
 }
-/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera. */
+/** Elevation the camera looks along (radians): negative = aiming down, positive = aiming up, 0 = level. Feeds aim.pitch so vertical aim tracks the camera.
+ * @internal
+ */
 export function cameraLookPitch(camera, target) {
     const horizontal = Math.hypot(target.x - camera.x, target.z - camera.z);
     return Math.atan2(target.y - camera.y, horizontal);
@@ -31,23 +35,48 @@ export const DEFAULT_ORBIT_CAMERA = {
 export const GAME_SIM_FRAME_PRIORITY = 0;
 /** Orbit follow reads the latest entity pose after GAME_SIM_FRAME_PRIORITY. */
 export const ORBIT_CAMERA_FRAME_PRIORITY = -1;
-/** Frame-rate independent exponential smoothing factor in [0, 1]. */
+/** Frame-rate independent exponential smoothing factor in [0, 1].
+ * @internal
+ */
 export function smoothBlend(deltaSeconds, speed) {
     return 1 - Math.exp(-speed * deltaSeconds);
 }
+/** @internal */
 export function resolveOrbitCameraConfig(patch) {
-    return {
+    const resolved = {
         ...DEFAULT_ORBIT_CAMERA,
         ...patch,
         collision: { ...DEFAULT_ORBIT_CAMERA.collision, ...patch?.collision },
     };
+    if (patch?.pitchClamp !== undefined) {
+        const [minPitch, maxPitch] = patch.pitchClamp;
+        resolved.minPolarAngle = patch.minPolarAngle ?? Math.PI / 2 - maxPitch;
+        resolved.maxPolarAngle = patch.maxPolarAngle ?? Math.PI / 2 - minPitch;
+    }
+    return resolved;
 }
+/**
+ * FOV that keeps a target's on-screen size constant as the spring-arm pulls the
+ * camera in. Widens the base FOV by the desired/pulled distance ratio; a no-op
+ * (returns the base) whenever the camera sits at or beyond its desired distance.
+  * @internal
+  */
+export function compensatedFov(baseFovDegrees, desiredDistance, pulledDistance) {
+    if (pulledDistance <= 0 || desiredDistance <= 0 || pulledDistance >= desiredDistance) {
+        return baseFovDegrees;
+    }
+    const half = (baseFovDegrees * Math.PI) / 360;
+    const widened = 2 * Math.atan(Math.tan(half) * (desiredDistance / pulledDistance));
+    return Math.min((widened * 180) / Math.PI, 170);
+}
+/** @internal */
 export function resolveTargetSmoothing(config, dragging) {
     if (dragging) {
         return config.dragTargetSmoothing;
     }
     return config.targetSmoothing;
 }
+/** @internal */
 export function resolveFollowTargetFromPosition(position, config) {
     const offset = config.targetOffset;
     return {
@@ -56,6 +85,7 @@ export function resolveFollowTargetFromPosition(position, config) {
         z: position[2] + (offset?.z ?? 0),
     };
 }
+/** @internal */
 export function lerpVec3(from, to, blend) {
     return {
         x: from.x + (to.x - from.x) * blend,
@@ -63,14 +93,31 @@ export function lerpVec3(from, to, blend) {
         z: from.z + (to.z - from.z) * blend,
     };
 }
+/** @internal */
 export function distanceBetween(a, b) {
     const dx = a.x - b.x;
     const dy = a.y - b.y;
     const dz = a.z - b.z;
     return Math.sqrt(dx * dx + dy * dy + dz * dz);
 }
+/** @internal */
 export function seedOrbitFollowState(input) {
     const target = resolveFollowTargetFromPosition(input.entityPosition, input.config);
+    const { initialDistance, initialYaw, initialPitch } = input.config;
+    if (initialYaw !== undefined || initialPitch !== undefined) {
+        const yaw = initialYaw ?? 0;
+        const pitch = initialPitch ?? Math.atan2(input.config.initialHeight - input.config.targetHeight, initialDistance);
+        const horizontal = initialDistance * Math.cos(pitch);
+        return {
+            target,
+            camera: {
+                x: target.x - horizontal * Math.sin(yaw),
+                y: target.y + initialDistance * Math.sin(pitch),
+                z: target.z - horizontal * Math.cos(yaw),
+            },
+            lockedDistance: initialDistance,
+        };
+    }
     return {
         target,
         camera: {
@@ -85,7 +132,8 @@ export function seedOrbitFollowState(input) {
  * Pure orbit follow step — smooth target tracking, camera carries target delta
  * (OrbitControls alone keeps camera fixed when only target moves), optional
  * distance lock. Call each frame before OrbitControls.update() in the shell.
- */
+  * @internal
+  */
 export function orbitFollowStep(input) {
     const target = { ...input.state.target };
     const camera = { ...input.state.camera };
@@ -124,7 +172,9 @@ export function orbitFollowStep(input) {
     }
     return { target, camera, lockedDistance, distance: distanceBetween(camera, target) };
 }
-/** @deprecated Use orbitFollowStep — kept for older call sites. */
+/** @deprecated Use orbitFollowStep — kept for older call sites.
+ * @internal
+ */
 export function cameraFollowStep(input) {
     const state = {
         target: input.previousTarget ?? input.target,

package/dist/camera/rigMath.d.ts

@@ -6,12 +6,19 @@ export interface CameraPose {
     lookAt: Vec3;
     fov: number;
 }
+/** @internal */
 export declare function rtsPanKeysConflict(input: ActionCodesMap | undefined): boolean;
+/** @internal */
 export declare function clamp(value: number, min: number, max: number): number;
+/** @internal */
 export declare function lerp(from: number, to: number, blend: number): number;
+/** @internal */
 export declare function smoothstep(t: number): number;
+/** @internal */
 export declare function forwardVector(yaw: number): Vec3;
-/** Screen-right of a yaw: `forward × up` with up = +Y. */
+/** Screen-right of a yaw: `forward × up` with up = +Y.
+ * @internal
+ */
 export declare function rightVector(yaw: number): Vec3;
 export interface ResolvedTopDown {
     height: number;
@@ -20,15 +27,19 @@ export interface ResolvedTopDown {
     offset: Vec3;
     followSmoothing: number;
 }
+/** @internal */
 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.
- */
+  * @internal
+  */
 export declare function topDownPose(follow: Vec3, resolved: ResolvedTopDown, fov: number): CameraPose;
-/** Exponential spring-arm approach toward a desired point (frame-rate independent). */
+/** Exponential spring-arm approach toward a desired point (frame-rate independent).
+ * @internal
+ */
 export declare function springArmStep(current: Vec3, desired: Vec3, damping: number, dt: number): Vec3;
 export interface ResolvedSideScroll {
     axis: "x" | "z";
@@ -37,26 +48,38 @@ export interface ResolvedSideScroll {
     lookHeight: number;
     followSmoothing: number;
 }
+/** @internal */
 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. */
+/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing.
+ * @internal
+ */
 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.
- */
+  * @internal
+  */
 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`. */
+/** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`.
+ * @internal
+ */
 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)). */
+/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)).
+ * @internal
+ */
 export declare function yawTo(from: Vec3, to: Vec3): number;
-/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI]. */
+/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI].
+ * @internal
+ */
 export declare function angleDelta(a: number, b: number): number;
-/** Exponential yaw smoothing that respects wrap-around. */
+/** Exponential yaw smoothing that respects wrap-around.
+ * @internal
+ */
 export declare function smoothYaw(current: number, desired: number, speed: number, dt: number): number;
 export interface ResolvedShoulder {
     shoulderOffset: number;
@@ -64,20 +87,25 @@ export interface ResolvedShoulder {
     distance: number;
     fov: number;
 }
+/** @internal */
 export declare function resolveShoulder(config: ShoulderCameraConfig | undefined, aiming: boolean): ResolvedShoulder;
-/** Blend two shoulder framings by an ADS factor in [0,1]. */
+/** Blend two shoulder framings by an ADS factor in [0,1].
+ * @internal
+ */
 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.
- */
+  * @internal
+  */
 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`.
- */
+  * @internal
+  */
 export declare function lockOnPose(player: Vec3, target: Vec3, config: LockOnCameraConfig | undefined, fov: number): {
     pose: CameraPose;
     yaw: number;
@@ -94,10 +122,15 @@ export interface ResolvedChase {
     bankMax: number;
     bankDamping: number;
 }
+/** @internal */
 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`. */
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
+ * @internal
+ */
 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. */
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped.
+ * @internal
+ */
 export declare function bankRollStep(currentRoll: number, yaw: number, previousYaw: number, dt: number, resolved: ResolvedChase): number;
 export interface ResolvedObserver {
     distance: number;
@@ -105,14 +138,23 @@ export interface ResolvedObserver {
     lookHeight: number;
     orbitSpeed: number;
 }
+/** @internal */
 export declare function resolveObserver(config: ObserverCameraConfig | undefined): ResolvedObserver;
-/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input. */
+/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input.
+ * @internal
+ */
 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). */
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+ * @internal
+ */
 export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
-/** Look point ahead of / above a chased vehicle. */
+/** Look point ahead of / above a chased vehicle.
+ * @internal
+ */
 export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
-/** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle. */
+/** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle.
+ * @internal
+ */
 export declare function seatPose(follow: Vec3, yaw: number, local: {
     x?: number;
     y?: number;
@@ -122,10 +164,15 @@ export interface TraumaState {
     trauma: number;
     time: number;
 }
+/** @internal */
 export declare function createTrauma(): TraumaState;
-/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1. */
+/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1.
+ * @internal
+ */
 export declare function addTrauma(state: TraumaState, amount: number): void;
-/** Decay trauma linearly toward 0 and advance the shake clock. */
+/** Decay trauma linearly toward 0 and advance the shake clock.
+ * @internal
+ */
 export declare function stepTrauma(state: TraumaState, decayPerSecond: number, dt: number): void;
 export interface ShakeOffset {
     x: number;
@@ -136,14 +183,35 @@ export interface ShakeOffset {
  * 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).
- */
+  * @internal
+  */
 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). */
+/** Calibrated trauma decay for `traumaShake`/`impactPresets` (trauma/second). */
+export declare const CALIBRATED_TRAUMA_SHAKE_DECAY_PER_SECOND = 1.4;
+/** Calibrated positional shake amplitude at full trauma (world units) for `traumaShake`. */
+export declare const CALIBRATED_TRAUMA_SHAKE_MAX_OFFSET = 0.55;
+/** Calibrated rotational shake amplitude at full trauma (radians) for `traumaShake`. */
+export declare const CALIBRATED_TRAUMA_SHAKE_MAX_ROLL = 0.1;
+/** Calibrated shake noise frequency (Hz) for `traumaShake`. */
+export declare const CALIBRATED_TRAUMA_SHAKE_FREQUENCY = 32;
+/**
+ * Calibrated trauma² camera shake: offset scales with `trauma` squared using
+ * game-feel defaults (decay 1.4/s, max offset 0.55, max roll 0.1 rad, noise
+ * freq 32×t) — the curve `impactPresets` trauma values are calibrated
+ * against, so an impact "just looks right" without hand-tuning `shakeOffset`.
+ *
+ * @capability camera-shake calibrated trauma² camera kick with zero tuning
+  * @internal
+  */
+export declare function traumaShake(trauma: number, time?: number): ShakeOffset;
+/** Linear cross-fade between two full camera poses (position, lookAt, fov).
+ * @internal
+ */
 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. */
@@ -164,7 +232,8 @@ export interface ResolvedDirectedCamera {
  * (#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.
- */
+  * @internal
+  */
 export declare function resolveDirectedCamera(director: DirectorCameraValues | undefined, staticConfig: StaticCameraValues): ResolvedDirectedCamera;
 export interface CinematicSample {
     pose: CameraPose;
@@ -175,5 +244,6 @@ export interface CinematicSample {
  * 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).
- */
+  * @internal
+  */
 export declare function cinematicSample(keyframes: readonly CameraKeyframe[], elapsed: number, loop: boolean, fallbackFov: number): CinematicSample;