@jgengine/core 0.18.1 → 0.21.0

package/dist/scene/behaviorRuntime.js

@@ -1,8 +1,15 @@
 import { createDecisionGraphRuntime } from "../ai/decisionGraph.js";
-import { advanceInterestGate, createInterestGateState } from "../ai/interestScheduler.js";
+import { advanceInterestGate, createInterestGateState, interestPhase } from "../ai/interestScheduler.js";
+import { advancePursuit, armPursuit, createPursuitState } from "../ai/pursuit.js";
+import { acquireTarget } from "../ai/targetAcquisition.js";
+import { createThreatTable } from "../ai/threat.js";
 import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
 import { resolveWalkerStep } from "../movement/solidObstacles.js";
 import { perContext } from "../runtime/perContext.js";
+import { notifyAfter } from "../store/changeSignal.js";
+import { visibleEntityIds } from "../runtime/worldProjection.js";
+import { behaviorDataEqual } from "./behaviors.js";
+import { distanceBetween } from "./spatial.js";
 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. */
@@ -11,14 +18,19 @@ 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) {
-    behaviorActions.set(id, actions);
+export function registerBehaviorActions(id, actions, options = {}) {
+    const entry = { actions, options };
+    behaviorActions.set(id, entry);
     return () => {
-        if (behaviorActions.get(id) === actions)
+        if (behaviorActions.get(id) === entry)
             behaviorActions.delete(id);
     };
 }
-const DECISION_GRAPH_CADENCE = { wakeRadius: Number.POSITIVE_INFINITY, activeInterval: 0 };
+// Bind unsaved policy without eagerly constructing the lazy AI runtime before boot-time restore.
+const pursuitPolicies = new WeakMap();
+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;
 }
@@ -30,12 +42,20 @@ function decisionGraphOf(entity) {
 }
 const runtimeOf = perContext((ctx) => {
     const nav = new Map();
-    const refresh = () => {
-        const live = new Set();
-        for (const entity of ctx.scene.entity.list()) {
-            live.add(entity.id);
-            if (nav.has(entity.id))
-                continue;
+    const descriptors = new Map();
+    const refreshId = (id) => {
+        const entity = ctx.scene.entity.get(id);
+        const descriptor = entity === null ? undefined : patrolOf(entity) ?? wanderOf(entity) ?? decisionGraphOf(entity)
+            ?? entity.behaviors.find(behavior => behavior.kind === "pursue");
+        if (entity !== null && descriptor !== undefined && nav.has(id) && behaviorDataEqual(descriptors.get(id), descriptor))
+            return;
+        const previous = nav.get(id);
+        nav.delete(id);
+        descriptors.delete(id);
+        try {
+            if (entity === null || descriptor === undefined)
+                return;
+            descriptors.set(id, descriptor);
             const patrol = patrolOf(entity);
             if (patrol !== null) {
                 const config = { waypoints: patrol.waypoints, speed: patrol.speed, loop: patrol.loop };
@@ -48,7 +68,7 @@ const runtimeOf = perContext((ctx) => {
                     reason: null,
                     pausedElapsed: 0,
                 });
-                continue;
+                return;
             }
             const wander = wanderOf(entity);
             if (wander !== null) {
@@ -62,32 +82,165 @@ const runtimeOf = perContext((ctx) => {
                     reason: null,
                     pausedElapsed: 0,
                 });
-                continue;
+                return;
             }
             const decisionGraph = decisionGraphOf(entity);
             if (decisionGraph !== null) {
-                const actions = behaviorActions.get(decisionGraph.actions);
-                if (actions === undefined)
-                    continue;
+                const registered = behaviorActions.get(decisionGraph.actions);
+                if (registered === undefined)
+                    return;
+                const cadence = thinkCadence(decisionGraph);
                 nav.set(entity.id, {
                     kind: "decisionGraph",
                     behavior: decisionGraph,
-                    runtime: createDecisionGraphRuntime(decisionGraph.graph, actions),
-                    gate: createInterestGateState(DECISION_GRAPH_CADENCE, ctx.rng()),
+                    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,
                 });
             }
+            const pursuing = entity.behaviors.find((behavior) => behavior.kind === "pursue");
+            if (pursuing?.kind === "pursue" && !nav.has(entity.id)) {
+                const cadence = { wakeRadius: Infinity, activeInterval: pursuing.thinkInterval ?? .1 };
+                const gate = createInterestGateState(cadence, interestPhase(entity.id));
+                gate.state = "active";
+                nav.set(entity.id, { kind: "pursue", behavior: pursuing,
+                    home: [...(ctx.scene.entity.spawnPoseOf(entity.id)?.position ?? entity.position)],
+                    targetId: null, returning: false, pursuit: createPursuitState(),
+                    gate, cadence, pending: 0,
+                    status: "active", reason: null, pausedElapsed: 0,
+                    ...(pursuing.threat === undefined ? {} : { threat: createThreatTable(pursuing.threat) }) });
+            }
         }
-        for (const id of nav.keys())
+        finally {
+            if (previous?.kind === "decisionGraph")
+                previous.runtime.abort({ ctx, entityId: id, dt: 0 }, previous.blackboard);
+        }
+    };
+    const refresh = () => {
+        const live = new Set();
+        for (const entity of ctx.scene.entity.list()) {
+            live.add(entity.id);
+            refreshId(entity.id);
+        }
+        for (const id of descriptors.keys())
             if (!live.has(id))
-                nav.delete(id);
+                refreshId(id);
     };
-    ctx.scene.entity.subscribeMembership(refresh);
+    ctx.scene.entity.subscribeBehaviors(refreshId);
     refresh();
     return { nav };
 });
+function resetPursue(ctx, id, entry) {
+    entry.targetId = null;
+    entry.returning = false;
+    entry.pursuit.attackCooldown = 0;
+    entry.pending = 0;
+    entry.gate = createInterestGateState(entry.cadence, interestPhase(id));
+    entry.gate.state = "active";
+    entry.threat?.clear();
+    ctx.scene.entity.setTarget(id, null);
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonnegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function validPursueSnapshot(value) {
+    if (!object(value) || value.kind !== "pursue" || !Array.isArray(value.home) || value.home.length !== 3
+        || !value.home.every(n => typeof n === "number" && Number.isFinite(n))
+        || !(value.targetId === null || typeof value.targetId === "string")
+        || !(value.explicitTargetId === null || typeof value.explicitTargetId === "string") || typeof value.returning !== "boolean"
+        || !object(value.pursuit) || !nonnegative(value.pursuit.attackCooldown) || !nonnegative(value.pending)
+        || !object(value.gate) || !(value.gate.state === "active" || value.gate.state === "dormant")
+        || !nonnegative(value.gate.clock) || !nonnegative(value.gate.awakeHold)
+        || !nonnegative(value.gate.phase) || value.gate.phase >= 1)
+        return false;
+    if (value.threat !== undefined) {
+        if (!object(value.threat) || !Array.isArray(value.threat.entries) || !nonnegative(value.threat.forcedRemaining)
+            || !(value.threat.forcedSource === null || typeof value.threat.forcedSource === "string"))
+            return false;
+        const seen = new Set();
+        for (const entry of value.threat.entries) {
+            if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || seen.has(entry[0])
+                || typeof entry[1] !== "number" || !Number.isFinite(entry[1]))
+                return false;
+            seen.add(entry[0]);
+        }
+    }
+    return true;
+}
+function restorePursue(entry, snapshot) {
+    entry.home = [...snapshot.home];
+    entry.targetId = snapshot.targetId;
+    entry.returning = snapshot.returning;
+    entry.pursuit = { ...snapshot.pursuit };
+    entry.gate = { ...snapshot.gate };
+    entry.pending = snapshot.pending;
+    if (entry.threat !== undefined && snapshot.threat !== undefined)
+        entry.threat.restore(snapshot.threat);
+    else
+        entry.threat?.clear();
+}
+function stepPursue(ctx, id, entry, dt) {
+    const entity = ctx.scene.entity.get(id);
+    if (entity === null)
+        return;
+    const { behavior, home } = entry;
+    const homeDistance = distanceBetween(entity.position, home);
+    const policy = pursuitPolicies.get(ctx);
+    const eligible = (candidate) => candidate !== id && ctx.scene.entity.get(candidate) !== null
+        && ctx.scene.entity.canReceive(candidate, behavior.attack.effect, behavior.attack.amount) === null
+        && (policy === undefined || policy(ctx, id, candidate) === true);
+    entry.threat?.decay(dt);
+    if (!entry.returning) {
+        const explicit = ctx.scene.entity.getTarget(id);
+        const forced = entry.threat?.forcedTarget() ?? null;
+        if (explicit !== null && eligible(explicit))
+            entry.targetId = explicit;
+        else if (forced !== null && eligible(forced))
+            entry.targetId = forced;
+        else {
+            const nearby = ctx.scene.entity.inRadius(id, behavior.aggroRadius, candidate => ctx.scene.entity.get(candidate)?.role === "player");
+            if (entry.targetId !== null && !nearby.includes(entry.targetId))
+                nearby.push(entry.targetId);
+            const held = entry.targetId;
+            entry.targetId = acquireTarget({ candidates: () => nearby, distance: ctx.scene.entity.distance,
+                range: (_self, candidate) => candidate === held ? Infinity : behavior.aggroRadius,
+                eligible: (_self, candidate) => eligible(candidate), score: (_self, candidate) => entry.threat?.threatOf(candidate) ?? 0,
+                tieBreak: (a, b) => (ctx.scene.entity.distance(id, a) ?? Infinity) - (ctx.scene.entity.distance(id, b) ?? Infinity)
+                    || (a < b ? -1 : a > b ? 1 : 0),
+            }, id, held).targetId;
+        }
+    }
+    const targetDistance = entry.targetId === null ? null : ctx.scene.entity.distance(id, entry.targetId);
+    const action = advancePursuit(entry.pursuit, dt, targetDistance, behavior.reach, behavior.cooldownMode, homeDistance, behavior.leashRange);
+    if (action === "leash" || (targetDistance === null && homeDistance > .1))
+        entry.returning = true;
+    if (entry.returning) {
+        entry.targetId = null;
+        ctx.scene.entity.setTarget(id, null);
+        ctx.scene.entity.moveTowardCommit(id, home, { speed: behavior.speed, stopDistance: 0, dt, face: true });
+        const position = ctx.scene.entity.get(id)?.position;
+        if (position !== undefined && distanceBetween(position, home) <= .1)
+            resetPursue(ctx, id, entry);
+    }
+    else if (action === "pursue" && entry.targetId !== null) {
+        ctx.scene.entity.moveTowardCommit(id, entry.targetId, { speed: behavior.speed, stopDistance: behavior.reach, dt, face: true });
+    }
+    else if (action === "attack" && entry.targetId !== null) {
+        ctx.scene.entity.effect({ from: id, to: entry.targetId, effect: behavior.attack.effect, via: { amount: behavior.attack.amount } });
+        armPursuit(entry.pursuit, behavior.attack.intervalSec);
+    }
+}
 function stepWander(ctx, id, nav, dt) {
     const entity = ctx.scene.entity.get(id);
     if (entity === null)
@@ -143,13 +296,13 @@ function posePatrol(ctx, id, nav, dt) {
     });
 }
 /**
- * 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 function advanceBehaviors(ctx, dt) {
     if (dt <= 0)
@@ -157,10 +310,14 @@ export function advanceBehaviors(ctx, dt) {
     const { nav } = runtimeOf(ctx);
     if (nav.size === 0)
         return;
+    let pursuitChanged = false;
     for (const [id, entry] of nav) {
         if (entry.status !== "active") {
-            if (entry.status === "paused")
+            if (entry.status === "paused") {
                 entry.pausedElapsed += dt;
+                if (entry.kind === "pursue")
+                    pursuitChanged = true;
+            }
             continue;
         }
         if (entry.kind === "patrol") {
@@ -170,19 +327,30 @@ export function advanceBehaviors(ctx, dt) {
         else if (entry.kind === "wander") {
             stepWander(ctx, id, entry, dt);
         }
+        else if (entry.kind === "pursue") {
+            entry.pending += dt;
+            pursuitChanged = true;
+            if (!advanceInterestGate(entry.gate, entry.cadence, dt, { proximity: 0 }).active)
+                continue;
+            const elapsed = entry.pending;
+            entry.pending = 0;
+            stepPursue(ctx, id, entry, elapsed);
+        }
         else {
             const entity = ctx.scene.entity.get(id);
             if (entity === null)
                 continue;
-            const step = advanceInterestGate(entry.gate, DECISION_GRAPH_CADENCE, dt, { proximity: 0 });
+            entry.pending += dt;
+            const step = advanceInterestGate(entry.gate, entry.cadence, dt, { proximity: 0 });
             if (!step.active)
                 continue;
-            const blackboard = {};
-            const status = entry.runtime.tick({ ctx, entityId: id, dt }, blackboard, dt);
-            if (status === "done" || status === "failed")
-                entry.runtime.restore({ runningPath: null });
+            const elapsed = entry.pending;
+            entry.pending = 0;
+            entry.runtime.tick({ ctx, entityId: id, dt: elapsed }, entry.blackboard, elapsed);
         }
     }
+    if (pursuitChanged)
+        ctx.touch();
 }
 /**
  * Obtain the per-context {@link BehaviorControl} surface for suspending, resuming, seeking, serializing,
@@ -199,6 +367,8 @@ export function behaviorControl(ctx) {
             return false;
         entry.status = status;
         entry.reason = reason;
+        if (entry.kind === "pursue")
+            ctx.touch();
         return true;
     };
     return {
@@ -211,6 +381,8 @@ export function behaviorControl(ctx) {
             entry.status = "paused";
             entry.reason = reason ?? null;
             entry.pausedElapsed = 0;
+            if (entry.kind === "pursue")
+                ctx.touch();
             return true;
         },
         resume: (id, policy = "freeze") => {
@@ -225,6 +397,8 @@ export function behaviorControl(ctx) {
             entry.status = "active";
             entry.reason = null;
             entry.pausedElapsed = 0;
+            if (entry.kind === "pursue")
+                ctx.touch();
             return true;
         },
         disable: (id, reason) => setStatus(id, "disabled", reason ?? null),
@@ -235,6 +409,8 @@ export function behaviorControl(ctx) {
             entry.status = "active";
             entry.reason = null;
             entry.pausedElapsed = 0;
+            if (entry.kind === "pursue")
+                ctx.touch();
             return true;
         },
         seek: (id, progress) => {
@@ -252,7 +428,12 @@ export function behaviorControl(ctx) {
                 return { kind: "patrol", state: { ...entry.state } };
             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 } };
+            if (entry.kind === "pursue")
+                return { kind: "pursue", home: [...entry.home], targetId: entry.targetId,
+                    explicitTargetId: ctx.scene.entity.getTarget(id),
+                    returning: entry.returning, pursuit: { ...entry.pursuit }, gate: { ...entry.gate }, pending: entry.pending,
+                    ...(entry.threat === undefined ? {} : { threat: entry.threat.snapshot() }) };
+            return { kind: "decisionGraph", graph: entry.runtime.snapshot(), gate: { ...entry.gate }, blackboard: { ...entry.blackboard }, pending: entry.pending };
         },
         restore: (id, snapshot) => {
             const entry = nav.get(id);
@@ -265,6 +446,8 @@ export function behaviorControl(ctx) {
             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") {
@@ -272,6 +455,14 @@ export function behaviorControl(ctx) {
                 entry.target = snapshot.target === null ? null : [...snapshot.target];
                 return true;
             }
+            if (entry.kind === "pursue" && snapshot.kind === "pursue") {
+                if (!validPursueSnapshot(snapshot))
+                    return false;
+                restorePursue(entry, snapshot);
+                ctx.scene.entity.setTarget(id, snapshot.explicitTargetId);
+                ctx.touch();
+                return true;
+            }
             return false;
         },
         inspect: (id) => {
@@ -286,5 +477,77 @@ 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;
+        },
+        threat: (id) => {
+            const entry = nav.get(id);
+            if (entry?.kind !== "pursue" || entry.threat === undefined)
+                return null;
+            return entry.threatControl ??= notifyAfter(entry.threat, ["add", "set", "taunt", "remove", "clear", "restore", "decay"], ctx.touch);
+        },
+        reset: (id) => {
+            const entry = nav.get(id);
+            if (entry?.kind !== "pursue")
+                return false;
+            resetPursue(ctx, id, entry);
+            ctx.touch();
+            return true;
+        },
     };
 }
+/** @internal Register persistence before boot-time restore without constructing an AI runtime. */
+export function installPursuitPersistence(ctx, aoiRadius, eligible) {
+    if (eligible !== undefined)
+        pursuitPolicies.set(ctx, eligible);
+    ctx.game.registerReplicate?.({
+        key: "pursuitBehaviors",
+        snapshot() {
+            const control = behaviorControl(ctx);
+            const instances = [];
+            for (const [id, entry] of runtimeOf(ctx).nav) {
+                if (entry.kind !== "pursue")
+                    continue;
+                instances.push({ id, snapshot: control.serialize(id),
+                    status: entry.status, reason: entry.reason, pausedElapsed: entry.pausedElapsed });
+            }
+            return { version: 1, instances };
+        },
+        decode(raw) {
+            if (!object(raw) || raw.version !== 1 || !Array.isArray(raw.instances))
+                return null;
+            const seen = new Set();
+            for (const value of raw.instances) {
+                if (!object(value) || typeof value.id !== "string" || seen.has(value.id)
+                    || !validPursueSnapshot(value.snapshot) || !(value.status === "active" || value.status === "paused" || value.status === "disabled")
+                    || !(value.reason === null || typeof value.reason === "string") || !nonnegative(value.pausedElapsed)
+                    || !ctx.scene.entity.get(value.id)?.behaviors.some(behavior => behavior.kind === "pursue"))
+                    return null;
+                seen.add(value.id);
+            }
+            return structuredClone(raw);
+        },
+        hydrate(data) {
+            const runtime = runtimeOf(ctx);
+            for (const record of data.instances) {
+                const entry = runtime.nav.get(record.id);
+                if (entry?.kind !== "pursue")
+                    continue;
+                restorePursue(entry, record.snapshot);
+                entry.status = record.status;
+                entry.reason = record.reason;
+                entry.pausedElapsed = record.pausedElapsed;
+            }
+            for (const record of data.instances)
+                ctx.scene.entity.setTarget(record.id, record.snapshot.explicitTargetId);
+            ctx.touch();
+        },
+        ...(aoiRadius === undefined ? {} : {
+            project(data, viewer, world) {
+                const visible = visibleEntityIds((world.entities ?? []), viewer, aoiRadius);
+                return { ...data, instances: data.instances.filter(record => visible.has(record.id)) };
+            },
+        }),
+    });
+}

package/dist/scene/behaviors.d.ts

@@ -1,6 +1,29 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
 import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
-import type { DecisionGraph } from "../ai/decisionGraph.js";
+import type { Blackboard, DecisionGraph } from "../ai/decisionGraph.js";
+import type { CooldownMode } from "../ai/pursuit.js";
+import type { ThreatTableConfig } from "../ai/threat.js";
+/** Scheduled chase/attack behavior; the default declares hostility toward player-role entities.
+ * GameDefinition.pursuit.eligible can further restrict every target source using the live world.
+ * Explicit targets and optional threat override nearest-player acquisition, not eligibility.
+ */
+export interface PursueBehavior {
+    kind: "pursue";
+    aggroRadius: number;
+    reach: number;
+    leashRange: number;
+    speed: number;
+    attack: {
+        effect: string;
+        amount: number;
+        intervalSec: number;
+    };
+    /** Seconds between acquisition/movement/attack ticks; default .1. Zero advances every frame. */
+    thinkInterval?: number;
+    cooldownMode?: CooldownMode;
+    /** Opt into a per-instance table available through `behaviorControl(ctx).threat(id)`. */
+    threat?: ThreatTableConfig;
+}
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -33,8 +56,18 @@ export interface DecisionGraphBehavior {
     kind: "decisionGraph";
     graph: DecisionGraph;
     actions: string;
+    /** Initial facts for this entity's persistent blackboard; systems write more through `behaviorControl(ctx).blackboard(id)`. */
+    blackboard?: Blackboard;
+    /** Seconds between graph ticks (`0` = every frame). Siblings are staggered; actions receive the elapsed time. */
+    thinkInterval?: number;
 }
-export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior | DecisionGraphBehavior;
+export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior | PursueBehavior | DecisionGraphBehavior;
+/** @internal Compare declarative behavior data at replacement boundaries, independent of object key order. */
+export declare function behaviorDataEqual(a: unknown, b: unknown): boolean;
+/** Attach aggro, collision-aware chase, cooldown attack and latched return-to-spawn as data.
+ * @capability pursue-behavior scheduled pursuit with bounded target acquisition and saved cooldown/leash state
+ */
+export declare function pursue(options: Omit<PursueBehavior, "kind">): PursueBehavior;
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;

package/dist/scene/behaviors.js

@@ -1,4 +1,33 @@
 import { command, keybind, proximityPrompt, } from "../interaction/proximityPrompt.js";
+/** @internal Compare declarative behavior data at replacement boundaries, independent of object key order. */
+export function behaviorDataEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object")
+        return false;
+    if (Array.isArray(a) || Array.isArray(b))
+        return Array.isArray(a) && Array.isArray(b)
+            && a.length === b.length && a.every((value, index) => behaviorDataEqual(value, b[index]));
+    const left = a, right = b;
+    const keys = Object.keys(left).filter(key => left[key] !== undefined);
+    return keys.length === Object.keys(right).filter(key => right[key] !== undefined).length
+        && keys.every(key => Object.hasOwn(right, key) && behaviorDataEqual(left[key], right[key]));
+}
+/** Attach aggro, collision-aware chase, cooldown attack and latched return-to-spawn as data.
+ * @capability pursue-behavior scheduled pursuit with bounded target acquisition and saved cooldown/leash state
+ */
+export function pursue(options) {
+    for (const [name, value] of Object.entries({ aggroRadius: options.aggroRadius, reach: options.reach,
+        leashRange: options.leashRange, speed: options.speed, intervalSec: options.attack.intervalSec,
+        thinkInterval: options.thinkInterval ?? .1 })) {
+        if (!Number.isFinite(value) || value < 0)
+            throw new Error(`pursue: ${name} must be finite and nonnegative`);
+    }
+    if (!Number.isFinite(options.attack.amount))
+        throw new Error("pursue: attack amount must be finite");
+    return { ...options, kind: "pursue", attack: { ...options.attack },
+        ...(options.threat === undefined ? {} : { threat: { ...options.threat } }) };
+}
 export function wander({ radius }) {
     return { kind: "wander", radius };
 }

package/dist/scene/entityStore.d.ts

@@ -1,4 +1,4 @@
-import type { BehaviorDescriptor } from "./behaviors.js";
+import { type BehaviorDescriptor } from "./behaviors.js";
 export type EntityRole = "player" | "npc" | "prop";
 export interface EntityMovement {
     walkSpeed?: number;
@@ -17,7 +17,7 @@ export interface SceneEntity<TMeta = unknown> {
     rotationY: number;
     rotationX: number;
     rotationZ: number;
-    /** World units per second, derived from consecutive setPose calls that carry `dt`. Zero until the entity moves under a dt. */
+    /** World units per second, derived by `setPose` with `dt` or explicitly replaced by `setVelocity`. Zero until set. */
     velocity: EntityPosition;
     role: EntityRole;
     movement: EntityMovement;
@@ -97,11 +97,14 @@ export interface EntityBlackboard {
     /** Milliseconds until the armed cooldown elapses; 0 when ready. */
     remaining(id: string, key: string, nowMs: number): number;
 }
+/** Entity state, pose writes, keyed behavior notifications and snapshot/hydration under stable instance IDs. */
 export interface EntityStore<TMeta = unknown> {
     spawn(name: string, options?: SpawnOptions<TMeta>): string;
     despawn(id: string): boolean;
     update(id: string, patch: EntityUpdatePatch<TMeta>): boolean;
     setPose(id: string, pose: EntityPose): boolean;
+    /** Replace velocity without moving the entity. Copies a finite three-number tuple; invalid input or a missing id returns false unchanged. */
+    setVelocity(id: string, velocity: EntityPosition): boolean;
     /** Register a constraint applied inside every `setPose` for this entity — the self-driven sibling of the shell's `beforeCommit` (#282.9): nav clamps, corridor walls, arena bounds without wrapping every call site. `null` clears; despawn clears automatically. */
     setPoseConstraint(id: string, constraint: PoseConstraint | null): void;
     get(id: string): SceneEntity<TMeta> | null;
@@ -112,6 +115,8 @@ export interface EntityStore<TMeta = unknown> {
     subscribe(listener: () => void): () => void;
     /** Notified only when the entity set changes (spawn/despawn/hydrate), never on a pose or field update — the render tree re-reconciles on membership, individual markers read live poses imperatively. */
     subscribeMembership(listener: () => void): () => void;
+    /** Changed behavior data or removal, keyed by id and notified before ordinary subscribers. Equal-data hydration and pose writes do not fire. */
+    subscribeBehaviors(listener: (id: string) => void): () => void;
     snapshot(): readonly SceneEntity<TMeta>[];
     /**
      * Apply a `snapshot()` (e.g. from an authoritative host) to this store — the counterpart of `snapshot()`
@@ -123,4 +128,10 @@ export interface EntityStore<TMeta = unknown> {
     resetToSpawn(id: string): boolean;
     blackboard: EntityBlackboard;
 }
-export declare function createEntityStore<TMeta = unknown>(): EntityStore<TMeta>;
+/** Commit hook for a derived index; runs after the write and before existing subscribers.
+ * `undefined` denotes a whole-store replacement. Value overwrites keep membership false.
+ */
+export interface EntityStoreOptions {
+    onChange?: (instanceId: string | undefined, membershipChanged: boolean) => void;
+}
+export declare function createEntityStore<TMeta = unknown>(options?: EntityStoreOptions): EntityStore<TMeta>;