@jgengine/shell 0.10.0 → 0.11.0

package/dist/camera/rigMath.js

@@ -6,28 +6,36 @@ function actionCodeList(codes) {
     const modes = codes;
     return [...(modes.hold ?? []), ...(modes.toggle ?? [])];
 }
+/** @internal */
 export function rtsPanKeysConflict(input) {
     if (input === undefined)
         return false;
     return Object.values(input).some((codes) => actionCodeList(codes).some((code) => RTS_WASD_CODES.includes(code)));
 }
+/** @internal */
 export function clamp(value, min, max) {
     return value < min ? min : value > max ? max : value;
 }
+/** @internal */
 export function lerp(from, to, blend) {
     return from + (to - from) * blend;
 }
+/** @internal */
 export function smoothstep(t) {
     const clamped = clamp(t, 0, 1);
     return clamped * clamped * (3 - 2 * clamped);
 }
+/** @internal */
 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. */
+/** Screen-right of a yaw: `forward × up` with up = +Y.
+ * @internal
+ */
 export function rightVector(yaw) {
     return { x: -Math.cos(yaw), y: 0, z: Math.sin(yaw) };
 }
+/** @internal */
 export function resolveTopDown(config) {
     return {
         height: config?.height ?? 18,
@@ -46,7 +54,8 @@ export function resolveTopDown(config) {
  * 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 function topDownPose(follow, resolved, fov) {
     const lookAt = {
         x: follow.x + resolved.offset.x,
@@ -65,10 +74,13 @@ export function topDownPose(follow, resolved, fov) {
         fov,
     };
 }
-/** Exponential spring-arm approach toward a desired point (frame-rate independent). */
+/** Exponential spring-arm approach toward a desired point (frame-rate independent).
+ * @internal
+ */
 export function springArmStep(current, desired, damping, dt) {
     return lerpVec3(current, desired, smoothBlend(dt, damping));
 }
+/** @internal */
 export function resolveSideScroll(config) {
     return {
         axis: config?.axis ?? "x",
@@ -78,7 +90,9 @@ export function resolveSideScroll(config) {
         followSmoothing: config?.followSmoothing ?? 8,
     };
 }
-/** 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 function sideScrollFollowBlend(followSmoothing, dt) {
     return followSmoothing <= 0 ? 1 : smoothBlend(dt, followSmoothing);
 }
@@ -86,7 +100,8 @@ export function sideScrollFollowBlend(followSmoothing, dt) {
  * 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 function resolveSideScrollPose(entityPos, resolved, fov) {
     const perpendicular = resolved.axis === "x" ? { x: 0, y: 0, z: 1 } : { x: 1, y: 0, z: 0 };
     return {
@@ -99,7 +114,9 @@ export function resolveSideScrollPose(entityPos, resolved, fov) {
         fov,
     };
 }
-/** 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 function speedToFov(speed, curve) {
     const base = curve?.base ?? 55;
     const max = curve?.max ?? 78;
@@ -108,11 +125,15 @@ export function speedToFov(speed, curve) {
         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)). */
+/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)).
+ * @internal
+ */
 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]. */
+/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI].
+ * @internal
+ */
 export function angleDelta(a, b) {
     let delta = (b - a) % (Math.PI * 2);
     if (delta > Math.PI)
@@ -121,10 +142,13 @@ export function angleDelta(a, b) {
         delta += Math.PI * 2;
     return delta;
 }
-/** Exponential yaw smoothing that respects wrap-around. */
+/** Exponential yaw smoothing that respects wrap-around.
+ * @internal
+ */
 export function smoothYaw(current, desired, speed, dt) {
     return current + angleDelta(current, desired) * smoothBlend(dt, speed);
 }
+/** @internal */
 export function resolveShoulder(config, aiming) {
     const hip = {
         shoulderOffset: config?.shoulderOffset ?? 0.6,
@@ -142,7 +166,9 @@ export function resolveShoulder(config, aiming) {
         fov: ads?.fov ?? hip.fov * 0.75,
     };
 }
-/** Blend two shoulder framings by an ADS factor in [0,1]. */
+/** Blend two shoulder framings by an ADS factor in [0,1].
+ * @internal
+ */
 export function blendShoulder(hip, ads, t) {
     return {
         shoulderOffset: lerp(hip.shoulderOffset, ads.shoulderOffset, t),
@@ -155,7 +181,8 @@ export function blendShoulder(hip, ads, 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.
- */
+  * @internal
+  */
 export function shoulderPose(follow, yaw, pitch, sideSign, shoulder) {
     const forward = forwardVector(yaw);
     const right = rightVector(yaw);
@@ -181,7 +208,8 @@ export function shoulderPose(follow, yaw, pitch, sideSign, shoulder) {
  * 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 function lockOnPose(player, target, config, fov) {
     const distance = config?.distance ?? 5;
     const height = config?.height ?? 2.4;
@@ -201,6 +229,7 @@ export function lockOnPose(player, target, config, fov) {
     };
     return { pose: { position, lookAt: focus, fov }, yaw };
 }
+/** @internal */
 export function resolveChase(config) {
     return {
         distance: config?.distance ?? 6,
@@ -215,7 +244,9 @@ export function resolveChase(config) {
         bankDamping: config?.bank?.damping ?? 8,
     };
 }
-/** 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 function leadFollowPoint(follow, previous, dt, resolved) {
     if (resolved.leadTime <= 0 || dt <= 0)
         return follow;
@@ -236,7 +267,9 @@ function wrapAngle(angle) {
         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. */
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped.
+ * @internal
+ */
 export function bankRollStep(currentRoll, yaw, previousYaw, dt, resolved) {
     if (resolved.bankPerYawRate <= 0)
         return 0;
@@ -244,6 +277,7 @@ export function bankRollStep(currentRoll, yaw, previousYaw, dt, resolved) {
     const target = clamp(-yawRate * resolved.bankPerYawRate, -resolved.bankMax, resolved.bankMax);
     return currentRoll + (target - currentRoll) * Math.min(1, resolved.bankDamping * dt);
 }
+/** @internal */
 export function resolveObserver(config) {
     return {
         distance: config?.distance ?? 8,
@@ -252,7 +286,9 @@ export function resolveObserver(config) {
         orbitSpeed: config?.orbitSpeed ?? 0.2,
     };
 }
-/** 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 function observerPose(subject, angle, resolved, fov) {
     const position = {
         x: subject.x + Math.sin(angle) * resolved.distance,
@@ -265,7 +301,9 @@ export function observerPose(subject, angle, resolved, fov) {
         fov,
     };
 }
-/** 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 function chaseDesiredPosition(follow, yaw, resolved) {
     const back = forwardVector(yaw);
     return {
@@ -274,7 +312,9 @@ export function chaseDesiredPosition(follow, yaw, resolved) {
         z: follow.z - back.z * resolved.distance,
     };
 }
-/** Look point ahead of / above a chased vehicle. */
+/** Look point ahead of / above a chased vehicle.
+ * @internal
+ */
 export function chaseLookAt(follow, yaw, resolved) {
     const forward = forwardVector(yaw);
     return {
@@ -283,7 +323,9 @@ export function chaseLookAt(follow, yaw, resolved) {
         z: follow.z + forward.z * 2,
     };
 }
-/** 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 function seatPose(follow, yaw, local, fov) {
     const forward = forwardVector(yaw);
     const right = rightVector(yaw);
@@ -301,14 +343,19 @@ export function seatPose(follow, yaw, local, fov) {
         fov,
     };
 }
+/** @internal */
 export function createTrauma() {
     return { trauma: 0, time: 0 };
 }
-/** 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 function addTrauma(state, amount) {
     state.trauma = clamp(state.trauma + amount, 0, 1);
 }
-/** Decay trauma linearly toward 0 and advance the shake clock. */
+/** Decay trauma linearly toward 0 and advance the shake clock.
+ * @internal
+ */
 export function stepTrauma(state, decayPerSecond, dt) {
     state.time += dt;
     state.trauma = clamp(state.trauma - decayPerSecond * dt, 0, 1);
@@ -321,7 +368,8 @@ function hashNoise(seed, time, frequency) {
  * 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 function shakeOffset(state, config) {
     const maxOffset = config?.maxOffset ?? 0.5;
     const maxRoll = config?.maxRoll ?? 0.06;
@@ -336,7 +384,33 @@ export function shakeOffset(state, config) {
         roll: maxRoll * shake * hashNoise(3, state.time, frequency),
     };
 }
-/** Linear cross-fade between two full camera poses (position, lookAt, fov). */
+/** Calibrated trauma decay for `traumaShake`/`impactPresets` (trauma/second). */
+export const CALIBRATED_TRAUMA_SHAKE_DECAY_PER_SECOND = 1.4;
+/** Calibrated positional shake amplitude at full trauma (world units) for `traumaShake`. */
+export const CALIBRATED_TRAUMA_SHAKE_MAX_OFFSET = 0.55;
+/** Calibrated rotational shake amplitude at full trauma (radians) for `traumaShake`. */
+export const CALIBRATED_TRAUMA_SHAKE_MAX_ROLL = 0.1;
+/** Calibrated shake noise frequency (Hz) for `traumaShake`. */
+export 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 function traumaShake(trauma, time = 0) {
+    return shakeOffset({ trauma: clamp(trauma, 0, 1), time }, {
+        maxOffset: CALIBRATED_TRAUMA_SHAKE_MAX_OFFSET,
+        maxRoll: CALIBRATED_TRAUMA_SHAKE_MAX_ROLL,
+        frequency: CALIBRATED_TRAUMA_SHAKE_FREQUENCY,
+    });
+}
+/** Linear cross-fade between two full camera poses (position, lookAt, fov).
+ * @internal
+ */
 export function crossfadePose(from, to, t) {
     const blend = clamp(t, 0, 1);
     return {
@@ -350,7 +424,8 @@ export function crossfadePose(from, to, t) {
  * (#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 function resolveDirectedCamera(director, staticConfig) {
     const directedFollow = director?.followEntityId;
     const followEntityId = directedFollow === undefined ? staticConfig.followEntityId : directedFollow;
@@ -363,7 +438,8 @@ export function resolveDirectedCamera(director, staticConfig) {
  * 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 function cinematicSample(keyframes, elapsed, loop, fallbackFov) {
     if (keyframes.length === 0) {
         const zero = { x: 0, y: 0, z: 0 };

package/dist/camera/rigResolve.d.ts

@@ -6,10 +6,12 @@ import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playab
  * 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.
- */
+  * @internal
+  */
 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.
- */
+  * @internal
+  */
 export declare function turntableAsObserver(config: GameCameraConfig | undefined): GameCameraConfig;

package/dist/camera/rigResolve.js

@@ -5,7 +5,8 @@
  * 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.
- */
+  * @internal
+  */
 export function resolveRigKind(config) {
     if (config?.rig !== undefined)
         return config.rig;
@@ -34,7 +35,8 @@ export function resolveRigKind(config) {
 /**
  * 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.
- */
+  * @internal
+  */
 export function turntableAsObserver(config) {
     const t = config?.turntable;
     if (t === undefined)

package/dist/camera/shakeChannel.d.ts

@@ -8,8 +8,12 @@ export { createCameraShakeChannel } from "./shakeChannelMath.js";
  * default channel directly.
  */
 export declare const defaultCameraShakeChannel: CameraShakeChannel;
-/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut). */
+/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut).
+ * @internal
+ */
 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. */
+/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI.
+ * @internal
+ */
 export declare function useCameraShake(): CameraShakeChannel;

package/dist/camera/shakeChannel.js

@@ -8,12 +8,16 @@ export { createCameraShakeChannel } from "./shakeChannelMath.js";
  * default channel directly.
  */
 export const defaultCameraShakeChannel = createCameraShakeChannel();
-/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut). */
+/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut).
+ * @internal
+ */
 export function cameraShake(amplitude, decayPerSecond) {
     defaultCameraShakeChannel.shake(amplitude, decayPerSecond);
 }
 export const CameraShakeContext = createContext(defaultCameraShakeChannel);
-/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI. */
+/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI.
+ * @internal
+ */
 export function useCameraShake() {
     return useContext(CameraShakeContext);
 }

package/dist/camera/shakeChannelMath.d.ts

@@ -5,4 +5,5 @@ export interface CameraShakeChannel {
     sample(config?: Parameters<typeof shakeOffset>[1]): ShakeOffset;
     trauma(): number;
 }
+/** @internal */
 export declare function createCameraShakeChannel(defaultDecayPerSecond?: number): CameraShakeChannel;

package/dist/camera/shakeChannelMath.js

@@ -1,4 +1,5 @@
 import { addTrauma, createTrauma, shakeOffset, stepTrauma } from "./rigMath.js";
+/** @internal */
 export function createCameraShakeChannel(defaultDecayPerSecond = 1.6) {
     const state = createTrauma();
     let decay = defaultDecayPerSecond;

package/dist/cartridge/runtime.d.ts

@@ -0,0 +1,15 @@
+import { type AbilityKit } from "@jgengine/core/combat/abilityKit";
+import type { GameLoop } from "@jgengine/core/game/defineGame";
+import type { GameContext, GameContextContent } from "@jgengine/core/runtime/gameContext";
+import { type CartridgeRun, type CartridgeSpec } from "./spec.js";
+export interface CartridgeRuntime {
+    content: GameContextContent;
+    loop: GameLoop<GameContext>;
+    run(ctx: GameContext): CartridgeRun;
+    weaponKit(ctx: GameContext): AbilityKit;
+    chooseUpgrade(ctx: GameContext, offerId: string): void;
+    begin(ctx: GameContext): void;
+    reset(ctx: GameContext): void;
+    spec: CartridgeSpec;
+}
+export declare function createCartridge(spec: CartridgeSpec): CartridgeRuntime;