@jgengine/core 0.10.0 → 0.12.0

package/dist/combat/breakMeters.d.ts

@@ -11,6 +11,11 @@ export interface StaggerMeter {
     recover(): void;
     tick(dtSeconds: number): void;
 }
+/**
+ * Build a stagger/poise gauge from landed hits toward a break threshold that staggers the target.
+ *
+ * @capability stagger-meter build toward a stagger/poise-break threshold from landed hits
+ */
 export declare function createStaggerMeter(config: StaggerMeterConfig): StaggerMeter;
 export interface BuildupMeterConfig {
     status: string;
@@ -29,4 +34,9 @@ export interface BuildupMeter {
     fraction(): number;
     tick(dtSeconds: number): void;
 }
+/**
+ * Accumulate an ailment buildup — bleed, freeze, poison — that procs a status once it fills, then decays.
+ *
+ * @capability stagger-meter accumulate an ailment buildup (bleed, freeze) until it procs
+ */
 export declare function createBuildupMeter(config: BuildupMeterConfig): BuildupMeter;

package/dist/combat/breakMeters.js

@@ -1,4 +1,9 @@
 import { createAccumulatorMeter } from "../stats/accumulatorMeter.js";
+/**
+ * Build a stagger/poise gauge from landed hits toward a break threshold that staggers the target.
+ *
+ * @capability stagger-meter build toward a stagger/poise-break threshold from landed hits
+ */
 export function createStaggerMeter(config) {
     const meter = createAccumulatorMeter({
         max: config.max,
@@ -27,6 +32,11 @@ export function createStaggerMeter(config) {
         },
     };
 }
+/**
+ * Accumulate an ailment buildup — bleed, freeze, poison — that procs a status once it fills, then decays.
+ *
+ * @capability stagger-meter accumulate an ailment buildup (bleed, freeze) until it procs
+ */
 export function createBuildupMeter(config) {
     const meter = createAccumulatorMeter({
         max: config.max,

package/dist/combat/castRunner.d.ts

@@ -37,4 +37,9 @@ export interface CastRunner {
     /** Advance by `dtSeconds`; `movedDistance` accumulates toward the config's `moveTolerance`. */
     tick(dtSeconds: number, movedDistance?: number): CastEvent | null;
 }
+/**
+ * Run a channeled cast/charge timer that movement or damage can interrupt — the spell cast bar.
+ *
+ * @capability cast-bar run a channeled cast timer that movement or damage can interrupt
+ */
 export declare function createCastRunner(): CastRunner;

package/dist/combat/castRunner.js

@@ -1,4 +1,9 @@
 const DEFAULT_MOVE_TOLERANCE = 0.04;
+/**
+ * Run a channeled cast/charge timer that movement or damage can interrupt — the spell cast bar.
+ *
+ * @capability cast-bar run a channeled cast timer that movement or damage can interrupt
+ */
 export function createCastRunner() {
     let active = null;
     function snapshot() {

package/dist/combat/comboPoints.d.ts

@@ -11,4 +11,9 @@ export interface ComboPoints {
     expiresIn(): number | null;
     clear(): void;
 }
+/**
+ * Build and spend finisher points — the combo-point economy behind rogue-style builders and spenders.
+ *
+ * @capability combo-points build up and spend finisher/combo points
+ */
 export declare function createComboPoints(config: ComboPointsConfig): ComboPoints;

package/dist/combat/comboPoints.js

@@ -1,3 +1,8 @@
+/**
+ * Build and spend finisher points — the combo-point economy behind rogue-style builders and spenders.
+ *
+ * @capability combo-points build up and spend finisher/combo points
+ */
 export function createComboPoints(config) {
     const max = config.max;
     const expireAfterSeconds = config.expireAfterSeconds;

package/dist/combat/comboString.d.ts

@@ -32,4 +32,9 @@ export interface ComboRunner {
     request(stepId: string, stance?: string): AdvanceComboResult;
     reset(): void;
 }
+/**
+ * Advance a chained melee string from timed inputs, tracking the current step and its cancel/continue windows.
+ *
+ * @capability combo-chain advance a chained melee string from timed button inputs
+ */
 export declare function createComboRunner(combo: ComboString, anim: AnimationState): ComboRunner;

package/dist/combat/comboString.js

@@ -32,6 +32,11 @@ export function advanceCombo(input) {
     }
     return { accepted: true, step: requested };
 }
+/**
+ * Advance a chained melee string from timed inputs, tracking the current step and its cancel/continue windows.
+ *
+ * @capability combo-chain advance a chained melee string from timed button inputs
+ */
 export function createComboRunner(combo, anim) {
     let current = null;
     return {

package/dist/combat/damageInterceptors.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 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.
+ */
+/** A damage application queued for resolution against a target. `amount` is always non-negative; healing is a separate concern. */
+export interface PendingDamage {
+    /** Instance receiving the damage. */
+    target: string;
+    /** Instance dealing the damage. */
+    source: string;
+    /** Damage magnitude, non-negative. */
+    amount: number;
+    /** Optional caller tag (weapon id, effect id, channel) carried through for provenance and downstream routing. */
+    tag?: string;
+}
+/**
+ * What an interceptor decides to do with the pending application it was handed.
+ * `split` parts continue at the NEXT interceptor (never re-entering the splitter),
+ * which is what keeps the pipeline bounded and recursion-free.
+ */
+export type InterceptDecision = {
+    kind: "pass";
+} | {
+    kind: "transform";
+    amount: number;
+    note?: string;
+} | {
+    kind: "clamp";
+    max: number;
+    note?: string;
+} | {
+    kind: "redirect";
+    target: string;
+    note?: string;
+} | {
+    kind: "split";
+    parts: readonly PendingDamage[];
+    note?: string;
+} | {
+    kind: "defer";
+    note?: string;
+} | {
+    kind: "reject";
+    note?: string;
+};
+/** Read-only context an interceptor may consult — deterministic clock and optional health lookup for HP-relative policies. */
+export interface InterceptContext {
+    /** Deterministic current time in milliseconds; interceptors never read a wall clock. */
+    nowMs: number;
+    /** Optional current/max pool lookup for the target, enabling HP-relative clamps like anti-one-shot. */
+    healthOf?(target: string): {
+        current: number;
+        max: number;
+    } | undefined;
+}
+/** A named stage in the interception pipeline. The `id` is stable so it can be installed, removed, and cited in provenance. */
+export interface DamageInterceptor {
+    /** Stable identifier used for install/remove and provenance. */
+    id: string;
+    /** Decide what happens to `pending`; must be deterministic given `ctx`. */
+    intercept(pending: PendingDamage, ctx: InterceptContext): InterceptDecision;
+}
+/** One row of provenance: which interceptor acted, what it decided, and the amount before/after it acted. */
+export interface InterceptRecord {
+    interceptor: string;
+    kind: InterceptDecision["kind"];
+    target: string;
+    before: number;
+    after: number;
+    note?: string;
+}
+/** The outcome of running a pending application through the pipeline: what to apply, what was deferred, and why each value changed. */
+export interface DamageResolution {
+    /** Final applications to commit (0..n after splits/rejections). */
+    applications: PendingDamage[];
+    /** Applications held back by a `defer` decision for the caller to resubmit later. */
+    deferred: PendingDamage[];
+    /** Ordered record of every interceptor decision. */
+    provenance: InterceptRecord[];
+}
+/** Upper bound on interceptor evaluations for a single resolution; guards against runaway `split`/`redirect` loops. */
+export declare 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 declare function resolveDamage(interceptors: readonly DamageInterceptor[], pending: PendingDamage, ctx: InterceptContext): DamageResolution;
+/** A mutable ordered interceptor chain that transitions can install into and remove from at runtime. */
+export interface DamagePipeline {
+    /** Append an interceptor, or replace an existing one with the same `id` in place. */
+    install(interceptor: DamageInterceptor): void;
+    /** Remove the interceptor with `id`; returns whether one was removed. */
+    remove(id: string): boolean;
+    /** Whether an interceptor with `id` is currently installed. */
+    has(id: string): boolean;
+    /** Installed interceptor ids in evaluation order (serializable install record). */
+    interceptorIds(): string[];
+    /** Resolve one pending application through the current chain. */
+    resolve(pending: PendingDamage, ctx: InterceptContext): DamageResolution;
+}
+/**
+ * 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 declare function createDamagePipeline(initial?: readonly DamageInterceptor[]): DamagePipeline;
+/** Caller data for a flat per-hit damage cap. */
+export interface DamageClampConfig {
+    /** Interceptor id; defaults to `"damage-clamp"`. */
+    id?: string;
+    /** Maximum damage a single application may carry. */
+    maxPerHit: number;
+}
+/**
+ * A stateless interceptor that caps any single application at `maxPerHit`.
+ *
+ * @capability damage-clamp cap incoming damage per hit at a configured maximum
+ */
+export declare function createDamageClamp(config: DamageClampConfig): DamageInterceptor;
+/** A per-target timed immunity policy: an interceptor plus grant/query/serialize controls, toggled by transitions. */
+export interface ImmunityWindow {
+    /** The interceptor to install; rejects damage to any target whose immunity has not expired. */
+    interceptor: DamageInterceptor;
+    /** Make `target` immune until `untilMs` (extends, never shortens, an existing window). */
+    grant(target: string, untilMs: number): void;
+    /** Make `target` immune for `durationMs` starting at `nowMs`. */
+    grantFor(target: string, nowMs: number, durationMs: number): void;
+    /** Whether `target` is immune at `nowMs`. */
+    active(target: string, nowMs: number): boolean;
+    /** Drop `target`'s immunity immediately. */
+    clear(target: string): void;
+    /** Drop every window that has expired at `nowMs` (bounded housekeeping for save size). */
+    clearExpired(nowMs: number): void;
+    /** Serializable snapshot: target → expiry ms. */
+    snapshot(): Record<string, number>;
+    /** Restore from a snapshot. */
+    restore(snap: Record<string, number>): void;
+}
+/**
+ * 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 declare function createImmunityWindow(id?: string): ImmunityWindow;
+/** Caller data for the anti-one-shot composition: "cannot cross lethal while above X, leave Y, then recover for Z". */
+export interface AntiOneShotConfig {
+    /** Interceptor id; defaults to `"anti-one-shot"`. */
+    id?: string;
+    /** Only intervene when the target's HP fraction is strictly above this (X). Below it, lethal hits pass. */
+    guardAboveFraction: number;
+    /** HP fraction to leave the target at after an intercepted near-lethal hit (Y). */
+    leaveFraction: number;
+    /** Immunity granted after an intercepted hit, in milliseconds (Z). */
+    recoverMs: number;
+}
+/** The anti-one-shot policy: an interceptor plus its serializable recovery-immunity state. */
+export interface AntiOneShotPolicy {
+    /** The interceptor to install ahead of lethal resolution. */
+    interceptor: DamageInterceptor;
+    /** Whether `target` is in the post-hit recovery i-frame at `nowMs`. */
+    immune(target: string, nowMs: number): boolean;
+    /** Serializable snapshot: target → recovery expiry ms. */
+    snapshot(): Record<string, number>;
+    /** Restore from a snapshot. */
+    restore(snap: Record<string, number>): void;
+}
+/**
+ * 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 declare function createAntiOneShotPolicy(config: AntiOneShotConfig): AntiOneShotPolicy;

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