@jgengine/core 0.18.1 → 0.21.0

package/dist/ai/decisionGraph.d.ts

@@ -4,13 +4,23 @@ export type BlackboardValue = number | boolean | string;
 export type Blackboard = Record<string, BlackboardValue>;
 /** Comparison operators supported by decision conditions. */
 export type DecisionOperator = "=" | "==" | "!=" | "<" | "<=" | ">" | ">=" | "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
-/** Serializable selector, sequence, condition, action, or utility node. */
+/**
+ * Serializable decision node.
+ * - `selector` runs children in order until one does not fail; `sequence` until one does not finish.
+ *   With `memory`, a composite whose child was running last tick resumes at that child instead of re-checking earlier ones.
+ * - `condition` compares a blackboard key; `action` calls a registered action.
+ * - `utility` runs the option with the highest weighted blackboard score.
+ * - `invert` swaps `done` and `failed`; `cooldown` fails for `seconds` after its child finishes;
+ *   `wait` stays running for `seconds`; `random` picks a child by `weights` from the runtime's `rng` and keeps it while it runs.
+ */
 export type DecisionNode = {
     kind: "selector";
     children: DecisionNode[];
+    memory?: boolean;
 } | {
     kind: "sequence";
     children: DecisionNode[];
+    memory?: boolean;
 } | {
     kind: "condition";
     key: string;
@@ -29,6 +39,20 @@ export type DecisionNode = {
         }[];
         node: DecisionNode;
     }[];
+} | {
+    kind: "invert";
+    child: DecisionNode;
+} | {
+    kind: "cooldown";
+    seconds: number;
+    child: DecisionNode;
+} | {
+    kind: "wait";
+    seconds: number;
+} | {
+    kind: "random";
+    children: DecisionNode[];
+    weights?: number[];
 };
 /** Root node for a serializable AI decision graph. */
 export type DecisionGraph = DecisionNode;
@@ -36,17 +60,39 @@ export type DecisionGraph = DecisionNode;
 export type DecisionStatus = "running" | "done" | "failed";
 /** Callback implementation for an action node. */
 export type DecisionAction<Context = unknown> = (ctx: Context, params: Record<string, BlackboardValue> | undefined, blackboard: Blackboard) => DecisionStatus;
-/** Serializable state retained by an active decision graph. */
+/** Called when an action that was running last tick is not reached this tick, so it can release what it holds. */
+export type DecisionAbort<Context = unknown> = (action: string, ctx: Context, params: Record<string, BlackboardValue> | undefined, blackboard: Blackboard) => void;
+/** Optional hooks and injected randomness for {@link createDecisionGraphRuntime}. */
+export interface DecisionGraphOptions<Context = unknown> {
+    onAbort?: DecisionAbort<Context>;
+    /** `[0, 1)` source for `random` nodes; pass `ctx.rng`. Required only when the graph has one. */
+    rng?: () => number;
+}
+/** Progress of a memory composite, `random` choice, or `wait` timer, keyed by node id (depth-first order). */
+export interface DecisionNodeMemory {
+    index: number;
+    elapsed: number;
+    tick: number;
+}
+/** Serializable state retained by an active decision graph. Fields besides `runningPath` are absent in older saves. */
 export interface DecisionGraphSnapshot {
     runningPath: number[] | null;
+    tick?: number;
+    clock?: number;
+    nodes?: Record<string, DecisionNodeMemory>;
+    cooldowns?: Record<string, number>;
 }
 /** Stateful evaluator for a serializable decision graph. */
 export interface DecisionGraphRuntime<Context = unknown> {
     tick(ctx: Context, blackboard: Blackboard, dt: number): DecisionStatus;
+    /** Name of the action left running by the last tick, or null. */
+    running(): string | null;
+    /** Abort the compiled running action once, retaining graph memory/timers. Clears ownership before invoking user onAbort, even if it throws. */
+    abort(ctx: Context, blackboard: Blackboard): void;
     snapshot(): DecisionGraphSnapshot;
     restore(next: DecisionGraphSnapshot): void;
 }
 /** Creates a deterministic runtime for a serializable decision graph.
- * @capability ai-decision-graph Evaluate serializable selector, sequence, condition, action, and utility AI decisions.
+ * @capability ai-decision-graph Evaluate serializable selector, sequence, condition, action, utility, timer, and random AI decisions with interrupt hooks.
  */
-export declare function createDecisionGraphRuntime<Context = unknown>(graph: DecisionGraph, actions: Record<string, DecisionAction<Context>>): DecisionGraphRuntime<Context>;
+export declare function createDecisionGraphRuntime<Context = unknown>(graph: DecisionGraph, actions: Record<string, DecisionAction<Context>>, options?: DecisionGraphOptions<Context>): DecisionGraphRuntime<Context>;

package/dist/ai/decisionGraph.js

@@ -21,12 +21,53 @@ function compare(left, op, right) {
             return typeof left === "number" && typeof right === "number" && left >= right;
     }
 }
+function childrenOf(node) {
+    switch (node.kind) {
+        case "selector":
+        case "sequence":
+        case "random":
+            return node.children;
+        case "utility":
+            return node.options.map((option) => option.node);
+        case "invert":
+        case "cooldown":
+            return [node.child];
+        default:
+            return [];
+    }
+}
+function compile(root) {
+    const byId = [];
+    const visit = (node, path) => {
+        const entry = { node, id: byId.length, path, children: [] };
+        byId.push(entry);
+        childrenOf(node).forEach((child, index) => entry.children.push(visit(child, [...path, index])));
+        return entry;
+    };
+    visit(root, []);
+    return byId;
+}
 /** Creates a deterministic runtime for a serializable decision graph.
- * @capability ai-decision-graph Evaluate serializable selector, sequence, condition, action, and utility AI decisions.
+ * @capability ai-decision-graph Evaluate serializable selector, sequence, condition, action, utility, timer, and random AI decisions with interrupt hooks.
  */
-export function createDecisionGraphRuntime(graph, actions) {
-    let runningPath = null;
-    function run(node, ctx, blackboard, dt, path) {
+export function createDecisionGraphRuntime(graph, actions, options = {}) {
+    const nodes = compile(graph);
+    const root = nodes[0];
+    let runningId = -1;
+    let tickCount = 0;
+    let clock = 0;
+    const memory = new Map();
+    const cooldowns = new Map();
+    const lastReached = new Float64Array(nodes.length).fill(-1);
+    function carried(id) {
+        const entry = memory.get(id);
+        return entry !== undefined && entry.tick === tickCount - 1 ? entry : undefined;
+    }
+    function hold(id, index, elapsed) {
+        memory.set(id, { index, elapsed, tick: tickCount });
+    }
+    function run(entry, ctx, blackboard, dt) {
+        const node = entry.node;
         switch (node.kind) {
             case "condition":
                 return compare(blackboard[node.key], node.op, node.value) ? "done" : "failed";
@@ -34,49 +75,144 @@ export function createDecisionGraphRuntime(graph, actions) {
                 const action = actions[node.action];
                 if (action === undefined)
                     throw new Error(`Decision action '${node.action}' is not registered`);
+                lastReached[entry.id] = tickCount;
                 const status = action(ctx, node.params, blackboard);
                 if (status === "running")
-                    runningPath = path;
+                    runningId = entry.id;
                 return status;
             }
             case "selector":
-                for (let index = 0; index < node.children.length; index += 1) {
-                    const status = run(node.children[index], ctx, blackboard, dt, [...path, index]);
-                    if (status !== "failed")
-                        return status;
+            case "sequence": {
+                const stopOn = node.kind === "selector" ? "failed" : "done";
+                const start = node.memory === true ? (carried(entry.id)?.index ?? 0) : 0;
+                memory.delete(entry.id);
+                for (let index = start; index < entry.children.length; index += 1) {
+                    const status = run(entry.children[index], ctx, blackboard, dt);
+                    if (status === stopOn)
+                        continue;
+                    if (status === "running" && node.memory === true)
+                        hold(entry.id, index, 0);
+                    return status;
                 }
-                return "failed";
-            case "sequence":
-                for (let index = 0; index < node.children.length; index += 1) {
-                    const status = run(node.children[index], ctx, blackboard, dt, [...path, index]);
-                    if (status !== "done")
-                        return status;
-                }
-                return "done";
+                return node.kind === "selector" ? "failed" : "done";
+            }
             case "utility": {
                 let best = -Infinity;
                 let bestIndex = -1;
                 for (let index = 0; index < node.options.length; index += 1) {
-                    const score = node.options[index].score.reduce((total, term) => total + (typeof blackboard[term.key] === "number" ? blackboard[term.key] : 0) * term.weight, 0);
+                    let score = 0;
+                    for (const term of node.options[index].score) {
+                        const value = blackboard[term.key];
+                        if (typeof value === "number")
+                            score += value * term.weight;
+                    }
                     if (score > best) {
                         best = score;
                         bestIndex = index;
                     }
                 }
-                return bestIndex < 0 ? "failed" : run(node.options[bestIndex].node, ctx, blackboard, dt, [...path, bestIndex]);
+                return bestIndex < 0 ? "failed" : run(entry.children[bestIndex], ctx, blackboard, dt);
+            }
+            case "invert": {
+                const status = run(entry.children[0], ctx, blackboard, dt);
+                return status === "running" ? status : status === "done" ? "failed" : "done";
+            }
+            case "cooldown": {
+                if (clock < (cooldowns.get(entry.id) ?? -Infinity))
+                    return "failed";
+                const status = run(entry.children[0], ctx, blackboard, dt);
+                if (status === "done")
+                    cooldowns.set(entry.id, clock + Math.max(0, node.seconds));
+                return status;
+            }
+            case "wait": {
+                const elapsed = (carried(entry.id)?.elapsed ?? 0) + dt;
+                if (elapsed >= node.seconds) {
+                    memory.delete(entry.id);
+                    return "done";
+                }
+                hold(entry.id, 0, elapsed);
+                runningId = entry.id;
+                return "running";
+            }
+            case "random": {
+                if (entry.children.length === 0)
+                    return "failed";
+                let index = carried(entry.id)?.index ?? -1;
+                if (index < 0) {
+                    if (options.rng === undefined)
+                        throw new Error("A random decision node needs options.rng (pass ctx.rng)");
+                    const weights = entry.children.map((_, i) => Math.max(0, node.weights?.[i] ?? 1));
+                    const total = weights.reduce((sum, weight) => sum + weight, 0);
+                    if (total <= 0)
+                        return "failed";
+                    let roll = options.rng() * total;
+                    index = 0;
+                    while (index < weights.length - 1 && roll >= weights[index])
+                        roll -= weights[index++];
+                }
+                memory.delete(entry.id);
+                const status = run(entry.children[index], ctx, blackboard, dt);
+                if (status === "running")
+                    hold(entry.id, index, 0);
+                return status;
             }
         }
     }
+    function idFromPath(path) {
+        let entry = root;
+        for (const index of path)
+            entry = entry?.children[index];
+        return entry?.id ?? -1;
+    }
     return {
         tick(ctx, blackboard, dt) {
-            runningPath = null;
-            return run(graph, ctx, blackboard, dt, []);
+            const previous = runningId;
+            tickCount += 1;
+            clock += Math.max(0, dt);
+            runningId = -1;
+            const status = run(root, ctx, blackboard, Math.max(0, dt));
+            const abandoned = previous >= 0 ? nodes[previous].node : null;
+            if (abandoned?.kind === "action" && lastReached[previous] !== tickCount) {
+                options.onAbort?.(abandoned.action, ctx, abandoned.params, blackboard);
+            }
+            return status;
+        },
+        running() {
+            const node = runningId >= 0 ? nodes[runningId].node : null;
+            return node?.kind === "action" ? node.action : null;
+        },
+        abort(ctx, blackboard) {
+            const node = runningId >= 0 ? nodes[runningId].node : null;
+            runningId = -1;
+            if (node?.kind === "action")
+                options.onAbort?.(node.action, ctx, node.params, blackboard);
         },
         snapshot() {
-            return { runningPath: runningPath === null ? null : [...runningPath] };
+            const nodeState = {};
+            for (const [id, entry] of memory)
+                nodeState[id] = { ...entry };
+            const cooldownState = {};
+            for (const [id, readyAt] of cooldowns)
+                cooldownState[id] = readyAt;
+            return {
+                runningPath: runningId >= 0 ? [...nodes[runningId].path] : null,
+                tick: tickCount,
+                clock,
+                nodes: nodeState,
+                cooldowns: cooldownState,
+            };
         },
         restore(next) {
-            runningPath = next.runningPath === null ? null : [...next.runningPath];
+            runningId = next.runningPath === null ? -1 : idFromPath(next.runningPath);
+            tickCount = next.tick ?? 0;
+            clock = next.clock ?? 0;
+            memory.clear();
+            cooldowns.clear();
+            for (const [id, entry] of Object.entries(next.nodes ?? {}))
+                memory.set(Number(id), { ...entry });
+            for (const [id, readyAt] of Object.entries(next.cooldowns ?? {}))
+                cooldowns.set(Number(id), readyAt);
         },
     };
 }

package/dist/ai/flock.d.ts

@@ -36,4 +36,4 @@ export interface FlockStepAgent {
 /** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions.
  * @internal
  */
-export declare function stepFlock(agents: FlockStepAgent[], config: FlockConfig, dt: number, target?: FlockVec3): void;
+export declare function stepFlock(agents: FlockStepAgent[], config: FlockConfig, dt: number, target?: FlockVec3, acceleration?: (agent: Readonly<FlockStepAgent>, index: number) => FlockVec3): void;

package/dist/ai/flock.js

@@ -134,7 +134,7 @@ function fillNeighbors(agents, agentIndex, invCell, gridCells, neighborScratch)
 /** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions.
  * @internal
  */
-export function stepFlock(agents, config, dt, target) {
+export function stepFlock(agents, config, dt, target, acceleration) {
     const count = agents.length;
     if (count === 0)
         return;
@@ -148,9 +148,12 @@ export function stepFlock(agents, config, dt, target) {
         fillNeighbors(agents, i, invCell, gridCells, neighborScratch);
         const steer = flockSteer(agents[i], neighborScratch, config, target);
         const base = i * 3;
-        steerScratch[base] = steer[0];
-        steerScratch[base + 1] = steer[1];
-        steerScratch[base + 2] = steer[2];
+        const external = acceleration?.(agents[i], i);
+        if (external !== undefined && (external.length !== 3 || external.some((axis) => !Number.isFinite(axis))))
+            throw new Error("flock acceleration must contain three finite components");
+        steerScratch[base] = steer[0] + (external?.[0] ?? 0);
+        steerScratch[base + 1] = steer[1] + (external?.[1] ?? 0);
+        steerScratch[base + 2] = steer[2] + (external?.[2] ?? 0);
     }
     for (let i = 0; i < count; i += 1) {
         const agent = agents[i];

package/dist/ai/groupAssist.d.ts

@@ -9,12 +9,22 @@ export interface AssistNetworkConfig {
     shareFraction?: number;
     distanceBetween?: (a: string, b: string) => number;
 }
+/** Plain JSON membership of an {@link AssistNetwork}, in registration order; threat lives in each member's own table. */
+export interface AssistNetworkState {
+    members: {
+        id: string;
+        groupId: string;
+    }[];
+}
 export interface AssistNetwork {
     register(member: AssistMember): void;
     remove(memberId: string): void;
     memberIds(groupId?: string): string[];
     assistersOf(memberId: string): string[];
     addThreat(memberId: string, sourceId: string, amount: number): string[];
+    snapshot(): AssistNetworkState;
+    /** Replaces the membership; `tableOf` supplies each member's (separately restored) threat table. */
+    restore(next: AssistNetworkState, tableOf: (memberId: string) => ThreatTable): void;
 }
 /** @internal */
 export declare function createAssistNetwork(config?: AssistNetworkConfig): AssistNetwork;

package/dist/ai/groupAssist.js

@@ -56,5 +56,16 @@ export function createAssistNetwork(config = {}) {
                 members.get(id).table.add(sourceId, amount * shareFraction);
             return assisters;
         },
+        snapshot() {
+            return { members: order.map((id) => ({ id, groupId: members.get(id).groupId })) };
+        },
+        restore(next, tableOf) {
+            members.clear();
+            order.length = 0;
+            for (const { id, groupId } of next.members) {
+                order.push(id);
+                members.set(id, { id, groupId, table: tableOf(id) });
+            }
+        },
     };
 }

package/dist/ai/pursuit.d.ts

@@ -51,6 +51,6 @@ export declare function armPursuit(state: PursuitState, intervalSeconds: number)
  *
  * On `"attack"` the caller applies the hit and calls {@link armPursuit} with the next interval.
  *
- * @capability pursuit chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+ * @capability pursuit enemy/mob aggro chase-to-reach with a cooldown-gated attack and optional leash-to-home; owns the attack cooldown
  */
 export declare function advancePursuit(state: PursuitState, dt: number, targetDistance: number | null, stopDistance: number, cooldownMode?: CooldownMode, homeDistance?: number, leashRange?: number): PursuitAction;

package/dist/ai/pursuit.js

@@ -36,7 +36,7 @@ function tickCooldown(state, dt) {
  *
  * On `"attack"` the caller applies the hit and calls {@link armPursuit} with the next interval.
  *
- * @capability pursuit chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+ * @capability pursuit enemy/mob aggro chase-to-reach with a cooldown-gated attack and optional leash-to-home; owns the attack cooldown
  */
 export function advancePursuit(state, dt, targetDistance, stopDistance, cooldownMode = "always", homeDistance = Number.NEGATIVE_INFINITY, leashRange = Number.POSITIVE_INFINITY) {
     if (cooldownMode === "always")

package/dist/ai/threat.d.ts

@@ -11,6 +11,12 @@ export interface HighestThreatOptions {
     current?: string | null;
     stickiness?: number;
 }
+/** Plain JSON state of a {@link ThreatTable}; `entries` keeps insertion order, which breaks ties in `highest`. */
+export interface ThreatTableState {
+    entries: [sourceId: string, threat: number][];
+    forcedSource: string | null;
+    forcedRemaining: number;
+}
 export interface ThreatTable {
     add(sourceId: string, amount: number): number;
     set(sourceId: string, amount: number): void;
@@ -23,5 +29,7 @@ export interface ThreatTable {
     remove(sourceId: string): void;
     clear(): void;
     size(): number;
+    snapshot(): ThreatTableState;
+    restore(next: ThreatTableState): void;
 }
 export declare function createThreatTable(config?: ThreatTableConfig): ThreatTable;

package/dist/ai/threat.js

@@ -97,5 +97,15 @@ export function createThreatTable(config = {}) {
         size() {
             return table.size;
         },
+        snapshot() {
+            return { entries: [...table], forcedSource, forcedRemaining };
+        },
+        restore(next) {
+            table.clear();
+            for (const [sourceId, threat] of next.entries)
+                table.set(sourceId, threat);
+            forcedSource = next.forcedSource;
+            forcedRemaining = next.forcedRemaining;
+        },
     };
 }

package/dist/anim/animGraph.d.ts

@@ -6,6 +6,7 @@ export type AnimParams = Readonly<Record<string, AnimParamValue>>;
 export type AnimState = {
     kind: "clip";
     clip: string;
+    variants?: readonly string[];
     speed?: number;
     loop?: boolean;
     rootMotion?: boolean;
@@ -88,11 +89,17 @@ interface LayerTransitionState {
     duration: number;
     fromWeights: Record<string, number>;
     fromTimes: Record<string, number>;
+    fromPlayback?: Record<string, {
+        speed: number;
+        loop: boolean;
+        rootMotion?: boolean;
+    }>;
 }
 interface LayerState {
     current: string;
     time: number;
     transition: LayerTransitionState | null;
+    selectedClip?: string;
 }
 /** Serializable evaluator state. */
 export interface AnimGraphState {
@@ -113,7 +120,10 @@ export interface AnimGraphOutput {
         name: string;
         clip: string;
     }[];
+    /** Root-bone travel over this advance from `rootMotion` states, in the rig's local units. */
     rootDelta?: [number, number, number];
+    /** `true` while an influencing current or fading-out state has `rootMotion`, even with no travel. */
+    rootMotion?: true;
 }
 /** The evaluator handle: arm triggers, advance, inspect, snapshot and restore. */
 export interface AnimGraphRuntime {
@@ -128,6 +138,10 @@ export interface AnimGraphRuntime {
     stateOf(layerId: string): string | null;
     advance(dt: number, params: AnimParams, clips: AnimGraphClipInfo): AnimGraphOutput;
 }
+/** Randomness used only when entering a clip state with variants. Omit to choose the first variant. */
+export interface AnimGraphRuntimeOptions {
+    rng?: () => number;
+}
 /** Entity blackboard key the shell reads extra graph parameters from: `ctx.scene.entity.blackboard.set(id, ANIM_PARAMS_KEY, { aiming: true })`. */
 export declare const ANIM_PARAMS_KEY = "anim.params";
 /** Static clip weights of a state at `params`, before any crossfade. */
@@ -140,5 +154,33 @@ export declare function stateClipWeights(state: AnimState, params: AnimParams):
  *
  * @capability anim-graph data-first animation state machine with blend trees, crossfades, layers, and clip events
  */
-export declare function createAnimGraphRuntime(initial: AnimGraph): AnimGraphRuntime;
+export declare function createAnimGraphRuntime(initial: AnimGraph, options?: AnimGraphRuntimeOptions): AnimGraphRuntime;
+/**
+ * Validates untrusted JSON (a saved scene document, a network payload) as an {@link AnimGraph}.
+ * Malformed states, transitions to unknown states, and bad conditions are dropped; a layer whose
+ * entry state is missing is dropped; the result is `undefined` when no layer survives.
+ *
+ * @capability anim-graph load an animation graph from saved JSON without trusting its shape
+ */
+export declare function parseAnimGraph(value: unknown): AnimGraph | undefined;
+/** A located, repairable error in an authored animation graph; paths are relative to the graph value. */
+export interface AnimGraphDiagnostic {
+    path: string;
+    message: string;
+    repair: string;
+}
+/** The whole authored graph is retained unchanged only when every supported field is valid. */
+export interface AnimGraphValidation {
+    graph: AnimGraph | undefined;
+    diagnostics: readonly AnimGraphDiagnostic[];
+}
+/**
+ * Validate an authored graph without dropping broken combat states or weakening transition conditions.
+ * Known malformed fields and dangling references reject the whole graph with relative repair locations;
+ * valid data, including authored object/array order, is returned unchanged. Unknown extension fields are
+ * retained. Clip availability belongs to the imported-rig diagnostics. Use {@link parseAnimGraph} when
+ * permissive repair is intentional.
+ * @capability anim-graph validate authored animation graphs with located repair diagnostics without partial fallback
+ */
+export declare function validateAnimGraph(value: unknown): AnimGraphValidation;
 export {};