@jgengine/core 0.9.0 → 0.11.0

package/dist/combat/encounterSequence.js

@@ -0,0 +1,426 @@
+function clone(phase) {
+    const copy = { id: phase.id };
+    if (phase.data !== undefined)
+        copy.data = phase.data;
+    if (phase.completion !== undefined)
+        copy.completion = phase.completion;
+    if (phase.spawn !== undefined)
+        copy.spawn = phase.spawn;
+    if (phase.repeat !== undefined)
+        copy.repeat = phase.repeat;
+    if (phase.children !== undefined)
+        copy.children = phase.children.map(clone);
+    return copy;
+}
+function readNumber(params, key, fallback) {
+    const value = params[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function readString(params, key) {
+    const value = params[key];
+    return typeof value === "string" ? value : null;
+}
+/**
+ * Built-in completion predicates covering the common encounter gates: `immediate` (leaf
+ * marker), `manual`/`flag` (external event via a caller flag), `timer` (phase seconds),
+ * `cleared` (tagged entity count drained), `metric` (threshold on a live value), `event`
+ * (cumulative event count), and `quorum` (at least N of nested predicates met). Merge your
+ * own over these through {@link EncounterConfig.predicates}.
+ *
+ * @capability encounter-predicates gate encounter phase completion on timers, cleared spawns, metrics, events, or a quorum of conditions
+ */
+export const BUILTIN_COMPLETION_PREDICATES = {
+    immediate: () => true,
+    manual: (params, ctx) => {
+        const flag = readString(params, "flag") ?? ctx.phaseId;
+        return ctx.signals.flags?.[flag] === true;
+    },
+    flag: (params, ctx) => {
+        const flag = readString(params, "flag") ?? ctx.phaseId;
+        return ctx.signals.flags?.[flag] === true;
+    },
+    timer: (params, ctx) => ctx.phaseElapsed >= readNumber(params, "seconds", 0),
+    cleared: (params, ctx) => {
+        const tag = readString(params, "tag");
+        if (tag === null)
+            return false;
+        const remaining = readNumber(params, "remaining", 0);
+        return (ctx.signals.counts?.[tag] ?? 0) <= remaining;
+    },
+    metric: (params, ctx) => {
+        const name = readString(params, "name");
+        if (name === null)
+            return false;
+        const value = ctx.signals.metrics?.[name] ?? 0;
+        const target = readNumber(params, "target", 0);
+        return readString(params, "direction") === "atMost" ? value <= target : value >= target;
+    },
+    event: (params, ctx) => {
+        const name = readString(params, "name");
+        if (name === null)
+            return false;
+        return (ctx.signals.events?.[name] ?? 0) >= readNumber(params, "count", 1);
+    },
+    quorum: (params, ctx) => {
+        const refs = params["predicates"];
+        if (!Array.isArray(refs))
+            return false;
+        const need = readNumber(params, "count", refs.length);
+        let met = 0;
+        for (const raw of refs) {
+            const ref = raw;
+            const predicate = BUILTIN_COMPLETION_PREDICATES[ref.kind];
+            if (predicate !== undefined && predicate(ref.params ?? {}, ctx))
+                met += 1;
+            if (met >= need)
+                return true;
+        }
+        return false;
+    },
+};
+/**
+ * Built-in spawn providers. `points` reads a named authored scene point list from context
+ * and cycles it to emit `count` requests, keeping coordinates in the scene rather than the
+ * sequence. `list` echoes literal requests authored in `params.requests`. Merge your own
+ * catalog- or director-backed providers through {@link EncounterConfig.spawnProviders}.
+ *
+ * @capability encounter-spawn-providers turn an entered encounter phase into spawn requests from authored scene points or an inline list
+ */
+export const BUILTIN_SPAWN_PROVIDERS = {
+    points: (params, ctx) => {
+        const ref = readString(params, "ref");
+        if (ref === null)
+            return [];
+        const points = ctx.spawnPoints[ref] ?? [];
+        if (points.length === 0)
+            return [];
+        const count = Math.max(0, Math.floor(readNumber(params, "count", points.length)));
+        const entityRef = readString(params, "entity") ?? ref;
+        const requests = [];
+        for (let index = 0; index < count; index += 1) {
+            requests.push({ ref: entityRef, point: points[index % points.length] });
+        }
+        return requests;
+    },
+    list: (params) => {
+        const raw = params["requests"];
+        return Array.isArray(raw) ? raw : [];
+    },
+};
+function collectIds(phases, out) {
+    for (const phase of phases) {
+        if (out.has(phase.id))
+            throw new Error(`encounter phase id "${phase.id}" is not unique`);
+        out.add(phase.id);
+        if (phase.children !== undefined)
+            collectIds(phase.children, out);
+    }
+}
+function indexTree(phases, parent, index) {
+    for (const phase of phases) {
+        index.set(phase.id, { phase, parent });
+        if (phase.children !== undefined)
+            indexTree(phase.children, phase, index);
+    }
+}
+function ensureRuntime(state, id) {
+    let runtime = state.nodes[id];
+    if (runtime === undefined) {
+        runtime = { status: "pending", iteration: 0, enteredAt: state.elapsed };
+        state.nodes[id] = runtime;
+    }
+    return runtime;
+}
+/**
+ * Build the initial, serializable state for an encounter from its config. Deep-copies the
+ * authored phase tree (so later injection never mutates the config), verifies phase ids are
+ * unique, and leaves every node pending. Does not enter the first phase — call
+ * {@link startEncounter} for that.
+ *
+ * @capability encounter-state create the serializable starting state of a hierarchical encounter sequence
+ */
+export function createEncounterState(config) {
+    const ids = new Set();
+    collectIds(config.phases, ids);
+    const roots = config.phases.map(clone);
+    const nodes = {};
+    for (const id of ids)
+        nodes[id] = { status: "pending", iteration: 0, enteredAt: 0 };
+    return { roots, nodes, activePath: [], elapsed: 0, started: false, done: false };
+}
+function access(state) {
+    const index = new Map();
+    indexTree(state.roots, null, index);
+    return {
+        index,
+        siblingsOf(id) {
+            const parent = index.get(id)?.parent;
+            return parent?.children ?? state.roots;
+        },
+    };
+}
+function resetSubtree(state, phase) {
+    const runtime = ensureRuntime(state, phase.id);
+    runtime.status = "pending";
+    if (phase.children !== undefined)
+        for (const child of phase.children)
+            resetSubtree(state, child);
+}
+/**
+ * Enter a node and, if it is a group, descend to its first child, pushing every entered id
+ * onto the active path and emitting enter + spawn events. Leaves the deepest entered node
+ * as the new cursor. Bounded by tree depth.
+ */
+function enterChain(config, state, tree, startId, ctx, events, spawned) {
+    let currentId = startId;
+    const providers = { ...BUILTIN_SPAWN_PROVIDERS, ...config.spawnProviders };
+    let guard = tree.index.size + 1;
+    while (currentId !== undefined && guard > 0) {
+        guard -= 1;
+        const entry = tree.index.get(currentId);
+        if (entry === undefined)
+            return;
+        const phase = entry.phase;
+        const runtime = ensureRuntime(state, currentId);
+        runtime.status = "active";
+        runtime.enteredAt = state.elapsed;
+        state.activePath.push(currentId);
+        events.push({ type: "enter", phaseId: currentId, iteration: runtime.iteration });
+        if (phase.spawn !== undefined) {
+            // A phase that introduces spawns cannot complete on the same tick it enters — the
+            // caller has not observed the spawn yet — so defer its evaluation to the next update.
+            spawned.add(currentId);
+            const provider = providers[phase.spawn.kind];
+            if (provider !== undefined) {
+                const requests = provider(phase.spawn.params ?? {}, {
+                    phaseId: currentId,
+                    iteration: runtime.iteration,
+                    elapsed: state.elapsed,
+                    spawnPoints: ctx.spawnPoints ?? {},
+                });
+                if (requests.length > 0)
+                    events.push({ type: "spawn", phaseId: currentId, provider: phase.spawn.kind, requests });
+            }
+        }
+        const firstChild = phase.children?.[0];
+        currentId = firstChild?.id;
+    }
+}
+/**
+ * Start a created encounter: enter the first root phase, descending to its first leaf, and
+ * return the initial enter/spawn events. A no-op (with no events) on an already-started or
+ * empty encounter. Mutates and returns `state`.
+ *
+ * @capability encounter-start enter the first phase of a hierarchical encounter and emit its opening spawn events
+ */
+export function startEncounter(config, state, ctx = {}) {
+    const events = [];
+    if (state.started || state.done || state.roots.length === 0)
+        return { state, events };
+    state.started = true;
+    const tree = access(state);
+    enterChain(config, state, tree, state.roots[0].id, ctx, events, new Set());
+    return { state, events };
+}
+function predicateMet(config, phase, runtime, state, ctx) {
+    const completion = phase.completion;
+    if (completion === undefined)
+        return { met: true, reason: phase.children === undefined ? "immediate" : "children" };
+    const predicates = { ...BUILTIN_COMPLETION_PREDICATES, ...config.predicates };
+    const predicate = predicates[completion.kind];
+    if (predicate === undefined)
+        return { met: false, reason: completion.kind };
+    const met = predicate(completion.params ?? {}, {
+        phaseId: phase.id,
+        iteration: runtime.iteration,
+        elapsed: state.elapsed,
+        phaseElapsed: state.elapsed - runtime.enteredAt,
+        signals: ctx.signals ?? {},
+    });
+    return { met, reason: completion.kind };
+}
+/**
+ * Advance an encounter by `dt` seconds against the caller `ctx`. Accumulates time, then
+ * repeatedly: evaluates the cursor node's completion predicate; on completion, either
+ * re-runs its subtree (`repeat`) or marks it complete and advances to the next sibling —
+ * bubbling up to parent groups whose children are exhausted — entering the next chain and
+ * emitting enter/spawn/complete events. Emits a final `done` event when the last phase
+ * completes. Bounded per call by node count; mutates and returns `state`.
+ *
+ * @capability encounter-advance step a hierarchical encounter, resolving predicate-gated completion, repeats, and nested advance with lifecycle events
+ */
+export function updateEncounter(config, state, dt, ctx = {}) {
+    const events = [];
+    if (!state.started || state.done || state.activePath.length === 0)
+        return { state, events };
+    if (dt > 0)
+        state.elapsed += dt;
+    const tree = access(state);
+    const justSpawned = new Set();
+    let guard = tree.index.size * 2 + 2;
+    while (guard > 0 && state.activePath.length > 0) {
+        guard -= 1;
+        const cursorId = state.activePath[state.activePath.length - 1];
+        // A phase that spawned earlier in this same step defers its completion to the next update.
+        if (justSpawned.has(cursorId))
+            break;
+        const entry = tree.index.get(cursorId);
+        if (entry === undefined) {
+            state.activePath.pop();
+            continue;
+        }
+        const phase = entry.phase;
+        const runtime = ensureRuntime(state, cursorId);
+        const { met, reason } = predicateMet(config, phase, runtime, state, ctx);
+        if (!met)
+            break;
+        if (runtime.iteration < Math.max(0, Math.floor(phase.repeat ?? 0))) {
+            runtime.iteration += 1;
+            if (phase.children !== undefined)
+                for (const child of phase.children)
+                    resetSubtree(state, child);
+            state.activePath.pop();
+            enterChain(config, state, tree, cursorId, ctx, events, justSpawned);
+            continue;
+        }
+        runtime.status = "complete";
+        events.push({ type: "complete", phaseId: cursorId, iteration: runtime.iteration, reason });
+        state.activePath.pop();
+        const siblings = tree.siblingsOf(cursorId);
+        const position = siblings.findIndex((sibling) => sibling.id === cursorId);
+        const nextSibling = position >= 0 ? siblings[position + 1] : undefined;
+        if (nextSibling !== undefined) {
+            enterChain(config, state, tree, nextSibling.id, ctx, events, justSpawned);
+        }
+        else if (state.activePath.length === 0) {
+            state.done = true;
+            events.push({ type: "done" });
+            break;
+        }
+    }
+    return { state, events };
+}
+/**
+ * Force the deepest active phase (or a named active phase) to complete now, regardless of
+ * its predicate — the escape hatch for external/scripted completion and failure/retry flows.
+ * Advances into the next phase and emits the same lifecycle events as a natural completion.
+ * Returns no events if the phase is not currently active. Mutates and returns `state`.
+ *
+ * @capability encounter-force-complete externally complete an active encounter phase to drive scripted or failure-retry transitions
+ */
+export function forceCompletePhase(config, state, ctx = {}, phaseId) {
+    const events = [];
+    if (!state.started || state.done || state.activePath.length === 0)
+        return { state, events };
+    const targetId = phaseId ?? state.activePath[state.activePath.length - 1];
+    if (!state.activePath.includes(targetId))
+        return { state, events };
+    // Collapse the active path down to the target so update resolves it as the cursor, then
+    // advance it via an always-true synthetic predicate scoped to this single phase.
+    while (state.activePath.length > 0 && state.activePath[state.activePath.length - 1] !== targetId) {
+        state.activePath.pop();
+    }
+    const tree = access(state);
+    const entry = tree.index.get(targetId);
+    if (entry === undefined)
+        return { state, events };
+    const originalCompletion = entry.phase.completion;
+    entry.phase.completion = { kind: "__forced__" };
+    const forcedConfig = {
+        ...config,
+        predicates: { ...config.predicates, __forced__: () => true },
+    };
+    const step = updateEncounter(forcedConfig, state, 0, ctx);
+    // Restore the authored predicate on the (possibly repeating) phase for future runs.
+    if (originalCompletion === undefined)
+        delete entry.phase.completion;
+    else
+        entry.phase.completion = originalCompletion;
+    return step;
+}
+/**
+ * Insert a phase into the working tree at runtime — before/after a sibling, or as a child of
+ * a group — without disturbing already-completed or active nodes. The injected subtree
+ * becomes part of the serializable state (so a mid-encounter save preserves it) and is
+ * reached in normal order if it sits ahead of the cursor. Ids must stay tree-unique. Mutates
+ * and returns `state`.
+ *
+ * @capability encounter-inject-phase dynamically insert a phase or branch into a running encounter, e.g. a boss on the final wave
+ */
+export function injectPhase(state, phase, at) {
+    const existing = new Set();
+    collectIds(state.roots, existing);
+    const incoming = new Set();
+    collectIds([phase], incoming);
+    for (const id of incoming)
+        if (existing.has(id))
+            throw new Error(`encounter phase id "${id}" is not unique`);
+    const copy = clone(phase);
+    const tree = access(state);
+    if ("childOf" in at) {
+        const parentEntry = tree.index.get(at.childOf);
+        if (parentEntry === undefined)
+            throw new Error(`inject target "${at.childOf}" not found`);
+        const parent = parentEntry.phase;
+        const children = parent.children !== undefined ? [...parent.children] : [];
+        const index = at.index === undefined ? children.length : Math.max(0, Math.min(children.length, at.index));
+        children.splice(index, 0, copy);
+        parent.children = children;
+    }
+    else {
+        const targetId = "before" in at ? at.before : at.after;
+        const targetEntry = tree.index.get(targetId);
+        if (targetEntry === undefined)
+            throw new Error(`inject target "${targetId}" not found`);
+        const siblings = targetEntry.parent?.children ?? state.roots;
+        const list = [...siblings];
+        const position = list.findIndex((sibling) => sibling.id === targetId);
+        const insertAt = "before" in at ? position : position + 1;
+        list.splice(insertAt, 0, copy);
+        if (targetEntry.parent === null)
+            state.roots = list;
+        else
+            targetEntry.parent.children = list;
+    }
+    resetSubtree(state, copy);
+    return state;
+}
+/**
+ * The deepest active phase id — the completion cursor a HUD reads to label the current
+ * wave/phase — or null before start and once done.
+ *
+ * @capability encounter-active-phase read the id of the phase an encounter is currently waiting on
+ */
+export function activePhaseId(state) {
+    return state.activePath.length > 0 ? state.activePath[state.activePath.length - 1] : null;
+}
+/**
+ * The runtime status of a phase by id (pending/active/complete), or null if the id is
+ * unknown — for driving per-phase HUD ticks and objective checklists.
+ *
+ * @capability encounter-phase-status read whether a specific encounter phase is pending, active, or complete
+ */
+export function phaseStatus(state, id) {
+    return state.nodes[id]?.status ?? null;
+}
+/**
+ * Progress across the whole tree: how many phases have completed out of the total node
+ * count, plus whether the encounter has finished. Counts injected phases.
+ *
+ * @capability encounter-progress read completed-vs-total progress across a hierarchical encounter for HUD or objective display
+ */
+export function encounterProgress(state) {
+    let total = 0;
+    let completed = 0;
+    const walk = (phases) => {
+        for (const phase of phases) {
+            total += 1;
+            if (state.nodes[phase.id]?.status === "complete")
+                completed += 1;
+            if (phase.children !== undefined)
+                walk(phase.children);
+        }
+    };
+    walk(state.roots);
+    return { completed, total, done: state.done };
+}

package/dist/combat/hitReaction.d.ts

@@ -8,6 +8,10 @@ export interface HitReactionConfig {
     knockback: number;
     vertical?: number;
     shake?: CameraShake;
+    /** Trauma (0..1) fed to a trauma² camera-shake channel — the calibrated alternative to `shake`. */
+    trauma?: number;
+    /** Slow-mo factor during hitstop (e.g. 0.05 = 5% speed); read by the game's own time-scale system, not applied here. */
+    timescale?: number;
 }
 export interface HitReactionInput {
     attackerPos: EntityPosition;
@@ -18,6 +22,58 @@ export interface HitReaction {
     hitstopMs: number;
     impulse: [number, number, number];
     shake: CameraShake | null;
+    trauma: number | null;
+    timescale: number | null;
 }
-export declare function resolveHitReaction(config: HitReactionConfig, input: HitReactionInput): HitReaction;
+/** A calibrated `resolveHitReaction` config for a named impact event — hitstop + trauma so feel works with zero tuning. */
+export interface ImpactPreset {
+    hitstopMs: number;
+    trauma: number;
+    timescale?: number;
+    knockback?: number;
+    vertical?: number;
+}
+/**
+ * Calibrated per-event impact feel — hitstop and trauma numbers harvested
+ * from a shipped game-feel reference, not hand-invented per game. `explosion`
+ * and `playerHit` are "heavy hit" events (60–90ms hitstop @ 0.05 timescale);
+ * `pickup`/`jumpLand` are light events with no hitstop. Trauma is later
+ * clamped to 1.0 by `resolveHitReaction`.
+ *
+ * @capability impact-feel calibrated hitstop + trauma preset for a named impact event
+ */
+export declare const impactPresets: {
+    readonly pickup: {
+        readonly hitstopMs: 0;
+        readonly trauma: 0.15;
+    };
+    readonly jumpLand: {
+        readonly hitstopMs: 0;
+        readonly trauma: 0.2;
+    };
+    readonly enemyKilled: {
+        readonly hitstopMs: 40;
+        readonly trauma: 0.3;
+    };
+    readonly playerHit: {
+        readonly hitstopMs: 70;
+        readonly trauma: 0.4;
+        readonly timescale: 0.05;
+    };
+    readonly explosion: {
+        readonly hitstopMs: 90;
+        readonly trauma: 0.7;
+        readonly timescale: 0.05;
+    };
+};
+/** A named key into {@link impactPresets} (`"pickup" | "jumpLand" | "enemyKilled" | "playerHit" | "explosion"`). */
+export type ImpactPresetName = keyof typeof impactPresets;
+/**
+ * Resolves hit feel (hitstop, knockback impulse, camera shake) from either a
+ * named `impactPresets` event (`resolveHitReaction("explosion", input)`) or a
+ * raw `HitReactionConfig` override.
+ *
+ * @capability impact-feel resolve hitstop/knockback/shake feel from an impact preset or raw config
+ */
+export declare function resolveHitReaction(config: HitReactionConfig | ImpactPresetName, input: HitReactionInput): HitReaction;
 export declare function applyImpulse(position: EntityPosition, impulse: [number, number, number]): EntityPosition;

package/dist/combat/hitReaction.js

@@ -1,18 +1,58 @@
+/**
+ * Calibrated per-event impact feel — hitstop and trauma numbers harvested
+ * from a shipped game-feel reference, not hand-invented per game. `explosion`
+ * and `playerHit` are "heavy hit" events (60–90ms hitstop @ 0.05 timescale);
+ * `pickup`/`jumpLand` are light events with no hitstop. Trauma is later
+ * clamped to 1.0 by `resolveHitReaction`.
+ *
+ * @capability impact-feel calibrated hitstop + trauma preset for a named impact event
+ */
+export const impactPresets = {
+    pickup: { hitstopMs: 0, trauma: 0.15 },
+    jumpLand: { hitstopMs: 0, trauma: 0.2 },
+    enemyKilled: { hitstopMs: 40, trauma: 0.3 },
+    playerHit: { hitstopMs: 70, trauma: 0.4, timescale: 0.05 },
+    explosion: { hitstopMs: 90, trauma: 0.7, timescale: 0.05 },
+};
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function configFromPreset(name) {
+    const preset = impactPresets[name];
+    return {
+        hitstopMs: preset.hitstopMs,
+        knockback: preset.knockback ?? 0,
+        trauma: preset.trauma,
+        ...(preset.vertical === undefined ? {} : { vertical: preset.vertical }),
+        ...(preset.timescale === undefined ? {} : { timescale: preset.timescale }),
+    };
+}
+/**
+ * Resolves hit feel (hitstop, knockback impulse, camera shake) from either a
+ * named `impactPresets` event (`resolveHitReaction("explosion", input)`) or a
+ * raw `HitReactionConfig` override.
+ *
+ * @capability impact-feel resolve hitstop/knockback/shake feel from an impact preset or raw config
+ */
 export function resolveHitReaction(config, input) {
+    const resolved = typeof config === "string" ? configFromPreset(config) : config;
     const power = input.power ?? 1;
     const dx = input.targetPos[0] - input.attackerPos[0];
     const dz = input.targetPos[2] - input.attackerPos[2];
     const planar = Math.hypot(dx, dz);
     const nx = planar === 0 ? 0 : dx / planar;
     const nz = planar === 0 ? 0 : dz / planar;
-    const magnitude = config.knockback * power;
-    const shake = config.shake === undefined
+    const magnitude = resolved.knockback * power;
+    const shake = resolved.shake === undefined
         ? null
-        : { amplitude: config.shake.amplitude * power, decay: config.shake.decay };
+        : { amplitude: resolved.shake.amplitude * power, decay: resolved.shake.decay };
+    const trauma = resolved.trauma === undefined ? null : clamp01(resolved.trauma * power);
     return {
-        hitstopMs: config.hitstopMs,
-        impulse: [nx * magnitude, (config.vertical ?? 0) * power, nz * magnitude],
+        hitstopMs: resolved.hitstopMs,
+        impulse: [nx * magnitude, (resolved.vertical ?? 0) * power, nz * magnitude],
         shake,
+        trauma,
+        timescale: resolved.timescale ?? null,
     };
 }
 export function applyImpulse(position, impulse) {

package/dist/combat/magazine.d.ts

@@ -0,0 +1,54 @@
+/** Draws ammo for a `Magazine`'s reload from wherever the reserve pool actually lives. */
+export interface MagazineReserve {
+    current(): number;
+    spend(amount: number): boolean;
+    gain?(amount: number): void;
+}
+/** Tuning for `createMagazine`: mag capacity, reload delay, and where reserve ammo is drawn from. */
+export interface MagazineConfig {
+    capacity: number;
+    reloadMs: number;
+    /** Starting loaded count; defaults to `capacity` (a full mag). */
+    loaded?: number;
+    /**
+     * A plain number seeds a self-contained reserve pool; a `MagazineReserve` bridges reload draws
+     * into an externally-owned pool (a shared ammo-type stat, another `ResourcePool`); omitted means
+     * an infinite reserve (classic arcade shooter, never locked out of reloading).
+     */
+    reserve?: number | MagazineReserve;
+}
+/**
+ * A per-weapon magazine: discrete loaded rounds, a timed reload that refills from a reserve pool,
+ * and the reserve-pool interaction itself — the primitive that replaces hand-rolling mag size,
+ * reload delay, and reserve bookkeeping per game (#536.2).
+ */
+export interface Magazine {
+    loaded(): number;
+    capacity(): number;
+    /** Reserve rounds available to reload from, or `null` when the reserve is infinite. */
+    reserve(): number | null;
+    isReloading(): boolean;
+    /** Reload progress in `[0, 1]`; 0 while idle. */
+    reloadFraction(): number;
+    isEmpty(): boolean;
+    isFull(): boolean;
+    canFire(rounds?: number): boolean;
+    /** Spend `rounds` (default 1) loaded ammo; returns false without effect when insufficient. */
+    fire(rounds?: number): boolean;
+    /** True when a reload could start: not already full, not already reloading, reserve has rounds. */
+    canReload(): boolean;
+    /** Begin the reload timer if `canReload()`; returns whether it started. */
+    startReload(): 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`. */
+    addReserve(amount: number): void;
+    /** Advance the reload timer; completes the reload once `reloadMs` has elapsed. */
+    tick(dtSeconds: number): void;
+}
+/**
+ * Builds a {@link Magazine}: discrete loaded ammo, a timed reload, and reserve-pool interaction.
+ *
+ * @capability magazine a weapon magazine with capacity, timed reload, and reserve-pool interaction
+ */
+export declare function createMagazine(config: MagazineConfig): Magazine;