@jgengine/core 0.18.1 → 0.21.0

package/dist/runtime/inputSnapshot.js

@@ -1,10 +1,17 @@
 import { sampleAxisBindings } from "../input/axisInput.js";
+import { createHapticChannels } from "../input/haptics.js";
 export function createInputSnapshot() {
     let heldSet = new Set();
     let previousHeldSet = new Set();
     let heldList = [];
     let pointerState = null;
     let analogValues = null;
+    let buffered = false;
+    let stepHeld = new Set();
+    const pendingPressed = new Set();
+    let stepPressed = new Set();
+    let stepReleased = new Set();
+    const haptics = new Map();
     const value = (action) => {
         const analog = analogValues?.[action];
         if (analog !== undefined)
@@ -13,10 +20,41 @@ export function createInputSnapshot() {
     };
     return {
         rumble: async () => false,
-        publish(held) {
+        haptics(userId) {
+            let channels = haptics.get(userId);
+            if (channels === undefined) {
+                channels = createHapticChannels();
+                haptics.set(userId, channels);
+            }
+            return channels;
+        },
+        publish(held, edges) {
             previousHeldSet = heldSet;
             heldList = Object.freeze([...held]);
             heldSet = new Set(held);
+            if (edges !== undefined) {
+                buffered = true;
+                if (edges.reset) {
+                    pendingPressed.clear();
+                    stepPressed.clear();
+                    stepReleased.clear();
+                    stepHeld = new Set(held);
+                }
+                else {
+                    for (const action of edges.pressed ?? [])
+                        pendingPressed.add(action);
+                }
+            }
+        },
+        beginStep() {
+            buffered = true;
+            stepPressed = new Set(pendingPressed);
+            pendingPressed.clear();
+            for (const action of heldSet)
+                if (!stepHeld.has(action))
+                    stepPressed.add(action);
+            stepReleased = new Set([...stepHeld].filter(action => !heldSet.has(action)));
+            stepHeld = new Set(heldSet);
         },
         publishPointer(state) {
             pointerState = state === null ? null : Object.freeze({ ...state });
@@ -30,7 +68,7 @@ export function createInputSnapshot() {
         value,
         analog: () => analogValues,
         axis: (bindings, ranges) => sampleAxisBindings(bindings, (action) => heldSet.has(action), pointerState, ranges, value),
-        justPressed: (action) => heldSet.has(action) && !previousHeldSet.has(action),
-        justReleased: (action) => !heldSet.has(action) && previousHeldSet.has(action),
+        justPressed: (action) => buffered ? stepPressed.has(action) : heldSet.has(action) && !previousHeldSet.has(action),
+        justReleased: (action) => buffered ? stepReleased.has(action) : !heldSet.has(action) && previousHeldSet.has(action),
     };
 }

package/dist/runtime/localPlayers.d.ts

@@ -0,0 +1,73 @@
+import type { GameContext } from "./gameContext.js";
+import { type InputSnapshot } from "./inputSnapshot.js";
+/** One local seat on a shared screen: a stable slot id, the user id the game spawns for it, and the device driving it. */
+export interface LocalPlayerSlot {
+    readonly slotId: string;
+    readonly index: number;
+    readonly userId: string;
+    /** Device that claimed the seat (`"gamepad:1"`), `null` for the primary seat before a device claims it. */
+    readonly deviceId: string | null;
+}
+/** Retunable seat policy. */
+export interface LocalPlayersConfig {
+    /** Seats on this screen, including the primary (default `1`: every device drives the primary player). */
+    maxSlots: number;
+    /**
+     * Whether the first device to press something claims the primary seat alongside keyboard and touch
+     * (`"first"`, default), or the primary stays keyboard/touch-only and every pad opens a new seat (`"none"`).
+     */
+    claimPrimary?: "first" | "none";
+}
+/** Options for {@link createLocalPlayers}. */
+export interface LocalPlayersOptions extends LocalPlayersConfig {
+    /** User id of seat 0 — `ctx.player.userId`. */
+    primaryUserId: string;
+    /** Input of seat 0 — `ctx.input`; other seats get their own snapshot. */
+    primaryInput?: InputSnapshot;
+    /** User id for seat `index >= 1` (default `` `${primaryUserId}:p${index + 1}` ``). */
+    userIdFor?: (index: number) => string;
+}
+/** Result of {@link LocalPlayers.assign}. */
+export interface LocalPlayerAssignment {
+    slot: LocalPlayerSlot;
+    /** True when this call opened the seat: spawn its entity through `onNewPlayer`. */
+    joined: boolean;
+}
+/** Serializable seat table. */
+export interface LocalPlayersSnapshot {
+    maxSlots: number;
+    claimPrimary: "first" | "none";
+    slots: LocalPlayerSlot[];
+}
+/** Seats for couch co-op: devices hot-join into slots, each slot has its own input. */
+export interface LocalPlayers {
+    /** Seat for a device that just produced input: its existing seat, the primary seat, a newly opened seat, or `null` when full. */
+    assign(deviceId: string): LocalPlayerAssignment | null;
+    /** Free a seat other than the primary; its device may hot-join again. */
+    release(slotId: string): boolean;
+    slots(): readonly LocalPlayerSlot[];
+    slot(slotId: string): LocalPlayerSlot | null;
+    slotForDevice(deviceId: string): LocalPlayerSlot | null;
+    /** The seat's user id and input, or `null` for an unknown seat. Seat 0 returns `ctx.player`'s id and `ctx.input`. */
+    local(slotId: string): {
+        userId: string;
+        input: InputSnapshot;
+    } | null;
+    /** Called after every assign that changes the table, release, restore and retune; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    config(): Required<LocalPlayersConfig>;
+    /** Change seat count or claim policy mid-game; seats above a lowered `maxSlots` stay until released. */
+    retune(next: LocalPlayersConfig): void;
+    snapshot(): LocalPlayersSnapshot;
+    restore(snapshot: LocalPlayersSnapshot): void;
+}
+/**
+ * Seat table for local multiplayer on one screen.
+ * @capability local-players Couch co-op seats: devices hot-join into slots, each with its own user id and input snapshot.
+ */
+export declare function createLocalPlayers(options: LocalPlayersOptions): LocalPlayers;
+/**
+ * The seat table of a game context, created on first use with one seat for `ctx.player` and `ctx.input`.
+ * The shell retunes it from `defineGame({ localPlayers })` and hot-joins pads into it.
+ */
+export declare function localPlayers(ctx: GameContext): LocalPlayers;

package/dist/runtime/localPlayers.js

@@ -0,0 +1,119 @@
+import { createInputSnapshot } from "./inputSnapshot.js";
+const PRIMARY_SLOT = "slot:0";
+/**
+ * Seat table for local multiplayer on one screen.
+ * @capability local-players Couch co-op seats: devices hot-join into slots, each with its own user id and input snapshot.
+ */
+export function createLocalPlayers(options) {
+    const userIdFor = options.userIdFor ?? ((index) => `${options.primaryUserId}:p${index + 1}`);
+    const primaryInput = options.primaryInput ?? createInputSnapshot();
+    let config = {
+        maxSlots: Math.max(1, Math.floor(options.maxSlots)),
+        claimPrimary: options.claimPrimary ?? "first",
+    };
+    let slots = [];
+    const inputs = new Map();
+    const listeners = new Set();
+    const changed = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    const primarySlot = (deviceId) => Object.freeze({ slotId: PRIMARY_SLOT, index: 0, userId: options.primaryUserId, deviceId });
+    const reset = (next) => {
+        slots = next.map((slot) => Object.freeze({ ...slot }));
+        if (!slots.some((slot) => slot.index === 0))
+            slots.unshift(primarySlot(null));
+        slots.sort((a, b) => a.index - b.index);
+        for (const slotId of [...inputs.keys()]) {
+            if (!slots.some((slot) => slot.slotId === slotId))
+                inputs.delete(slotId);
+        }
+    };
+    reset([]);
+    const inputFor = (slot) => {
+        if (slot.index === 0)
+            return primaryInput;
+        let input = inputs.get(slot.slotId);
+        if (input === undefined) {
+            input = createInputSnapshot();
+            inputs.set(slot.slotId, input);
+        }
+        return input;
+    };
+    return {
+        assign(deviceId) {
+            const existing = slots.find((slot) => slot.deviceId === deviceId);
+            if (existing !== undefined)
+                return { slot: existing, joined: false };
+            if (config.claimPrimary === "first" || config.maxSlots === 1) {
+                const primary = slots[0];
+                if (primary.deviceId === null) {
+                    slots[0] = primarySlot(deviceId);
+                    changed();
+                    return { slot: slots[0], joined: false };
+                }
+                if (config.maxSlots === 1)
+                    return { slot: primary, joined: false };
+            }
+            if (slots.length >= config.maxSlots)
+                return null;
+            let index = 1;
+            while (slots.some((slot) => slot.index === index))
+                index += 1;
+            const slot = Object.freeze({ slotId: `slot:${index}`, index, userId: userIdFor(index), deviceId });
+            slots = [...slots, slot].sort((a, b) => a.index - b.index);
+            changed();
+            return { slot, joined: true };
+        },
+        release(slotId) {
+            if (slotId === PRIMARY_SLOT)
+                return false;
+            const next = slots.filter((slot) => slot.slotId !== slotId);
+            if (next.length === slots.length)
+                return false;
+            slots = next;
+            inputs.delete(slotId);
+            changed();
+            return true;
+        },
+        slots: () => slots,
+        slot: (slotId) => slots.find((slot) => slot.slotId === slotId) ?? null,
+        slotForDevice: (deviceId) => slots.find((slot) => slot.deviceId === deviceId) ?? null,
+        local(slotId) {
+            const slot = slots.find((candidate) => candidate.slotId === slotId);
+            return slot === undefined ? null : { userId: slot.userId, input: inputFor(slot) };
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        config: () => config,
+        retune(next) {
+            config = { maxSlots: Math.max(1, Math.floor(next.maxSlots)), claimPrimary: next.claimPrimary ?? config.claimPrimary };
+            changed();
+        },
+        snapshot() {
+            return { ...config, slots: slots.map((slot) => ({ ...slot })) };
+        },
+        restore(snapshot) {
+            config = { maxSlots: Math.max(1, Math.floor(snapshot.maxSlots)), claimPrimary: snapshot.claimPrimary };
+            reset(snapshot.slots);
+            changed();
+        },
+    };
+}
+const LOCAL_PLAYERS = new WeakMap();
+/**
+ * The seat table of a game context, created on first use with one seat for `ctx.player` and `ctx.input`.
+ * The shell retunes it from `defineGame({ localPlayers })` and hot-joins pads into it.
+ */
+export function localPlayers(ctx) {
+    let players = LOCAL_PLAYERS.get(ctx);
+    if (players === undefined) {
+        players = createLocalPlayers({ maxSlots: 1, primaryUserId: ctx.player.userId, primaryInput: ctx.input });
+        LOCAL_PLAYERS.set(ctx, players);
+    }
+    return players;
+}

package/dist/runtime/runtimeSave.d.ts

@@ -2,7 +2,7 @@ import { type SaveBackend, type SaveStatus, type SaveTimers } from "../game/save
 import type { WorldSnapshot } from "./worldSnapshot.js";
 /**
  * The narrow slice of a live `GameContext` a runtime save reads and writes — a
- * `GameContext` satisfies it directly (`ctx.snapshot`/`ctx.hydrate`/`ctx.subscribe`).
+ * `GameContext` satisfies it directly (`ctx.state`/`ctx.restore`/`ctx.subscribe`).
  * Depending on this instead of the full context keeps the save controller a deep,
  * decoupled module: it captures and restores the *whole* opted-in world without
  * knowing any subsystem.
@@ -10,6 +10,10 @@ import type { WorldSnapshot } from "./worldSnapshot.js";
 export interface RuntimeSaveTarget {
     snapshot(): WorldSnapshot;
     hydrate(snapshot: WorldSnapshot): void;
+    /** Complete authoritative capture when the target distinguishes persistence from replication. */
+    state?(): WorldSnapshot;
+    /** Authoritative inverse of `state`; used together with it instead of replication hydration. */
+    restore?(state: WorldSnapshot): void;
     subscribe(listener: () => void): () => void;
 }
 /** `"autosave"` writes a fresh capture on a trailing timer while the world changes (at most once per `autosaveMs`, so a never-idle world still persists); `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
@@ -39,8 +43,8 @@ export interface RuntimeSaveConfig {
 export type RuntimeSaveOptions = Omit<RuntimeSaveConfig, "target">;
 /**
  * Whole-world save/load bound to a live world and a pluggable backend. `save()`
- * captures `target.snapshot()` and writes it; `load()` reads it back and
- * `target.hydrate()`s the whole world. In `autosave` mode it also writes on a
+ * captures `target.state()` and writes it; `load()` reads it back and
+ * calls `target.restore()`. Older targets use `snapshot()`/`hydrate()`. In `autosave` mode it also writes on a
  * trailing timer while the world keeps changing. Named slots, versioned migration, and offline↔cloud
  * (backend swap) all come for free from the underlying save store.
  */
@@ -51,13 +55,13 @@ export interface RuntimeSave {
     save(): Promise<void>;
     /** Semantic alias for `save()` — call it from a save point, a quest-complete or area-enter handler. */
     checkpoint(): Promise<void>;
-    /** Load the active slot and hydrate the whole world; resolves `true` when a real save was applied, `false` for an empty slot. */
+    /** Load the active slot and hydrate the whole world; resolves `true` when a real save was applied, `false` for an empty slot or failed payload read. Failed reads never restore cached state. */
     load(): Promise<boolean>;
-    /** Whether the active slot holds a saved world — gate a title-screen "Continue" on it. */
+    /** Whether the active slot holds a saved world — gate a title-screen "Continue" on it. Failed payload reads resolve false and report error status. */
     hasSave(): Promise<boolean>;
     /** Delete the active slot's save. */
     clear(): Promise<void>;
-    /** Switch slot and load it, hydrating the world when that slot has a save. */
+    /** Switch slot and load it, hydrating the world when that slot has a save. Failed payload reads resolve false without restoring cached state. */
     switchSlot(slot: string): Promise<boolean>;
     /** The slots this game has written — back a load/save menu. */
     slots(): Promise<string[]>;

package/dist/runtime/runtimeSave.js

@@ -48,7 +48,7 @@ export function createRuntimeSave(config) {
     }
     function persist() {
         clearTimer();
-        store.set(config.target.snapshot());
+        store.set(config.target.state?.() ?? config.target.snapshot());
         return store.save();
     }
     /**
@@ -77,7 +77,10 @@ export function createRuntimeSave(config) {
             return false;
         restoring = true;
         try {
-            config.target.hydrate(snapshot);
+            if (config.target.restore !== undefined)
+                config.target.restore(snapshot);
+            else
+                config.target.hydrate(snapshot);
         }
         finally {
             restoring = false;
@@ -91,15 +94,18 @@ export function createRuntimeSave(config) {
         save,
         checkpoint: save,
         async load() {
-            return applyLoaded(await store.load());
+            const snapshot = await store.load();
+            return store.status() !== "error" && applyLoaded(snapshot);
         },
         async hasSave() {
-            return hasContent(await store.load());
+            const snapshot = await store.load();
+            return store.status() !== "error" && hasContent(snapshot);
         },
         clear: () => store.clear(),
         async switchSlot(slot) {
             clearTimer();
-            return applyLoaded(await store.switchSlot(slot));
+            const snapshot = await store.switchSlot(slot);
+            return store.status() !== "error" && applyLoaded(snapshot);
         },
         slots: () => store.slots(),
         subscribe: (listener) => store.subscribe(listener),

package/dist/runtime/simContext.d.ts

@@ -1,4 +1,5 @@
 import type { EntityStore } from "../scene/entityStore.js";
+import type { SimClock } from "../time/simClock.js";
 import { type PoseHistory, type RenderPose } from "./poseInterpolation.js";
 import { type SimAdvanceResult, type SimLoop, type SimulationConfig } from "./simLoop.js";
 /** Where a registered stage runs inside one simulation step. */
@@ -7,7 +8,8 @@ export type SimStagePhase = "beforeMovement" | "afterMovement" | "afterTick";
 export interface SimStage {
     id: string;
     phase: SimStagePhase;
-    run(dt: number, tick: number): void;
+    /** dt is real seconds; gameDt is the scaled authoritative game-seconds for this step. */
+    run(dt: number, tick: number, gameDt: number): void;
 }
 /** Serializable `ctx.sim` state: loop position plus the interpolation pose history. */
 export interface SimContextState {
@@ -21,8 +23,10 @@ export interface SimContextState {
  */
 export interface SimContext {
     readonly loop: SimLoop;
-    /** Advance the loop; `body` runs once per simulation step with that step's dt. Pose history is captured before each step. */
-    advance(realDt: number, body: (dt: number, tick: number) => void): SimAdvanceResult;
+    /** Advance simulation and its game clock once per step. The callback receives real dt, tick and scaled game dt. Prediction can opt out of clock advancement. */
+    advance(realDt: number, body: (dt: number, tick: number, gameDt: number) => void, options?: {
+        advanceTime?: boolean;
+    }): SimAdvanceResult;
     tick(): number;
     /** Interpolation fraction for the current frame, 1 on a variable loop. */
     alpha(): number;
@@ -42,4 +46,5 @@ export interface SimContext {
 export declare function createSimContext(options: {
     config?: SimulationConfig;
     entities: EntityStore;
+    time?: Pick<SimClock, "advance">;
 }): SimContext;

package/dist/runtime/simContext.js

@@ -7,9 +7,10 @@ export function createSimContext(options) {
     const poses = createPoseHistory({ snapDistance: loop.config().snapDistance });
     const stages = new Map();
     let advancing = false;
+    let currentGameDt = 0;
     return {
         loop,
-        advance(realDt, body) {
+        advance(realDt, body, stepOptions) {
             if (advancing)
                 throw new Error("ctx.sim.advance is not reentrant");
             advancing = true;
@@ -17,11 +18,14 @@ export function createSimContext(options) {
                 return loop.advance(realDt, (dt, tick) => {
                     if (loop.isFixed())
                         poses.beginStep(entities);
-                    body(dt, tick);
+                    const gameDt = stepOptions?.advanceTime === false ? 0 : options.time?.advance(dt) ?? dt;
+                    currentGameDt = gameDt;
+                    body(dt, tick, gameDt);
                 });
             }
             finally {
                 advancing = false;
+                currentGameDt = 0;
             }
         },
         tick: () => loop.tick(),
@@ -49,7 +53,7 @@ export function createSimContext(options) {
                 return;
             const tick = loop.tick();
             for (const stage of list)
-                stage.run(dt, tick);
+                stage.run(dt, tick, advancing ? currentGameDt : dt);
         },
         retune(config) {
             loop.retune(config);

package/dist/runtime/simSnapshot.js

@@ -47,6 +47,8 @@ export function createContextSimSnapshot(ctx) {
         capture: () => structuredClone(ctx.snapshot()),
         restore: (data) => ctx.hydrate(structuredClone(data)),
     });
+    registry.register({ id: "projectiles", capture: ctx.scene.entity.projectileState, restore: ctx.scene.entity.restoreProjectiles });
+    registry.register({ id: "environment", capture: ctx.environment.snapshot, restore: ctx.environment.restore });
     registry.register({ id: "clock", capture: () => ctx.time.snapshot(), restore: (data) => ctx.time.hydrate(data) });
     registry.register({ id: "sim", capture: () => ctx.sim.snapshot(), restore: (data) => ctx.sim.restore(data) });
     if (rngStateOf(ctx.rng) !== null) {

package/dist/runtime/transport.d.ts

@@ -63,16 +63,25 @@ export type GameRuntimeFeedView = {
     entries: unknown[];
 };
 export type GameRuntimeTransport = {
+    /**
+     * Join a server. `sessionId` names this client session (one tab, one mounted view) so the host keeps
+     * the user a member while any of their sessions is still live.
+     */
     joinServer: (args: {
         gameId: string;
         serverId?: string;
         role?: MultiplayerRole;
+        sessionId?: string;
     }) => Promise<JoinServerOutcome>;
+    /** Leave a server. With `sessionId` only that session ends; the user leaves once no session remains. Without it the user leaves outright. */
     leaveServer: (args: {
         serverId: string;
+        sessionId?: string;
     }) => Promise<void>;
     runCommand: (args: RunCommandArgs) => Promise<TransportRunCommandResult>;
 };
+/** Fresh id for one client session's join/leave pair (see {@link GameRuntimeTransport.joinServer}). */
+export declare function createTransportSessionId(): string;
 export type FeedUnsubscribe = () => void;
 export type GameRuntimeFeeds = {
     subscribeServer: (serverId: string, onChange: (view: GameRuntimeServerView | null) => void) => FeedUnsubscribe;

package/dist/runtime/transport.js

@@ -1 +1,7 @@
-export {};
+/** Fresh id for one client session's join/leave pair (see {@link GameRuntimeTransport.joinServer}). */
+export function createTransportSessionId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.randomUUID)
+        return cryptoApi.randomUUID();
+    return `s-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}

package/dist/runtime/worldReplication.d.ts

@@ -35,6 +35,8 @@ export interface WorldDiff {
  */
 export interface WorldReplicatorOptions {
     worldVersion?: () => number;
+    /** Cursor loaded with a persisted baseline; new commits continue above it. Default `0`. */
+    initialRevision?: number;
 }
 /**
  * Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the

package/dist/runtime/worldReplication.js

@@ -10,7 +10,7 @@ const CORE_KEYS = new Set(["entities", "stats", "store"]);
 export function createWorldReplicator(takeSnapshot, options = {}) {
     const worldVersion = options.worldVersion;
     let committedVersion;
-    let revision = 0;
+    let revision = options.initialRevision ?? 0;
     const entities = new Map();
     const removedEntities = new Map();
     const stats = new Map();

package/dist/scene/assetCatalog.d.ts

@@ -16,6 +16,8 @@ export interface ModelDims {
 }
 export interface ModelAssetRef {
     url: string;
+    /** Preserve a composed prefab's authored local origin instead of recentering its measured bounds. */
+    anchor?: "center" | "origin";
     /** Measured at asset reindex: horizontal footprint, footprint center, and lowest Y in model space (pre-scale). Lets the shell auto-center and ground-snap corner-pivot kit models. */
     dims?: ModelDims;
     /** Opt-in compact triangle mesh extracted at asset reindex (see {@link "scene/collisionMesh".CollisionMeshData}) — feeds mesh-accurate hitboxes for concave models. */

package/dist/scene/behaviorRuntime.d.ts

@@ -1,7 +1,10 @@
-import type { DecisionAction, DecisionGraphRuntime } from "../ai/decisionGraph.js";
+import type { Blackboard, DecisionAbort, DecisionAction, DecisionGraphRuntime } from "../ai/decisionGraph.js";
 import { type InterestGateState } from "../ai/interestScheduler.js";
+import { type PursuitState } from "../ai/pursuit.js";
+import { type ThreatTable, type ThreatTableState } from "../ai/threat.js";
 import { type PathFollowState, type PathProgress, type Waypoint } from "../nav/pathFollow.js";
 import type { GameContext } from "../runtime/gameContext.js";
+import type { GameDefinition } from "../game/defineGame.js";
 /** Whether a behavior instance advances and writes pose (`active`), is temporarily suspended retaining
  * state (`paused`), or is held off until re-enabled (`disabled`). */
 export type BehaviorStatus = "active" | "paused" | "disabled";
@@ -13,14 +16,19 @@ export interface BehaviorActionContext {
 }
 /** Callback used by a registered decision graph behavior action. */
 export type BehaviorAction = DecisionAction<BehaviorActionContext>;
+/** Optional hooks for a registered behavior action set. */
+export interface BehaviorActionOptions {
+    /** Called when an action running last think is pre-empted by another branch, to stop movement or release claims. */
+    onAbort?: DecisionAbort<BehaviorActionContext>;
+}
 /** Register the named actions used by decision graph behavior descriptors.
  * @capability behavior-actions register named callbacks for decision graph behavior descriptors
  */
-export declare function registerBehaviorActions(id: string, actions: Record<string, BehaviorAction>): () => void;
+export declare function registerBehaviorActions(id: string, actions: Record<string, BehaviorAction>, options?: BehaviorActionOptions): () => void;
 /**
  * Catch-up policy applied when a paused instance resumes. `freeze` (default, deterministic) discards
  * the time spent paused; `advance` silently fast-forwards the instance by the paused duration without
- * emitting intermediate pose writes. Only patrol honors `advance`; wander treats it as `freeze`.
+ * emitting intermediate pose writes. Only patrol honors `advance`; wander/pursue treat it as `freeze`.
  */
 export type BehaviorResumePolicy = "freeze" | "advance";
 /** Serializable snapshot of one behavior instance — round-trips exactly through
@@ -32,15 +40,30 @@ export type BehaviorSnapshot = {
     readonly kind: "wander";
     readonly origin: Waypoint;
     readonly target: Waypoint | null;
-} | {
+} | PursueBehaviorSnapshot | {
     readonly kind: "decisionGraph";
     readonly graph: ReturnType<DecisionGraphRuntime["snapshot"]>;
     readonly gate: InterestGateState;
+    readonly blackboard?: Blackboard;
+    /** Seconds accrued since the last think. */
+    readonly pending?: number;
 };
+/** Plain pursuit progress, including its original spawn home and scheduled elapsed time. */
+export interface PursueBehaviorSnapshot {
+    readonly kind: "pursue";
+    readonly home: Waypoint;
+    readonly targetId: string | null;
+    readonly explicitTargetId: string | null;
+    readonly returning: boolean;
+    readonly pursuit: PursuitState;
+    readonly gate: InterestGateState;
+    readonly pending: number;
+    readonly threat?: ThreatTableState;
+}
 /** Inspection readout for editor/debug tooling, from {@link BehaviorControl.inspect}/{@link BehaviorControl.list}. */
 export interface BehaviorInspection {
     id: string;
-    kind: "patrol" | "wander" | "decisionGraph";
+    kind: "patrol" | "wander" | "decisionGraph" | "pursue";
     status: BehaviorStatus;
     reason: string | null;
 }
@@ -72,15 +95,21 @@ export interface BehaviorControl {
     inspect(id: string): BehaviorInspection | null;
     /** Inspect every live instance (bounded by spawned behavior entities). */
     list(): BehaviorInspection[];
+    /** The live, persistent blackboard of a decision graph instance for perception and game systems to write facts into, or `null`. */
+    blackboard(id: string): Blackboard | null;
+    /** Optional pursuit threat table; explicit `setTarget` wins over taunt/threat and proximity. */
+    threat(id: string): ThreatTable | null;
+    /** Clear pursuit target/cooldown/threat and reset its cadence, retaining the original home. */
+    reset(id: string): boolean;
 }
 /**
- * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} one tick — the
+ * Advance every spawned entity carrying a patrol, wander, pursuit or decision graph behavior one tick — the
  * engine reads the descriptor, keeps the per-entity nav state itself, and poses the entity, so ambient
  * traffic and idle NPC routes are register-once (attach the behavior at spawn) instead of a per-game
  * per-frame `advancePathFollow` + `setPose` loop. Instances that are paused or disabled through
  * {@link behaviorControl} retain their state and are skipped. The shell/host call this each frame; a game never does.
  *
- * @capability behavior-tick auto-advance patrol/wander behaviors on spawned entities, no per-game route loop
+ * @capability behavior-tick auto-advance spawned patrol, wander, pursuit and decision graph behaviors with lifecycle control
  */
 export declare function advanceBehaviors(ctx: GameContext, dt: number): void;
 /**
@@ -91,3 +120,5 @@ export declare function advanceBehaviors(ctx: GameContext, dt: number): void;
  * @capability behavior-control pause/disable/resume/seek/inspect behavior instances per entity
  */
 export declare function behaviorControl(ctx: GameContext): BehaviorControl;
+/** @internal Register persistence before boot-time restore without constructing an AI runtime. */
+export declare function installPursuitPersistence(ctx: GameContext, aoiRadius?: number, eligible?: NonNullable<GameDefinition["pursuit"]>["eligible"]): void;