@jgengine/core 0.18.0 → 0.19.0

package/dist/ai/decisionGraph.js

@@ -0,0 +1,212 @@
+function compare(left, op, right) {
+    switch (op) {
+        case "=":
+        case "==":
+        case "eq":
+            return left === right;
+        case "!=":
+        case "ne":
+            return left !== right;
+        case "<":
+        case "lt":
+            return typeof left === "number" && typeof right === "number" && left < right;
+        case "<=":
+        case "lte":
+            return typeof left === "number" && typeof right === "number" && left <= right;
+        case ">":
+        case "gt":
+            return typeof left === "number" && typeof right === "number" && left > right;
+        case ">=":
+        case "gte":
+            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, utility, timer, and random AI decisions with interrupt hooks.
+ */
+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";
+            case "action": {
+                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")
+                    runningId = entry.id;
+                return status;
+            }
+            case "selector":
+            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 node.kind === "selector" ? "failed" : "done";
+            }
+            case "utility": {
+                let best = -Infinity;
+                let bestIndex = -1;
+                for (let index = 0; index < node.options.length; index += 1) {
+                    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(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) {
+            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;
+        },
+        snapshot() {
+            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) {
+            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/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/mobBrainGraph.d.ts

@@ -0,0 +1,3 @@
+import type { DecisionGraph } from "./decisionGraph.js";
+/** Graph-shaped description of the mob brain's idle, wander, chase, engage, and evade decisions. */
+export declare const mobBrainGraph: DecisionGraph;

package/dist/ai/mobBrainGraph.js

@@ -0,0 +1,25 @@
+/** Graph-shaped description of the mob brain's idle, wander, chase, engage, and evade decisions. */
+export const mobBrainGraph = {
+    kind: "selector",
+    children: [
+        { kind: "sequence", children: [
+                { kind: "condition", key: "evading", op: "=", value: true },
+                { kind: "action", action: "evade" },
+            ] },
+        { kind: "sequence", children: [
+                { kind: "condition", key: "targetId", op: "!=", value: "" },
+                { kind: "selector", children: [
+                        { kind: "sequence", children: [
+                                { kind: "condition", key: "leashExceeded", op: "=", value: true },
+                                { kind: "action", action: "evade" },
+                            ] },
+                        { kind: "sequence", children: [
+                                { kind: "condition", key: "inAttackRange", op: "=", value: true },
+                                { kind: "action", action: "engage" },
+                            ] },
+                        { kind: "action", action: "chase" },
+                    ] },
+            ] },
+        { kind: "action", action: "wanderOrIdle" },
+    ],
+};

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/tacticalQueries.d.ts

@@ -0,0 +1,30 @@
+import type { NavMeshData } from "../nav/navMesh.js";
+import type { Vec3 } from "../world/geometry.js";
+/**
+ * Returns boundary locations that are hidden from a threat.
+ * @capability tactical-cover-points derive cover candidates from navigation-mesh boundaries
+ */
+export declare function coverPoints(mesh: NavMeshData, threatPos: Vec3, losBlocked: (a: Vec3, b: Vec3) => boolean): Vec3[];
+/** Functions that score one candidate position; higher values are preferred. */
+export interface TacticalPositionEvaluators {
+    distanceTo?: (point: Vec3) => number;
+    flankOf?: (point: Vec3) => number;
+    retreatFrom?: (point: Vec3) => number;
+}
+/** Weights and a hard bound for tactical candidate scoring. */
+export interface TacticalPositionWeights {
+    distanceTo?: number;
+    flankOf?: number;
+    retreatFrom?: number;
+    maxCandidates?: number;
+}
+/** A candidate position with its deterministic weighted tactical score. */
+export interface ScoredPosition {
+    point: Vec3;
+    score: number;
+}
+/**
+ * Score positions and retain at most `maxCandidates`, ordered highest score first.
+ * @capability tactical-position-score rank bounded tactical positions with caller-defined weights
+ */
+export declare function scorePositions(points: readonly Vec3[], evaluators: TacticalPositionEvaluators, weights?: TacticalPositionWeights): ScoredPosition[];

package/dist/ai/tacticalQueries.js

@@ -0,0 +1,45 @@
+/**
+ * Returns boundary locations that are hidden from a threat.
+ * @capability tactical-cover-points derive cover candidates from navigation-mesh boundaries
+ */
+export function coverPoints(mesh, threatPos, losBlocked) {
+    const edges = new Map();
+    const shared = new Set();
+    for (const poly of mesh.polys) {
+        for (let i = 0; i < poly.length; i += 1) {
+            const a = poly[i];
+            const b = poly[(i + 1) % poly.length];
+            const key = a < b ? `${a}:${b}` : `${b}:${a}`;
+            if (edges.has(key))
+                shared.add(key);
+            else
+                edges.set(key, { a, b });
+        }
+    }
+    const result = [];
+    for (const [key, edge] of edges) {
+        if (shared.has(key))
+            continue;
+        const a = [mesh.verts[edge.a * 3] ?? 0, mesh.verts[edge.a * 3 + 1] ?? 0, mesh.verts[edge.a * 3 + 2] ?? 0];
+        const b = [mesh.verts[edge.b * 3] ?? 0, mesh.verts[edge.b * 3 + 1] ?? 0, mesh.verts[edge.b * 3 + 2] ?? 0];
+        const midpoint = [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2, (a[2] + b[2]) / 2];
+        if (losBlocked(midpoint, threatPos))
+            result.push(midpoint);
+    }
+    return result;
+}
+/**
+ * Score positions and retain at most `maxCandidates`, ordered highest score first.
+ * @capability tactical-position-score rank bounded tactical positions with caller-defined weights
+ */
+export function scorePositions(points, evaluators, weights = {}) {
+    const scored = points.map((point) => ({
+        point,
+        score: (evaluators.distanceTo?.(point) ?? 0) * (weights.distanceTo ?? 0)
+            + (evaluators.flankOf?.(point) ?? 0) * (weights.flankOf ?? 0)
+            + (evaluators.retreatFrom?.(point) ?? 0) * (weights.retreatFrom ?? 0),
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const max = Math.max(0, Math.floor(weights.maxCandidates ?? scored.length));
+    return scored.slice(0, max);
+}

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

@@ -0,0 +1,155 @@
+/** Parameter value a graph reads: floats for blends and comparisons, booleans for gates. */
+export type AnimParamValue = number | boolean;
+/** The parameter set a graph evaluates against each advance. */
+export type AnimParams = Readonly<Record<string, AnimParamValue>>;
+/** A state plays one clip, or blends clips by one or two parameters. */
+export type AnimState = {
+    kind: "clip";
+    clip: string;
+    speed?: number;
+    loop?: boolean;
+    rootMotion?: boolean;
+} | {
+    kind: "blend1D";
+    param: string;
+    points: readonly {
+        at: number;
+        clip: string;
+    }[];
+    speed?: number;
+    loop?: boolean;
+    rootMotion?: boolean;
+} | {
+    kind: "blend2D";
+    params: readonly [string, string];
+    points: readonly {
+        at: readonly [number, number];
+        clip: string;
+    }[];
+    speed?: number;
+    loop?: boolean;
+    rootMotion?: boolean;
+};
+/** Comparison operators an {@link AnimCondition} supports. */
+export type AnimCompare = ">" | "<" | ">=" | "<=" | "==" | "!=";
+/** A parameter comparison; every condition on a transition must hold. */
+export interface AnimCondition {
+    param: string;
+    op: AnimCompare;
+    value: AnimParamValue;
+}
+/** Edge between states. `from: "*"` matches any state except `to`. */
+export interface AnimTransition {
+    from: string | "*";
+    to: string;
+    /** All must hold. */
+    when?: readonly AnimCondition[];
+    /** Fires once when this trigger was set since the last advance; consumed on use. */
+    trigger?: string;
+    /** Crossfade seconds. Default 0.2. */
+    duration?: number;
+    /** Only leave `from` once its normalized time reaches this (one-shots returning to locomotion). */
+    exitTime?: number;
+}
+/** A blend layer with its own state machine. Masked layers apply only to bones whose track names start with a prefix. */
+export interface AnimLayer {
+    id: string;
+    entry: string;
+    states: Readonly<Record<string, AnimState>>;
+    transitions: readonly AnimTransition[];
+    /** Bone name prefixes this layer drives; absent means the whole rig. */
+    mask?: readonly string[];
+    additive?: boolean;
+    /** Layer influence 0..1. Default 1. */
+    weight?: number;
+}
+/** A named moment inside a clip (foot plant, hit frame, reload point). */
+export interface AnimEvent {
+    clip: string;
+    atSec: number;
+    name: string;
+}
+/** Serializable animation graph. Clip durations come from the rig at runtime (see {@link AnimGraphClipInfo}). */
+export interface AnimGraph {
+    layers: readonly AnimLayer[];
+    events?: readonly AnimEvent[];
+}
+/** Per-clip duration in seconds, read from the loaded rig. */
+export type AnimGraphClipInfo = Readonly<Record<string, number | {
+    duration: number;
+    rootTrack?: {
+        times: Float32Array;
+        values: Float32Array;
+    };
+}>>;
+interface LayerTransitionState {
+    to: string;
+    elapsed: number;
+    duration: number;
+    fromWeights: Record<string, number>;
+    fromTimes: Record<string, number>;
+}
+interface LayerState {
+    current: string;
+    time: number;
+    transition: LayerTransitionState | null;
+}
+/** Serializable evaluator state. */
+export interface AnimGraphState {
+    layers: Record<string, LayerState>;
+    triggers: string[];
+}
+/** One clip's contribution: weight 0..1 and the time to seek it to. */
+export interface AnimClipOutput {
+    clip: string;
+    weight: number;
+    time: number;
+    layer: string;
+}
+/** What one advance asks the rig to show. */
+export interface AnimGraphOutput {
+    clips: AnimClipOutput[];
+    events: {
+        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 any layer's current state has `rootMotion`, even on an advance with no travel. */
+    rootMotion?: true;
+}
+/** The evaluator handle: arm triggers, advance, inspect, snapshot and restore. */
+export interface AnimGraphRuntime {
+    graph(): AnimGraph;
+    retune(graph: AnimGraph): void;
+    state(): AnimGraphState;
+    snapshot(): AnimGraphState;
+    restore(state: AnimGraphState): void;
+    /** Arm a trigger for the next advance. */
+    trigger(name: string): void;
+    /** Current state id of a layer. */
+    stateOf(layerId: string): string | null;
+    advance(dt: number, params: AnimParams, clips: AnimGraphClipInfo): AnimGraphOutput;
+}
+/** 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. */
+export declare function stateClipWeights(state: AnimState, params: AnimParams): Record<string, number>;
+/**
+ * Headless animation state machine and blend evaluator. It owns every clip's playback time and weight, so the
+ * renderer only seeks and weights actions on a mixer, and headless hosts, replays, and tests advance the same
+ * graph without three.js. Transitions are data (parameter comparisons and consumed triggers), layers can be
+ * masked or additive, and events fire by clip time, including across loop wraps.
+ *
+ * @capability anim-graph data-first animation state machine with blend trees, crossfades, layers, and clip events
+ */
+export declare function createAnimGraphRuntime(initial: AnimGraph): 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;
+export {};