@jgengine/core 0.18.1 → 0.21.0

package/dist/combat/regenShield.d.ts

@@ -31,6 +31,14 @@ export interface RegenShieldConfig {
      */
     pool?: RegenShieldPool;
 }
+/** Complete mutable shield state, including pending external damage detection. */
+export interface RegenShieldState {
+    max: number;
+    current: number;
+    sinceDamageMs: number;
+    activeDelayMs: number;
+    observed: number | null;
+}
 /**
  * A shield pool that stops regenerating for `regenDelayMs` after every hit, then refills at
  * `regenPerSecond` — the delayed-regen primitive that replaces snapshot-comparing stat values per
@@ -38,6 +46,10 @@ export interface RegenShieldConfig {
  * regenerates once it elapses.
  */
 export interface RegenShield {
+    /** Detached pool value, bounds, and regen timing. */
+    state(): RegenShieldState;
+    /** Restore state; returns false without mutation when an external pool's max differs. */
+    restore(next: RegenShieldState): boolean;
     current(): number;
     max(): number;
     setMax(value: number): void;
@@ -49,6 +61,8 @@ export interface RegenShield {
     /** Absorb `amount` and reset the regen grace timer; returns damage that got through (0 while the shield holds). */
     damage(amount: number): number;
     /** Add `amount` without touching the regen timer (a pickup or scripted refill). */
+    refill(amount: number): void;
+    /** @deprecated Use `refill(amount)` for pickups; `restore(state)` loads persisted state. */
     restore(amount: number): void;
     set(value: number): void;
     /**

package/dist/combat/regenShield.js

@@ -39,7 +39,30 @@ export function createRegenShield(config) {
             sinceDamageMs = 0;
         observed = live;
     }
+    function refill(amount) {
+        if (amount <= 0)
+            return;
+        syncExternal();
+        write(readCurrent() + amount);
+        observed = pool === undefined ? observed : readCurrent();
+    }
+    function restore(next) {
+        if (typeof next === "number")
+            return refill(next);
+        if (pool !== undefined && readMax() !== next.max)
+            return false;
+        if (pool === undefined)
+            ownMax = Math.max(0, next.max);
+        write(next.current);
+        sinceDamageMs = Math.max(0, next.sinceDamageMs);
+        activeDelayMs = Math.max(0, next.activeDelayMs);
+        observed = pool === undefined ? null : next.observed;
+        return true;
+    }
     return {
+        state: () => ({ max: readMax(), current: readCurrent(), sinceDamageMs, activeDelayMs, observed }),
+        restore,
+        refill,
         current: readCurrent,
         max: readMax,
         setMax(value) {
@@ -65,13 +88,6 @@ export function createRegenShield(config) {
             observed = pool === undefined ? observed : readCurrent();
             return overflow;
         },
-        restore(amount) {
-            if (amount <= 0)
-                return;
-            syncExternal();
-            write(readCurrent() + amount);
-            observed = pool === undefined ? observed : readCurrent();
-        },
         set(value) {
             write(value);
             observed = pool === undefined ? observed : readCurrent();

package/dist/combat/shotOrigin.d.ts

@@ -64,6 +64,12 @@ export declare const DEFAULT_EYE_HEIGHT: number;
 export declare function eyeHeightFromColliders(set: EntityColliderSet | null | undefined): number;
 export declare function aimDirection(aim: Aim): EntityPosition | null;
 export declare function aimSpreadDeg(aim: Aim): number;
+/**
+ * Resolves a shot's world origin and direction from the shooter's eye or muzzle and an {@link Aim}, ready for
+ * `ctx.scene.raycast` — the aim half of a hitscan weapon.
+ *
+ * @capability hitscan-shot aim a hitscan shot (shoot a gun): resolve origin and direction from the eye or muzzle for a raycast
+ */
 export declare function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy?: ShotOriginPolicy): ResolvedShot | null;
 /**
  * Resolves a `converge` shot with scene knowledge: fires from the gun muzzle but bends the direction

package/dist/combat/shotOrigin.js

@@ -29,6 +29,12 @@ export function aimDirection(aim) {
 export function aimSpreadDeg(aim) {
     return "origin" in aim ? 0 : aim.spread ?? 0;
 }
+/**
+ * Resolves a shot's world origin and direction from the shooter's eye or muzzle and an {@link Aim}, ready for
+ * `ctx.scene.raycast` — the aim half of a hitscan weapon.
+ *
+ * @capability hitscan-shot aim a hitscan shot (shoot a gun): resolve origin and direction from the eye or muzzle for a raycast
+ */
 export function resolveShot(deps, from, aim, policy = { kind: "eye" }) {
     const aimDir = aimDirection(aim);
     if (aimDir === null && policy.kind !== "camera" && policy.kind !== "world")

package/dist/combat/weaponFeedback.d.ts

@@ -0,0 +1,36 @@
+import type { WeaponHandlingFrame, WeaponShot } from "./weaponHandling.js";
+/**
+ * Signals {@link createWeaponFeedbackSignals} reports each tick, named for `createFeedbackMixer` routes.
+ * `shot`, `kick` and `impact` are pulses that read non-zero only on the tick they happened; the rest follow
+ * the handling frame.
+ */
+export type WeaponFeedbackSignal = "shot" | "kick" | "impact" | "recoil" | "cameraKick" | "spread" | "ads";
+/** Serializable pending pulses, so a snapshot taken between a shot and the next read loses nothing. */
+export interface WeaponFeedbackState {
+    shots: number;
+    kick: number;
+    impact: number;
+}
+/** Collects weapon events between presentation ticks and hands them to a feedback mixer as one signal record. */
+export interface WeaponFeedbackSignals {
+    /** Record a shot from `WeaponHandling.fire()`. Several shots before one `read` sum. */
+    shot(shot: WeaponShot): void;
+    /** Record a hit landing, in the game's own units (damage, `0..1` strength). Several impacts keep the largest. */
+    impact(strength: number): void;
+    /**
+     * Return this tick's signals and clear the pulses. `frame` (from `WeaponHandling.tick`) fills `recoil`,
+     * `cameraKick`, `spread` and `ads`; without it they read `0`. The record is reused between calls.
+     */
+    read(frame?: WeaponHandlingFrame): Readonly<Record<WeaponFeedbackSignal, number>>;
+    snapshot(): WeaponFeedbackState;
+    restore(state: WeaponFeedbackState): void;
+    reset(): void;
+}
+/**
+ * Creates {@link WeaponFeedbackSignals}: the bridge from shots, recoil kick and impacts to `createFeedbackMixer`
+ * routes (camera shake, audio, rumble). Route `kick` with no smoothing into camera-shake trauma, `impact` with
+ * a `release` into rumble, and `ads`/`spread` into continuous audio or FOV targets. Deterministic and
+ * allocation-free per read.
+ * @capability weapon-feedback turn weapon shots, recoil kick and impacts into per-tick feedback-mixer signals for camera shake, audio and rumble
+ */
+export declare function createWeaponFeedbackSignals(): WeaponFeedbackSignals;

package/dist/combat/weaponFeedback.js

@@ -0,0 +1,42 @@
+/**
+ * Creates {@link WeaponFeedbackSignals}: the bridge from shots, recoil kick and impacts to `createFeedbackMixer`
+ * routes (camera shake, audio, rumble). Route `kick` with no smoothing into camera-shake trauma, `impact` with
+ * a `release` into rumble, and `ads`/`spread` into continuous audio or FOV targets. Deterministic and
+ * allocation-free per read.
+ * @capability weapon-feedback turn weapon shots, recoil kick and impacts into per-tick feedback-mixer signals for camera shake, audio and rumble
+ */
+export function createWeaponFeedbackSignals() {
+    const pending = { shots: 0, kick: 0, impact: 0 };
+    const out = { shot: 0, kick: 0, impact: 0, recoil: 0, cameraKick: 0, spread: 0, ads: 0 };
+    return {
+        shot(shot) {
+            pending.shots += 1;
+            pending.kick += Math.hypot(shot.kickPitch, shot.kickYaw);
+        },
+        impact(strength) {
+            pending.impact = Math.max(pending.impact, strength);
+        },
+        read(frame) {
+            out.shot = pending.shots;
+            out.kick = pending.kick;
+            out.impact = pending.impact;
+            out.recoil = frame === undefined ? 0 : Math.hypot(frame.aimPitch, frame.aimYaw);
+            out.cameraKick = frame === undefined ? 0 : Math.hypot(frame.cameraPitch, frame.cameraYaw);
+            out.spread = frame?.spread ?? 0;
+            out.ads = frame?.adsProgress ?? 0;
+            pending.shots = 0;
+            pending.kick = 0;
+            pending.impact = 0;
+            return out;
+        },
+        snapshot: () => ({ ...pending }),
+        restore(state) {
+            Object.assign(pending, state);
+        },
+        reset() {
+            pending.shots = 0;
+            pending.kick = 0;
+            pending.impact = 0;
+        },
+    };
+}

package/dist/combat/weaponHandling.d.ts

@@ -0,0 +1,161 @@
+/** Recoil per shot, in radians of aim. `pitch > 0` climbs the muzzle, `yaw > 0` pulls right. */
+export interface WeaponRecoilTuning {
+    /**
+     * Fixed kick per shot index as `[pitch, yaw]` rad — the learnable part of a spray pattern. Past its end the
+     * last entry repeats. Omit for a flat `pitch` kick every shot.
+     */
+    pattern?: readonly (readonly [number, number])[];
+    /** Kick per shot when there is no `pattern`, rad (default `0`). */
+    pitch?: number;
+    /** Random extra kick, rad, drawn per shot from the injected `random` within ±this cone (default `0`). */
+    randomCone?: number;
+    /** Share of each kick that moves the camera rather than the aim, `0..1` (default `0`: all aim). */
+    cameraShare?: number;
+    /** Rate the accumulated kick recovers toward centre, rad/s (default `0`: none). */
+    recoverRate?: number;
+    /** Seconds after a shot before recovery starts (default `0.1`). */
+    recoverDelay?: number;
+    /** Aim kick multiplier while aiming down sights (default `1`). */
+    adsScale?: number;
+}
+/** Cone of fire, as a half-angle in radians. */
+export interface WeaponSpreadTuning {
+    /** Resting spread, rad. */
+    base: number;
+    /** Spread added per shot (bloom), rad (default `0`). */
+    perShot?: number;
+    /** Largest bloom, rad (default `base + 10 · perShot`). */
+    max?: number;
+    /** Rate bloom recovers toward `base`, rad/s (default `0`). */
+    recoverRate?: number;
+    /** Seconds after a shot before bloom recovers (default `0.1`). */
+    recoverDelay?: number;
+    /** Multipliers on the final spread for stance and aim; each defaults to `1`. */
+    ads?: number;
+    crouching?: number;
+    moving?: number;
+    airborne?: number;
+}
+/**
+ * Tuning for {@link createWeaponHandling}. Every number is an angle in radians or a time in seconds, so two
+ * weapons differ by numbers a person can reason about: a controllable rifle climbs a little and recovers
+ * fast; a shotgun kicks hard and blooms wide.
+ */
+export interface WeaponHandlingTuning {
+    recoil?: WeaponRecoilTuning;
+    spread: WeaponSpreadTuning;
+    /** Seconds to go fully into or out of aim-down-sights (default `0.2`). */
+    adsTime?: number;
+}
+/** Stance and aim for one tick. */
+export interface WeaponStance {
+    ads?: boolean;
+    crouching?: boolean;
+    moving?: boolean;
+    airborne?: boolean;
+}
+/** Serializable handling state. */
+export interface WeaponHandlingState {
+    aimPitch: number;
+    aimYaw: number;
+    cameraPitch: number;
+    cameraYaw: number;
+    bloom: number;
+    shotIndex: number;
+    sinceShot: number;
+    adsProgress: number;
+}
+/** What one shot did: the cone to sample and the kick it applied. */
+export interface WeaponShot {
+    /** Half-angle of the cone this shot fires into, rad, with stance multipliers applied. */
+    spread: number;
+    /** Aim kick applied by this shot, rad. */
+    kickPitch: number;
+    kickYaw: number;
+}
+/** Live handling readout: the offsets to add to aim and camera, current spread and ADS blend. */
+export interface WeaponHandlingFrame {
+    /** Recoil offset to add to the aim direction, rad. */
+    aimPitch: number;
+    aimYaw: number;
+    /** Recoil offset to add to the camera only (view punch), rad. */
+    cameraPitch: number;
+    cameraYaw: number;
+    /** Current half-angle spread with stance multipliers, rad. */
+    spread: number;
+    /** `0` hip … `1` fully aimed. */
+    adsProgress: number;
+}
+/**
+ * The player-to-weapon relationship as state: recoil that climbs and recovers, spread that blooms and
+ * settles, and an aim-down-sights blend. Cadence, ammo and hits stay in `weaponFire`/`magazine`; this owns
+ * how the weapon feels between them. First-person, third-person and over-the-shoulder presentations read
+ * the same frame.
+ */
+export interface WeaponHandling {
+    /** Register one shot (call when the cadence fires) and return its spread and kick. */
+    fire(stance?: WeaponStance): WeaponShot;
+    /** Advance recovery, bloom decay and ADS by `dt`. */
+    tick(dt: number, stance?: WeaponStance): WeaponHandlingFrame;
+    frame(): WeaponHandlingFrame;
+    retune(next: WeaponHandlingTuning): void;
+    snapshot(): WeaponHandlingState;
+    restore(state: WeaponHandlingState): void;
+    reset(): void;
+}
+/**
+ * Creates a {@link WeaponHandling}. Pass `random` (e.g. `ctx.rng` or `seededRng(seed)`) for the random
+ * recoil cone; without it the cone is skipped, so the result stays deterministic either way.
+ * @capability weapon-handling recoil patterns with camera kick and recovery, spread bloom, stance multipliers and ADS as serializable state
+ */
+export declare function createWeaponHandling(initial: WeaponHandlingTuning, options?: {
+    random?: () => number;
+}): WeaponHandling;
+/** Deterministic weapon-feel metrics from {@link measureWeapon}. */
+export interface WeaponReport {
+    /** Spread of the first shot from rest, rad. */
+    firstShotSpread: number;
+    /** Spread of the tenth shot of a held burst, rad. */
+    tenthShotSpread: number;
+    /** Spread of every shot in the burst, rad; `spreadByShot[n - 1]` is the spread after `n - 1` shots of bloom. */
+    spreadByShot: number[];
+    /** Aim climb after a full burst, rad; set `burst` to the magazine size for climb over a magazine. */
+    burstClimb: number;
+    /** Seconds after the burst until aim recoil is back within 5% of its peak and bloom within 5% of base. */
+    resetSeconds: number;
+    /** Seconds to go fully into aim-down-sights. */
+    adsSeconds: number;
+    /** Shots until the expected damage reaches `targetHealth` (`0` without `damage`, `Infinity` if it never does). */
+    shotsToKill: number;
+    /** Seconds from the first to the killing shot at `interval` (`0` without `damage` or when one shot kills). */
+    timeToKill: number;
+}
+/** Options for {@link measureWeapon}. */
+export interface WeaponProbeOptions {
+    /** Seconds between shots (`60 / rpm`). */
+    interval: number;
+    /** Shots in the held burst (default `30`). */
+    burst?: number;
+    /** Damage per projectile at the muzzle. */
+    damage?: number;
+    /** Projectiles per shot, e.g. shotgun pellets (default `1`). */
+    pellets?: number;
+    targetHealth?: number;
+    /** Distance to the target, m. Without it every projectile hits. */
+    range?: number;
+    /** Radius of the target's hittable area, m (default `0.4`). */
+    targetRadius?: number;
+    /** Damage multiplier at a range, the game's falloff policy (default: none). */
+    damageAt?: (range: number) => number;
+    /** Stance the burst and kill run are fired in (e.g. `{ ads: true }` after the ADS time). */
+    stance?: WeaponStance;
+    dt?: number;
+}
+/**
+ * Fires a held burst through a fresh handling instance at a fixed interval and reports spread growth,
+ * climb, reset time, ADS time and time-to-kill. Time-to-kill counts expected damage: each projectile hits
+ * with the share of its spread cone the target covers at `range`, scaled by `damageAt(range)`, so a
+ * blooming rifle and a wide shotgun compare at the distance the game cares about.
+ * @capability weapon-metrics measure a weapon's feel as numbers — spread per shot, climb over a magazine, reset time, ADS time, time-to-kill at a range
+ */
+export declare function measureWeapon(create: () => WeaponHandling, options: WeaponProbeOptions): WeaponReport;

package/dist/combat/weaponHandling.js

@@ -0,0 +1,202 @@
+function fresh(tuning) {
+    return {
+        aimPitch: 0,
+        aimYaw: 0,
+        cameraPitch: 0,
+        cameraYaw: 0,
+        bloom: tuning.spread.base,
+        shotIndex: 0,
+        // Finite so a snapshot survives JSON; anything past every delay behaves the same.
+        sinceShot: 1e9,
+        adsProgress: 0,
+    };
+}
+function toward(value, amount) {
+    if (value === 0)
+        return 0;
+    return Math.abs(value) <= amount ? 0 : value - Math.sign(value) * amount;
+}
+/**
+ * Creates a {@link WeaponHandling}. Pass `random` (e.g. `ctx.rng` or `seededRng(seed)`) for the random
+ * recoil cone; without it the cone is skipped, so the result stays deterministic either way.
+ * @capability weapon-handling recoil patterns with camera kick and recovery, spread bloom, stance multipliers and ADS as serializable state
+ */
+export function createWeaponHandling(initial, options = {}) {
+    let tuning = initial;
+    const random = options.random;
+    const state = fresh(tuning);
+    const out = { aimPitch: 0, aimYaw: 0, cameraPitch: 0, cameraYaw: 0, spread: 0, adsProgress: 0 };
+    function spreadFor(stance) {
+        const spread = tuning.spread;
+        const ads = 1 + ((spread.ads ?? 1) - 1) * state.adsProgress;
+        const crouch = stance?.crouching === true ? (spread.crouching ?? 1) : 1;
+        const moving = stance?.moving === true ? (spread.moving ?? 1) : 1;
+        const air = stance?.airborne === true ? (spread.airborne ?? 1) : 1;
+        return state.bloom * ads * crouch * moving * air;
+    }
+    function write(stance) {
+        out.aimPitch = state.aimPitch;
+        out.aimYaw = state.aimYaw;
+        out.cameraPitch = state.cameraPitch;
+        out.cameraYaw = state.cameraYaw;
+        out.spread = spreadFor(stance);
+        out.adsProgress = state.adsProgress;
+        return out;
+    }
+    return {
+        fire(stance) {
+            const recoil = tuning.recoil;
+            const spread = spreadFor(stance);
+            let kickPitch = 0;
+            let kickYaw = 0;
+            if (recoil !== undefined) {
+                const pattern = recoil.pattern;
+                const entry = pattern !== undefined && pattern.length > 0 ? pattern[Math.min(state.shotIndex, pattern.length - 1)] : undefined;
+                kickPitch = entry?.[0] ?? recoil.pitch ?? 0;
+                kickYaw = entry?.[1] ?? 0;
+                const cone = recoil.randomCone ?? 0;
+                if (cone > 0 && random !== undefined) {
+                    kickPitch += (random() * 2 - 1) * cone;
+                    kickYaw += (random() * 2 - 1) * cone;
+                }
+                const scale = 1 + ((recoil.adsScale ?? 1) - 1) * state.adsProgress;
+                kickPitch *= scale;
+                kickYaw *= scale;
+                const cameraShare = Math.max(0, Math.min(1, recoil.cameraShare ?? 0));
+                state.aimPitch += kickPitch * (1 - cameraShare);
+                state.aimYaw += kickYaw * (1 - cameraShare);
+                state.cameraPitch += kickPitch * cameraShare;
+                state.cameraYaw += kickYaw * cameraShare;
+            }
+            const perShot = tuning.spread.perShot ?? 0;
+            const max = tuning.spread.max ?? tuning.spread.base + perShot * 10;
+            state.bloom = Math.min(max, state.bloom + perShot);
+            state.shotIndex += 1;
+            state.sinceShot = 0;
+            return { spread, kickPitch, kickYaw };
+        },
+        tick(dt, stance) {
+            const step = Math.max(0, dt);
+            state.sinceShot += step;
+            const adsTime = Math.max(1e-3, tuning.adsTime ?? 0.2);
+            const adsTarget = stance?.ads === true ? 1 : 0;
+            state.adsProgress += Math.max(-step / adsTime, Math.min(step / adsTime, adsTarget - state.adsProgress));
+            const recoil = tuning.recoil;
+            if (recoil !== undefined && state.sinceShot >= (recoil.recoverDelay ?? 0.1)) {
+                const amount = (recoil.recoverRate ?? 0) * step;
+                state.aimPitch = toward(state.aimPitch, amount);
+                state.aimYaw = toward(state.aimYaw, amount);
+                state.cameraPitch = toward(state.cameraPitch, amount);
+                state.cameraYaw = toward(state.cameraYaw, amount);
+                if (state.aimPitch === 0 && state.aimYaw === 0)
+                    state.shotIndex = 0;
+            }
+            const spread = tuning.spread;
+            if (state.sinceShot >= (spread.recoverDelay ?? 0.1)) {
+                state.bloom = Math.max(spread.base, state.bloom - (spread.recoverRate ?? 0) * step);
+            }
+            return write(stance);
+        },
+        frame: () => write(undefined),
+        retune(next) {
+            tuning = next;
+            state.bloom = Math.max(next.spread.base, state.bloom);
+        },
+        snapshot: () => ({ ...state }),
+        restore(next) {
+            Object.assign(state, next);
+        },
+        reset() {
+            Object.assign(state, fresh(tuning));
+        },
+    };
+}
+function hitChance(spread, range, radius) {
+    if (range === undefined || range <= 0)
+        return 1;
+    const coneRadius = range * Math.tan(Math.max(0, spread));
+    return coneRadius <= radius ? 1 : (radius / coneRadius) ** 2;
+}
+/**
+ * Fires a held burst through a fresh handling instance at a fixed interval and reports spread growth,
+ * climb, reset time, ADS time and time-to-kill. Time-to-kill counts expected damage: each projectile hits
+ * with the share of its spread cone the target covers at `range`, scaled by `damageAt(range)`, so a
+ * blooming rifle and a wide shotgun compare at the distance the game cares about.
+ * @capability weapon-metrics measure a weapon's feel as numbers — spread per shot, climb over a magazine, reset time, ADS time, time-to-kill at a range
+ */
+export function measureWeapon(create, options) {
+    const dt = options.dt ?? 1 / 120;
+    const burst = options.burst ?? 30;
+    const interval = Math.max(dt, options.interval);
+    const stance = options.stance;
+    const settle = (weapon) => {
+        if (stance?.ads !== true)
+            return;
+        for (let i = 0; i < Math.ceil(5 / dt) && weapon.frame().adsProgress < 1; i += 1)
+            weapon.tick(dt, stance);
+    };
+    const hold = (weapon) => {
+        for (let t = 0; t < interval - 1e-9; t += dt)
+            weapon.tick(dt, stance);
+    };
+    const weapon = create();
+    settle(weapon);
+    const spreadByShot = [];
+    for (let shot = 0; shot < burst; shot += 1) {
+        spreadByShot.push(weapon.fire(stance).spread);
+        hold(weapon);
+    }
+    const peak = weapon.snapshot();
+    const burstClimb = peak.aimPitch;
+    const base = weapon.frame().spread;
+    let resetSeconds = Number.POSITIVE_INFINITY;
+    const baseSpread = create().frame().spread;
+    for (let i = 1; i <= Math.ceil(10 / dt); i += 1) {
+        const frame = weapon.tick(dt);
+        const aimSettled = Math.abs(frame.aimPitch) <= Math.abs(peak.aimPitch) * 0.05 + 1e-9;
+        const spreadSettled = frame.spread <= baseSpread + (base - baseSpread) * 0.05 + 1e-9;
+        if (aimSettled && spreadSettled) {
+            resetSeconds = i * dt;
+            break;
+        }
+    }
+    const ads = create();
+    let adsSeconds = Number.POSITIVE_INFINITY;
+    for (let i = 1; i <= Math.ceil(5 / dt); i += 1) {
+        if (ads.tick(dt, { ads: true }).adsProgress >= 1) {
+            adsSeconds = i * dt;
+            break;
+        }
+    }
+    const damage = options.damage ?? 0;
+    let shotsToKill = 0;
+    if (damage > 0) {
+        const health = options.targetHealth ?? 0;
+        const perHit = damage * (options.range !== undefined && options.damageAt !== undefined ? options.damageAt(options.range) : 1);
+        const pellets = Math.max(1, Math.floor(options.pellets ?? 1));
+        const radius = options.targetRadius ?? 0.4;
+        const shooter = create();
+        settle(shooter);
+        let dealt = 0;
+        shotsToKill = Number.POSITIVE_INFINITY;
+        for (let shot = 1; shot <= 10_000 && perHit > 0; shot += 1) {
+            dealt += perHit * pellets * hitChance(shooter.fire(stance).spread, options.range, radius);
+            if (dealt >= health - 1e-9) {
+                shotsToKill = shot;
+                break;
+            }
+            hold(shooter);
+        }
+    }
+    const timeToKill = shotsToKill > 0 ? (shotsToKill - 1) * interval : 0;
+    return {
+        firstShotSpread: spreadByShot[0] ?? 0,
+        tenthShotSpread: spreadByShot[9] ?? 0,
+        spreadByShot,
+        burstClimb,
+        resetSeconds,
+        adsSeconds,
+        shotsToKill,
+        timeToKill,
+    };
+}

package/dist/combat/weaponPresentation.d.ts

@@ -0,0 +1,115 @@
+import type { WeaponHandlingFrame } from "./weaponHandling.js";
+/** Camera-space position `[x, y, z]` in metres: `+x` right, `+y` up, `-z` forward. */
+export type ViewmodelOffset = readonly [number, number, number];
+/**
+ * How one weapon sits in first person. Offsets are camera-space metres, angles are radians, FOVs are
+ * degrees. Every field is optional; two weapons differ by the ones they set.
+ */
+export interface WeaponPresentationTuning {
+    /** Viewmodel anchor at the hip (default `[0.34, -0.26, -0.72]`). */
+    hip?: ViewmodelOffset;
+    /** Viewmodel anchor fully aimed; put the sight on the camera axis (default `[0, -0.07, -0.55]`). */
+    ads?: ViewmodelOffset;
+    /** Viewmodel FOV in degrees, independent of the world FOV; omit to draw the viewmodel at the world FOV. */
+    viewmodelFov?: {
+        hip?: number;
+        ads?: number;
+    };
+    /** World FOV multiplier at full ADS, e.g. `0.8` for a light zoom (default `1`). */
+    adsZoom?: number;
+    /** Viewmodel lag behind look motion. */
+    sway?: {
+        /** Radians of lag per rad/s of look speed (default `0.02`). */
+        perRadPerSec?: number;
+        /** Largest lag, rad (default `0.08`). */
+        max?: number;
+        /** How fast lag follows its target, 1/s (default `12`). */
+        response?: number;
+        /** Lag multiplier at full ADS (default `0.3`). */
+        adsScale?: number;
+    };
+    /** Walk bob driven by the movement probe's speed and `bobPhase`. */
+    bob?: {
+        /** Side and vertical amplitude in metres at `fullSpeed` (default `[0.012, 0.01]`). */
+        amplitude?: readonly [number, number];
+        /** Ground speed that gives the full amplitude, m/s (default `4`). */
+        fullSpeed?: number;
+        /** Bob multiplier at full ADS (default `0.25`). */
+        adsScale?: number;
+    };
+    /** Viewmodel reaction to the handling's recoil offset. */
+    kick?: {
+        /** Metres pushed back per radian of recoil (default `1.2`). */
+        back?: number;
+        /** Viewmodel muzzle rise per radian of recoil (default `1.5`). */
+        rise?: number;
+    };
+}
+/** One frame of inputs: look motion, the movement probe, and the weapon's handling readout. */
+export interface WeaponPresentationInput {
+    /** Look yaw speed, rad/s, positive turning left (the same sign as a camera yaw that grows left). */
+    lookYawRate: number;
+    /** Look pitch speed, rad/s, positive looking up. */
+    lookPitchRate: number;
+    /** Horizontal ground speed, m/s (e.g. `EntityRenderCues.speed`). */
+    speed: number;
+    /** `0..1` walk-cycle phase (e.g. `EntityRenderCues.bobPhase`). */
+    bobPhase: number;
+    handling: WeaponHandlingFrame;
+}
+/**
+ * Where the viewmodel and camera go this frame. First person applies all of it; third person and
+ * over-the-shoulder read `lookPitch`/`lookYaw`, `aimPitch`/`aimYaw` and `adsProgress` from the same frame.
+ */
+export interface WeaponPose {
+    /** Viewmodel anchor, camera-space metres. */
+    offset: [number, number, number];
+    /** Viewmodel rotation about its anchor, rad: `pitch > 0` muzzle up, `yaw > 0` muzzle left, `roll > 0` tilts left. */
+    pitch: number;
+    yaw: number;
+    roll: number;
+    /** Viewmodel FOV in degrees, or `null` to use the world FOV. */
+    viewmodelFov: number | null;
+    /** Multiplier for the world FOV (ADS zoom). */
+    fovScale: number;
+    /** Offset to add to the camera look, rad: aim kick plus view punch. `lookYaw > 0` pulls right. */
+    lookPitch: number;
+    lookYaw: number;
+    /** Offset shots follow, rad; a third-person rig or upper-body aim reads this. */
+    aimPitch: number;
+    aimYaw: number;
+    /** `0` hip … `1` fully aimed. */
+    adsProgress: number;
+}
+/** Serializable presentation state: the current sway lag. */
+export interface WeaponPresentationState {
+    swayPitch: number;
+    swayYaw: number;
+}
+/** Turns a {@link WeaponHandlingFrame} plus look and movement into a viewmodel and camera pose. */
+export interface WeaponPresentation {
+    /** Advance sway by `dt` and return the pose. The returned object is reused between calls. */
+    update(dt: number, input: WeaponPresentationInput): WeaponPose;
+    pose(): WeaponPose;
+    retune(next: WeaponPresentationTuning): void;
+    snapshot(): WeaponPresentationState;
+    restore(state: WeaponPresentationState): void;
+    reset(): void;
+}
+/** Default hip anchor, matching the shell's built-in viewmodel. */
+export declare const DEFAULT_VIEWMODEL_HIP: ViewmodelOffset;
+/** Default ADS anchor: the built-in viewmodel's top rail on the camera axis. */
+export declare const DEFAULT_VIEWMODEL_ADS: ViewmodelOffset;
+/**
+ * Creates a {@link WeaponPresentation}: per-weapon viewmodel offset, ADS pose and viewmodel FOV, sway
+ * and inertia from look speed, bob from the movement probe, and a recoil kick, all driven by the same
+ * handling frame third-person and over-the-shoulder rigs read. Deterministic and allocation-free per update.
+ * @capability weapon-presentation per-weapon viewmodel offset, ADS pose, viewmodel FOV, sway, bob and recoil kick from a weapon handling frame
+ */
+export declare function createWeaponPresentation(initial?: WeaponPresentationTuning): WeaponPresentation;
+/**
+ * Scale for a viewmodel drawn at `viewmodelFov` through a camera at `worldFov` (both degrees): multiply
+ * the viewmodel's camera-space x and y by this and it projects as if rendered with its own FOV, without
+ * a second camera or render pass.
+ */
+export declare function viewmodelFovScale(worldFov: number, viewmodelFov: number): number;