@jgengine/core 0.14.0 → 0.15.0-next.0

package/dist/combat/comboMeter.js

@@ -0,0 +1,215 @@
+function sortTiers(tiers) {
+    return tiers === undefined ? [] : [...tiers].sort((a, b) => a.threshold - b.threshold);
+}
+/** Index of the highest tier whose `threshold` `count` has reached, or `-1` below the first. */
+function activeIndex(count, tiers) {
+    let idx = -1;
+    for (let i = 0; i < tiers.length; i += 1) {
+        if (count >= tiers[i].threshold)
+            idx = i;
+        else
+            break;
+    }
+    return idx;
+}
+/**
+ * A count-based combo / multiplier meter: an integer hit chain that climbs with
+ * every `hit()` and drops when a decay window elapses, crossing free-string tier
+ * thresholds ("good" → "great" → "savage") that derive a score multiplier, while
+ * tracking the peak reached. Time is injected (`now`, default `Date.now`) and/or
+ * driven by `update(dt)`; `view()` returns a pooled draw-state and
+ * `snapshot`/`restore` round-trips the chain through a save.
+ *
+ * Distinct from the existing meters — reused none of them because none is this
+ * shape: `stats/eventMeter` is a value/heat gauge that rises by tagged gains and
+ * decays continuously (not an integer chain count with a reset-on-hit window);
+ * `combat/comboPoints` is a finisher-point pool that hard-expires with no tiers,
+ * multiplier, or subscribe; `stats/accumulatorMeter` is a float gauge crossing
+ * `at`-value tiers, not a count with a draining window and derived multiplier.
+ *
+ * @capability combo-meter count-based combo/multiplier meter with a decay window, free-string tier thresholds, derived multiplier, peak tracking and snapshot/restore
+ */
+export function createComboMeter(config) {
+    const now = config.now ?? Date.now;
+    let windowMs = Math.max(0, config.windowMs);
+    let tiers = sortTiers(config.tiers);
+    let dropStep = config.dropStep;
+    let multiplierPerTier = config.multiplierPerTier;
+    let multiplierCurve = config.multiplierCurve;
+    let count = Math.max(0, Math.floor(config.count ?? 0));
+    let peak = count;
+    let kind = "";
+    // Logical clock (ms). `manual` flips true on the first update(dt) call, after
+    // which the injected `now` is ignored and only update(dt) advances time.
+    let manual = false;
+    let time = now();
+    let lastNow = time;
+    // Absolute logical time the current window ends; null when the chain is empty.
+    let deadline = count > 0 && windowMs > 0 ? time + windowMs : null;
+    const listeners = new Set();
+    const pooledView = {
+        count: 0,
+        peak: 0,
+        tier: null,
+        tierIndex: -1,
+        multiplier: 1,
+        remainingMs: 0,
+        fraction: 0,
+        kind: "",
+    };
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Sync the logical clock from wall time unless update(dt) has taken over. */
+    function syncWall() {
+        if (manual)
+            return;
+        const t = now();
+        time += t - lastNow;
+        lastNow = t;
+    }
+    /** Drop the chain once for each elapsed window; returns whether anything changed. */
+    function processExpiry() {
+        if (deadline === null || windowMs <= 0)
+            return false;
+        let changed = false;
+        while (deadline !== null && time >= deadline) {
+            if (dropStep !== undefined && dropStep > 0 && count - dropStep > 0) {
+                count -= dropStep;
+                deadline += windowMs;
+            }
+            else {
+                count = 0;
+                deadline = null;
+            }
+            changed = true;
+        }
+        return changed;
+    }
+    /** Bring the clock and expiry state up to date before any read. */
+    function pull() {
+        syncWall();
+        if (processExpiry())
+            notify();
+    }
+    function multiplierAt(c) {
+        const idx = activeIndex(c, tiers);
+        if (idx >= 0) {
+            const explicit = tiers[idx].multiplier;
+            if (explicit !== undefined)
+                return explicit;
+        }
+        if (multiplierPerTier !== undefined)
+            return 1 + (idx + 1) * multiplierPerTier;
+        if (multiplierCurve !== undefined)
+            return multiplierCurve(c, idx);
+        return 1;
+    }
+    function remaining() {
+        if (count <= 0 || deadline === null)
+            return 0;
+        return Math.max(0, deadline - time);
+    }
+    return {
+        hit(hitKind = "") {
+            syncWall();
+            processExpiry();
+            count += 1;
+            if (count > peak)
+                peak = count;
+            kind = hitKind;
+            deadline = windowMs > 0 ? time + windowMs : null;
+            notify();
+            return count;
+        },
+        update(dtSeconds) {
+            manual = true;
+            if (dtSeconds > 0)
+                time += dtSeconds * 1000;
+            if (processExpiry())
+                notify();
+        },
+        count() {
+            pull();
+            return count;
+        },
+        peak() {
+            pull();
+            return peak;
+        },
+        tier() {
+            pull();
+            const idx = activeIndex(count, tiers);
+            return idx >= 0 ? tiers[idx].id : null;
+        },
+        multiplier() {
+            pull();
+            return multiplierAt(count);
+        },
+        remainingMs() {
+            pull();
+            return remaining();
+        },
+        fraction() {
+            pull();
+            return windowMs <= 0 ? 0 : Math.max(0, Math.min(1, remaining() / windowMs));
+        },
+        view() {
+            pull();
+            const idx = activeIndex(count, tiers);
+            const rem = remaining();
+            pooledView.count = count;
+            pooledView.peak = peak;
+            pooledView.tier = idx >= 0 ? tiers[idx].id : null;
+            pooledView.tierIndex = idx;
+            pooledView.multiplier = multiplierAt(count);
+            pooledView.remainingMs = rem;
+            pooledView.fraction = windowMs <= 0 ? 0 : Math.max(0, Math.min(1, rem / windowMs));
+            pooledView.kind = kind;
+            return pooledView;
+        },
+        reset() {
+            count = 0;
+            peak = 0;
+            kind = "";
+            deadline = null;
+            notify();
+        },
+        configure(patch) {
+            if (patch.windowMs !== undefined)
+                windowMs = Math.max(0, patch.windowMs);
+            if (patch.tiers !== undefined)
+                tiers = sortTiers(patch.tiers);
+            if ("dropStep" in patch)
+                dropStep = patch.dropStep;
+            if ("multiplierPerTier" in patch)
+                multiplierPerTier = patch.multiplierPerTier;
+            if ("multiplierCurve" in patch)
+                multiplierCurve = patch.multiplierCurve;
+            // Re-arm the window if it changed while a chain is live.
+            if (patch.windowMs !== undefined && count > 0) {
+                deadline = windowMs > 0 ? time + windowMs : null;
+            }
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            syncWall();
+            processExpiry();
+            const idx = activeIndex(count, tiers);
+            return { count, peak, remainingMs: remaining(), tier: idx >= 0 ? tiers[idx].id : null };
+        },
+        restore(snapshot) {
+            syncWall();
+            count = Math.max(0, Math.floor(snapshot.count));
+            peak = Math.max(count, Math.floor(snapshot.peak));
+            kind = "";
+            deadline = count > 0 && windowMs > 0 && snapshot.remainingMs > 0 ? time + snapshot.remainingMs : null;
+            notify();
+        },
+    };
+}

package/dist/combat/comboPoints.d.ts

@@ -2,6 +2,13 @@ export interface ComboPointsConfig {
     max: number;
     expireAfterSeconds?: number;
 }
+/** Complete serializable state for {@link ComboPoints}; `remaining: null` means no expiry is running. */
+export interface ComboPointsSnapshot {
+    points: number;
+    remaining: number | null;
+    max: number;
+    expireAfterSeconds: number | null;
+}
 export interface ComboPoints {
     points(): number;
     gain(amount?: number): number;
@@ -10,6 +17,10 @@ export interface ComboPoints {
     tick(dtSeconds: number): void;
     expiresIn(): number | null;
     clear(): void;
+    /** The whole builder as plain data — save it, ship it to a host, diff it in a test. */
+    snapshot(): ComboPointsSnapshot;
+    /** Adopt a snapshot, replacing points, expiry, and tuning. */
+    restore(state: ComboPointsSnapshot): void;
 }
 /**
  * Build and spend finisher points — the combo-point economy behind rogue-style builders and spenders.

package/dist/combat/comboPoints.js

@@ -4,8 +4,8 @@
  * @capability combo-points build up and spend finisher/combo points
  */
 export function createComboPoints(config) {
-    const max = config.max;
-    const expireAfterSeconds = config.expireAfterSeconds;
+    let max = config.max;
+    let expireAfterSeconds = config.expireAfterSeconds;
     let current = 0;
     let remaining = null;
     return {
@@ -49,6 +49,15 @@ export function createComboPoints(config) {
                 return null;
             return remaining;
         },
+        snapshot() {
+            return { points: current, remaining, max, expireAfterSeconds: expireAfterSeconds ?? null };
+        },
+        restore(state) {
+            max = state.max;
+            expireAfterSeconds = state.expireAfterSeconds ?? undefined;
+            current = Math.max(0, Math.min(max, state.points));
+            remaining = current <= 0 ? null : state.remaining;
+        },
         clear() {
             current = 0;
             remaining = null;

package/dist/combat/damageResolution.d.ts

@@ -29,7 +29,7 @@ export interface DamageHitInput {
     currentStatus?: StatusInstance | null;
     /** Statuses the target is immune to. */
     immunity?: StatusImmunity | null;
-    /** Deterministic RNG for the status roll; defaults to `Math.random`. */
+    /** Deterministic RNG for the status roll. Omitting it falls back to `Math.random` and warns once — pass `ctx.rng`. */
     rng?: () => number;
 }
 /**

package/dist/combat/defensiveWindow.d.ts

@@ -11,6 +11,11 @@ export interface DefensiveWindowConfig {
     };
 }
 export type DefenseOutcome = "parry" | "block" | "iframe" | "hit";
+/**
+ * Result of resolving an incoming hit against a defensive window: `outcome` is the graded defense
+ * (`"parry"`/`"block"`/`"iframe"`/`"hit"`) and `perfect` is true when the input landed inside the
+ * tight just-frame at the window's start rather than its wider active span.
+ */
 export interface DefenseResolution {
     outcome: DefenseOutcome;
     perfect: boolean;

package/dist/combat/effects.d.ts

@@ -29,11 +29,29 @@ export interface AppliedPoolDelta {
     statId: string;
     delta: number;
 }
+/**
+ * Identity of an entity slain by a lethal effect, captured before the death system despawns it.
+ * Serializable and genre-agnostic: `catalogId` is the slain entity's spawn kind/name (the same
+ * value the `entity.died` event carries), `name` an optional human-readable label for kill feeds,
+ * and `userId` the owning player when the slain unit was player-controlled. The slain entity's
+ * instance id is already {@link EffectResult.instanceId}.
+ */
+export interface SlainIdentity {
+    catalogId: string;
+    name?: string;
+    userId?: string;
+}
 export interface EffectResult {
     instanceId: string;
     effect: string;
     applied: AppliedPoolDelta[];
     lethal: boolean;
+    /**
+     * Present only on a lethal hit: the slain entity's identity, captured before despawn so
+     * kill-credit / XP can read `catalogId`/`name` without a game-side spawn-time registry.
+     * A non-lethal hit omits this field.
+     */
+    slain?: SlainIdentity;
 }
 export interface LethalContext {
     from: string;
@@ -68,6 +86,12 @@ export interface EffectSystemDeps {
     getStat(itemId: string, stat: string): number | null;
     spatial: CombatSpatialDeps;
     drainStatByEffect?: Record<string, string>;
+    /**
+     * Resolve the target's identity, called on a lethal hit *before* {@link onLethal} despawns it.
+     * The returned {@link SlainIdentity} is attached to the lethal {@link EffectResult.slain} so kill
+     * credit works without a parallel registry. Return `null`/`undefined` to omit identity.
+     */
+    resolveSlainIdentity?(instanceId: string): SlainIdentity | null | undefined;
     onLethal?(instanceId: string, ctx: LethalContext): void;
 }
 export interface EffectSystem {

package/dist/combat/effects.js

@@ -103,8 +103,13 @@ export function createEffectSystem(deps) {
         if (canReceive(instanceId, effect, drainMagnitude) !== null)
             return null;
         const result = drainPools(instanceId, effect, rule, drainMagnitude);
-        if (result.lethal)
+        if (result.lethal) {
+            // Capture identity before onLethal, which runs the death system and despawns the target.
+            const slain = deps.resolveSlainIdentity?.(instanceId);
+            if (slain !== null && slain !== undefined)
+                result.slain = slain;
             deps.onLethal?.(instanceId, { from, via, effect });
+        }
         return result;
     }
     return {

package/dist/combat/projectiles.d.ts

@@ -40,6 +40,12 @@ export interface ProjectileSettleReport {
     at: EntityPosition;
     effect: string;
     hit: boolean;
+    /**
+     * True for lobbed/exploding shots (grenades, launchers, rockets) whose real path is an arc,
+     * false for direct-fire shots (bullets, bolts) that travel muzzle→impact in a straight line.
+     * Presentation uses it to keep straight-line tracers off arced projectiles.
+     */
+    ballistic: boolean;
 }
 export interface ProjectileObjectsDeps {
     list(): readonly {

package/dist/combat/projectiles.js

@@ -308,7 +308,7 @@ export function createProjectileSystem(deps) {
                     radius,
                     falloff: splashRadius === null ? "none" : "linear",
                 });
-                deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: hits.length > 0 });
+                deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: hits.length > 0, ballistic: true });
                 return { status: "settled", shotId, at, hits, origin: originTuple };
             }
             const { visible, rawHits } = predictHits(input);
@@ -343,7 +343,7 @@ export function createProjectileSystem(deps) {
             else {
                 at = missPoint(input);
             }
-            deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: hits.length > 0 });
+            deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: hits.length > 0, ballistic: false });
             return { status: "settled", shotId, at, hits, origin: originTuple };
         },
     };

package/dist/combat/regenShield.d.ts

@@ -1,3 +1,20 @@
+/**
+ * External storage a {@link RegenShield} reads and writes instead of keeping the value itself —
+ * an entity stat, a replicated store, a save record. This is the same port `Magazine` exposes as
+ * `MagazineReserve`, and it exists for the same reason: in most games the shield value is already
+ * owned by the stat system that damage, the HUD, and replication all read, so a primitive that
+ * insists on owning the number privately cannot be adopted without creating a second source of truth.
+ *
+ * A pool-backed shield also watches for *external* decreases — damage applied through the game's own
+ * effect pipeline rather than through `damage()` — and restarts the regen grace period when it sees
+ * one, which is the per-entity snapshot bookkeeping games otherwise hand-roll.
+ */
+export interface RegenShieldPool {
+    current(): number;
+    max(): number;
+    /** Write the value back; implementations clamp to their own bounds. */
+    set(value: number): void;
+}
 /** Tuning for `createRegenShield`: pool size, refill rate, and the post-damage grace period. */
 export interface RegenShieldConfig {
     max: number;
@@ -5,8 +22,14 @@ export interface RegenShieldConfig {
     regenPerSecond: number;
     /** Grace period after the last damage before regen resumes. */
     regenDelayMs: number;
-    /** Starting value; defaults to `max` (full). */
+    /** Starting value; defaults to `max` (full). Ignored when `pool` is set — the pool owns the value. */
     current?: number;
+    /**
+     * Back this shield with external storage instead of internal state. `max` and `current` then come
+     * from the pool, `setMax` is a no-op (the pool owns its bounds), and a drop in the pool's value
+     * between ticks is treated as damage for the purposes of the regen grace period.
+     */
+    pool?: RegenShieldPool;
 }
 /**
  * A shield pool that stops regenerating for `regenDelayMs` after every hit, then refills at
@@ -28,8 +51,23 @@ export interface RegenShield {
     /** Add `amount` without touching the regen timer (a pickup or scripted refill). */
     restore(amount: number): void;
     set(value: number): void;
+    /**
+     * Restart the regen grace period without changing the value — for damage the shield cannot see,
+     * such as a hit that landed on health after the shield was already down, or damage routed through
+     * a game's own effect pipeline.
+     */
+    noteDamage(): void;
     /** Advance time: count down the grace period, then regenerate once it has elapsed. */
-    tick(dtSeconds: number): void;
+    tick(dtSeconds: number, rates?: RegenShieldRates): void;
+}
+/**
+ * Per-tick rate overrides, for games that derive regen from live state — a talent tree, a buff, an
+ * equipped mod — rather than a constant fixed when the shield was built. Omit to use the configured
+ * values; the grace period in effect is whichever `regenDelayMs` was last passed to `tick`.
+ */
+export interface RegenShieldRates {
+    regenPerSecond?: number;
+    regenDelayMs?: number;
 }
 /**
  * Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit.

package/dist/combat/regenShield.js

@@ -4,46 +4,94 @@
  * @capability regen-shield a rechargeable overshield that absorbs damage and refills after a lull
  */
 export function createRegenShield(config) {
-    let max = Math.max(0, config.max);
+    const pool = config.pool;
     const regenPerSecond = Math.max(0, config.regenPerSecond);
     const regenDelayMs = Math.max(0, config.regenDelayMs);
     function clamp(value, ceiling) {
         return Math.max(0, Math.min(ceiling, value));
     }
-    let current = clamp(config.current ?? max, max);
+    let ownMax = Math.max(0, config.max);
+    let ownCurrent = clamp(config.current ?? ownMax, ownMax);
     let sinceDamageMs = regenDelayMs;
+    /** Grace period currently in force — the configured one until a `tick` overrides it. */
+    let activeDelayMs = regenDelayMs;
+    const readMax = () => (pool === undefined ? ownMax : Math.max(0, pool.max()));
+    const readCurrent = () => (pool === undefined ? ownCurrent : clamp(pool.current(), readMax()));
+    function write(value) {
+        const next = clamp(value, readMax());
+        if (pool === undefined)
+            ownCurrent = next;
+        else
+            pool.set(next);
+    }
+    /**
+     * Last value this shield knows about, so a pool-backed shield can tell its own writes apart from
+     * damage applied elsewhere. `null` until the first observation, so the first tick never reads a
+     * cold start as a hit.
+     */
+    let observed = pool === undefined ? null : readCurrent();
+    /** Detect an external decrease in a pool-backed value and restart the grace period if one happened. */
+    function syncExternal() {
+        if (pool === undefined)
+            return;
+        const live = readCurrent();
+        if (observed !== null && live < observed)
+            sinceDamageMs = 0;
+        observed = live;
+    }
     return {
-        current: () => current,
-        max: () => max,
+        current: readCurrent,
+        max: readMax,
         setMax(value) {
-            max = Math.max(0, value);
-            current = clamp(current, max);
+            // A pool owns its own bounds (an entity stat's max, a save record's cap); resizing it here
+            // would silently disagree with whatever else writes that storage.
+            if (pool !== undefined)
+                return;
+            ownMax = Math.max(0, value);
+            ownCurrent = clamp(ownCurrent, ownMax);
         },
-        fraction: () => (max <= 0 ? 0 : current / max),
-        isFull: () => current >= max,
-        isBroken: () => current <= 0,
-        suppressed: () => sinceDamageMs < regenDelayMs,
+        fraction: () => (readMax() <= 0 ? 0 : readCurrent() / readMax()),
+        isFull: () => readCurrent() >= readMax(),
+        isBroken: () => readCurrent() <= 0,
+        suppressed: () => sinceDamageMs < activeDelayMs,
         damage(amount) {
             if (amount <= 0)
                 return 0;
+            syncExternal();
             sinceDamageMs = 0;
-            const overflow = Math.max(0, amount - current);
-            current = clamp(current - amount, max);
+            const live = readCurrent();
+            const overflow = Math.max(0, amount - live);
+            write(live - amount);
+            observed = pool === undefined ? observed : readCurrent();
             return overflow;
         },
         restore(amount) {
-            if (amount > 0)
-                current = clamp(current + amount, max);
+            if (amount <= 0)
+                return;
+            syncExternal();
+            write(readCurrent() + amount);
+            observed = pool === undefined ? observed : readCurrent();
         },
         set(value) {
-            current = clamp(value, max);
+            write(value);
+            observed = pool === undefined ? observed : readCurrent();
+        },
+        noteDamage() {
+            syncExternal();
+            sinceDamageMs = 0;
         },
-        tick(dtSeconds) {
+        tick(dtSeconds, rates) {
+            activeDelayMs = Math.max(0, rates?.regenDelayMs ?? regenDelayMs);
             if (dtSeconds <= 0)
                 return;
+            // Advance time first, THEN observe: damage that landed since the last tick resets the timer to
+            // zero for this tick, so the tick that sees a hit never also regenerates over it.
             sinceDamageMs += dtSeconds * 1000;
-            if (sinceDamageMs >= regenDelayMs)
-                current = clamp(current + regenPerSecond * dtSeconds, max);
+            syncExternal();
+            if (sinceDamageMs < activeDelayMs)
+                return;
+            write(readCurrent() + Math.max(0, rates?.regenPerSecond ?? regenPerSecond) * dtSeconds);
+            observed = pool === undefined ? observed : readCurrent();
         },
     };
 }

package/dist/combat/resourcePool.d.ts

@@ -4,6 +4,19 @@ export interface ResourcePoolConfig {
     regenPerSecond?: number;
     decayPerSecond?: number;
 }
+/** Complete serializable state for a {@link ResourcePool}. */
+export interface ResourcePoolSnapshot {
+    current: number;
+    max: number;
+    regenPerSecond: number;
+    decayPerSecond: number;
+}
+/** Runtime tuning patch for {@link ResourcePool.retune} — omitted fields keep their current value. */
+export interface ResourcePoolRetune {
+    max?: number;
+    regenPerSecond?: number;
+    decayPerSecond?: number;
+}
 export interface ResourcePool {
     current(): number;
     max(): number;
@@ -16,6 +29,12 @@ export interface ResourcePool {
     tick(dtSeconds: number): void;
     isFull(): boolean;
     isEmpty(): boolean;
+    /** The whole pool as plain data — save it, ship it to a host, diff it in a test. */
+    snapshot(): ResourcePoolSnapshot;
+    /** Adopt a snapshot, replacing current value and tuning. */
+    restore(state: ResourcePoolSnapshot): void;
+    /** Change regen/decay/max mid-run (a buff, a difficulty change) without rebuilding the pool. */
+    retune(patch: ResourcePoolRetune): void;
 }
 /**
  * A regenerating resource pool — mana, stamina, energy — that actions spend from and that refills over time.

package/dist/combat/resourcePool.js

@@ -5,8 +5,8 @@
  */
 export function createResourcePool(config) {
     let max = Math.max(0, config.max);
-    const regenPerSecond = Math.max(0, config.regenPerSecond ?? 0);
-    const decayPerSecond = Math.max(0, config.decayPerSecond ?? 0);
+    let regenPerSecond = Math.max(0, config.regenPerSecond ?? 0);
+    let decayPerSecond = Math.max(0, config.decayPerSecond ?? 0);
     let current = clamp(config.initial ?? max, max);
     function clamp(value, ceiling) {
         return Math.max(0, Math.min(ceiling, value));
@@ -56,5 +56,23 @@ export function createResourcePool(config) {
         isEmpty() {
             return current <= 0;
         },
+        snapshot() {
+            return { current, max, regenPerSecond, decayPerSecond };
+        },
+        restore(state) {
+            max = Math.max(0, state.max);
+            regenPerSecond = Math.max(0, state.regenPerSecond);
+            decayPerSecond = Math.max(0, state.decayPerSecond);
+            current = clamp(state.current, max);
+        },
+        retune(patch) {
+            if (patch.max !== undefined)
+                max = Math.max(0, patch.max);
+            if (patch.regenPerSecond !== undefined)
+                regenPerSecond = Math.max(0, patch.regenPerSecond);
+            if (patch.decayPerSecond !== undefined)
+                decayPerSecond = Math.max(0, patch.decayPerSecond);
+            current = clamp(current, max);
+        },
     };
 }

package/dist/combat/shotOrigin.d.ts

@@ -43,6 +43,11 @@ export type ShotOriginPolicy = {
     origin: EntityPosition;
     direction?: EntityPosition;
 };
+/**
+ * A shot's resolved firing geometry in world space: `origin` is the point the projectile/ray starts
+ * from and `direction` is its normalized aim vector, both computed by {@link resolveShot} from the
+ * shooter's position, facing, and the chosen origin policy.
+ */
 export interface ResolvedShot {
     origin: EntityPosition;
     direction: EntityPosition;

package/dist/combat/statusApplication.d.ts

@@ -70,7 +70,7 @@ export interface StatusApplicationInput {
     immunity?: StatusImmunity | null;
     /** Attribution written onto the resulting instance. */
     source?: string;
-    /** Deterministic RNG returning `[0,1)`; defaults to `Math.random`. Pass a seeded stream for reproducibility. */
+    /** Deterministic RNG returning `[0,1)`. Omitting it falls back to `Math.random` and warns once — pass `ctx.rng` or a seeded stream. */
     rng?: () => number;
 }
 /** Why an application did or did not take, plus the roll for provenance. */

package/dist/combat/statusApplication.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 function clamp01(value) {
     if (value < 0)
         return 0;
@@ -15,7 +16,7 @@ function clamp01(value) {
  */
 export function resolveStatusApplication(input) {
     const { spec, scale, current, immunity, source } = input;
-    const rng = input.rng ?? Math.random;
+    const rng = resolveRng(input.rng, "applyStatus");
     if (immunity?.statuses?.includes(spec.status) === true) {
         return { kind: "immune", instance: current ?? null, chance: 0, roll: null };
     }