@jgengine/core 0.14.0 → 0.15.0

package/dist/combat/comboMeter.d.ts

@@ -0,0 +1,140 @@
+/**
+ * One tier threshold in a {@link ComboMeter}. Tiers gate on the integer combo
+ * `count` (not a filled fraction), and `id` is a free string the game owns and
+ * styles ("good", "great", "savage", …) — the model never interprets it.
+ */
+export interface ComboTier {
+    /** Combo count at or above which this tier becomes active. Tiers sort ascending. */
+    threshold: number;
+    /** Free-string tier id the game styles; the model never branches on it. */
+    id: string;
+    /** Explicit multiplier while this tier is active. Overrides any fallback curve. */
+    multiplier?: number;
+}
+/** Options for {@link createComboMeter}. */
+export interface ComboMeterConfig {
+    /**
+     * Decay window in ms: how long after the last {@link ComboMeter.hit} the combo
+     * survives before it drops. Each `hit` resets this window; when it elapses the
+     * combo drops (to 0, or by {@link ComboMeterConfig.dropStep}).
+     */
+    windowMs: number;
+    /** Tier thresholds on the integer count. Sorted ascending internally; ids are free strings. */
+    tiers?: readonly ComboTier[];
+    /**
+     * When the window elapses, drop the count by this many instead of clearing to 0,
+     * re-arming the window so a long combo bleeds down step by step. Omit → drop to 0.
+     */
+    dropStep?: number;
+    /**
+     * Fallback multiplier growth when the active tier has no explicit `multiplier`:
+     * `1 + (tierIndex + 1) * multiplierPerTier`. Below the first tier the multiplier
+     * is always 1. Ignored where a tier sets its own `multiplier`.
+     */
+    multiplierPerTier?: number;
+    /**
+     * Last-resort multiplier curve when neither the active tier's `multiplier` nor
+     * `multiplierPerTier` applies. Receives the current count and active tier index
+     * (`-1` below the first tier). Not serialized — snapshot/restore carry state, not config.
+     */
+    multiplierCurve?: (count: number, tierIndex: number) => number;
+    /** Injected clock (ms). Default `Date.now`. Ignored once {@link ComboMeter.update} drives time. */
+    now?: () => number;
+    /** Initial combo count (pre-seed a demo/save at a high chain). Default 0. */
+    count?: number;
+}
+/**
+ * A pooled, read-only snapshot of the live meter for a renderer to draw each
+ * frame. Reused across {@link ComboMeter.view} calls and overwritten on the next
+ * one — read it, do not retain it. For a save, use {@link ComboMeter.snapshot}.
+ */
+export interface ComboMeterView {
+    /** Current combo count. */
+    count: number;
+    /** Highest count reached since the last {@link ComboMeter.reset}. */
+    peak: number;
+    /** Active tier id, or `null` below the first tier. */
+    tier: string | null;
+    /** Active tier index into the sorted tier list, or `-1` below the first tier. */
+    tierIndex: number;
+    /** Derived multiplier for the active tier (default 1). */
+    multiplier: number;
+    /** Milliseconds left in the decay window before the next drop (0 when idle). */
+    remainingMs: number;
+    /** Window remaining as `0..1` — for a draining ring/bar. */
+    fraction: number;
+    /** Free-string `kind` of the most recent hit, or `""` — carried through, never interpreted. */
+    kind: string;
+}
+/** Serializable state for save/restore — clock-agnostic (stores time left, not an absolute deadline). */
+export interface ComboMeterSnapshot {
+    /** Combo count. */
+    count: number;
+    /** Peak count reached. */
+    peak: number;
+    /** Milliseconds remaining in the decay window at snapshot time. */
+    remainingMs: number;
+    /** Active tier id at snapshot time (recomputed on restore; kept for readability). */
+    tier: string | null;
+}
+/**
+ * A live, observable combo/multiplier meter — an integer hit chain with a decay
+ * window, free-string tier thresholds, a derived multiplier, and peak tracking.
+ */
+export interface ComboMeter {
+    /**
+     * Register a landed hit: bump the count by one and reset the decay window. `kind`
+     * is a free string carried through to {@link ComboMeter.view} for the renderer to
+     * color/skin; the model never interprets it. Returns the new count.
+     */
+    hit(kind?: string): number;
+    /**
+     * Advance the decay window by `dtSeconds`, dropping the combo when the window
+     * elapses. Calling this once switches the meter to delta-driven time (the injected
+     * `now` clock is then ignored) — drive it each frame, or omit it and let reads read
+     * `now`. Notifies subscribers when the count changes.
+     */
+    update(dtSeconds: number): void;
+    /** Current combo count (processes any pending window expiry against the clock first). */
+    count(): number;
+    /** Highest count reached since the last {@link ComboMeter.reset}. */
+    peak(): number;
+    /** Active tier id, or `null` below the first tier. */
+    tier(): string | null;
+    /** Derived multiplier for the active tier (default 1). */
+    multiplier(): number;
+    /** Milliseconds left in the decay window before the next drop (0 when idle). */
+    remainingMs(): number;
+    /** Window remaining as `0..1`, for a draining ring/bar. */
+    fraction(): number;
+    /** The pooled view to draw this frame (do not retain). */
+    view(): ComboMeterView;
+    /** Clear the chain, peak, and window to empty. Notifies subscribers. */
+    reset(): void;
+    /** Patch config (window, tiers, drop step, multiplier curve) in place. Notifies subscribers. */
+    configure(patch: Partial<ComboMeterConfig>): void;
+    /** Observe changes (hit, drop, reset, configure, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ComboMeterSnapshot;
+    /** Restore from a {@link ComboMeterSnapshot}, re-anchoring the window to the current clock. */
+    restore(snapshot: ComboMeterSnapshot): void;
+}
+/**
+ * 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 declare function createComboMeter(config: ComboMeterConfig): ComboMeter;

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.