@jgengine/core 0.18.0 → 0.19.0

package/dist/audio/engineLayers.js

@@ -0,0 +1,115 @@
+function indexLayers(layers) {
+    const byRpm = (a, b) => layers[a].rpm - layers[b].rpm;
+    const index = { on: [], off: [], any: [] };
+    layers.forEach((layer, i) => index[layer.load ?? "any"].push(i));
+    if (index.on.length === 0 || index.off.length === 0) {
+        index.any.push(...index.on, ...index.off);
+        index.on = [];
+        index.off = [];
+    }
+    index.on.sort(byRpm);
+    index.off.sort(byRpm);
+    index.any.sort(byRpm);
+    return index;
+}
+function smoothstep(edge0, edge1, x) {
+    if (edge1 <= edge0)
+        return x >= edge1 ? 1 : 0;
+    const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
+    return t * t * (3 - 2 * t);
+}
+/**
+ * Layered engine sound: each set of rpm-keyed samples is equal-power crossfaded between the two
+ * samples bracketing the current rpm and pitched by `rpm / layer.rpm`; the on- and off-load sets are
+ * equal-power crossfaded by smoothed `engineLoad`. A config with only one load set plays it at every
+ * load. `play` drives `ctx.game.audio` directly, so a game needs no per-layer glue.
+ *
+ * @capability engine-layers layered engine audio: rpm-keyed samples crossfaded, with on-load and off-load sets picked by engine load
+ */
+export function createEngineLayers(initial) {
+    let config = initial;
+    let index = indexLayers(config.layers);
+    let mixes = [];
+    let load = 0;
+    const params = {};
+    function rebuild() {
+        index = indexLayers(config.layers);
+        mixes = config.layers.map((layer, i) => ({ id: `${config.id}:${i}`, sound: layer.sound, gain: 0, rate: 1 }));
+    }
+    rebuild();
+    function crossfade(set, rpm, weight) {
+        if (set.length === 0 || weight <= 0)
+            return;
+        const layers = config.layers;
+        let upper = 0;
+        while (upper < set.length && layers[set[upper]].rpm < rpm)
+            upper += 1;
+        if (upper === 0 || upper === set.length) {
+            const only = set[upper === 0 ? 0 : set.length - 1];
+            mixes[only].gain += weight;
+            return;
+        }
+        const lowIndex = set[upper - 1];
+        const highIndex = set[upper];
+        const low = layers[lowIndex].rpm;
+        const high = layers[highIndex].rpm;
+        const t = high > low ? (rpm - low) / (high - low) : 1;
+        mixes[lowIndex].gain += weight * Math.cos((t * Math.PI) / 2);
+        mixes[highIndex].gain += weight * Math.sin((t * Math.PI) / 2);
+    }
+    return {
+        update(dt, signals) {
+            const rpm = Number.isFinite(signals.rpm) ? Math.max(0, signals.rpm) : 0;
+            const target = Number.isFinite(signals.load) ? Math.min(1, Math.max(0, signals.load)) : 0;
+            const response = config.loadResponse ?? 10;
+            load = Number.isFinite(response) ? load + (target - load) * (1 - Math.exp(-response * Math.max(0, dt))) : target;
+            const [from, to] = config.loadCrossfade ?? [0.15, 0.6];
+            const onWeight = smoothstep(from, to, load);
+            for (let i = 0; i < mixes.length; i += 1) {
+                const layer = config.layers[i];
+                mixes[i].gain = 0;
+                mixes[i].rate = layer.rpm > 0 ? rpm / layer.rpm : 1;
+            }
+            crossfade(index.any, rpm, 1);
+            crossfade(index.on, rpm, Math.sin((onWeight * Math.PI) / 2));
+            crossfade(index.off, rpm, Math.cos((onWeight * Math.PI) / 2));
+            for (let i = 0; i < mixes.length; i += 1)
+                mixes[i].gain *= config.layers[i].gain ?? 1;
+            return mixes;
+        },
+        play(audio, options = {}) {
+            const scale = options.gain ?? 1;
+            const loopOptions = options.at === undefined ? undefined : { at: options.at };
+            params.at = options.at;
+            params.velocity = options.velocity;
+            params.lowpass = options.lowpass;
+            params.highpass = options.highpass;
+            for (const mix of mixes) {
+                audio.loop(mix.id, mix.sound, loopOptions);
+                params.rate = mix.rate;
+                params.gain = mix.gain * scale;
+                audio.setLoop(mix.id, params);
+            }
+        },
+        stop(audio) {
+            for (const mix of mixes)
+                audio.stopLoop(mix.id);
+        },
+        mix: () => mixes,
+        retune(next) {
+            config = next;
+            rebuild();
+        },
+        snapshot: () => ({ load }),
+        restore(state) {
+            load = state.load;
+        },
+        reset() {
+            load = 0;
+            for (const mix of mixes) {
+                mix.gain = 0;
+                mix.rate = 1;
+            }
+        },
+    };
+}

package/dist/combat/abilityKit.d.ts

@@ -76,5 +76,6 @@ export interface AbilityKit {
  * A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
  *
  * @capability ability-bar a bar of cooldown-gated abilities the player triggers by slot
+ * @capability global-cooldown share one cooldown across every ability slot (MMO global cooldown) with a cooldown group
  */
 export declare function createAbilityKit(configs: readonly AbilitySlotConfig[], options?: AbilityKitOptions): AbilityKit;

package/dist/combat/abilityKit.js

@@ -43,6 +43,7 @@ function snapshotOf(runtime, resourceAvailable, group) {
  * A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
  *
  * @capability ability-bar a bar of cooldown-gated abilities the player triggers by slot
+ * @capability global-cooldown share one cooldown across every ability slot (MMO global cooldown) with a cooldown group
  */
 export function createAbilityKit(configs, options = {}) {
     const boundResource = options.resource;

package/dist/combat/death.d.ts

@@ -18,6 +18,13 @@ export interface OnDeathCommandRule {
     };
 }
 export type DropMode = "grant" | "world";
+/**
+ * Catalog `onDeath` for an entity: loot tables to roll, `dropMode: "world"` to scatter drops on the ground
+ * (rendered with loot beams) instead of granting them into the killer's bag, and commands to run. Fires only
+ * when the entity dies through `ctx.scene.entity.effect`, not a raw `stats.delta`.
+ *
+ * @capability on-death-drops make a killed enemy drop loot on the ground or into the killer's bag via catalog onDeath
+ */
 export interface OnDeathSpec {
     drops?: string | OnDeathDropRule[];
     command?: string | OnDeathCommandRule;

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,
+    };
+}