@jgengine/core 0.25.0 → 0.27.0

package/dist/combat/damageTable.d.ts

@@ -0,0 +1,116 @@
+/**
+ * One damage type's row in a damage table: a caller-owned id (`"kinetic"`, `"fire"`) and how it
+ * fares against each resistance class a target can present (`"flesh"`, `"shield"`, `"armor"`).
+ * Values below `1` are resisted, `1` is neutral, above `1` is a weakness, and `0` is immune.
+ */
+export interface DamageTypeDef {
+    id: string;
+    /** Resistance class → multiplier. A class the type omits uses the table's `defaultMultiplier`. */
+    vs?: Readonly<Record<string, number>>;
+    /** True when armor points never reduce this type. Defaults to false. */
+    bypassArmor?: boolean;
+}
+/**
+ * The armor curve: `mitigation = armor / (armor + halfValue)`. Naming the half value instead of a
+ * percentage per point is what makes a generated gun's armor number readable — armor equal to
+ * `halfValue` halves the hit, and mitigation approaches the cap without ever reaching it.
+ */
+export interface ArmorConfig {
+    /** Armor points at which the hit is halved. Default `100`. */
+    halfValue?: number;
+    /** Ceiling on the mitigated fraction, so armor never fully negates a hit. Default `0.9`. */
+    maxMitigation?: number;
+}
+/**
+ * A serializable damage table: damage types scored against resistance classes, plus the armor curve
+ * those rows are read with. It is data a generated gun (B3.1) and a weapon runtime (B2.3) pass in;
+ * the engine holds no built-in elemental chart.
+ */
+export interface DamageTableDef {
+    types: readonly DamageTypeDef[];
+    /** Multiplier for a type/class pair the table does not list. Default `1`. */
+    defaultMultiplier?: number;
+    armor?: ArmorConfig;
+}
+/** One readable row: a type against a resistance class at a given armor value. */
+export interface DamageTableRow {
+    type: string;
+    resistance: string;
+    /** Type × resistance multiplier before armor. */
+    multiplier: number;
+    /** Armor points this row was read at. */
+    armor: number;
+    /** Fraction of the hit armor removes, in `[0, maxMitigation]`. */
+    mitigation: number;
+    /** `multiplier × (1 - mitigation)` — the fraction of the base that lands. */
+    net: number;
+    /** `base × net`, when the read supplied a base. */
+    damage?: number;
+}
+/** Raised when a hit names a damage type the table does not define, rather than silently dealing 1×.
+ * @capability damage-type-unknown reject a hit whose damage type the table does not define instead of dealing 1×
+ */
+export declare class UnknownDamageTypeError extends Error {
+    readonly type: string;
+    constructor(type: string);
+}
+/** Raised when a table lists the same damage type twice, which would make the winner depend on order.
+ * @capability damage-type-duplicate reject a damage table that defines one type twice
+ */
+export declare class DuplicateDamageTypeError extends Error {
+    readonly type: string;
+    constructor(type: string);
+}
+/** Default armor points at which a hit is halved. */
+export declare const DEFAULT_ARMOR_HALF_VALUE = 100;
+/** Default ceiling on armor mitigation, so armor never fully negates a hit. */
+export declare const DEFAULT_MAX_MITIGATION = 0.9;
+/** Validate a table once at construction: duplicate ids and non-finite multipliers fail loudly.
+ * @capability damage-table-validate reject a damage table with duplicate types or non-finite multipliers before combat runs
+ */
+export declare function assertDamageTable(table: DamageTableDef): void;
+/** Fraction of a hit that armor removes at `armor` points; `0` at zero armor, capped by config.
+ * @capability armor-mitigation read the fraction of a hit armor removes at a given armor value
+ */
+export declare function armorMitigation(armor: number, config?: ArmorConfig): number;
+/**
+ * The type × resistance multiplier for one class, before armor. An unknown type throws; an unknown
+ * resistance class uses the table's `defaultMultiplier`, since target classes may be narrower than
+ * the table's coverage.
+ *
+ * @capability damage-table score a data-defined damage type against a resistance class, with the outcome readable as a table
+ */
+export declare function typeMultiplier(table: DamageTableDef, type: string, resistance: string): number;
+/** Whether armor points reduce this damage type.
+ * @capability armor-bypass ask whether a damage type ignores armor points
+ */
+export declare function typeBypassesArmor(table: DamageTableDef, type: string): boolean;
+/**
+ * Resolve one hit through the table: type multiplier, then armor mitigation, and the base scaled by
+ * both. Formula order matters only for the numbers a UI shows — the product is the same.
+ *
+ * @capability damage-table-resolve resolve a damage type against a resistance class and armor into a multiplier, mitigation, and final damage
+ */
+export declare function resolveTableDamage(table: DamageTableDef, input: {
+    type: string;
+    resistance: string;
+    armor?: number;
+    base?: number;
+}): DamageTableRow;
+/**
+ * Read the whole table as rows — every listed type against every listed resistance class, each with
+ * the armor it was read at and the damage a base would land. This is the table a designer reads and
+ * a test asserts, so a resistance change is visible without running combat.
+ *
+ * @capability damage-table-read read a damage table as rows of type × resistance × armor mitigation, with final damage per base
+ */
+export declare function readDamageTable(table: DamageTableDef, read?: {
+    base?: number;
+    armor?: number | Readonly<Record<string, number>>;
+    types?: readonly string[];
+    resistances?: readonly string[];
+}): DamageTableRow[];
+/** Render rows as fixed-width lines for a devtools probe, a CLI dump, or a test's diff.
+ * @capability damage-table-format render damage-table rows as fixed-width lines for a probe, a CLI dump, or a test
+ */
+export declare function formatDamageTable(rows: readonly DamageTableRow[]): string[];

package/dist/combat/damageTable.js

@@ -0,0 +1,165 @@
+/** Raised when a hit names a damage type the table does not define, rather than silently dealing 1×.
+ * @capability damage-type-unknown reject a hit whose damage type the table does not define instead of dealing 1×
+ */
+export class UnknownDamageTypeError extends Error {
+    type;
+    constructor(type) {
+        super(`Unknown damage type: ${type}`);
+        this.name = "UnknownDamageTypeError";
+        this.type = type;
+    }
+}
+/** Raised when a table lists the same damage type twice, which would make the winner depend on order.
+ * @capability damage-type-duplicate reject a damage table that defines one type twice
+ */
+export class DuplicateDamageTypeError extends Error {
+    type;
+    constructor(type) {
+        super(`Duplicate damage type: ${type}`);
+        this.name = "DuplicateDamageTypeError";
+        this.type = type;
+    }
+}
+/** Default armor points at which a hit is halved. */
+export const DEFAULT_ARMOR_HALF_VALUE = 100;
+/** Default ceiling on armor mitigation, so armor never fully negates a hit. */
+export const DEFAULT_MAX_MITIGATION = 0.9;
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+/** Validate a table once at construction: duplicate ids and non-finite multipliers fail loudly.
+ * @capability damage-table-validate reject a damage table with duplicate types or non-finite multipliers before combat runs
+ */
+export function assertDamageTable(table) {
+    const seen = new Set();
+    for (const type of table.types) {
+        if (seen.has(type.id))
+            throw new DuplicateDamageTypeError(type.id);
+        seen.add(type.id);
+        for (const [resistance, multiplier] of Object.entries(type.vs ?? {})) {
+            if (!Number.isFinite(multiplier) || multiplier < 0) {
+                throw new RangeError(`Damage type "${type.id}" has a bad multiplier vs "${resistance}": ${multiplier}`);
+            }
+        }
+    }
+    const defaultMultiplier = table.defaultMultiplier ?? 1;
+    if (!Number.isFinite(defaultMultiplier) || defaultMultiplier < 0) {
+        throw new RangeError(`Damage table defaultMultiplier must be finite and >= 0, got ${defaultMultiplier}`);
+    }
+}
+function findType(table, type) {
+    for (const entry of table.types)
+        if (entry.id === type)
+            return entry;
+    throw new UnknownDamageTypeError(type);
+}
+/** Fraction of a hit that armor removes at `armor` points; `0` at zero armor, capped by config.
+ * @capability armor-mitigation read the fraction of a hit armor removes at a given armor value
+ */
+export function armorMitigation(armor, config) {
+    const points = Math.max(0, armor);
+    if (points <= 0)
+        return 0;
+    const halfValue = Math.max(1e-6, config?.halfValue ?? DEFAULT_ARMOR_HALF_VALUE);
+    const cap = clamp01(config?.maxMitigation ?? DEFAULT_MAX_MITIGATION);
+    return Math.min(cap, points / (points + halfValue));
+}
+/**
+ * The type × resistance multiplier for one class, before armor. An unknown type throws; an unknown
+ * resistance class uses the table's `defaultMultiplier`, since target classes may be narrower than
+ * the table's coverage.
+ *
+ * @capability damage-table score a data-defined damage type against a resistance class, with the outcome readable as a table
+ */
+export function typeMultiplier(table, type, resistance) {
+    const entry = findType(table, type);
+    const listed = entry.vs?.[resistance];
+    if (listed !== undefined)
+        return listed;
+    return table.defaultMultiplier ?? 1;
+}
+/** Whether armor points reduce this damage type.
+ * @capability armor-bypass ask whether a damage type ignores armor points
+ */
+export function typeBypassesArmor(table, type) {
+    return findType(table, type).bypassArmor === true;
+}
+/**
+ * Resolve one hit through the table: type multiplier, then armor mitigation, and the base scaled by
+ * both. Formula order matters only for the numbers a UI shows — the product is the same.
+ *
+ * @capability damage-table-resolve resolve a damage type against a resistance class and armor into a multiplier, mitigation, and final damage
+ */
+export function resolveTableDamage(table, input) {
+    const multiplier = typeMultiplier(table, input.type, input.resistance);
+    const armorPoints = Math.max(0, input.armor ?? 0);
+    const mitigation = typeBypassesArmor(table, input.type)
+        ? 0
+        : armorMitigation(armorPoints, table.armor);
+    const net = multiplier * (1 - mitigation);
+    const row = {
+        type: input.type,
+        resistance: input.resistance,
+        multiplier,
+        armor: armorPoints,
+        mitigation,
+        net,
+    };
+    if (input.base !== undefined)
+        row.damage = input.base * net;
+    return row;
+}
+function listedResistances(table) {
+    const seen = new Set();
+    for (const type of table.types)
+        for (const resistance of Object.keys(type.vs ?? {}))
+            seen.add(resistance);
+    return [...seen].sort();
+}
+/**
+ * Read the whole table as rows — every listed type against every listed resistance class, each with
+ * the armor it was read at and the damage a base would land. This is the table a designer reads and
+ * a test asserts, so a resistance change is visible without running combat.
+ *
+ * @capability damage-table-read read a damage table as rows of type × resistance × armor mitigation, with final damage per base
+ */
+export function readDamageTable(table, read) {
+    assertDamageTable(table);
+    const types = read?.types ?? table.types.map((entry) => entry.id);
+    const resistances = read?.resistances ?? listedResistances(table);
+    const rows = [];
+    for (const type of types) {
+        for (const resistance of resistances) {
+            const armor = typeof read?.armor === "number" ? read.armor : (read?.armor?.[resistance] ?? 0);
+            const input = {
+                type,
+                resistance,
+                armor,
+            };
+            if (read?.base !== undefined)
+                input.base = read.base;
+            rows.push(resolveTableDamage(table, input));
+        }
+    }
+    return rows;
+}
+function pad(value, width) {
+    return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+/** Render rows as fixed-width lines for a devtools probe, a CLI dump, or a test's diff.
+ * @capability damage-table-format render damage-table rows as fixed-width lines for a probe, a CLI dump, or a test
+ */
+export function formatDamageTable(rows) {
+    const typeWidth = Math.max(4, ...rows.map((row) => row.type.length));
+    const resistanceWidth = Math.max(10, ...rows.map((row) => row.resistance.length));
+    return rows.map((row) => {
+        const multiplier = `×${row.multiplier.toFixed(2)}`;
+        const mitigation = row.armor > 0 ? `${(row.mitigation * 100).toFixed(0)}%` : "0%";
+        const damage = row.damage === undefined ? "" : ` → ${row.damage.toFixed(1)}`;
+        return `${pad(row.type, typeWidth)} vs ${pad(row.resistance, resistanceWidth)} ${pad(multiplier, 6)} armor ${pad(String(row.armor), 4)} ${pad(mitigation, 4)} net ×${row.net.toFixed(2)}${damage}`;
+    });
+}

package/dist/combat/hitZones.d.ts

@@ -0,0 +1,70 @@
+/** One hit zone: what a hit there multiplies, and how much likelier it is to crit. */
+export interface HitZoneDef {
+    id: string;
+    /** Multiplier for a hit in this zone that does not crit. Default `1`. */
+    multiplier?: number;
+    /** Added to the table's base crit chance for hits in this zone. Default `0`. */
+    critChance?: number;
+    /** Crit multiplier in this zone; defaults to the table's `critMultiplier`. */
+    critMultiplier?: number;
+}
+/**
+ * A serializable hit-zone table: where a hit landed, what that multiplies, and the table's base crit
+ * chance and multiplier. A generated gun or a weapon runtime passes its own zones in; the engine has
+ * no built-in headshot.
+ */
+export interface HitZoneTable {
+    zones: readonly HitZoneDef[];
+    /** Zone used when a caller names one the table does not list. Must appear in `zones`. */
+    defaultZone: string;
+    /** Base crit chance in `[0,1]`. Default `0`. */
+    critChance?: number;
+    /** Base crit multiplier. Default `2`. */
+    critMultiplier?: number;
+}
+/** One resolved zone: where the hit landed, whether it crit, and the single multiplier to apply. */
+export interface HitZoneResolution {
+    zone: string;
+    crit: boolean;
+    /**
+     * The one multiplier this hit earns. A crit *replaces* the zone's normal multiplier instead of
+     * compounding with it, so a headshot crit can never silently become zone × crit.
+     */
+    multiplier: number;
+    /** The crit draw, or `null` when the chance was zero and no draw was taken. */
+    roll: number | null;
+    /** True when the named zone was absent from the table and `defaultZone` was used. */
+    fallback: boolean;
+}
+/** Raised when neither the named zone nor the table's `defaultZone` exists — a data error, not a 1× hit.
+ * @capability hit-zone-unknown reject a hit zone table whose named default does not exist
+ */
+export declare class UnknownHitZoneError extends Error {
+    readonly zone: string;
+    constructor(zone: string);
+}
+/** Default crit multiplier for a zone that does not name one. */
+export declare const DEFAULT_CRIT_MULTIPLIER = 2;
+/** Validate a zone table once at construction: duplicate ids and a missing default fail loudly.
+ * @capability hit-zone-validate reject a hit-zone table with duplicate zones or a missing default
+ */
+export declare function assertHitZoneTable(table: HitZoneTable): void;
+/**
+ * The multiplier a zone earns for a known crit outcome, without rolling. `resolveHitZone` and a
+ * time-to-kill quote both read through this, so a quoted crit uses the same number combat does.
+ *
+ * @capability hit-zone-multiplier quote a zone's multiplier for a known crit outcome without rolling
+ */
+export declare function hitZoneMultiplier(table: HitZoneTable, zone: string | undefined, crit: boolean): {
+    zone: string;
+    multiplier: number;
+    fallback: boolean;
+};
+/**
+ * Resolve where a hit landed into one multiplier: roll the crit chance for that zone, and apply the
+ * crit multiplier when it lands, otherwise the zone's own multiplier. The injected `rng` keeps the
+ * roll reproducible; a zero chance draws nothing, so a deterministic test can force either outcome.
+ *
+ * @capability hit-zone resolve a hit zone into one damage multiplier, crit by zone with an injected RNG
+ */
+export declare function resolveHitZone(table: HitZoneTable, zone: string | undefined, rng?: () => number): HitZoneResolution;

package/dist/combat/hitZones.js

@@ -0,0 +1,77 @@
+import { resolveRng } from "../random/resolveRng.js";
+/** Raised when neither the named zone nor the table's `defaultZone` exists — a data error, not a 1× hit.
+ * @capability hit-zone-unknown reject a hit zone table whose named default does not exist
+ */
+export class UnknownHitZoneError extends Error {
+    zone;
+    constructor(zone) {
+        super(`Unknown hit zone: ${zone}`);
+        this.name = "UnknownHitZoneError";
+        this.zone = zone;
+    }
+}
+/** Default crit multiplier for a zone that does not name one. */
+export const DEFAULT_CRIT_MULTIPLIER = 2;
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+function findZone(table, zone) {
+    for (const entry of table.zones)
+        if (entry.id === zone)
+            return entry;
+    return undefined;
+}
+/** Validate a zone table once at construction: duplicate ids and a missing default fail loudly.
+ * @capability hit-zone-validate reject a hit-zone table with duplicate zones or a missing default
+ */
+export function assertHitZoneTable(table) {
+    const seen = new Set();
+    for (const zone of table.zones) {
+        if (seen.has(zone.id))
+            throw new RangeError(`Duplicate hit zone: ${zone.id}`);
+        seen.add(zone.id);
+    }
+    if (!seen.has(table.defaultZone))
+        throw new UnknownHitZoneError(table.defaultZone);
+}
+/**
+ * The multiplier a zone earns for a known crit outcome, without rolling. `resolveHitZone` and a
+ * time-to-kill quote both read through this, so a quoted crit uses the same number combat does.
+ *
+ * @capability hit-zone-multiplier quote a zone's multiplier for a known crit outcome without rolling
+ */
+export function hitZoneMultiplier(table, zone, crit) {
+    const named = zone ?? table.defaultZone;
+    let entry = findZone(table, named);
+    const fallback = entry === undefined;
+    if (entry === undefined)
+        entry = findZone(table, table.defaultZone);
+    if (entry === undefined)
+        throw new UnknownHitZoneError(named);
+    const multiplier = crit
+        ? (entry.critMultiplier ?? table.critMultiplier ?? DEFAULT_CRIT_MULTIPLIER)
+        : (entry.multiplier ?? 1);
+    return { zone: entry.id, multiplier, fallback };
+}
+/**
+ * Resolve where a hit landed into one multiplier: roll the crit chance for that zone, and apply the
+ * crit multiplier when it lands, otherwise the zone's own multiplier. The injected `rng` keeps the
+ * roll reproducible; a zero chance draws nothing, so a deterministic test can force either outcome.
+ *
+ * @capability hit-zone resolve a hit zone into one damage multiplier, crit by zone with an injected RNG
+ */
+export function resolveHitZone(table, zone, rng) {
+    const chance = clamp01((table.critChance ?? 0) + (findZone(table, zone ?? table.defaultZone)?.critChance ?? 0));
+    let roll = null;
+    let crit = false;
+    if (chance > 0) {
+        roll = resolveRng(rng, "hitZone")();
+        crit = roll < chance;
+    }
+    const resolved = hitZoneMultiplier(table, zone, crit);
+    return { zone: resolved.zone, crit, multiplier: resolved.multiplier, roll, fallback: resolved.fallback };
+}

package/dist/combat/magazine.d.ts

@@ -29,6 +29,8 @@ export interface MagazineSnapshot {
     loaded: number;
     reloadElapsedMs: number | null;
     reserve: number | null;
+    /** Present and `true` only while a reload is suspended, so idle snapshots keep their shape. */
+    paused?: boolean;
 }
 /**
  * A per-weapon magazine: discrete loaded rounds, a timed reload that refills from a reserve pool,
@@ -54,6 +56,12 @@ export interface Magazine {
     canReload(): boolean;
     /** Begin the reload timer if `canReload()`; returns whether it started. */
     startReload(): boolean;
+    /** Suspend an in-progress reload, keeping its elapsed progress, so it can be resumed later. */
+    pauseReload(): boolean;
+    /** Continue a paused reload from the progress it kept. */
+    resumeReload(): boolean;
+    /** True while a reload is suspended by `pauseReload()`. */
+    isPaused(): boolean;
     /** Abort an in-progress reload; loaded/reserve are unchanged (only completion moves ammo). */
     cancelReload(): void;
     /** Add `amount` to a self-contained numeric reserve (a pickup); a no-op against an infinite or externally-owned reserve without a `gain`. */

package/dist/combat/magazine.js

@@ -39,6 +39,7 @@ export function createMagazine(config) {
     }
     let loaded = clampLoaded(config.loaded ?? capacity);
     let reloadElapsedMs = null;
+    let paused = false;
     return {
         loaded: () => loaded,
         capacity: () => capacity,
@@ -65,7 +66,7 @@ export function createMagazine(config) {
             return true;
         },
         reserve: () => (isInfiniteReserve ? null : reserve.current()),
-        isReloading: () => reloadElapsedMs !== null,
+        isReloading: () => reloadElapsedMs !== null && !paused,
         reloadFraction: () => (reloadElapsedMs === null || reloadMs <= 0 ? 0 : Math.min(1, reloadElapsedMs / reloadMs)),
         isEmpty: () => loaded <= 0,
         isFull: () => loaded >= capacity,
@@ -91,17 +92,32 @@ export function createMagazine(config) {
             if (!this.canReload())
                 return false;
             reloadElapsedMs = 0;
+            paused = false;
             return true;
         },
+        pauseReload() {
+            if (reloadElapsedMs === null || paused)
+                return false;
+            paused = true;
+            return true;
+        },
+        resumeReload() {
+            if (!paused)
+                return false;
+            paused = false;
+            return true;
+        },
+        isPaused: () => paused,
         cancelReload() {
             reloadElapsedMs = null;
+            paused = false;
         },
         addReserve(amount) {
             if (amount > 0)
                 reserve.gain?.(amount);
         },
         tick(dtSeconds) {
-            if (dtSeconds <= 0 || reloadElapsedMs === null)
+            if (dtSeconds <= 0 || reloadElapsedMs === null || paused)
                 return;
             reloadElapsedMs += dtSeconds * 1000;
             if (reloadElapsedMs < reloadMs)
@@ -119,6 +135,7 @@ export function createMagazine(config) {
                 loaded,
                 reloadElapsedMs,
                 reserve: isInfiniteReserve ? null : reserve.current(),
+                ...(paused ? { paused: true } : {}),
             };
         },
         restore(snapshot) {
@@ -139,6 +156,7 @@ export function createMagazine(config) {
                 snapshot.reloadElapsedMs === null
                     ? null
                     : Math.max(0, Math.min(reloadMs, snapshot.reloadElapsedMs));
+            paused = reloadElapsedMs !== null && snapshot.paused === true;
             return true;
         },
     };