@jgengine/core 0.24.0 → 0.26.0

package/dist/combat/statusRuntime.d.ts

@@ -0,0 +1,142 @@
+import { type StatusApplicationOutcome, type StatusInstance, type StatusStackPolicy } from "./statusApplication.js";
+/**
+ * What a status does on each tick. Damage ticks are reported with the channel the caller's damage
+ * pipeline resolves, so a burn still meets resistances and armor; stat ticks are a per-stack delta
+ * summed by {@link StatusRuntime.statDelta} (`slow` → move speed, `corrode` → armor).
+ */
+export type StatusEffect = {
+    kind: "damage";
+    channel: string;
+} | {
+    kind: "stat";
+    stat: string;
+};
+/**
+ * One status the runtime can apply: how a fresh application folds into a live one
+ * ({@link StatusStackPolicy}), how long it lives, how often and how hard it ticks, and what a tick
+ * does. The stack rule is the *only* thing that changes stacks — per-tick magnitude is
+ * `magnitude × stacks`, never `magnitude ^ applications`.
+ */
+export interface StatusDef {
+    /** Caller-owned id (`"burn"`, `"shock"`, `"slow"`, `"corrode"`) — the runtime never branches on it. */
+    id: string;
+    /** Behaviour when the target already carries this status. */
+    stack: StatusStackPolicy;
+    /** Base lifetime in milliseconds. */
+    durationMs: number;
+    /** Milliseconds between ticks; defaults to `durationMs` (one tick as it expires). */
+    intervalMs?: number;
+    /** Per-stack effect size: damage per tick, or a stat delta per stack. */
+    magnitude?: number;
+    /** What each tick does. Omitted means a status with no periodic effect (HUD/predicate only). */
+    effect?: StatusEffect;
+    /** Landing chance in `[0,1]` before any application scale; default `1`. */
+    chance?: number;
+}
+/** A damage tick, already routed through the caller's `applyDamage` when one was supplied. */
+export interface StatusDamageTick {
+    kind: "damage";
+    target: string;
+    status: string;
+    stacks: number;
+    channel: string;
+    /** Raw `magnitude × stacks` before the caller's resistances and armor. */
+    amount: number;
+    /** What the caller's pipeline reported as dealt; equals `amount` when no pipeline was supplied. */
+    dealt: number;
+}
+/** A stat tick: a per-stack delta the caller reads while the status lives. */
+export interface StatusStatTick {
+    kind: "stat";
+    target: string;
+    status: string;
+    stacks: number;
+    stat: string;
+    delta: number;
+}
+/** A status ended: remove its HUD row and any stat delta it was contributing. */
+export interface StatusExpiredTick {
+    kind: "expired";
+    target: string;
+    status: string;
+    stacks: number;
+}
+/** Everything one `tick` call produced, in target-then-status order. */
+export type StatusTickEvent = StatusDamageTick | StatusStatTick | StatusExpiredTick;
+/** Options for one application; scales compose with the definition's own base values. */
+export interface StatusApplyOptions {
+    source?: string;
+    chanceScale?: number;
+    durationScale?: number;
+    magnitudeScale?: number;
+}
+/** One live status plus its tick timer, as saved and restored. */
+export interface StatusRuntimeEntry {
+    instance: StatusInstance;
+    untilTickMs: number;
+}
+/** Serializable runtime state: carried statuses, tick timers, and the counters a probe reports. */
+export interface StatusRuntimeState {
+    targets: Array<{
+        id: string;
+        entries: StatusRuntimeEntry[];
+    }>;
+    ticks: number;
+    applied: number;
+    expired: number;
+}
+/** Tunables a game can adjust at runtime without discarding carried statuses. */
+export interface StatusRuntimeOptions {
+    /** Status definitions; re-supply through {@link StatusRuntime.retune} when they change. */
+    statuses: readonly StatusDef[];
+    /** Injected `[0,1)` stream for landing rolls. Omitting it falls back to `Math.random` and warns once. */
+    rng?: () => number;
+    /** Route a damage tick through the caller's resistances/armor and return what it dealt. */
+    applyDamage?: (tick: StatusDamageTick) => number;
+    /** Most ticks one status emits per call; the remainder carries to the next call, never dropped. Default `8`. */
+    maxTicksPerCall?: number;
+    /** Register a one-line devtools probe under this name. */
+    devtoolsName?: string;
+}
+/** A pool of per-target statuses that applies stack rules, ticks effects, and hands its state out. */
+export interface StatusRuntime {
+    /** Try to apply one status to a target, folding into an existing instance per its declared stack rule. */
+    apply(targetId: string, statusId: string, options?: StatusApplyOptions): StatusApplicationOutcome;
+    statusesOf(targetId: string): readonly StatusInstance[];
+    has(targetId: string, statusId: string): boolean;
+    /** Sum of `magnitude × stacks` for every live status whose effect is this stat. */
+    statDelta(targetId: string, stat: string): number;
+    /** Advance every live status; returns each tick's effect and each expiry. */
+    tick(dtSeconds: number): StatusTickEvent[];
+    /** Drop one status, or every status, from a target. */
+    clear(targetId: string, statusId?: string): void;
+    snapshot(): StatusRuntimeState;
+    restore(next: StatusRuntimeState): void;
+    /** Swap the definitions (hot reload, tuning) while carried statuses keep running. */
+    retune(statuses: readonly StatusDef[]): void;
+    /** Counters for a probe or a test. */
+    stats(): {
+        targets: number;
+        active: number;
+        ticks: number;
+        applied: number;
+        expired: number;
+    };
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/** Raised when a caller names a status id the runtime has no definition for.
+ * @capability status-unknown reject a status id the runtime has no definition for
+ */
+export declare class UnknownStatusError extends Error {
+    readonly status: string;
+    constructor(status: string);
+}
+/**
+ * Build a status runtime over serializable definitions. Applications reuse
+ * {@link resolveStatusApplication} for chance and stacking, so a refresh/stack-to-N/ignore rule has
+ * exactly one implementation; `tick` then applies each status's declared effect per stack.
+ *
+ * @capability status-runtime tick data-defined statuses (burn, shock, slow, corrode) with declared stacking rules and per-tick effects
+ */
+export declare function createStatusRuntime(options: StatusRuntimeOptions): StatusRuntime;

package/dist/combat/statusRuntime.js

@@ -0,0 +1,236 @@
+import { devtools } from "../devtools/devtools.js";
+import { resolveRng } from "../random/resolveRng.js";
+import { resolveStatusApplication, } from "./statusApplication.js";
+/** Raised when a caller names a status id the runtime has no definition for.
+ * @capability status-unknown reject a status id the runtime has no definition for
+ */
+export class UnknownStatusError extends Error {
+    status;
+    constructor(status) {
+        super(`Unknown status: ${status}`);
+        this.name = "UnknownStatusError";
+        this.status = status;
+    }
+}
+function intervalOf(def) {
+    return Math.max(1, Math.round(def.intervalMs ?? def.durationMs));
+}
+function tickCountOf(def) {
+    if (def.durationMs <= 0)
+        return 0;
+    return Math.max(1, Math.round(def.durationMs / intervalOf(def)));
+}
+function specOf(def) {
+    const spec = {
+        status: def.id,
+        chance: def.chance ?? 1,
+        durationMs: Math.max(0, def.durationMs),
+        ticks: tickCountOf(def),
+        magnitude: def.magnitude ?? 0,
+        stack: def.stack,
+    };
+    return spec;
+}
+/**
+ * Build a status runtime over serializable definitions. Applications reuse
+ * {@link resolveStatusApplication} for chance and stacking, so a refresh/stack-to-N/ignore rule has
+ * exactly one implementation; `tick` then applies each status's declared effect per stack.
+ *
+ * @capability status-runtime tick data-defined statuses (burn, shock, slow, corrode) with declared stacking rules and per-tick effects
+ */
+export function createStatusRuntime(options) {
+    const rng = resolveRng(options.rng, "statusRuntime");
+    const maxTicksPerCall = Math.max(1, Math.round(options.maxTicksPerCall ?? 8));
+    let defs = new Map();
+    const targets = new Map();
+    let ticks = 0;
+    let applied = 0;
+    let expired = 0;
+    function retune(statuses) {
+        defs = new Map(statuses.map((def) => [def.id, def]));
+    }
+    retune(options.statuses);
+    function defOf(statusId) {
+        const def = defs.get(statusId);
+        if (def === undefined)
+            throw new UnknownStatusError(statusId);
+        return def;
+    }
+    function targetOf(targetId) {
+        let byId = targets.get(targetId);
+        if (byId === undefined) {
+            byId = new Map();
+            targets.set(targetId, byId);
+        }
+        return byId;
+    }
+    function effectEvent(targetId, def, instance) {
+        const effect = def.effect;
+        if (effect === undefined)
+            return [];
+        const amount = (def.magnitude ?? 0) * instance.stacks;
+        if (effect.kind === "stat") {
+            return [{
+                    kind: "stat",
+                    target: targetId,
+                    status: def.id,
+                    stacks: instance.stacks,
+                    stat: effect.stat,
+                    delta: amount,
+                }];
+        }
+        const tick = {
+            kind: "damage",
+            target: targetId,
+            status: def.id,
+            stacks: instance.stacks,
+            channel: effect.channel,
+            amount,
+            dealt: amount,
+        };
+        if (options.applyDamage !== undefined)
+            tick.dealt = options.applyDamage(tick);
+        return [tick];
+    }
+    function apply(targetId, statusId, applyOptions) {
+        const def = defOf(statusId);
+        const byId = targetOf(targetId);
+        const current = byId.get(statusId)?.instance ?? null;
+        const outcome = resolveStatusApplication({
+            spec: specOf(def),
+            scale: {
+                ...(applyOptions?.chanceScale !== undefined ? { applyChance: applyOptions.chanceScale } : {}),
+                ...(applyOptions?.durationScale !== undefined ? { duration: applyOptions.durationScale } : {}),
+                ...(applyOptions?.magnitudeScale !== undefined ? { magnitude: applyOptions.magnitudeScale } : {}),
+            },
+            current,
+            ...(applyOptions?.source !== undefined ? { source: applyOptions.source } : {}),
+            rng,
+        });
+        if (outcome.instance === null)
+            return outcome;
+        if (outcome.kind === "ignored" || outcome.kind === "missed" || outcome.kind === "immune")
+            return outcome;
+        // A fresh application restarts the tick clock, so stacking cannot bank a burst of instant ticks.
+        byId.set(statusId, { instance: outcome.instance, untilTickMs: intervalOf(def) });
+        if (outcome.kind === "applied")
+            applied += 1;
+        return outcome;
+    }
+    function stats() {
+        let active = 0;
+        for (const byId of targets.values())
+            active += byId.size;
+        return { targets: targets.size, active, ticks, applied, expired };
+    }
+    function probeLine() {
+        const counts = stats();
+        return `${counts.targets} targets ${counts.active} statuses · ${counts.applied} applied ${counts.expired} expired · ${counts.ticks} ticks`;
+    }
+    const unregister = options.devtoolsName === undefined
+        ? null
+        : devtools.probes.register(options.devtoolsName, () => probeLine());
+    return {
+        apply,
+        statusesOf(targetId) {
+            const byId = targets.get(targetId);
+            if (byId === undefined)
+                return [];
+            return [...byId.values()].map((entry) => entry.instance);
+        },
+        has(targetId, statusId) {
+            return targets.get(targetId)?.has(statusId) === true;
+        },
+        statDelta(targetId, stat) {
+            const byId = targets.get(targetId);
+            if (byId === undefined)
+                return 0;
+            let total = 0;
+            for (const [statusId, entry] of byId) {
+                const def = defs.get(statusId);
+                if (def?.effect?.kind !== "stat" || def.effect.stat !== stat)
+                    continue;
+                total += (def.magnitude ?? 0) * entry.instance.stacks;
+            }
+            return total;
+        },
+        tick(dtSeconds) {
+            const events = [];
+            if (!(dtSeconds > 0))
+                return events;
+            const stepMs = dtSeconds * 1000;
+            ticks += 1;
+            for (const [targetId, byId] of targets) {
+                for (const [statusId, entry] of byId) {
+                    const def = defs.get(statusId);
+                    // Time past the status's own lifetime must not buy extra ticks, so a long frame neither
+                    // over-ticks nor skips the tick that falls due on the last frame of the status.
+                    const livedMs = Math.min(stepMs, Math.max(0, entry.instance.remainingMs));
+                    if (def !== undefined) {
+                        const intervalMs = intervalOf(def);
+                        entry.untilTickMs -= livedMs;
+                        let emitted = 0;
+                        while (entry.untilTickMs <= 0 && emitted < maxTicksPerCall) {
+                            entry.untilTickMs += intervalMs;
+                            emitted += 1;
+                            entry.instance.ticks = Math.max(0, entry.instance.ticks - 1);
+                            for (const event of effectEvent(targetId, def, entry.instance))
+                                events.push(event);
+                        }
+                    }
+                    entry.instance.remainingMs -= livedMs;
+                    if (entry.instance.remainingMs <= 0) {
+                        entry.instance.remainingMs = 0;
+                        byId.delete(statusId);
+                        expired += 1;
+                        events.push({ kind: "expired", target: targetId, status: statusId, stacks: 0 });
+                    }
+                }
+                if (byId.size === 0)
+                    targets.delete(targetId);
+            }
+            return events;
+        },
+        clear(targetId, statusId) {
+            const byId = targets.get(targetId);
+            if (byId === undefined)
+                return;
+            if (statusId === undefined)
+                targets.delete(targetId);
+            else
+                byId.delete(statusId);
+        },
+        snapshot() {
+            return {
+                targets: [...targets.entries()].map(([id, byId]) => ({
+                    id,
+                    entries: [...byId.values()].map((entry) => ({
+                        instance: { ...entry.instance },
+                        untilTickMs: entry.untilTickMs,
+                    })),
+                })),
+                ticks,
+                applied,
+                expired,
+            };
+        },
+        restore(next) {
+            targets.clear();
+            ticks = next.ticks;
+            applied = next.applied;
+            expired = next.expired;
+            for (const saved of next.targets) {
+                const byId = new Map();
+                for (const entry of saved.entries) {
+                    byId.set(entry.instance.status, { instance: { ...entry.instance }, untilTickMs: entry.untilTickMs });
+                }
+                targets.set(saved.id, byId);
+            }
+        },
+        retune,
+        stats,
+        dispose() {
+            unregister?.();
+        },
+    };
+}

package/dist/combat/weaponDefinition.d.ts

@@ -0,0 +1,106 @@
+import type { WeaponHandlingTuning } from "./weaponHandling.js";
+/** A world-space point or direction in metres. */
+export type WeaponVec3 = readonly [number, number, number];
+/** How a held or tapped trigger turns into shots. */
+export type WeaponFireMode = "single" | "auto" | "burst";
+/** Shots one trigger pull commits to. A burst finishes even if the trigger is released. */
+export interface WeaponBurstDef {
+    /** Shots per pull, `1..64`. */
+    count: number;
+}
+/** A ray resolved in the caller's world on the same tick it is fired. */
+export interface WeaponHitscanDef {
+    kind: "hitscan";
+    /** Longest ray the caller may return a contact within, m. Required so every shot is bounded. */
+    maxRange: number;
+}
+/** A travelling pellet simulated by the runtime, resolved when it meets the caller's world. */
+export interface WeaponProjectileDef {
+    kind: "projectile";
+    /** Launch speed, m/s. */
+    speed: number;
+    /** Downward acceleration, m/s². `0` flies straight; `9.81` is Earth gravity for reference. */
+    gravity?: number;
+    /** Linear velocity decay, 1/s. `0` keeps speed until it hits. */
+    drag?: number;
+    /** Seconds before an unspent projectile expires. Required so every pellet is bounded. */
+    lifetime: number;
+    /** Optional hard distance cap, m, on top of `lifetime`. */
+    maxRange?: number;
+}
+/** Loaded rounds, reload time, and where reloads draw from. */
+export interface WeaponMagazineDef {
+    capacity: number;
+    reloadMs: number;
+    /** Rounds available to reload from; omitted means an unlimited reserve. */
+    reserve?: number;
+}
+/** What one pellet does when it reaches a registered damage target. */
+export interface WeaponDamageDef {
+    /** Damage type id in the caller's `DamageTableDef`. */
+    type: string;
+    /** Damage before the hit-zone multiplier, the table, armor, and falloff. */
+    base: number;
+    /** Status ids the hit tries to apply; the damage runtime owns their chance and effects. */
+    statuses?: readonly string[];
+}
+/** Linear damage falloff between two distances. */
+export interface WeaponFalloffDef {
+    /** Distance, m, where damage starts dropping. */
+    start: number;
+    /** Distance, m, where it reaches `endScale`; clamped beyond. */
+    end: number;
+    /** Damage multiplier at `end`, `0..1`. */
+    endScale: number;
+}
+/**
+ * One weapon as plain data: cadence, fire mode, delivery, magazine, feel and damage. Nothing here is
+ * a function, so a generator can roll it, a save can store it, and two weapons differ by their fields.
+ */
+export interface WeaponDefinition {
+    id: string;
+    /** Shots per minute at full cadence. */
+    roundsPerMinute: number;
+    fireMode: WeaponFireMode;
+    /** Burst size; required for `"burst"` and ignored otherwise. */
+    burst?: WeaponBurstDef;
+    delivery: WeaponHitscanDef | WeaponProjectileDef;
+    /** Pellets per shot, `1..64` (default `1`). */
+    pellets?: number;
+    /** Discrete ammo; omit for a weapon that never runs dry or reloads. */
+    magazine?: WeaponMagazineDef;
+    /** Recoil pattern, spread bloom and ADS time — exactly what `createWeaponHandling` consumes. */
+    handling: WeaponHandlingTuning;
+    damage: WeaponDamageDef;
+    /** Damage over distance, applied to both deliveries. Omit for no falloff. */
+    falloff?: WeaponFalloffDef;
+    /** Most pellets this weapon keeps live at once (default `32`, clamp `1..256`). */
+    maxInFlight?: number;
+    /** Start a reload by itself when the trigger is pulled dry (default `true`). */
+    autoReload?: boolean;
+}
+/** Cap on `WeaponDefinition.maxInFlight`; bounds per-tick projectile work. */
+export declare const MAX_WEAPON_PELLETS_IN_FLIGHT = 256;
+/** Default live-pellet cap for a weapon that does not name one. */
+export declare const DEFAULT_WEAPON_PELLETS_IN_FLIGHT = 32;
+/** Cap on `WeaponDefinition.pellets`; bounds rays and damage resolutions per shot. */
+export declare const MAX_WEAPON_PELLETS_PER_SHOT = 64;
+/** Cap on `WeaponBurstDef.count`. */
+export declare const MAX_WEAPON_BURST_COUNT = 64;
+/**
+ * Check a definition before it reaches the runtime, so a rolled weapon fails loudly at construction
+ * instead of firing nothing. Throws `RangeError` naming the field.
+ *
+ * @capability weapon-definition-validate reject a malformed weapon definition at construction with the field named
+ */
+export declare function assertWeaponDefinition(definition: WeaponDefinition): void;
+/**
+ * Milliseconds between shots at full cadence: `60_000 / roundsPerMinute`.
+ *
+ * @capability weapon-cadence convert a rounds-per-minute weapon rate into the interval a fire gate takes
+ */
+export declare function weaponIntervalMs(definition: WeaponDefinition): number;
+/** Damage multiplier at a distance: `1` before `falloff.start`, linearly down to `endScale` at `end`. */
+export declare function weaponDamageAt(definition: WeaponDefinition, distance: number): number;
+/** Live pellets one definition may keep, clamped to a bounded range. */
+export declare function weaponMaxInFlight(definition: WeaponDefinition): number;

package/dist/combat/weaponDefinition.js

@@ -0,0 +1,108 @@
+/** Cap on `WeaponDefinition.maxInFlight`; bounds per-tick projectile work. */
+export const MAX_WEAPON_PELLETS_IN_FLIGHT = 256;
+/** Default live-pellet cap for a weapon that does not name one. */
+export const DEFAULT_WEAPON_PELLETS_IN_FLIGHT = 32;
+/** Cap on `WeaponDefinition.pellets`; bounds rays and damage resolutions per shot. */
+export const MAX_WEAPON_PELLETS_PER_SHOT = 64;
+/** Cap on `WeaponBurstDef.count`. */
+export const MAX_WEAPON_BURST_COUNT = 64;
+function assertFinite(value, field, min, max) {
+    if (!Number.isFinite(value) || value < min || (max !== undefined && value > max)) {
+        const range = max === undefined ? `>= ${min}` : `in [${min}, ${max}]`;
+        throw new RangeError(`Weapon definition field "${field}" must be a finite number ${range}; got ${String(value)}`);
+    }
+}
+/**
+ * Check a definition before it reaches the runtime, so a rolled weapon fails loudly at construction
+ * instead of firing nothing. Throws `RangeError` naming the field.
+ *
+ * @capability weapon-definition-validate reject a malformed weapon definition at construction with the field named
+ */
+export function assertWeaponDefinition(definition) {
+    if (definition.id.trim() === "")
+        throw new RangeError('Weapon definition field "id" must not be empty');
+    assertFinite(definition.roundsPerMinute, "roundsPerMinute", Number.MIN_VALUE);
+    if (definition.fireMode !== "single" && definition.fireMode !== "auto" && definition.fireMode !== "burst") {
+        throw new RangeError(`Weapon definition field "fireMode" must be single, auto or burst; got ${String(definition.fireMode)}`);
+    }
+    if (definition.fireMode === "burst") {
+        if (definition.burst === undefined)
+            throw new RangeError('Weapon definition field "burst" is required for fireMode "burst"');
+        assertFinite(definition.burst.count, "burst.count", 1, MAX_WEAPON_BURST_COUNT);
+        if (!Number.isInteger(definition.burst.count))
+            throw new RangeError('Weapon definition field "burst.count" must be an integer');
+    }
+    if (definition.pellets !== undefined) {
+        assertFinite(definition.pellets, "pellets", 1, MAX_WEAPON_PELLETS_PER_SHOT);
+        if (!Number.isInteger(definition.pellets))
+            throw new RangeError('Weapon definition field "pellets" must be an integer');
+    }
+    if (definition.maxInFlight !== undefined) {
+        assertFinite(definition.maxInFlight, "maxInFlight", 1, MAX_WEAPON_PELLETS_IN_FLIGHT);
+        if (!Number.isInteger(definition.maxInFlight))
+            throw new RangeError('Weapon definition field "maxInFlight" must be an integer');
+    }
+    assertFinite(definition.damage.base, "damage.base", Number.MIN_VALUE);
+    if (definition.damage.type.trim() === "")
+        throw new RangeError('Weapon definition field "damage.type" must not be empty');
+    const delivery = definition.delivery;
+    if (delivery.kind === "hitscan") {
+        assertFinite(delivery.maxRange, "delivery.maxRange", Number.MIN_VALUE);
+    }
+    else if (delivery.kind === "projectile") {
+        assertFinite(delivery.speed, "delivery.speed", Number.MIN_VALUE);
+        assertFinite(delivery.lifetime, "delivery.lifetime", Number.MIN_VALUE);
+        if (delivery.gravity !== undefined)
+            assertFinite(delivery.gravity, "delivery.gravity", 0, 1e5);
+        if (delivery.drag !== undefined)
+            assertFinite(delivery.drag, "delivery.drag", 0, 1e5);
+        if (delivery.maxRange !== undefined)
+            assertFinite(delivery.maxRange, "delivery.maxRange", Number.MIN_VALUE);
+    }
+    else {
+        throw new RangeError(`Weapon definition field "delivery.kind" must be hitscan or projectile; got ${String(delivery.kind)}`);
+    }
+    if (definition.magazine !== undefined) {
+        assertFinite(definition.magazine.capacity, "magazine.capacity", 1);
+        if (!Number.isInteger(definition.magazine.capacity))
+            throw new RangeError('Weapon definition field "magazine.capacity" must be an integer');
+        assertFinite(definition.magazine.reloadMs, "magazine.reloadMs", 0);
+        if (definition.magazine.reserve !== undefined)
+            assertFinite(definition.magazine.reserve, "magazine.reserve", 0);
+    }
+    assertFinite(definition.handling.spread.base, "handling.spread.base", 0, Math.PI / 2);
+    if (definition.handling.spread.perShot !== undefined)
+        assertFinite(definition.handling.spread.perShot, "handling.spread.perShot", 0);
+    if (definition.handling.spread.recoverRate !== undefined)
+        assertFinite(definition.handling.spread.recoverRate, "handling.spread.recoverRate", 0);
+    if (definition.falloff !== undefined) {
+        assertFinite(definition.falloff.start, "falloff.start", 0);
+        assertFinite(definition.falloff.end, "falloff.end", 0);
+        assertFinite(definition.falloff.endScale, "falloff.endScale", 0, 1);
+        if (definition.falloff.end < definition.falloff.start) {
+            throw new RangeError('Weapon definition field "falloff.end" must not be before "falloff.start"');
+        }
+    }
+}
+/**
+ * Milliseconds between shots at full cadence: `60_000 / roundsPerMinute`.
+ *
+ * @capability weapon-cadence convert a rounds-per-minute weapon rate into the interval a fire gate takes
+ */
+export function weaponIntervalMs(definition) {
+    return 60_000 / definition.roundsPerMinute;
+}
+/** Damage multiplier at a distance: `1` before `falloff.start`, linearly down to `endScale` at `end`. */
+export function weaponDamageAt(definition, distance) {
+    const falloff = definition.falloff;
+    if (falloff === undefined || distance <= falloff.start)
+        return 1;
+    if (falloff.end <= falloff.start)
+        return falloff.endScale;
+    const t = Math.min(1, (distance - falloff.start) / (falloff.end - falloff.start));
+    return 1 + (falloff.endScale - 1) * t;
+}
+/** Live pellets one definition may keep, clamped to a bounded range. */
+export function weaponMaxInFlight(definition) {
+    return Math.min(MAX_WEAPON_PELLETS_IN_FLIGHT, Math.max(1, Math.floor(definition.maxInFlight ?? DEFAULT_WEAPON_PELLETS_IN_FLIGHT)));
+}