@jgengine/core 0.9.0 → 0.11.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;
+};