@jgengine/core 0.9.0 → 0.11.0

package/dist/combat/damageInterceptors.js

@@ -0,0 +1,251 @@
+/**
+ * Ordered, inspectable damage-resolution interception (#931).
+ *
+ * A pending damage application flows through an ordered list of interceptors
+ * BEFORE lethality is resolved. Each interceptor may pass, transform, clamp,
+ * redirect, split, defer, or reject the application, and every decision is
+ * recorded as provenance so combat resolution stays auditable — no hidden
+ * callbacks. Invulnerability, i-frames, and anti-one-shot clamps are ordinary
+ * interceptors installed and removed by state transitions, not a boss branch.
+ *
+ * All state is serializable (`Record<string, number>` maps), all randomness is
+ * absent (pure), and work is bounded by `MAX_INTERCEPT_STEPS` so split/redirect
+ * can never recurse without limit.
+ */
+/** Upper bound on interceptor evaluations for a single resolution; guards against runaway `split`/`redirect` loops. */
+export const MAX_INTERCEPT_STEPS = 256;
+/**
+ * Run one pending damage application through an ordered interceptor list before
+ * lethality resolves, returning the final applications, any deferred ones, and
+ * full provenance. Pure and deterministic; bounded by `MAX_INTERCEPT_STEPS`.
+ *
+ * @capability damage-interception intercept a pending damage application before lethal resolution with ordered, inspectable stages
+ */
+export function resolveDamage(interceptors, pending, ctx) {
+    const applications = [];
+    const deferred = [];
+    const provenance = [];
+    const queue = [{ pending: normalize(pending), next: 0 }];
+    let steps = 0;
+    while (queue.length > 0) {
+        if (++steps > MAX_INTERCEPT_STEPS)
+            break;
+        const item = queue.shift();
+        if (item === undefined)
+            break;
+        if (item.next >= interceptors.length) {
+            applications.push(item.pending);
+            continue;
+        }
+        const interceptor = interceptors[item.next];
+        if (interceptor === undefined) {
+            applications.push(item.pending);
+            continue;
+        }
+        const current = item.pending;
+        const interceptorId = interceptor.id;
+        const decision = interceptor.intercept(current, ctx);
+        const before = current.amount;
+        function record(after, note) {
+            const row = {
+                interceptor: interceptorId,
+                kind: decision.kind,
+                target: current.target,
+                before,
+                after,
+            };
+            if (note !== undefined)
+                row.note = note;
+            provenance.push(row);
+        }
+        const nextIndex = item.next + 1;
+        switch (decision.kind) {
+            case "pass":
+                record(before);
+                queue.push({ pending: current, next: nextIndex });
+                break;
+            case "transform": {
+                const amount = Math.max(0, decision.amount);
+                record(amount, decision.note);
+                queue.push({ pending: { ...current, amount }, next: nextIndex });
+                break;
+            }
+            case "clamp": {
+                const amount = Math.min(current.amount, Math.max(0, decision.max));
+                record(amount, decision.note);
+                queue.push({ pending: { ...current, amount }, next: nextIndex });
+                break;
+            }
+            case "redirect":
+                record(before, decision.note);
+                queue.push({ pending: { ...current, target: decision.target }, next: nextIndex });
+                break;
+            case "split":
+                record(before, decision.note);
+                for (const part of decision.parts)
+                    queue.push({ pending: normalize(part), next: nextIndex });
+                break;
+            case "defer":
+                record(before, decision.note);
+                deferred.push(current);
+                break;
+            case "reject":
+                record(0, decision.note);
+                break;
+        }
+    }
+    return { applications, deferred, provenance };
+}
+function normalize(pending) {
+    return pending.amount >= 0 ? pending : { ...pending, amount: 0 };
+}
+/**
+ * Create a mutable damage interception chain that state transitions install into
+ * and remove from — e.g. add an invulnerability interceptor on phase enter and
+ * drop it on phase exit. Evaluation order is install order.
+ *
+ * @capability damage-pipeline install and remove ordered damage interceptors that transitions toggle at runtime
+ */
+export function createDamagePipeline(initial) {
+    const interceptors = initial === undefined ? [] : [...initial];
+    function indexOf(id) {
+        return interceptors.findIndex((entry) => entry.id === id);
+    }
+    return {
+        install(interceptor) {
+            const idx = indexOf(interceptor.id);
+            if (idx >= 0)
+                interceptors[idx] = interceptor;
+            else
+                interceptors.push(interceptor);
+        },
+        remove(id) {
+            const idx = indexOf(id);
+            if (idx < 0)
+                return false;
+            interceptors.splice(idx, 1);
+            return true;
+        },
+        has(id) {
+            return indexOf(id) >= 0;
+        },
+        interceptorIds() {
+            return interceptors.map((entry) => entry.id);
+        },
+        resolve(pending, ctx) {
+            return resolveDamage(interceptors, pending, ctx);
+        },
+    };
+}
+/**
+ * A stateless interceptor that caps any single application at `maxPerHit`.
+ *
+ * @capability damage-clamp cap incoming damage per hit at a configured maximum
+ */
+export function createDamageClamp(config) {
+    const id = config.id ?? "damage-clamp";
+    return {
+        id,
+        intercept(pending) {
+            if (pending.amount <= config.maxPerHit)
+                return { kind: "pass" };
+            return { kind: "clamp", max: config.maxPerHit, note: `capped at ${config.maxPerHit}` };
+        },
+    };
+}
+/**
+ * A per-target immunity/invulnerability window as an ordinary damage policy —
+ * granted and cleared by state transitions (i-frames, phase invuln), rejecting
+ * damage while active. Deterministic (time is passed in) and serializable.
+ *
+ * @capability immunity-window reject damage during a per-target invulnerability window installed by transitions
+ */
+export function createImmunityWindow(id = "immunity") {
+    const until = new Map();
+    const window = {
+        interceptor: {
+            id,
+            intercept(pending, ctx) {
+                const expiry = until.get(pending.target);
+                if (expiry !== undefined && ctx.nowMs < expiry)
+                    return { kind: "reject", note: `immune until ${expiry}` };
+                return { kind: "pass" };
+            },
+        },
+        grant(target, untilMs) {
+            const prev = until.get(target);
+            until.set(target, prev === undefined ? untilMs : Math.max(prev, untilMs));
+        },
+        grantFor(target, nowMs, durationMs) {
+            window.grant(target, nowMs + durationMs);
+        },
+        active(target, nowMs) {
+            const expiry = until.get(target);
+            return expiry !== undefined && nowMs < expiry;
+        },
+        clear(target) {
+            until.delete(target);
+        },
+        clearExpired(nowMs) {
+            for (const [target, expiry] of [...until])
+                if (nowMs >= expiry)
+                    until.delete(target);
+        },
+        snapshot() {
+            return Object.fromEntries(until);
+        },
+        restore(snap) {
+            until.clear();
+            for (const [target, expiry] of Object.entries(snap))
+                until.set(target, expiry);
+        },
+    };
+    return window;
+}
+/**
+ * Compose a reusable anti-one-shot / chip-guard clamp from caller data:
+ * while above `guardAboveFraction` a hit cannot drop the target below
+ * `leaveFraction`, and after such a save the target gets `recoverMs` of
+ * immunity. Below the guard fraction, lethal hits pass unchanged.
+ *
+ * @capability anti-one-shot clamp a near-lethal hit to leave a health floor then grant recovery immunity
+ */
+export function createAntiOneShotPolicy(config) {
+    const id = config.id ?? "anti-one-shot";
+    const immuneUntil = new Map();
+    const policy = {
+        interceptor: {
+            id,
+            intercept(pending, ctx) {
+                const expiry = immuneUntil.get(pending.target);
+                if (expiry !== undefined && ctx.nowMs < expiry)
+                    return { kind: "reject", note: "anti-one-shot i-frame" };
+                const hp = ctx.healthOf?.(pending.target);
+                if (hp === undefined || hp.max <= 0)
+                    return { kind: "pass" };
+                const fraction = hp.current / hp.max;
+                if (fraction <= config.guardAboveFraction)
+                    return { kind: "pass" };
+                const floor = config.leaveFraction * hp.max;
+                if (hp.current - pending.amount >= floor)
+                    return { kind: "pass" };
+                const clamped = Math.max(0, hp.current - floor);
+                immuneUntil.set(pending.target, ctx.nowMs + config.recoverMs);
+                return { kind: "clamp", max: clamped, note: `anti-one-shot: leave ${floor}, recover ${config.recoverMs}ms` };
+            },
+        },
+        immune(target, nowMs) {
+            const expiry = immuneUntil.get(target);
+            return expiry !== undefined && nowMs < expiry;
+        },
+        snapshot() {
+            return Object.fromEntries(immuneUntil);
+        },
+        restore(snap) {
+            immuneUntil.clear();
+            for (const [target, expiry] of Object.entries(snap))
+                immuneUntil.set(target, expiry);
+        },
+    };
+    return policy;
+}

package/dist/combat/damageMatchup.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Caller-owned id for a damage channel — `"fire"`, `"ballistic"`, `"physical"`, `"corrosive"`.
+ * The engine never branches on the value; a channel is whatever a game's data declares.
+ */
+export type DamageChannelId = string;
+/**
+ * Caller-owned id for a target trait — `"armored"`, `"fleshy"`, `"wet"`, `"boss"`.
+ * Traits are the receiver-side facets a matchup scores a channel against.
+ */
+export type TargetTraitId = string;
+/**
+ * The independent, typed outputs a channel-vs-trait matchup can scale. Every field is an
+ * optional multiplier that defaults to `1` (identity), so a matchup entry names only the axes
+ * it bends. `impact` scales the direct hit, `applyChance` the odds a status lands, `magnitude`
+ * and `duration` the applied status itself, and `extra` carries any further caller-defined
+ * scalar (knockback, stagger, heat) the engine forwards without interpreting.
+ */
+export interface MatchupOutputs {
+    /** Multiplier on direct impact magnitude. */
+    impact?: number;
+    /** Multiplier on status application probability. */
+    applyChance?: number;
+    /** Multiplier on applied status magnitude (e.g. damage per tick). */
+    magnitude?: number;
+    /** Multiplier on applied status duration/ticks. */
+    duration?: number;
+    /** Caller-defined extra scalar outputs, multiplied per axis like the named ones. */
+    extra?: Record<string, number>;
+}
+/**
+ * A serializable, data-defined matchup table: `channel → trait → outputs`. When a hit's channel
+ * meets a target carrying several traits, every matching entry's outputs multiply together, so
+ * axes compose independently (a trait can halve impact yet double status duration). `default`
+ * applies for a channel/trait pair the table does not mention.
+ */
+export interface DamageMatchup<TChannel extends string = DamageChannelId, TTrait extends string = TargetTraitId> {
+    /** Channel keyed to a per-trait outputs table. */
+    entries: Partial<Record<TChannel, Partial<Record<TTrait, MatchupOutputs>>>>;
+    /** Outputs used when no listed trait matches the channel; identity when omitted. */
+    default?: MatchupOutputs;
+}
+/** One `(trait → outputs)` pair that contributed to a resolved matchup — provenance for UI/debug. */
+export interface MatchupContribution {
+    trait: TargetTraitId;
+    outputs: MatchupOutputs;
+}
+/** Fully-resolved matchup outputs (every axis populated) plus the contributions that produced them. */
+export interface ResolvedMatchup {
+    channel: DamageChannelId;
+    impact: number;
+    applyChance: number;
+    magnitude: number;
+    duration: number;
+    /** Extra scalar outputs, each defaulting to 1 unless a contribution set it. */
+    extra: Record<string, number>;
+    /** Whether at least one listed trait matched (false means `default`/identity was used). */
+    matched: boolean;
+    contributions: MatchupContribution[];
+}
+/**
+ * Resolve a channel against a target's traits into independent, multiplied outputs. Pure and
+ * order-independent: every trait the channel has an entry for contributes, its axes multiplying
+ * into the running product; unmatched traits are skipped, and when nothing matches the table's
+ * `default` (or identity) is used. Bounded by the trait count — no world scan.
+ *
+ * @capability damage-matchup score a data-defined damage channel against a target's traits into independent typed multipliers
+ */
+export declare function resolveMatchup<TChannel extends string = DamageChannelId, TTrait extends string = TargetTraitId>(matchup: DamageMatchup<TChannel, TTrait>, channel: TChannel | string, targetTraits: readonly (TTrait | string)[]): ResolvedMatchup;

package/dist/combat/damageMatchup.js

@@ -0,0 +1,42 @@
+function multiplyInto(acc, outputs) {
+    if (outputs.impact !== undefined)
+        acc.impact *= outputs.impact;
+    if (outputs.applyChance !== undefined)
+        acc.applyChance *= outputs.applyChance;
+    if (outputs.magnitude !== undefined)
+        acc.magnitude *= outputs.magnitude;
+    if (outputs.duration !== undefined)
+        acc.duration *= outputs.duration;
+    if (outputs.extra !== undefined) {
+        for (const [key, value] of Object.entries(outputs.extra)) {
+            acc.extra[key] = (acc.extra[key] ?? 1) * value;
+        }
+    }
+}
+/**
+ * Resolve a channel against a target's traits into independent, multiplied outputs. Pure and
+ * order-independent: every trait the channel has an entry for contributes, its axes multiplying
+ * into the running product; unmatched traits are skipped, and when nothing matches the table's
+ * `default` (or identity) is used. Bounded by the trait count — no world scan.
+ *
+ * @capability damage-matchup score a data-defined damage channel against a target's traits into independent typed multipliers
+ */
+export function resolveMatchup(matchup, channel, targetTraits) {
+    const acc = { impact: 1, applyChance: 1, magnitude: 1, duration: 1, extra: {} };
+    const contributions = [];
+    const byTrait = matchup.entries[channel];
+    if (byTrait !== undefined) {
+        for (const trait of targetTraits) {
+            const outputs = byTrait[trait];
+            if (outputs === undefined)
+                continue;
+            multiplyInto(acc, outputs);
+            contributions.push({ trait, outputs });
+        }
+    }
+    const matched = contributions.length > 0;
+    if (!matched && matchup.default !== undefined) {
+        multiplyInto(acc, matchup.default);
+    }
+    return { channel, ...acc, matched, contributions };
+}

package/dist/combat/damageResolution.d.ts

@@ -0,0 +1,63 @@
+import { type DamageChannelId, type DamageMatchup, type ResolvedMatchup, type TargetTraitId } from "./damageMatchup.js";
+import { type ReceivedDamageResult, type ReceivedModifier } from "./receivedDamage.js";
+import { type StatusApplicationOutcome, type StatusApplicationSpec, type StatusImmunity, type StatusInstance } from "./statusApplication.js";
+/**
+ * One data-defined damage hit: a channel, a base impact, the target's traits and carried statuses,
+ * and the caller-owned matchup/received/status data that shapes the outcome. Everything is
+ * serializable; the only non-data input is the injected `rng`, so authority can resolve a hit and
+ * replicate the returned instances.
+ */
+export interface DamageHitInput {
+    channel: DamageChannelId;
+    /** Base direct impact before matchup and receiver modifiers. */
+    impact: number;
+    target: string;
+    source?: string;
+    /** Traits the target presents to the matchup (`"armored"`, `"shielded"`). */
+    targetTraits?: readonly TargetTraitId[];
+    /** Statuses the target already carries — feeds received predicates and stacking. */
+    targetStatuses?: readonly string[];
+    /** Caller tags on the hit (`"crit"`, `"aoe"`). */
+    tags?: readonly string[];
+    /** Channel-vs-trait table; omitted means identity outputs. */
+    matchup?: DamageMatchup;
+    /** Receiver-side modifiers to run over the post-matchup impact. */
+    received?: readonly ReceivedModifier[];
+    /** A status this hit tries to apply; omitted means impact only. */
+    status?: StatusApplicationSpec;
+    /** The target's existing instance of `status`, for stacking/refresh. */
+    currentStatus?: StatusInstance | null;
+    /** Statuses the target is immune to. */
+    immunity?: StatusImmunity | null;
+    /** Deterministic RNG for the status roll; defaults to `Math.random`. */
+    rng?: () => number;
+}
+/**
+ * The full, provenance-rich result of resolving a hit — every stage kept for UI and debugging.
+ * `impact` is the final number to drain; `matchup`, `received`, and `status` expose exactly how it
+ * got there. Authority applies `impact` (plus `received.redirects`/`conversions`) and the returned
+ * status `instance`; nothing here mutates game state.
+ */
+export interface DamageHitResolution {
+    channel: DamageChannelId;
+    /** Final impact on the primary target/channel after matchup and receiver modifiers. */
+    impact: number;
+    immune: boolean;
+    /** The matchup outputs and their contributions. */
+    matchup: ResolvedMatchup;
+    /** The receiver-side pass over the matchup-scaled impact. */
+    received: ReceivedDamageResult;
+    /** The status application outcome, when the hit carried a `status`. */
+    status?: StatusApplicationOutcome;
+}
+/**
+ * Resolve a full damage hit through the data-defined pipeline: score the channel against the
+ * target's traits ({@link resolveMatchup}), scale base impact by the matchup's `impact` axis,
+ * run receiver-side modifiers ({@link resolveReceivedDamage}), then roll status application scaled
+ * by the matchup's `applyChance`/`magnitude`/`duration` axes ({@link resolveStatusApplication}).
+ * Pure and deterministic given a seeded `rng`; returns full provenance and never mutates state, so
+ * it is safe to run on the authority and replicate the results.
+ *
+ * @capability damage-hit resolve a full data-defined damage hit — matchup, impact, receiver modifiers, and status application — with provenance
+ */
+export declare function resolveDamageHit(input: DamageHitInput): DamageHitResolution;

package/dist/combat/damageResolution.js

@@ -0,0 +1,50 @@
+import { resolveMatchup, } from "./damageMatchup.js";
+import { resolveReceivedDamage, } from "./receivedDamage.js";
+import { resolveStatusApplication, } from "./statusApplication.js";
+/**
+ * Resolve a full damage hit through the data-defined pipeline: score the channel against the
+ * target's traits ({@link resolveMatchup}), scale base impact by the matchup's `impact` axis,
+ * run receiver-side modifiers ({@link resolveReceivedDamage}), then roll status application scaled
+ * by the matchup's `applyChance`/`magnitude`/`duration` axes ({@link resolveStatusApplication}).
+ * Pure and deterministic given a seeded `rng`; returns full provenance and never mutates state, so
+ * it is safe to run on the authority and replicate the results.
+ *
+ * @capability damage-hit resolve a full data-defined damage hit — matchup, impact, receiver modifiers, and status application — with provenance
+ */
+export function resolveDamageHit(input) {
+    const matchup = resolveMatchup(input.matchup ?? { entries: {} }, input.channel, input.targetTraits ?? []);
+    const context = {
+        channel: input.channel,
+        target: input.target,
+        ...(input.source !== undefined ? { source: input.source } : {}),
+        ...(input.targetStatuses !== undefined ? { targetStatuses: input.targetStatuses } : {}),
+        ...(input.tags !== undefined ? { tags: input.tags } : {}),
+    };
+    const received = resolveReceivedDamage({
+        amount: input.impact * matchup.impact,
+        context,
+        modifiers: input.received ?? [],
+    });
+    const resolution = {
+        channel: input.channel,
+        impact: received.amount,
+        immune: received.immune,
+        matchup,
+        received,
+    };
+    if (input.status !== undefined) {
+        resolution.status = resolveStatusApplication({
+            spec: input.status,
+            scale: {
+                applyChance: matchup.applyChance,
+                magnitude: matchup.magnitude,
+                duration: matchup.duration,
+            },
+            current: input.currentStatus ?? null,
+            immunity: input.immunity ?? null,
+            ...(input.source !== undefined ? { source: input.source } : {}),
+            ...(input.rng !== undefined ? { rng: input.rng } : {}),
+        });
+    }
+    return resolution;
+}

package/dist/combat/death.d.ts

@@ -1,6 +1,7 @@
-import type { DeathReason, GameEvents } from "../game/events.js";
+import type { GameEvents } from "../game/events.js";
 import type { Drop } from "../game/lootTable.js";
 import type { ScatterOptions } from "../game/worldItem.js";
+import type { DeathReason } from "./deathReason.js";
 import type { EffectVia } from "./effects.js";
 export type DeathReasonKind = DeathReason["kind"];
 export interface OnDeathDropRule {
@@ -60,6 +61,11 @@ export interface DeathSystem {
     resolveDeath(instanceId: string, reason: DeathReason): DeathResolution;
     revive(instanceId: string): boolean;
 }
+/**
+ * Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
+ *
+ * @capability death-system resolve entity death and its on-death consequences
+ */
 export declare function createDeathSystem(deps: DeathSystemDeps): DeathSystem;
 export interface EffectDeathContext {
     from: string;

package/dist/combat/death.js

@@ -11,6 +11,11 @@ export function normalizeOnDeath(spec) {
 function matchesReason(when, reason) {
     return when === undefined || when.reason === reason.kind;
 }
+/**
+ * Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
+ *
+ * @capability death-system resolve entity death and its on-death consequences
+ */
 export function createDeathSystem(deps) {
     const dead = new Set();
     return {

package/dist/combat/deathReason.d.ts

@@ -0,0 +1,14 @@
+/** Why an entity died — who or what gets credit, for drop/command rules and the `entity.died` event. */
+export type DeathReason = {
+    kind: "player_kill";
+    killerUserId: string;
+    via?: {
+        item?: string;
+    };
+} | {
+    kind: "environment";
+    source: string;
+} | {
+    kind: "self";
+    source: string;
+};

package/dist/combat/deathReason.js

@@ -0,0 +1 @@
+export {};

package/dist/combat/defensiveWindow.d.ts

@@ -31,4 +31,9 @@ export interface DefensiveWindow {
     evaluate(nowMs: number, attack: AttackMeta): DefenseResolution;
     isInvulnerable(nowMs: number): boolean;
 }
+/**
+ * Open a timed defensive window — block, parry, or i-frames — and test incoming hits against it.
+ *
+ * @capability parry-window time a block/parry/i-frame defensive window against incoming hits
+ */
 export declare function createDefensiveWindow(config: DefensiveWindowConfig): DefensiveWindow;

package/dist/combat/defensiveWindow.js

@@ -32,6 +32,11 @@ export function resolveDefense(input) {
         return { outcome: "block", perfect: true };
     return { outcome: "hit", perfect: false };
 }
+/**
+ * Open a timed defensive window — block, parry, or i-frames — and test incoming hits against it.
+ *
+ * @capability parry-window time a block/parry/i-frame defensive window against incoming hits
+ */
 export function createDefensiveWindow(config) {
     let openedAt = null;
     function elapsed(nowMs) {

package/dist/combat/dotField.d.ts

@@ -0,0 +1,47 @@
+import type { BuildupProc } from "./breakMeters.js";
+/** A single damage-over-time instance: how hard, how often, and for how long. */
+export interface DotSpec {
+    /** Damage dealt at each interval. */
+    damagePerTick: number;
+    /** Milliseconds between damage ticks; clamped to a positive minimum. */
+    intervalMs: number;
+    /** Total lifetime in milliseconds; the DoT expires once its age reaches this. */
+    durationMs: number;
+    /** Label echoed on each emitted tick (bleed, poison, burn); defaults to the apply key. */
+    status?: string;
+}
+/** One damage event (or expiry marker) emitted by `DotField.tick` for the game to route through its effects. */
+export interface DotTick {
+    /** The key the DoT was applied under. */
+    id: string;
+    /** The DoT's `status` label, or its key when none was given. */
+    status: string;
+    /** Damage to route through the game's effect pipeline this frame; 0 on a bare expiry marker. */
+    damage: number;
+    /** True on the entry that ends the DoT — remove any HUD icon on it. */
+    expired: boolean;
+}
+/**
+ * A pool of timed damage-over-time instances keyed by string (`bleed`, `poison`, `burn`) — the
+ * recurring-damage counterpart to `breakMeters`' one-shot buildup procs (#536.4). `tick` advances
+ * every active DoT and returns the damage due this frame, one entry per interval crossed, so the game
+ * routes each through its own effect pipeline; a pure scheduler that never applies damage itself.
+ */
+export interface DotField {
+    /** Start or refresh a DoT under `id`; reapplying the same key restarts its age and lifetime. */
+    apply(id: string, spec: DotSpec): void;
+    /** Bridge a `breakMeters` buildup proc into recurring damage under `id`. */
+    applyProc(id: string, proc: BuildupProc, damagePerTick: number, intervalMs: number): void;
+    active(id: string): boolean;
+    cancel(id: string): void;
+    clear(): void;
+    count(): number;
+    /** Advance every active DoT; returns the damage due this frame plus an `expired` marker per finished DoT. */
+    tick(dtSeconds: number): DotTick[];
+}
+/**
+ * Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`.
+ *
+ * @capability dot-field track stacking damage-over-time effects and drain damage each frame
+ */
+export declare function createDotField(): DotField;

package/dist/combat/dotField.js

@@ -0,0 +1,52 @@
+/**
+ * Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`.
+ *
+ * @capability dot-field track stacking damage-over-time effects and drain damage each frame
+ */
+export function createDotField() {
+    const dots = new Map();
+    return {
+        apply(id, spec) {
+            dots.set(id, {
+                status: spec.status ?? id,
+                damagePerTick: spec.damagePerTick,
+                intervalMs: Math.max(1, spec.intervalMs),
+                durationMs: Math.max(0, spec.durationMs),
+                ageMs: 0,
+                ticksEmitted: 0,
+            });
+        },
+        applyProc(id, proc, damagePerTick, intervalMs) {
+            this.apply(id, { damagePerTick, intervalMs, durationMs: proc.durationMs, status: proc.status });
+        },
+        active: (id) => dots.has(id),
+        cancel: (id) => void dots.delete(id),
+        clear: () => dots.clear(),
+        count: () => dots.size,
+        tick(dtSeconds) {
+            if (dtSeconds <= 0)
+                return [];
+            const dtMs = dtSeconds * 1000;
+            const emitted = [];
+            for (const [id, dot] of dots) {
+                dot.ageMs += dtMs;
+                const activeMs = Math.min(dot.ageMs, dot.durationMs);
+                const dueTicks = Math.floor(activeMs / dot.intervalMs);
+                let last = null;
+                while (dot.ticksEmitted < dueTicks) {
+                    dot.ticksEmitted += 1;
+                    last = { id, status: dot.status, damage: dot.damagePerTick, expired: false };
+                    emitted.push(last);
+                }
+                if (dot.ageMs >= dot.durationMs) {
+                    dots.delete(id);
+                    if (last !== null)
+                        last.expired = true;
+                    else
+                        emitted.push({ id, status: dot.status, damage: 0, expired: true });
+                }
+            }
+            return emitted;
+        },
+    };
+}

package/dist/combat/downed.d.ts

@@ -32,4 +32,9 @@ export interface DownedState {
     clear(instanceId: string): void;
     snapshot(): Record<string, DownedEntry>;
 }
+/**
+ * A downed/bleed-out state that ticks toward death and that teammates can revive before the timer runs out.
+ *
+ * @capability downed-revive a downed/bleed-out state teammates can revive before death
+ */
 export declare function createDownedState(config: DownedConfig): DownedState;

package/dist/combat/downed.js

@@ -1,3 +1,8 @@
+/**
+ * A downed/bleed-out state that ticks toward death and that teammates can revive before the timer runs out.
+ *
+ * @capability downed-revive a downed/bleed-out state teammates can revive before death
+ */
 export function createDownedState(config) {
     const bleedoutSeconds = Math.max(0, config.bleedoutSeconds);
     const reviveSeconds = config.reviveSeconds !== undefined ? Math.max(0, config.reviveSeconds) : 0;