@jgengine/core 0.10.0 → 0.12.0

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

@@ -39,5 +39,9 @@ export interface DotField {
     /** 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`. */
+/**
+ * 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

@@ -1,4 +1,8 @@
-/** Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`. */
+/**
+ * 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 {

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;

package/dist/combat/effects.d.ts

@@ -69,4 +69,9 @@ export interface EffectSystem {
     preview(input: SingleTargetEffectInput): number;
     applyEffect(input: EffectInput): EffectResult[];
 }
+/**
+ * Apply, stack, and tick timed status effects — buffs, debuffs, DoTs — on entities.
+ *
+ * @capability status-effects apply and tick timed status effects and buffs on entities
+ */
 export declare function createEffectSystem(deps: EffectSystemDeps): EffectSystem;

package/dist/combat/effects.js

@@ -21,6 +21,11 @@ export function resolveAreaTargets(spatial, input, accept) {
     return targets;
 }
 const DEFAULT_DRAIN_STAT = "damage";
+/**
+ * Apply, stack, and tick timed status effects — buffs, debuffs, DoTs — on entities.
+ *
+ * @capability status-effects apply and tick timed status effects and buffs on entities
+ */
 export function createEffectSystem(deps) {
     function resolveRule(instanceId, effect) {
         return deps.resolveReceive(instanceId)?.[effect] ?? null;

package/dist/combat/encounterSequence.d.ts

@@ -0,0 +1,258 @@
+import type { NavPoint } from "../nav/navGrid.js";
+/**
+ * Lifecycle status of one phase in an encounter sequence: waiting to run, currently
+ * running, or finished. Groups and leaves share the same three states.
+ */
+export type PhaseStatus = "pending" | "active" | "complete";
+/**
+ * Reference to a registered completion predicate: a `kind` naming the evaluator plus
+ * opaque `params` the evaluator reads. The sequence core never interprets `params`; the
+ * predicate registered under `kind` does.
+ */
+export interface PhaseCompletionRef {
+    kind: string;
+    params?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Reference to a registered spawn provider invoked when a phase is entered: a `kind`
+ * naming the provider plus opaque `params`. Spawning is one optional node adapter — a
+ * phase without `spawn` simply emits no spawn requests.
+ */
+export interface PhaseSpawnRef {
+    kind: string;
+    params?: Readonly<Record<string, unknown>>;
+}
+/**
+ * One node in an encounter sequence tree. `data` is caller-owned and opaque to the core.
+ * A node with `children` is a group whose children run in order; a node without is a leaf.
+ * `completion` gates when the node finishes, `spawn` names an on-enter provider, and
+ * `repeat` re-runs the node's subtree that many extra times before advancing.
+ */
+export interface EncounterPhase<TData = unknown> {
+    /** Stable, tree-unique id. Survives serialization and phase injection. */
+    id: string;
+    data?: TData;
+    children?: readonly EncounterPhase<TData>[];
+    /**
+     * Completion predicate reference. A leaf without one completes immediately (a marker or
+     * spawn-only phase); a group without one completes once all its children complete.
+     */
+    completion?: PhaseCompletionRef;
+    spawn?: PhaseSpawnRef;
+    /** Extra runs of this node's subtree before advancing. Default 0 (runs once). */
+    repeat?: number;
+}
+/** Per-node runtime record. Serializable — holds no functions or tree references. */
+export interface PhaseRuntime {
+    status: PhaseStatus;
+    /** 0-based repeat iteration currently running. */
+    iteration: number;
+    /** `elapsed` at which the node was most recently entered, for time-based predicates. */
+    enteredAt: number;
+}
+/**
+ * Full serializable encounter state: the working phase tree (including any injected
+ * phases), a per-node runtime map, the active path from root to the deepest open node,
+ * accumulated time, and whether the sequence has finished. Round-trips through JSON with
+ * no behavioral change; the registries live in {@link EncounterConfig}, not here.
+ */
+export interface EncounterState<TData = unknown> {
+    roots: EncounterPhase<TData>[];
+    nodes: Record<string, PhaseRuntime>;
+    /** Ids from a root down to the deepest open node; empty before start and once done. */
+    activePath: string[];
+    elapsed: number;
+    started: boolean;
+    done: boolean;
+}
+/**
+ * Caller-supplied signals a completion predicate reads. Every field is optional and
+ * opaque to the core: `counts` of tagged live entities, continuous `metrics`, cumulative
+ * `events`, and boolean `flags`. Deterministic given the same values.
+ */
+export interface EncounterSignals {
+    counts?: Readonly<Record<string, number>>;
+    metrics?: Readonly<Record<string, number>>;
+    events?: Readonly<Record<string, number>>;
+    flags?: Readonly<Record<string, boolean>>;
+}
+/**
+ * Context passed to {@link startEncounter} / {@link updateEncounter}: the caller signals
+ * predicates evaluate against, plus named `spawnPoints` catalogs (authored in the scene,
+ * referenced by key) that spawn providers place against. Never holds coordinates the
+ * sequence itself owns.
+ */
+export interface EncounterContext {
+    signals?: EncounterSignals;
+    /** Named lists of authored scene spawn points, referenced by spawn providers by key. */
+    spawnPoints?: Readonly<Record<string, readonly NavPoint[]>>;
+}
+/** Evaluation context a completion predicate receives for the node under test. */
+export interface PredicateContext {
+    phaseId: string;
+    iteration: number;
+    /** Total accumulated encounter time. */
+    elapsed: number;
+    /** Time since this node was entered (0 on the tick it is entered). */
+    phaseElapsed: number;
+    signals: EncounterSignals;
+}
+/**
+ * A completion predicate: pure and deterministic, returns true when the node it gates is
+ * finished. Registered under a `kind` and reused across phases with different `params`.
+ */
+export type CompletionPredicate = (params: Readonly<Record<string, unknown>>, ctx: PredicateContext) => boolean;
+/** A single spawn request a provider emits; `ref` is caller-defined, `point` optional. */
+export interface EncounterSpawnRequest {
+    ref: string;
+    point?: NavPoint;
+    data?: unknown;
+}
+/** Evaluation context a spawn provider receives when its phase is entered. */
+export interface SpawnProviderContext {
+    phaseId: string;
+    iteration: number;
+    elapsed: number;
+    spawnPoints: Readonly<Record<string, readonly NavPoint[]>>;
+}
+/**
+ * A spawn provider: given the phase's `params` and context, returns the spawn requests to
+ * emit on enter. Deterministic; reads authored scene points from `ctx.spawnPoints` rather
+ * than embedding coordinates.
+ */
+export type SpawnProvider = (params: Readonly<Record<string, unknown>>, ctx: SpawnProviderContext) => readonly EncounterSpawnRequest[];
+/** A lifecycle event emitted while stepping an encounter, carrying provenance. */
+export type EncounterEvent = {
+    type: "enter";
+    phaseId: string;
+    iteration: number;
+} | {
+    type: "spawn";
+    phaseId: string;
+    provider: string;
+    requests: readonly EncounterSpawnRequest[];
+} | {
+    type: "complete";
+    phaseId: string;
+    iteration: number;
+    reason: string;
+} | {
+    type: "done";
+};
+/** Result of a step: the (mutated, returned) state and the events emitted this step. */
+export interface EncounterStep<TData = unknown> {
+    state: EncounterState<TData>;
+    events: EncounterEvent[];
+}
+/**
+ * Non-serializable configuration for an encounter: the authored phase tree plus predicate
+ * and spawn-provider registries. Re-supplied alongside a loaded {@link EncounterState}, the
+ * way `advanceSpawnDirector` pairs config with state, so the state itself stays pure data.
+ */
+export interface EncounterConfig<TData = unknown> {
+    phases: readonly EncounterPhase<TData>[];
+    /** Extra predicates, merged over the built-ins (a same-named entry overrides). */
+    predicates?: Readonly<Record<string, CompletionPredicate>>;
+    /** Extra spawn providers, merged over the built-ins. */
+    spawnProviders?: Readonly<Record<string, SpawnProvider>>;
+}
+/** Where to insert an injected phase, relative to an existing node by id. */
+export type PhaseInjectAt = {
+    before: string;
+} | {
+    after: string;
+} | {
+    childOf: string;
+    index?: number;
+};
+/**
+ * Built-in completion predicates covering the common encounter gates: `immediate` (leaf
+ * marker), `manual`/`flag` (external event via a caller flag), `timer` (phase seconds),
+ * `cleared` (tagged entity count drained), `metric` (threshold on a live value), `event`
+ * (cumulative event count), and `quorum` (at least N of nested predicates met). Merge your
+ * own over these through {@link EncounterConfig.predicates}.
+ *
+ * @capability encounter-predicates gate encounter phase completion on timers, cleared spawns, metrics, events, or a quorum of conditions
+ */
+export declare const BUILTIN_COMPLETION_PREDICATES: Readonly<Record<string, CompletionPredicate>>;
+/**
+ * Built-in spawn providers. `points` reads a named authored scene point list from context
+ * and cycles it to emit `count` requests, keeping coordinates in the scene rather than the
+ * sequence. `list` echoes literal requests authored in `params.requests`. Merge your own
+ * catalog- or director-backed providers through {@link EncounterConfig.spawnProviders}.
+ *
+ * @capability encounter-spawn-providers turn an entered encounter phase into spawn requests from authored scene points or an inline list
+ */
+export declare const BUILTIN_SPAWN_PROVIDERS: Readonly<Record<string, SpawnProvider>>;
+/**
+ * Build the initial, serializable state for an encounter from its config. Deep-copies the
+ * authored phase tree (so later injection never mutates the config), verifies phase ids are
+ * unique, and leaves every node pending. Does not enter the first phase — call
+ * {@link startEncounter} for that.
+ *
+ * @capability encounter-state create the serializable starting state of a hierarchical encounter sequence
+ */
+export declare function createEncounterState<TData>(config: EncounterConfig<TData>): EncounterState<TData>;
+/**
+ * Start a created encounter: enter the first root phase, descending to its first leaf, and
+ * return the initial enter/spawn events. A no-op (with no events) on an already-started or
+ * empty encounter. Mutates and returns `state`.
+ *
+ * @capability encounter-start enter the first phase of a hierarchical encounter and emit its opening spawn events
+ */
+export declare function startEncounter<TData>(config: EncounterConfig<TData>, state: EncounterState<TData>, ctx?: EncounterContext): EncounterStep<TData>;
+/**
+ * Advance an encounter by `dt` seconds against the caller `ctx`. Accumulates time, then
+ * repeatedly: evaluates the cursor node's completion predicate; on completion, either
+ * re-runs its subtree (`repeat`) or marks it complete and advances to the next sibling —
+ * bubbling up to parent groups whose children are exhausted — entering the next chain and
+ * emitting enter/spawn/complete events. Emits a final `done` event when the last phase
+ * completes. Bounded per call by node count; mutates and returns `state`.
+ *
+ * @capability encounter-advance step a hierarchical encounter, resolving predicate-gated completion, repeats, and nested advance with lifecycle events
+ */
+export declare function updateEncounter<TData>(config: EncounterConfig<TData>, state: EncounterState<TData>, dt: number, ctx?: EncounterContext): EncounterStep<TData>;
+/**
+ * Force the deepest active phase (or a named active phase) to complete now, regardless of
+ * its predicate — the escape hatch for external/scripted completion and failure/retry flows.
+ * Advances into the next phase and emits the same lifecycle events as a natural completion.
+ * Returns no events if the phase is not currently active. Mutates and returns `state`.
+ *
+ * @capability encounter-force-complete externally complete an active encounter phase to drive scripted or failure-retry transitions
+ */
+export declare function forceCompletePhase<TData>(config: EncounterConfig<TData>, state: EncounterState<TData>, ctx?: EncounterContext, phaseId?: string): EncounterStep<TData>;
+/**
+ * Insert a phase into the working tree at runtime — before/after a sibling, or as a child of
+ * a group — without disturbing already-completed or active nodes. The injected subtree
+ * becomes part of the serializable state (so a mid-encounter save preserves it) and is
+ * reached in normal order if it sits ahead of the cursor. Ids must stay tree-unique. Mutates
+ * and returns `state`.
+ *
+ * @capability encounter-inject-phase dynamically insert a phase or branch into a running encounter, e.g. a boss on the final wave
+ */
+export declare function injectPhase<TData>(state: EncounterState<TData>, phase: EncounterPhase<TData>, at: PhaseInjectAt): EncounterState<TData>;
+/**
+ * The deepest active phase id — the completion cursor a HUD reads to label the current
+ * wave/phase — or null before start and once done.
+ *
+ * @capability encounter-active-phase read the id of the phase an encounter is currently waiting on
+ */
+export declare function activePhaseId<TData>(state: EncounterState<TData>): string | null;
+/**
+ * The runtime status of a phase by id (pending/active/complete), or null if the id is
+ * unknown — for driving per-phase HUD ticks and objective checklists.
+ *
+ * @capability encounter-phase-status read whether a specific encounter phase is pending, active, or complete
+ */
+export declare function phaseStatus<TData>(state: EncounterState<TData>, id: string): PhaseStatus | null;
+/**
+ * Progress across the whole tree: how many phases have completed out of the total node
+ * count, plus whether the encounter has finished. Counts injected phases.
+ *
+ * @capability encounter-progress read completed-vs-total progress across a hierarchical encounter for HUD or objective display
+ */
+export declare function encounterProgress<TData>(state: EncounterState<TData>): {
+    completed: number;
+    total: number;
+    done: boolean;
+};