@jgengine/core 0.18.0 → 0.19.0

package/dist/runtime/simLoop.js

@@ -0,0 +1,72 @@
+const DEFAULT_MAX_CATCH_UP = 5;
+const DEFAULT_SNAP_DISTANCE = 8;
+function resolveConfig(config) {
+    const hz = config?.hz;
+    return {
+        hz: typeof hz === "number" && Number.isFinite(hz) && hz > 0 ? hz : "variable",
+        maxCatchUpSteps: Math.max(1, Math.floor(config?.maxCatchUpSteps ?? DEFAULT_MAX_CATCH_UP)),
+        snapDistance: config?.snapDistance ?? DEFAULT_SNAP_DISTANCE,
+    };
+}
+/**
+ * The simulation stepper every driver (shell frame, headless runner, authoritative host) advances through, so
+ * the sim sees the same dt sequence regardless of who drives it. Fixed mode accumulates real time and steps in
+ * equal slices with a catch-up cap; variable mode steps once per advance.
+ *
+ * @capability sim-loop fixed-step or variable simulation stepping with tick count, catch-up cap, and interpolation alpha
+ */
+export function createSimLoop(initial) {
+    let config = resolveConfig(initial);
+    let tick = 0;
+    let accumulator = 0;
+    let alpha = 1;
+    function stepSeconds() {
+        return config.hz === "variable" ? null : 1 / config.hz;
+    }
+    return {
+        advance(realDt, step) {
+            if (!(realDt > 0))
+                return { steps: 0, alpha, tick, dropped: 0 };
+            const stepDt = stepSeconds();
+            if (stepDt === null) {
+                tick += 1;
+                alpha = 1;
+                step(realDt, tick);
+                return { steps: 1, alpha, tick, dropped: 0 };
+            }
+            accumulator += realDt;
+            let steps = 0;
+            while (accumulator >= stepDt && steps < config.maxCatchUpSteps) {
+                tick += 1;
+                step(stepDt, tick);
+                accumulator -= stepDt;
+                steps += 1;
+            }
+            let dropped = 0;
+            if (accumulator >= stepDt) {
+                dropped = Math.floor(accumulator / stepDt);
+                accumulator -= dropped * stepDt;
+            }
+            alpha = accumulator / stepDt;
+            return { steps, alpha, tick, dropped };
+        },
+        tick: () => tick,
+        alpha: () => alpha,
+        stepSeconds,
+        isFixed: () => config.hz !== "variable",
+        retune(next) {
+            config = resolveConfig({ ...config, ...next });
+            if (config.hz === "variable") {
+                accumulator = 0;
+                alpha = 1;
+            }
+        },
+        config: () => config,
+        snapshot: () => ({ tick, accumulator }),
+        restore(state) {
+            tick = state.tick;
+            accumulator = state.accumulator;
+            alpha = config.hz === "variable" ? 1 : accumulator * config.hz;
+        },
+    };
+}

package/dist/runtime/simSnapshot.d.ts

@@ -0,0 +1,32 @@
+import type { GameContext } from "./gameContext.js";
+/** One piece of simulation state that can be captured and restored by id. */
+export interface SimSnapshotContributor<T = unknown> {
+    id: string;
+    capture(): T;
+    restore(data: T): void;
+}
+/** Captured contributor data keyed by contributor id. */
+export type SimSnapshot = Record<string, unknown>;
+/** Registry of {@link SimSnapshotContributor}s that captures and restores them together. */
+export interface SimSnapshotRegistry {
+    register<T>(contributor: SimSnapshotContributor<T>): () => void;
+    capture(): SimSnapshot;
+    /** Alias of {@link capture}, matching the engine's snapshot/restore naming. */
+    snapshot(): SimSnapshot;
+    /** Restore every contributor present in `snapshot`; contributors missing from it are left untouched. */
+    restore(snapshot: SimSnapshot): void;
+    ids(): string[];
+}
+/**
+ * A registry of everything that must round-trip for a simulation to resume bit-for-bit: world state, the
+ * clock, the rng cursor, the loop accumulator, and whatever a physics backend or game adds. Pair with
+ * {@link createInputRecorder} for replay.
+ *
+ * @capability sim-snapshot capture and restore whole-simulation state for replay, rollback, and regression tests
+ */
+export declare function createSimSnapshotRegistry(): SimSnapshotRegistry;
+/**
+ * The engine's own contributors for a context: replicated world state, the sim clock, the loop and pose
+ * history, and the rng cursor when `ctx.rng` is a seeded stream. Games register theirs on the same registry.
+ */
+export declare function createContextSimSnapshot(ctx: GameContext): SimSnapshotRegistry;

package/dist/runtime/simSnapshot.js

@@ -0,0 +1,60 @@
+import { rngStateOf, restoreRng } from "../random/rng.js";
+/**
+ * A registry of everything that must round-trip for a simulation to resume bit-for-bit: world state, the
+ * clock, the rng cursor, the loop accumulator, and whatever a physics backend or game adds. Pair with
+ * {@link createInputRecorder} for replay.
+ *
+ * @capability sim-snapshot capture and restore whole-simulation state for replay, rollback, and regression tests
+ */
+export function createSimSnapshotRegistry() {
+    const contributors = new Map();
+    function capture() {
+        const out = {};
+        for (const [id, contributor] of contributors)
+            out[id] = contributor.capture();
+        return out;
+    }
+    return {
+        register(contributor) {
+            if (contributors.has(contributor.id)) {
+                throw new Error(`sim snapshot contributor "${contributor.id}" is already registered`);
+            }
+            contributors.set(contributor.id, contributor);
+            return () => {
+                contributors.delete(contributor.id);
+            };
+        },
+        capture,
+        snapshot: capture,
+        restore(snapshot) {
+            for (const [id, contributor] of contributors) {
+                if (id in snapshot)
+                    contributor.restore(snapshot[id]);
+            }
+        },
+        ids: () => Array.from(contributors.keys()),
+    };
+}
+/**
+ * The engine's own contributors for a context: replicated world state, the sim clock, the loop and pose
+ * history, and the rng cursor when `ctx.rng` is a seeded stream. Games register theirs on the same registry.
+ */
+export function createContextSimSnapshot(ctx) {
+    const registry = createSimSnapshotRegistry();
+    // ctx.snapshot() hands back live rows; clone both ways so a captured snapshot stays frozen while the sim keeps running.
+    registry.register({
+        id: "world",
+        capture: () => structuredClone(ctx.snapshot()),
+        restore: (data) => ctx.hydrate(structuredClone(data)),
+    });
+    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) {
+        registry.register({
+            id: "rng",
+            capture: () => rngStateOf(ctx.rng) ?? 0,
+            restore: (cursor) => restoreRng(ctx.rng, cursor),
+        });
+    }
+    return registry;
+}

package/dist/runtime/snapshot.d.ts

@@ -36,6 +36,8 @@ export type RuntimeInventorySlot = {
     slot?: number;
 };
 export type RuntimePlayerRow = {
+    territoryOwnedCount?: number;
+    ownedTerritoryChunkKeys?: string[];
     userId: string;
     inventories: Record<string, RuntimeInventorySlot[]>;
     economy: Record<string, number>;
@@ -46,6 +48,12 @@ export type RuntimePlayerRow = {
     session?: Record<string, unknown>;
 };
 export type RuntimeChunkRow = {
+    /** Cell key to owner id, persisted with its spatial chunk. */
+    territory?: Record<string, string>;
+    territoryReceipts?: Record<string, {
+        claimedAt: number;
+        costPaid: number;
+    }>;
     chunkKey: string;
     objects: RuntimeObjectRow[];
     entities: RuntimeEntityRow[];

package/dist/runtime/snapshotBuffer.d.ts

@@ -0,0 +1,33 @@
+/** A sampled pair of snapshots and interpolation factor. */
+export type SnapshotBufferSample<T> = {
+    before: T;
+    after: T;
+    alpha: number;
+};
+/** Serializable snapshot-buffer state. */
+export type SnapshotBufferState<T> = {
+    delayMs: number;
+    capacity: number;
+    entries: Array<{
+        atMs: number;
+        value: T;
+    }>;
+};
+/** Handle for a timestamped delayed snapshot buffer. */
+export type SnapshotBuffer<T> = {
+    push(atMs: number, value: T): void;
+    sampleAt(nowMs: number): SnapshotBufferSample<T> | null;
+    snapshot(): SnapshotBufferState<T>;
+    restore(next: SnapshotBufferState<T>): void;
+    retune(config: {
+        delayMs?: number;
+        capacity?: number;
+    }): void;
+};
+/** Stores timestamped snapshots and samples a delayed, interpolatable pair.
+ * @capability runtime snapshot interpolation
+ */
+export declare function createSnapshotBuffer<T>(config: {
+    delayMs: number;
+    capacity: number;
+}): SnapshotBuffer<T>;

package/dist/runtime/snapshotBuffer.js

@@ -0,0 +1,58 @@
+/** Stores timestamped snapshots and samples a delayed, interpolatable pair.
+ * @capability runtime snapshot interpolation
+ */
+export function createSnapshotBuffer(config) {
+    let delayMs = Math.max(0, config.delayMs);
+    let capacity = Math.max(1, Math.floor(config.capacity));
+    let entries = [];
+    const trim = () => {
+        if (entries.length > capacity)
+            entries = entries.slice(-capacity);
+    };
+    return {
+        push(atMs, value) {
+            const entry = { atMs, value };
+            const index = entries.findIndex((item) => item.atMs > atMs);
+            if (index < 0)
+                entries.push(entry);
+            else
+                entries.splice(index, 0, entry);
+            trim();
+        },
+        sampleAt(nowMs) {
+            if (entries.length === 0)
+                return null;
+            const target = nowMs - delayMs;
+            if (target <= entries[0].atMs)
+                return { before: entries[0].value, after: entries[0].value, alpha: 0 };
+            const last = entries[entries.length - 1];
+            if (target >= last.atMs)
+                return { before: last.value, after: last.value, alpha: 1 };
+            for (let i = 1; i < entries.length; i += 1) {
+                const after = entries[i];
+                if (target <= after.atMs) {
+                    const before = entries[i - 1];
+                    const span = after.atMs - before.atMs;
+                    return { before: before.value, after: after.value, alpha: span === 0 ? 1 : (target - before.atMs) / span };
+                }
+            }
+            return null;
+        },
+        snapshot() {
+            return { delayMs, capacity, entries: entries.map((entry) => ({ ...entry })) };
+        },
+        restore(next) {
+            delayMs = Math.max(0, next.delayMs);
+            capacity = Math.max(1, Math.floor(next.capacity));
+            entries = next.entries.map((entry) => ({ ...entry })).sort((a, b) => a.atMs - b.atMs);
+            trim();
+        },
+        retune(config) {
+            if (config.delayMs !== undefined)
+                delayMs = Math.max(0, config.delayMs);
+            if (config.capacity !== undefined)
+                capacity = Math.max(1, Math.floor(config.capacity));
+            trim();
+        },
+    };
+}

package/dist/runtime/transport.d.ts

@@ -1,10 +1,38 @@
 import type { ChatSync } from "../multiplayer/chatContract.js";
 import type { PlayerPose } from "../multiplayer/poseSyncGate.js";
 import type { PresenceTransport } from "../multiplayer/presenceContract.js";
+import type { WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/** A revision-stamped world baseline or compact diff sent to a server-authoritative client. */
+export type WorldSyncFrame = {
+    kind: "baseline";
+    revision: number;
+    snapshot: WorldSnapshot;
+} | {
+    kind: "diff";
+    revision: number;
+    diff: WorldDiff;
+};
+/** A short-lived credential allowing a disconnected client to reclaim one server membership. */
+export type ResumeTicket = {
+    userId: string;
+    serverId: string;
+    token: string;
+};
 export type JoinServerResult = {
     serverId: string;
     isNew: boolean;
+    resumeTicket?: ResumeTicket;
+};
+/** Join failures are returned to the caller so the triggering surface can offer retry. */
+export type JoinServerOutcome = (JoinServerResult & {
+    ok: true;
+}) | {
+    ok: false;
+    reason: "full" | "closed" | "unauthorized";
 };
+/** Connection role used for authoritative world access; spectators are read-only. */
+export type MultiplayerRole = "player" | "spectator";
 export type RunCommandArgs = {
     serverId: string;
     command: string;
@@ -21,7 +49,7 @@ export type GameRuntimeServerView = {
     gameId: string;
     revision: number;
     memberUserIds: string[];
-    serverState: unknown;
+    serverState: unknown | WorldSyncFrame;
     updatedAt: number;
 };
 export type GameRuntimePlayerView = {
@@ -35,15 +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;
-    }) => Promise<JoinServerResult>;
+        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;
@@ -54,6 +92,7 @@ export type GameRuntimeFeeds = {
         serverId: string;
         action: string;
     }, onChange: (view: GameRuntimeFeedView) => void) => FeedUnsubscribe;
+    requestServerBaseline?: (serverId: string) => void;
 };
 export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = {
     transport: GameRuntimeTransport;

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

@@ -37,3 +37,5 @@ export declare function setChunk(snapshot: GameRuntimeSnapshot, chunkKey: string
 export declare function updateChunk(snapshot: GameRuntimeSnapshot, chunkKey: string, update: (chunk: RuntimeChunkRow) => RuntimeChunkRow): GameRuntimeSnapshot;
 /** Drop a chunk from a snapshot and mark the key dirty so the host deletes its stored row. */
 export declare function deleteChunk(snapshot: GameRuntimeSnapshot, chunkKey: string): GameRuntimeSnapshot;
+/** Square chunk neighborhood around a world position, including its own chunk. */
+export declare function chunkKeysAround(position: readonly [number, number, number], rings?: number, size?: number): string[];

package/dist/runtime/worldChunks.js

@@ -81,3 +81,17 @@ export function deleteChunk(snapshot, chunkKey) {
         dirty: { ...snapshot.dirty, server: true, chunks: withChunkDirty(snapshot, chunkKey) },
     };
 }
+/** Square chunk neighborhood around a world position, including its own chunk. */
+export function chunkKeysAround(position, rings = 1, size = DEFAULT_CHUNK_SIZE) {
+    if (!Number.isSafeInteger(rings) || rings < 0 || rings > 128)
+        throw new RangeError("rings must be an integer from 0 to 128");
+    if (!Number.isFinite(size) || size <= 0 || !position.every(Number.isFinite))
+        throw new RangeError("Invalid chunk position or size");
+    const center = chunkCoordAt(position, size);
+    const keys = [];
+    for (let cx = center.cx - rings; cx <= center.cx + rings; cx++) {
+        for (let cz = center.cz - rings; cz <= center.cz + rings; cz++)
+            keys.push(chunkKeyOf({ cx, cz }));
+    }
+    return keys;
+}

package/dist/runtime/worldProjection.d.ts

@@ -8,6 +8,11 @@ import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
  * growing a per-feature branch.
  */
 export interface ReplicationPolicy {
+    /** Decimal places used for replicated positions and angles. */
+    quantize?: {
+        position?: number;
+        angle?: number;
+    };
     /**
      * Replicate each player's private per-user state (inventory) only to that player — other viewers
      * receive none of it. Off by default so existing games keep broadcasting every player's state.
@@ -24,6 +29,10 @@ export interface ReplicationPolicy {
  * @internal host projection plumbing — games set ReplicationPolicy; the runtime applies it.
  */
 export declare function policyProjectsViewers(policy: ReplicationPolicy | undefined): boolean;
+/** Quantize replicated entity poses according to a host projection policy.
+ * @internal host projection plumbing
+ */
+export declare function quantizeWorldForReplication(world: WorldSnapshot, policy: ReplicationPolicy | undefined): WorldSnapshot;
 /**
  * Cull an entity list to a viewer's area of interest: keep the viewer's own entity plus every entity
  * within `radius` of it. When the viewer has no locatable entity the full list is returned (fail-open —

package/dist/runtime/worldProjection.js

@@ -4,7 +4,23 @@
 export function policyProjectsViewers(policy) {
     if (policy === undefined)
         return false;
-    return policy.privatePerUser === true || policy.aoiRadius !== undefined;
+    return policy.privatePerUser === true || policy.aoiRadius !== undefined || policy.quantize !== undefined;
+}
+/** Quantize replicated entity poses according to a host projection policy.
+ * @internal host projection plumbing
+ */
+export function quantizeWorldForReplication(world, policy) {
+    if (policy?.quantize?.position === undefined && policy?.quantize?.angle === undefined)
+        return world;
+    const digits = (value, places) => places === undefined ? value : Number(value.toFixed(Math.max(0, places)));
+    const entities = world["entities"]?.map((entity) => ({
+        ...entity,
+        position: entity.position.map((value) => digits(value, policy.quantize?.position)),
+        rotationY: digits(entity.rotationY, policy.quantize?.angle),
+        rotationX: digits(entity.rotationX, policy.quantize?.angle),
+        rotationZ: digits(entity.rotationZ, policy.quantize?.angle),
+    }));
+    return entities === undefined ? world : { ...world, entities };
 }
 function distanceSquared(a, b) {
     const dx = a[0] - b[0];

package/dist/runtime/worldSnapshot.d.ts

@@ -1,6 +1,10 @@
 /** Who a host→client snapshot is being projected for — the identity a {@link SnapshotModule.project} filters against. */
 export interface SnapshotViewer {
     readonly userId: string;
+    /** A read-only connection role; spectators receive snapshots but cannot mutate the world. */
+    readonly role?: "player" | "spectator";
+    /** Host tick used by {@link SnapshotModule.priority} to throttle low-priority modules. */
+    readonly tick?: number;
 }
 /**
  * The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the
@@ -37,6 +41,8 @@ export interface SnapshotModule<T = unknown> {
     project?(data: T, viewer: SnapshotViewer, world: WorldSnapshot): T;
     /** Monotone change counter; unchanged between host commits means this module didn't mutate and need not re-serialize. */
     version?(): number;
+    /** Return the host tick interval for this module; values greater than one omit it on intervening ticks. */
+    priority?(data: T, viewer: SnapshotViewer): number;
 }
 /** Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem. */
 export type WorldSnapshot = Record<string, unknown>;

package/dist/runtime/worldSnapshot.js

@@ -13,6 +13,9 @@ export function composeWorldSnapshot(modules, viewer) {
     const snapshot = {};
     for (const module of modules) {
         const value = raw[module.key];
+        const interval = viewer?.tick === undefined ? 1 : Math.max(1, Math.floor(module.priority?.(value, viewer) ?? 1));
+        if (viewer?.tick !== undefined && interval > 1 && viewer.tick % interval !== 0)
+            continue;
         snapshot[module.key] =
             module.project !== undefined ? module.project(value, viewer, raw) : value;
     }

package/dist/scene/behaviorRuntime.d.ts

@@ -1,8 +1,27 @@
+import type { Blackboard, DecisionAbort, DecisionAction, DecisionGraphRuntime } from "../ai/decisionGraph.js";
+import { type InterestGateState } from "../ai/interestScheduler.js";
 import { type PathFollowState, type PathProgress, type Waypoint } from "../nav/pathFollow.js";
 import type { GameContext } from "../runtime/gameContext.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";
+/** Context supplied to a registered decision graph action. */
+export interface BehaviorActionContext {
+    ctx: GameContext;
+    entityId: string;
+    dt: number;
+}
+/** 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>, 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
@@ -18,11 +37,18 @@ export type BehaviorSnapshot = {
     readonly kind: "wander";
     readonly origin: Waypoint;
     readonly target: Waypoint | null;
+} | {
+    readonly kind: "decisionGraph";
+    readonly graph: ReturnType<DecisionGraphRuntime["snapshot"]>;
+    readonly gate: InterestGateState;
+    readonly blackboard?: Blackboard;
+    /** Seconds accrued since the last think. */
+    readonly pending?: number;
 };
 /** Inspection readout for editor/debug tooling, from {@link BehaviorControl.inspect}/{@link BehaviorControl.list}. */
 export interface BehaviorInspection {
     id: string;
-    kind: "patrol" | "wander";
+    kind: "patrol" | "wander" | "decisionGraph";
     status: BehaviorStatus;
     reason: string | null;
 }
@@ -54,6 +80,8 @@ 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;
 }
 /**
  * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} one tick — the

package/dist/scene/behaviorRuntime.js

@@ -1,4 +1,5 @@
-import { seededRng } from "../random/rng.js";
+import { createDecisionGraphRuntime } from "../ai/decisionGraph.js";
+import { advanceInterestGate, createInterestGateState } from "../ai/interestScheduler.js";
 import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
 import { resolveWalkerStep } from "../movement/solidObstacles.js";
 import { perContext } from "../runtime/perContext.js";
@@ -6,12 +7,30 @@ const DEFAULT_WANDER_SPEED = 1.5;
 const WANDER_ARRIVAL = 0.6;
 /** Below this share of its intended step a wanderer counts as blocked and re-rolls its target. */
 const WANDER_BLOCKED_FRACTION = 0.25;
+const behaviorActions = new Map();
+/** Register the named actions used by decision graph behavior descriptors.
+ * @capability behavior-actions register named callbacks for decision graph behavior descriptors
+ */
+export function registerBehaviorActions(id, actions, options = {}) {
+    const entry = { actions, options };
+    behaviorActions.set(id, entry);
+    return () => {
+        if (behaviorActions.get(id) === entry)
+            behaviorActions.delete(id);
+    };
+}
+function thinkCadence(behavior) {
+    return { wakeRadius: Number.POSITIVE_INFINITY, activeInterval: Math.max(0, behavior.thinkInterval ?? 0) };
+}
 function patrolOf(entity) {
     return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
 }
 function wanderOf(entity) {
     return entity.behaviors.find((b) => b.kind === "wander") ?? null;
 }
+function decisionGraphOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "decisionGraph") ?? null;
+}
 const runtimeOf = perContext((ctx) => {
     const nav = new Map();
     const refresh = () => {
@@ -41,7 +60,30 @@ const runtimeOf = perContext((ctx) => {
                     radius: wander.radius,
                     origin: entity.position,
                     target: null,
-                    roll: seededRng(`wander:${entity.id}`),
+                    roll: () => ctx.rng(),
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+                continue;
+            }
+            const decisionGraph = decisionGraphOf(entity);
+            if (decisionGraph !== null) {
+                const registered = behaviorActions.get(decisionGraph.actions);
+                if (registered === undefined)
+                    continue;
+                const cadence = thinkCadence(decisionGraph);
+                nav.set(entity.id, {
+                    kind: "decisionGraph",
+                    behavior: decisionGraph,
+                    runtime: createDecisionGraphRuntime(decisionGraph.graph, registered.actions, {
+                        rng: () => ctx.rng(),
+                        ...(registered.options.onAbort === undefined ? {} : { onAbort: registered.options.onAbort }),
+                    }),
+                    gate: createInterestGateState(cadence, ctx.rng()),
+                    cadence,
+                    blackboard: { ...(decisionGraph.blackboard ?? {}) },
+                    pending: 0,
                     status: "active",
                     reason: null,
                     pausedElapsed: 0,
@@ -135,9 +177,21 @@ export function advanceBehaviors(ctx, dt) {
             entry.state = advancePathFollow(entry.config, entry.state, dt);
             posePatrol(ctx, id, entry, dt);
         }
-        else {
+        else if (entry.kind === "wander") {
             stepWander(ctx, id, entry, dt);
         }
+        else {
+            const entity = ctx.scene.entity.get(id);
+            if (entity === null)
+                continue;
+            entry.pending += dt;
+            const step = advanceInterestGate(entry.gate, entry.cadence, dt, { proximity: 0 });
+            if (!step.active)
+                continue;
+            const elapsed = entry.pending;
+            entry.pending = 0;
+            entry.runtime.tick({ ctx, entityId: id, dt: elapsed }, entry.blackboard, elapsed);
+        }
     }
 }
 /**
@@ -206,7 +260,9 @@ export function behaviorControl(ctx) {
                 return null;
             if (entry.kind === "patrol")
                 return { kind: "patrol", state: { ...entry.state } };
-            return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+            if (entry.kind === "wander")
+                return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+            return { kind: "decisionGraph", graph: entry.runtime.snapshot(), gate: { ...entry.gate }, blackboard: { ...entry.blackboard }, pending: entry.pending };
         },
         restore: (id, snapshot) => {
             const entry = nav.get(id);
@@ -216,6 +272,13 @@ export function behaviorControl(ctx) {
                 entry.state = { ...snapshot.state };
                 return true;
             }
+            if (entry.kind === "decisionGraph" && snapshot.kind === "decisionGraph") {
+                entry.runtime.restore(snapshot.graph);
+                entry.gate = { ...snapshot.gate };
+                entry.blackboard = { ...(snapshot.blackboard ?? entry.behavior.blackboard ?? {}) };
+                entry.pending = snapshot.pending ?? 0;
+                return true;
+            }
             if (entry.kind === "wander" && snapshot.kind === "wander") {
                 entry.origin = [...snapshot.origin];
                 entry.target = snapshot.target === null ? null : [...snapshot.target];
@@ -235,5 +298,9 @@ export function behaviorControl(ctx) {
                 out.push({ id, kind: entry.kind, status: entry.status, reason: entry.reason });
             return out;
         },
+        blackboard: (id) => {
+            const entry = nav.get(id);
+            return entry?.kind === "decisionGraph" ? entry.blackboard : null;
+        },
     };
 }