@jgengine/core 0.10.0 → 0.11.0

package/dist/scene/authoredTriggers.js

@@ -0,0 +1,340 @@
+/**
+ * Authored behavior triggers on editor volumes and markers — a small `on`/`action` meta vocabulary
+ * so "when player enters this volume, spawn wave 2" is scene data, not game code. Games declare
+ * actions (typed via ParamSchema); the editor inspector renders their fields; a pure runtime
+ * watches membership and dispatches to handlers.
+ */
+import { parseParams } from "./sceneKinds.js";
+/** Reserved meta keys for the trigger vocabulary — action params use every other schema field. @internal */
+export const TRIGGER_ON_KEY = "on";
+/** @internal */
+export const TRIGGER_ACTION_KEY = "action";
+/** @internal */
+export const TRIGGER_RADIUS_KEY = "triggerRadius";
+/** @internal */
+export const TRIGGER_LIST_KEY = "triggers";
+const TRIGGER_EVENTS = ["enter", "exit", "interact"];
+/** Default proximity radius (m) for marker enter/exit/interact when neither triggerRadius nor radius is set. @internal */
+export const DEFAULT_TRIGGER_RADIUS = 2.5;
+const actionRegistry = new Map();
+/**
+ * Declare a game action the editor can assign to volume/marker triggers. Idempotent per `id`
+ * (last registration wins). Call at module load next to catalogs.
+ *
+ * @capability authored-triggers schema'd on/action vocabulary on volumes and markers with runtime dispatch
+ */
+export function registerTriggerAction(definition) {
+    actionRegistry.set(definition.id, definition);
+}
+/** Registered definition for an action id, or undefined when the game never declared it. */
+export function getTriggerAction(id) {
+    return actionRegistry.get(id);
+}
+/** Every registered action, optionally filtered by target collection. */
+export function listTriggerActions(target) {
+    const all = [...actionRegistry.values()];
+    if (target === undefined)
+        return all;
+    return all.filter((definition) => definition.targets === undefined || definition.targets.includes(target));
+}
+/** Clears the action registry — tests only. @internal */
+export function clearTriggerActions() {
+    actionRegistry.clear();
+}
+function isTriggerEvent(value) {
+    return typeof value === "string" && TRIGGER_EVENTS.includes(value);
+}
+function metaNumber(meta, key) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Resolve the proximity radius for a marker trigger from meta. @internal */
+export function triggerRadiusOf(meta, fallback = DEFAULT_TRIGGER_RADIUS) {
+    const explicit = metaNumber(meta, TRIGGER_RADIUS_KEY) ?? metaNumber(meta, "radius");
+    if (explicit === undefined)
+        return fallback;
+    return Math.max(0, explicit);
+}
+function specsFromMeta(meta) {
+    if (meta === undefined)
+        return [];
+    const list = meta[TRIGGER_LIST_KEY];
+    if (Array.isArray(list)) {
+        if (list.length === 0) {
+            // Empty multi-list is the inspector's "cleared" sentinel — fall through to flat on/action.
+        }
+        else {
+            const out = [];
+            for (const entry of list) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const row = entry;
+                if (!isTriggerEvent(row[TRIGGER_ON_KEY]))
+                    continue;
+                const action = row[TRIGGER_ACTION_KEY];
+                if (typeof action !== "string" || action.length === 0)
+                    continue;
+                out.push({ on: row[TRIGGER_ON_KEY], action, paramsMeta: row });
+            }
+            return out;
+        }
+    }
+    if (!isTriggerEvent(meta[TRIGGER_ON_KEY]))
+        return [];
+    const action = meta[TRIGGER_ACTION_KEY];
+    if (typeof action !== "string" || action.length === 0)
+        return [];
+    return [{ on: meta[TRIGGER_ON_KEY], action, paramsMeta: meta }];
+}
+function resolveParams(actionId, paramsMeta) {
+    const definition = actionRegistry.get(actionId);
+    if (definition === undefined)
+        return {};
+    return parseParams(definition.schema, paramsMeta);
+}
+/**
+ * Read every valid `on`/`action` binding off a raw meta bag. Unknown events/actions are dropped;
+ * params are schema-parsed when the action is registered, else empty.
+ * @internal
+ */
+export function readTriggerSpecs(meta) {
+    return specsFromMeta(meta).map((spec) => ({
+        on: spec.on,
+        action: spec.action,
+        params: resolveParams(spec.action, spec.paramsMeta),
+    }));
+}
+/**
+ * Collect every authored trigger on a document's markers and volumes. Pure — no runtime state.
+ * Action params use the live {@link registerTriggerAction} registry when present.
+ *
+ * @capability authored-triggers schema'd on/action vocabulary on volumes and markers with runtime dispatch
+ */
+export function collectAuthoredTriggers(document) {
+    const out = [];
+    for (const marker of document.markers) {
+        const radius = triggerRadiusOf(marker.meta);
+        for (const spec of readTriggerSpecs(marker.meta)) {
+            out.push({
+                sourceId: marker.id,
+                sourceKind: "marker",
+                objectKind: marker.kind,
+                on: spec.on,
+                action: spec.action,
+                params: spec.params,
+                radius,
+            });
+        }
+    }
+    for (const volume of document.volumes) {
+        for (const spec of readTriggerSpecs(volume.meta)) {
+            out.push({
+                sourceId: volume.id,
+                sourceKind: "volume",
+                objectKind: volume.kind,
+                on: spec.on,
+                action: spec.action,
+                params: spec.params,
+                radius: 0,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * True when `point` is inside an editor volume (sphere / cylinder / box). Cylinder height defaults
+ * to diameter when omitted; sphere ignores y for the common ground-plane case only when the volume
+ * radius covers the full vertical span — here y is tested for sphere and box too.
+ */
+export function pointInVolume(volume, point) {
+    const dx = point.x - volume.center.x;
+    const dy = point.y - volume.center.y;
+    const dz = point.z - volume.center.z;
+    if (volume.shape === "box") {
+        const hx = volume.halfExtents?.x ?? 5;
+        const hy = volume.halfExtents?.y ?? 5;
+        const hz = volume.halfExtents?.z ?? 5;
+        return Math.abs(dx) <= hx && Math.abs(dy) <= hy && Math.abs(dz) <= hz;
+    }
+    const radius = volume.radius ?? 5;
+    if (volume.shape === "cylinder") {
+        const height = volume.height ?? radius * 2;
+        if (Math.hypot(dx, dz) > radius)
+            return false;
+        return Math.abs(dy) <= height / 2;
+    }
+    return Math.hypot(dx, dy, dz) <= radius;
+}
+/** True when `point` is within `radius` of a marker's position (sphere for enter/exit/interact). @internal */
+export function pointNearMarker(marker, point, radius) {
+    const dx = point.x - marker.position.x;
+    const dy = point.y - marker.position.y;
+    const dz = point.z - marker.position.z;
+    return Math.hypot(dx, dy, dz) <= radius;
+}
+function membershipKey(sourceId, actorId) {
+    return `${sourceId}\0${actorId}`;
+}
+function actorPoint(actor) {
+    const p = actor.position;
+    if (Array.isArray(p))
+        return { x: p[0], y: p[1], z: p[2] };
+    return p;
+}
+function insideSource(document, trigger, point) {
+    if (trigger.sourceKind === "volume") {
+        const volume = document.volumes.find((entry) => entry.id === trigger.sourceId);
+        return volume !== undefined && pointInVolume(volume, point);
+    }
+    const marker = document.markers.find((entry) => entry.id === trigger.sourceId);
+    return marker !== undefined && pointNearMarker(marker, point, trigger.radius);
+}
+/**
+ * Build a runtime that watches a document's authored triggers against moving actors and dispatches
+ * to per-action handlers (and optional catch-all). Pure membership math; the game supplies actors
+ * each tick from its own player/entity poses.
+ *
+ * @capability authored-triggers schema'd on/action vocabulary on volumes and markers with runtime dispatch
+ */
+export function createAuthoredTriggerRuntime(options) {
+    const document = options.document;
+    const triggers = options.triggers ?? collectAuthoredTriggers(document);
+    let members = new Set();
+    const sourceIds = new Map();
+    for (const trigger of triggers) {
+        const list = sourceIds.get(trigger.sourceId) ?? [];
+        list.push(trigger);
+        sourceIds.set(trigger.sourceId, list);
+    }
+    function emit(events) {
+        for (const event of events) {
+            options.handlers?.[event.action]?.(event);
+            options.onDispatch?.(event);
+        }
+    }
+    return {
+        triggers: () => triggers,
+        reset() {
+            members = new Set();
+        },
+        step(input) {
+            const next = new Set();
+            const insideNow = new Map();
+            for (const actor of input.actors) {
+                const point = actorPoint(actor);
+                for (const [sourceId, sourceTriggers] of sourceIds) {
+                    const probe = sourceTriggers[0];
+                    if (!insideSource(document, probe, point))
+                        continue;
+                    const key = membershipKey(sourceId, actor.id);
+                    next.add(key);
+                    let set = insideNow.get(sourceId);
+                    if (set === undefined) {
+                        set = new Set();
+                        insideNow.set(sourceId, set);
+                    }
+                    set.add(actor.id);
+                }
+            }
+            const events = [];
+            for (const [sourceId, actorsInside] of insideNow) {
+                const sourceTriggers = sourceIds.get(sourceId) ?? [];
+                for (const actorId of actorsInside) {
+                    const key = membershipKey(sourceId, actorId);
+                    const wasInside = members.has(key);
+                    if (!wasInside) {
+                        for (const trigger of sourceTriggers) {
+                            if (trigger.on !== "enter")
+                                continue;
+                            events.push({
+                                on: "enter",
+                                action: trigger.action,
+                                sourceId: trigger.sourceId,
+                                sourceKind: trigger.sourceKind,
+                                objectKind: trigger.objectKind,
+                                actorId,
+                                params: trigger.params,
+                            });
+                        }
+                    }
+                }
+            }
+            for (const key of members) {
+                if (next.has(key))
+                    continue;
+                const sep = key.indexOf("\0");
+                const sourceId = key.slice(0, sep);
+                const actorId = key.slice(sep + 1);
+                for (const trigger of sourceIds.get(sourceId) ?? []) {
+                    if (trigger.on !== "exit")
+                        continue;
+                    events.push({
+                        on: "exit",
+                        action: trigger.action,
+                        sourceId: trigger.sourceId,
+                        sourceKind: trigger.sourceKind,
+                        objectKind: trigger.objectKind,
+                        actorId,
+                        params: trigger.params,
+                    });
+                }
+            }
+            const interactActors = new Set(input.interact ?? []);
+            if (interactActors.size > 0) {
+                for (const actor of input.actors) {
+                    if (!interactActors.has(actor.id))
+                        continue;
+                    const point = actorPoint(actor);
+                    for (const sourceTriggers of sourceIds.values()) {
+                        const probe = sourceTriggers[0];
+                        if (!insideSource(document, probe, point))
+                            continue;
+                        for (const trigger of sourceTriggers) {
+                            if (trigger.on !== "interact")
+                                continue;
+                            events.push({
+                                on: "interact",
+                                action: trigger.action,
+                                sourceId: trigger.sourceId,
+                                sourceKind: trigger.sourceKind,
+                                objectKind: trigger.objectKind,
+                                actorId: actor.id,
+                                params: trigger.params,
+                            });
+                        }
+                    }
+                }
+            }
+            members = next;
+            emit(events);
+            return events;
+        },
+    };
+}
+/**
+ * Build a meta patch that sets a single flat trigger (`on` + `action` + optional param fields) and
+ * clears a multi-trigger list if present. Used by the editor inspector.
+ * @internal
+ */
+export function triggerMetaPatch(on, action, params = {}) {
+    if (on === "" || action.length === 0) {
+        return { [TRIGGER_ON_KEY]: undefined, [TRIGGER_ACTION_KEY]: undefined, [TRIGGER_LIST_KEY]: undefined };
+    }
+    return {
+        [TRIGGER_ON_KEY]: on,
+        [TRIGGER_ACTION_KEY]: action,
+        [TRIGGER_LIST_KEY]: undefined,
+        ...params,
+    };
+}
+/** Read the single flat trigger (`on`/`action`) from meta for the inspector, ignoring non-empty multi-lists. @internal */
+export function readFlatTrigger(meta) {
+    if (meta === undefined)
+        return { on: "", action: "" };
+    const list = meta[TRIGGER_LIST_KEY];
+    if (Array.isArray(list) && list.length > 0)
+        return { on: "", action: "" };
+    const on = isTriggerEvent(meta[TRIGGER_ON_KEY]) ? meta[TRIGGER_ON_KEY] : "";
+    const action = typeof meta[TRIGGER_ACTION_KEY] === "string" ? meta[TRIGGER_ACTION_KEY] : "";
+    return { on, action };
+}

package/dist/scene/behaviorRuntime.d.ts

@@ -0,0 +1,75 @@
+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";
+/**
+ * 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`.
+ */
+export type BehaviorResumePolicy = "freeze" | "advance";
+/** Serializable snapshot of one behavior instance — round-trips exactly through
+ * {@link BehaviorControl.serialize}/{@link BehaviorControl.restore}. */
+export type BehaviorSnapshot = {
+    readonly kind: "patrol";
+    readonly state: PathFollowState;
+} | {
+    readonly kind: "wander";
+    readonly origin: Waypoint;
+    readonly target: Waypoint | null;
+};
+/** Inspection readout for editor/debug tooling, from {@link BehaviorControl.inspect}/{@link BehaviorControl.list}. */
+export interface BehaviorInspection {
+    id: string;
+    kind: "patrol" | "wander";
+    status: BehaviorStatus;
+    reason: string | null;
+}
+/**
+ * Per-entity control surface for the behavior runtime — pause/resume/disable/enable an instance,
+ * seek it to semantic progress, serialize/restore its state, and inspect it, all keyed by stable
+ * entity id without a full-world scan. Obtain it with {@link behaviorControl}.
+ */
+export interface BehaviorControl {
+    /** Current status of the instance, or `null` if the entity has no live behavior. */
+    status(id: string): BehaviorStatus | null;
+    /** Human-readable reason attached to the last pause/disable, or `null`. */
+    reason(id: string): string | null;
+    /** Suspend advancement and pose writes, retaining state. No-op (`false`) if not active. */
+    pause(id: string, reason?: string): boolean;
+    /** Resume a paused instance, applying the catch-up `policy` (default `freeze`). */
+    resume(id: string, policy?: BehaviorResumePolicy): boolean;
+    /** Hold the instance off (no advance, no pose) until {@link enable}. Retains state. */
+    disable(id: string, reason?: string): boolean;
+    /** Re-activate a disabled instance from its retained state (no catch-up). */
+    enable(id: string): boolean;
+    /** Jump a patrol instance to semantic {@link PathProgress}. Returns `false` for non-patrol instances. */
+    seek(id: string, progress: PathProgress): boolean;
+    /** Capture the instance's exact serializable state, or `null` if absent. */
+    serialize(id: string): BehaviorSnapshot | null;
+    /** Restore an instance from a {@link BehaviorSnapshot} of the matching kind. */
+    restore(id: string, snapshot: BehaviorSnapshot): boolean;
+    /** Inspect one instance, or `null` if absent. */
+    inspect(id: string): BehaviorInspection | null;
+    /** Inspect every live instance (bounded by spawned behavior entities). */
+    list(): BehaviorInspection[];
+}
+/**
+ * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} 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
+ */
+export declare function advanceBehaviors(ctx: GameContext, dt: number): void;
+/**
+ * Obtain the per-context {@link BehaviorControl} surface for suspending, resuming, seeking, serializing,
+ * and inspecting behavior instances by entity id — the lifecycle contract games use to hand pose
+ * ownership to possession/streaming/staggering code instead of bypassing the behavior runtime.
+ *
+ * @capability behavior-control pause/disable/resume/seek/inspect behavior instances per entity
+ */
+export declare function behaviorControl(ctx: GameContext): BehaviorControl;

package/dist/scene/behaviorRuntime.js

@@ -0,0 +1,217 @@
+import { seededRng } from "../random/rng.js";
+import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
+import { perContext } from "../runtime/perContext.js";
+const DEFAULT_WANDER_SPEED = 1.5;
+const WANDER_ARRIVAL = 0.6;
+function patrolOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
+}
+function wanderOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "wander") ?? null;
+}
+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 patrol = patrolOf(entity);
+            if (patrol !== null) {
+                const config = { waypoints: patrol.waypoints, speed: patrol.speed, loop: patrol.loop };
+                nav.set(entity.id, {
+                    kind: "patrol",
+                    config,
+                    state: patrol.startProgress !== undefined ? pathFollowSeek(config, patrol.startProgress) : createPathFollow(config),
+                    groundClamp: patrol.groundClamp ?? false,
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+                continue;
+            }
+            const wander = wanderOf(entity);
+            if (wander !== null) {
+                nav.set(entity.id, {
+                    kind: "wander",
+                    radius: wander.radius,
+                    origin: entity.position,
+                    target: null,
+                    roll: seededRng(`wander:${entity.id}`),
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+            }
+        }
+        for (const id of nav.keys())
+            if (!live.has(id))
+                nav.delete(id);
+    };
+    ctx.scene.entity.subscribeMembership(refresh);
+    refresh();
+    return { nav };
+});
+function stepWander(ctx, id, nav, dt) {
+    const entity = ctx.scene.entity.get(id);
+    if (entity === null)
+        return;
+    const [px, , pz] = entity.position;
+    if (nav.target === null || Math.hypot(px - nav.target[0], pz - nav.target[2]) < WANDER_ARRIVAL) {
+        const angle = nav.roll() * Math.PI * 2;
+        const distance = Math.sqrt(nav.roll()) * nav.radius;
+        const tx = nav.origin[0] + Math.cos(angle) * distance;
+        const tz = nav.origin[2] + Math.sin(angle) * distance;
+        nav.target = [tx, ctx.world.groundHeightAt(tx, tz), tz];
+    }
+    const speed = entity.movement.walkSpeed ?? DEFAULT_WANDER_SPEED;
+    const dx = nav.target[0] - px;
+    const dz = nav.target[2] - pz;
+    const dist = Math.hypot(dx, dz);
+    if (dist < 1e-6)
+        return;
+    const step = Math.min(dist, speed * dt);
+    const nx = px + (dx / dist) * step;
+    const nz = pz + (dz / dist) * step;
+    ctx.scene.entity.setPose(id, {
+        position: [nx, ctx.world.groundHeightAt(nx, nz), nz],
+        rotationY: Math.atan2(dx, dz),
+        dt,
+    });
+}
+function posePatrol(ctx, id, nav, dt) {
+    const [x, y, z] = nav.state.position;
+    ctx.scene.entity.setPose(id, {
+        position: nav.groundClamp ? [x, ctx.world.groundHeightAt(x, z), z] : [x, y, z],
+        rotationY: nav.state.heading,
+        dt,
+    });
+}
+/**
+ * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} 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
+ */
+export function advanceBehaviors(ctx, dt) {
+    if (dt <= 0)
+        return;
+    const { nav } = runtimeOf(ctx);
+    if (nav.size === 0)
+        return;
+    for (const [id, entry] of nav) {
+        if (entry.status !== "active") {
+            if (entry.status === "paused")
+                entry.pausedElapsed += dt;
+            continue;
+        }
+        if (entry.kind === "patrol") {
+            entry.state = advancePathFollow(entry.config, entry.state, dt);
+            posePatrol(ctx, id, entry, dt);
+        }
+        else {
+            stepWander(ctx, id, entry, dt);
+        }
+    }
+}
+/**
+ * Obtain the per-context {@link BehaviorControl} surface for suspending, resuming, seeking, serializing,
+ * and inspecting behavior instances by entity id — the lifecycle contract games use to hand pose
+ * ownership to possession/streaming/staggering code instead of bypassing the behavior runtime.
+ *
+ * @capability behavior-control pause/disable/resume/seek/inspect behavior instances per entity
+ */
+export function behaviorControl(ctx) {
+    const { nav } = runtimeOf(ctx);
+    const setStatus = (id, status, reason) => {
+        const entry = nav.get(id);
+        if (entry === undefined)
+            return false;
+        entry.status = status;
+        entry.reason = reason;
+        return true;
+    };
+    return {
+        status: (id) => nav.get(id)?.status ?? null,
+        reason: (id) => nav.get(id)?.reason ?? null,
+        pause: (id, reason) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "active")
+                return false;
+            entry.status = "paused";
+            entry.reason = reason ?? null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        resume: (id, policy = "freeze") => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "paused")
+                return false;
+            if (policy === "advance" && entry.kind === "patrol" && entry.pausedElapsed > 0) {
+                entry.state = advancePathFollow(entry.config, entry.state, entry.pausedElapsed);
+                // Emit a single final pose at the caught-up position (no intermediate writes).
+                posePatrol(ctx, id, entry, entry.pausedElapsed);
+            }
+            entry.status = "active";
+            entry.reason = null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        disable: (id, reason) => setStatus(id, "disabled", reason ?? null),
+        enable: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "disabled")
+                return false;
+            entry.status = "active";
+            entry.reason = null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        seek: (id, progress) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.kind !== "patrol")
+                return false;
+            entry.state = pathFollowSeek(entry.config, progress);
+            return true;
+        },
+        serialize: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined)
+                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] };
+        },
+        restore: (id, snapshot) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.kind !== snapshot.kind)
+                return false;
+            if (entry.kind === "patrol" && snapshot.kind === "patrol") {
+                entry.state = { ...snapshot.state };
+                return true;
+            }
+            if (entry.kind === "wander" && snapshot.kind === "wander") {
+                entry.origin = [...snapshot.origin];
+                entry.target = snapshot.target === null ? null : [...snapshot.target];
+                return true;
+            }
+            return false;
+        },
+        inspect: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined)
+                return null;
+            return { id, kind: entry.kind, status: entry.status, reason: entry.reason };
+        },
+        list: () => {
+            const out = [];
+            for (const [id, entry] of nav)
+                out.push({ id, kind: entry.kind, status: entry.status, reason: entry.reason });
+            return out;
+        },
+    };
+}

package/dist/scene/behaviors.d.ts

@@ -1,5 +1,5 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
-import type { Waypoint } from "../nav/pathFollow.js";
+import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -9,6 +9,16 @@ export interface PatrolBehavior {
     waypoints: readonly Waypoint[];
     speed: number;
     loop: boolean;
+    /**
+     * Optional initial progress the follower is seeded at instead of waypoint zero — lets a fleet of
+     * route followers start at distributed phases. Round-trips through the behavior lifecycle seek/serialize.
+     */
+    startProgress?: PathProgress;
+    /**
+     * Sample world ground height for the pose Y each tick, so a route authored in the XZ plane rides
+     * uneven terrain. Default false (waypoint Y is used verbatim).
+     */
+    groundClamp?: boolean;
 }
 export interface PromptableBehavior {
     kind: "promptable";
@@ -21,10 +31,12 @@ export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBeh
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;
-export declare function patrol({ waypoints, speed, loop, }: {
+export declare function patrol({ waypoints, speed, loop, startProgress, groundClamp, }: {
     waypoints: readonly Waypoint[];
     speed: number;
     loop?: boolean;
+    startProgress?: PathProgress;
+    groundClamp?: boolean;
 }): PatrolBehavior;
 export declare function promptable(prompt: ProximityPrompt): PromptableBehavior;
 export declare function talkable(dialogueId: string): PromptableBehavior;

package/dist/scene/behaviors.js

@@ -2,8 +2,13 @@ import { command, keybind, proximityPrompt, } from "../interaction/proximityProm
 export function wander({ radius }) {
     return { kind: "wander", radius };
 }
-export function patrol({ waypoints, speed, loop = true, }) {
-    return { kind: "patrol", waypoints, speed, loop };
+export function patrol({ waypoints, speed, loop = true, startProgress, groundClamp, }) {
+    const behavior = { kind: "patrol", waypoints, speed, loop };
+    if (startProgress !== undefined)
+        behavior.startProgress = startProgress;
+    if (groundClamp !== undefined)
+        behavior.groundClamp = groundClamp;
+    return behavior;
 }
 export function promptable(prompt) {
     return { kind: "promptable", prompt };