@jgengine/core 0.27.0 → 0.28.0

package/dist/mission/triggers.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Missions driven from authored scene markers. A designer places a marker (or volume) in the editor
+ * and sets one of the registered mission actions in the inspector — `mission_start`,
+ * `mission_objective` or `mission_fail` — and the runtime starts, advances or fails the mission when
+ * an actor trips it. Nothing about the marker is mission-specific code; it is the shared authored
+ * trigger vocabulary, plus the marker positions a positional objective reads.
+ */
+import { type AuthoredTrigger, type TriggerActionDefinition, type TriggerDispatchEvent } from "../scene/authoredTriggers.js";
+import type { SceneDocumentLike, ScenePoint3 } from "../world/sceneShapes.js";
+import type { MissionRuntime } from "./mission.js";
+/**
+ * Marker positions from an authored scene, keyed by marker id — what a positional objective reads.
+ *
+ * @capability mission-triggers read authored scene marker positions for positional objectives
+ */
+export declare function missionMarkers(document: SceneDocumentLike): Record<string, ScenePoint3>;
+/**
+ * The mission actions a game registers so the editor inspector can assign them to a marker or volume.
+ * Params land flat on the object's `meta` beside `on`/`action`, like any authored trigger.
+ *
+ * @capability mission-triggers start, advance and fail a mission from authored scene markers
+ */
+export declare const MISSION_TRIGGER_ACTIONS: readonly TriggerActionDefinition[];
+/**
+ * Register {@link MISSION_TRIGGER_ACTIONS} so the editor lists them. Idempotent; call at module load
+ * next to the game's catalogs.
+ *
+ * @capability mission-triggers start, advance and fail a mission from authored scene markers
+ */
+export declare function registerMissionTriggerActions(): void;
+/** Watches a document's authored mission triggers against moving actors. */
+export interface MissionTriggerBridge {
+    /** Advance one tick; fires the mission actions the actors tripped. */
+    step(input: {
+        actors: readonly {
+            id: string;
+            position: readonly [number, number, number] | {
+                x: number;
+                y: number;
+                z: number;
+            };
+        }[];
+        interact?: readonly string[];
+    }): readonly TriggerDispatchEvent[];
+    /** The mission triggers this bridge was built from. */
+    triggers(): readonly AuthoredTrigger[];
+    /** Drop membership so the next step re-fires enters for still-inside actors. */
+    reset(): void;
+}
+/**
+ * Wire authored markers to a {@link MissionRuntime}: an actor entering a `mission_start` marker starts
+ * the named mission, `mission_objective` completes the named objective, and `mission_fail` lands the
+ * named fail state. Pure membership math over the document, exactly like any other authored trigger.
+ *
+ * @capability mission-triggers start, advance and fail a mission from authored scene markers
+ */
+export declare function createMissionTriggerBridge(options: {
+    runtime: MissionRuntime;
+    document: SceneDocumentLike;
+    triggers?: readonly AuthoredTrigger[];
+}): MissionTriggerBridge;

package/dist/mission/triggers.js

@@ -0,0 +1,108 @@
+/**
+ * Missions driven from authored scene markers. A designer places a marker (or volume) in the editor
+ * and sets one of the registered mission actions in the inspector — `mission_start`,
+ * `mission_objective` or `mission_fail` — and the runtime starts, advances or fails the mission when
+ * an actor trips it. Nothing about the marker is mission-specific code; it is the shared authored
+ * trigger vocabulary, plus the marker positions a positional objective reads.
+ */
+import { createAuthoredTriggerRuntime, registerTriggerAction, } from "../scene/authoredTriggers.js";
+/**
+ * Marker positions from an authored scene, keyed by marker id — what a positional objective reads.
+ *
+ * @capability mission-triggers read authored scene marker positions for positional objectives
+ */
+export function missionMarkers(document) {
+    const out = {};
+    for (const marker of document.markers) {
+        out[marker.id] = { x: marker.position.x, y: marker.position.y, z: marker.position.z };
+    }
+    return out;
+}
+/**
+ * The mission actions a game registers so the editor inspector can assign them to a marker or volume.
+ * Params land flat on the object's `meta` beside `on`/`action`, like any authored trigger.
+ *
+ * @capability mission-triggers start, advance and fail a mission from authored scene markers
+ */
+export const MISSION_TRIGGER_ACTIONS = [
+    {
+        id: "mission_start",
+        label: "Start mission",
+        schema: { fields: [{ type: "text", key: "mission", label: "Mission", default: "" }] },
+        events: ["enter"],
+    },
+    {
+        id: "mission_objective",
+        label: "Complete mission objective",
+        schema: {
+            fields: [
+                { type: "text", key: "mission", label: "Mission", default: "" },
+                { type: "text", key: "objective", label: "Objective", default: "" },
+            ],
+        },
+        events: ["enter", "interact"],
+    },
+    {
+        id: "mission_fail",
+        label: "Fail mission",
+        schema: {
+            fields: [
+                { type: "text", key: "mission", label: "Mission", default: "" },
+                { type: "text", key: "state", label: "Fail state", default: "" },
+            ],
+        },
+        events: ["enter", "interact"],
+    },
+];
+/**
+ * Register {@link MISSION_TRIGGER_ACTIONS} so the editor lists them. Idempotent; call at module load
+ * next to the game's catalogs.
+ *
+ * @capability mission-triggers start, advance and fail a mission from authored scene markers
+ */
+export function registerMissionTriggerActions() {
+    for (const action of MISSION_TRIGGER_ACTIONS)
+        registerTriggerAction(action);
+}
+function textParam(event, key) {
+    const value = event.params[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Wire authored markers to a {@link MissionRuntime}: an actor entering a `mission_start` marker starts
+ * the named mission, `mission_objective` completes the named objective, and `mission_fail` lands the
+ * named fail state. Pure membership math over the document, exactly like any other authored trigger.
+ *
+ * @capability mission-triggers start, advance and fail a mission from authored scene markers
+ */
+export function createMissionTriggerBridge(options) {
+    const handlers = {
+        mission_start: (event) => {
+            const mission = textParam(event, "mission");
+            if (mission !== undefined)
+                options.runtime.start(mission);
+        },
+        mission_objective: (event) => {
+            const mission = textParam(event, "mission");
+            const objective = textParam(event, "objective");
+            if (mission !== undefined && objective !== undefined)
+                options.runtime.signal(mission, objective);
+        },
+        mission_fail: (event) => {
+            const mission = textParam(event, "mission");
+            const state = textParam(event, "state");
+            if (mission !== undefined && state !== undefined)
+                options.runtime.fail(mission, state);
+        },
+    };
+    const runtime = createAuthoredTriggerRuntime({
+        document: options.document,
+        handlers,
+        triggers: options.triggers,
+    });
+    return {
+        step: (input) => runtime.step(input),
+        triggers: () => runtime.triggers(),
+        reset: () => runtime.reset(),
+    };
+}

package/dist/nav/traffic.d.ts

@@ -151,7 +151,6 @@ export interface TrafficSnapshot {
         ticks: number;
         maxStillSeconds: number;
         maxDeadlockSeconds: number;
-        slowestTickMs: number;
     };
 }
 /** Everything {@link createTraffic} needs: the graph, the injected generator and the caller's policies. */

package/dist/nav/traffic.js

@@ -861,7 +861,6 @@ export function createTraffic(options) {
                     ticks,
                     maxStillSeconds,
                     maxDeadlockSeconds,
-                    slowestTickMs,
                 },
             };
         },
@@ -883,7 +882,7 @@ export function createTraffic(options) {
             ticks = next.counters.ticks;
             maxStillSeconds = next.counters.maxStillSeconds;
             maxDeadlockSeconds = next.counters.maxDeadlockSeconds;
-            slowestTickMs = next.counters.slowestTickMs;
+            slowestTickMs = 0;
             for (const saved of next.cars) {
                 const car = {
                     ...saved,

package/dist/runtime/context/combat.js

@@ -59,6 +59,17 @@ export function createCombatSubsystem(d) {
             const userId = userIdOf(instanceId);
             return { catalogId: entity.name, name: entity.name, ...(userId === undefined ? {} : { userId }) };
         },
+        onDamage(application) {
+            events.emit("combat.damage", {
+                target: application.target,
+                source: application.source,
+                type: application.effect,
+                amount: application.dealt,
+                absorbed: Math.max(0, application.incoming - application.dealt),
+                remaining: application.remaining,
+                lethal: application.lethal,
+            });
+        },
         onLethal(instanceId, lethalCtx) {
             // Capture identity + onDeath *before* resolveDeath despawns the entity.
             const dyingEntity = entities.get(instanceId);

package/dist/settings/accessibilitySettings.d.ts

@@ -0,0 +1,81 @@
+import type { AccessibilityState, ColorblindMode } from "../ui/accessibility.js";
+import type { GameSettingDef, SettingOption, SettingValue, SettingsStore } from "./settingsModel.js";
+/**
+ * A "hold or toggle" preference for actions that can be either (aim, sprint, crouch, block). Shared
+ * because players expect one setting to cover them all, rather than each game inventing a flag.
+ */
+export type HoldVsToggle = "hold" | "toggle";
+/** The persisted settings ids behind the accessibility section. */
+export declare const ACCESSIBILITY_SETTING_IDS: {
+    readonly textScale: "accessibility.textScale";
+    readonly colorblind: "accessibility.colorblind";
+    readonly reducedMotion: "accessibility.reducedMotion";
+    readonly highContrast: "accessibility.highContrast";
+    readonly captions: "accessibility.captions";
+    readonly holdVsToggle: "controls.holdVsToggle";
+};
+/** Text-scale choices, as numeric strings the settings store persists. */
+export declare const TEXT_SCALE_OPTIONS: readonly SettingOption[];
+/** Colorblind palette choices. `none` keeps the game's own colours. */
+export declare const COLORBLIND_OPTIONS: readonly SettingOption[];
+/** Hold-versus-toggle choices for actions that support both. */
+export declare const HOLD_VS_TOGGLE_OPTIONS: readonly SettingOption[];
+/** Read a stored text scale, clamped to the supported range. */
+export declare function readTextScale(store: SettingsStore): number;
+/** Read a stored colorblind mode, falling back to `none` for an unknown value. */
+export declare function readColorblind(store: SettingsStore): ColorblindMode;
+/** Read the hold-or-toggle preference, falling back to `hold`. */
+export declare function readHoldVsToggle(store: SettingsStore): HoldVsToggle;
+/**
+ * Read the whole accessibility state the presentation needs (reduced motion, high contrast, text
+ * scale, colorblind mode, captions) plus the hold/toggle preference, from the shared settings store.
+ *
+ * @capability accessibility-settings read accessibility preferences and the hold-vs-toggle choice from the shared settings store
+ */
+export declare function readAccessibilitySettings(store: SettingsStore): {
+    state: AccessibilityState;
+    holdVsToggle: HoldVsToggle;
+};
+/** One accessibility setting as the shared settings menu renders it. */
+export interface AccessibilitySettingRow {
+    id: string;
+    label: string;
+    kind: "slider" | "toggle" | "select";
+    value: SettingValue;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly SettingOption[];
+    format?: (value: number) => string;
+    set: (value: SettingValue) => void;
+    /** When this row drives presentation, the accessibility state key it maps to. */
+    affects?: keyof AccessibilityState;
+}
+/**
+ * The accessibility rows, wired to the settings store: text scale, colorblind palette, reduced
+ * motion, high contrast, captions and hold-vs-toggle. The shell adds them as its `accessibility`
+ * category and any game can render them inside its own settings layout.
+ *
+ * @capability accessibility-settings-rows accessibility setting rows (text scale, colorblind, reduced motion, high contrast, captions, hold-vs-toggle) backed by the shared settings store
+ */
+export declare function accessibilitySettingRows(store: SettingsStore): AccessibilitySettingRow[];
+/**
+ * Declarative form of the accessibility rows for `defineGame({ settings })`, for a game that wants
+ * them inside its own setting categories rather than the built-in `accessibility` one.
+ */
+export declare function accessibilitySettingDefs(category?: string): GameSettingDef[];
+/** One frame of an action's raw input. */
+export interface HoldToggleInput {
+    /** The action's key/button went down this frame (the edge). */
+    pressed: boolean;
+    /** The action's key/button is down. */
+    held: boolean;
+}
+/**
+ * The action's active state for one frame under a {@link HoldVsToggle} preference: `hold` follows the
+ * button, `toggle` latches on each press edge. Call with the previous result so toggle mode can flip
+ * without the caller keeping a second flag.
+ *
+ * @capability hold-vs-toggle resolve one action frame under a hold-or-toggle preference
+ */
+export declare function holdToggleActive(previous: boolean, input: HoldToggleInput, mode: HoldVsToggle): boolean;

package/dist/settings/accessibilitySettings.js

@@ -0,0 +1,152 @@
+import { DEFAULT_ACCESSIBILITY, clampTextScale } from "../ui/accessibility.js";
+/** The persisted settings ids behind the accessibility section. */
+export const ACCESSIBILITY_SETTING_IDS = {
+    textScale: "accessibility.textScale",
+    colorblind: "accessibility.colorblind",
+    reducedMotion: "accessibility.reducedMotion",
+    highContrast: "accessibility.highContrast",
+    captions: "accessibility.captions",
+    holdVsToggle: "controls.holdVsToggle",
+};
+/** Text-scale choices, as numeric strings the settings store persists. */
+export const TEXT_SCALE_OPTIONS = [
+    { value: "1", label: "100%" },
+    { value: "1.15", label: "115%" },
+    { value: "1.3", label: "130%" },
+    { value: "1.5", label: "150%" },
+    { value: "1.75", label: "175%" },
+    { value: "2", label: "200%" },
+];
+/** Colorblind palette choices. `none` keeps the game's own colours. */
+export const COLORBLIND_OPTIONS = [
+    { value: "none", label: "Off" },
+    { value: "protanopia", label: "Protanopia" },
+    { value: "deuteranopia", label: "Deuteranopia" },
+    { value: "tritanopia", label: "Tritanopia" },
+    { value: "grayscale", label: "Grayscale" },
+];
+/** Hold-versus-toggle choices for actions that support both. */
+export const HOLD_VS_TOGGLE_OPTIONS = [
+    { value: "hold", label: "Hold" },
+    { value: "toggle", label: "Toggle" },
+];
+/** Read a stored text scale, clamped to the supported range. */
+export function readTextScale(store) {
+    return clampTextScale(Number(store.get(ACCESSIBILITY_SETTING_IDS.textScale, 1)));
+}
+/** Read a stored colorblind mode, falling back to `none` for an unknown value. */
+export function readColorblind(store) {
+    const value = String(store.get(ACCESSIBILITY_SETTING_IDS.colorblind, "none"));
+    const known = COLORBLIND_OPTIONS.some((option) => option.value === value);
+    return known ? value : "none";
+}
+/** Read the hold-or-toggle preference, falling back to `hold`. */
+export function readHoldVsToggle(store) {
+    const value = String(store.get(ACCESSIBILITY_SETTING_IDS.holdVsToggle, "hold"));
+    return value === "toggle" ? "toggle" : "hold";
+}
+/**
+ * Read the whole accessibility state the presentation needs (reduced motion, high contrast, text
+ * scale, colorblind mode, captions) plus the hold/toggle preference, from the shared settings store.
+ *
+ * @capability accessibility-settings read accessibility preferences and the hold-vs-toggle choice from the shared settings store
+ */
+export function readAccessibilitySettings(store) {
+    return {
+        state: {
+            reducedMotion: Boolean(store.get(ACCESSIBILITY_SETTING_IDS.reducedMotion, DEFAULT_ACCESSIBILITY.reducedMotion)),
+            highContrast: Boolean(store.get(ACCESSIBILITY_SETTING_IDS.highContrast, DEFAULT_ACCESSIBILITY.highContrast)),
+            textScale: readTextScale(store),
+            colorblind: readColorblind(store),
+            captions: Boolean(store.get(ACCESSIBILITY_SETTING_IDS.captions, DEFAULT_ACCESSIBILITY.captions)),
+        },
+        holdVsToggle: readHoldVsToggle(store),
+    };
+}
+/**
+ * The accessibility rows, wired to the settings store: text scale, colorblind palette, reduced
+ * motion, high contrast, captions and hold-vs-toggle. The shell adds them as its `accessibility`
+ * category and any game can render them inside its own settings layout.
+ *
+ * @capability accessibility-settings-rows accessibility setting rows (text scale, colorblind, reduced motion, high contrast, captions, hold-vs-toggle) backed by the shared settings store
+ */
+export function accessibilitySettingRows(store) {
+    return [
+        {
+            id: ACCESSIBILITY_SETTING_IDS.textScale,
+            label: "Text size",
+            kind: "select",
+            value: String(readTextScale(store)),
+            options: TEXT_SCALE_OPTIONS,
+            set: (value) => store.set(ACCESSIBILITY_SETTING_IDS.textScale, Number(value)),
+            affects: "textScale",
+        },
+        {
+            id: ACCESSIBILITY_SETTING_IDS.colorblind,
+            label: "Colourblind palette",
+            kind: "select",
+            value: readColorblind(store),
+            options: COLORBLIND_OPTIONS,
+            set: (value) => store.set(ACCESSIBILITY_SETTING_IDS.colorblind, String(value)),
+            affects: "colorblind",
+        },
+        {
+            id: ACCESSIBILITY_SETTING_IDS.reducedMotion,
+            label: "Reduce motion",
+            kind: "toggle",
+            value: Boolean(store.get(ACCESSIBILITY_SETTING_IDS.reducedMotion, DEFAULT_ACCESSIBILITY.reducedMotion)),
+            set: (value) => store.set(ACCESSIBILITY_SETTING_IDS.reducedMotion, Boolean(value)),
+            affects: "reducedMotion",
+        },
+        {
+            id: ACCESSIBILITY_SETTING_IDS.highContrast,
+            label: "High contrast",
+            kind: "toggle",
+            value: Boolean(store.get(ACCESSIBILITY_SETTING_IDS.highContrast, DEFAULT_ACCESSIBILITY.highContrast)),
+            set: (value) => store.set(ACCESSIBILITY_SETTING_IDS.highContrast, Boolean(value)),
+            affects: "highContrast",
+        },
+        {
+            id: ACCESSIBILITY_SETTING_IDS.captions,
+            label: "Captions",
+            kind: "toggle",
+            value: Boolean(store.get(ACCESSIBILITY_SETTING_IDS.captions, DEFAULT_ACCESSIBILITY.captions)),
+            set: (value) => store.set(ACCESSIBILITY_SETTING_IDS.captions, Boolean(value)),
+            affects: "captions",
+        },
+        {
+            id: ACCESSIBILITY_SETTING_IDS.holdVsToggle,
+            label: "Hold or toggle aim",
+            kind: "select",
+            value: readHoldVsToggle(store),
+            options: HOLD_VS_TOGGLE_OPTIONS,
+            set: (value) => store.set(ACCESSIBILITY_SETTING_IDS.holdVsToggle, String(value)),
+        },
+    ];
+}
+/**
+ * Declarative form of the accessibility rows for `defineGame({ settings })`, for a game that wants
+ * them inside its own setting categories rather than the built-in `accessibility` one.
+ */
+export function accessibilitySettingDefs(category = "accessibility") {
+    return [
+        { id: ACCESSIBILITY_SETTING_IDS.textScale, label: "Text size", category, kind: "select", default: "1", options: TEXT_SCALE_OPTIONS },
+        { id: ACCESSIBILITY_SETTING_IDS.colorblind, label: "Colourblind palette", category, kind: "select", default: "none", options: COLORBLIND_OPTIONS },
+        { id: ACCESSIBILITY_SETTING_IDS.reducedMotion, label: "Reduce motion", category, kind: "toggle", default: false },
+        { id: ACCESSIBILITY_SETTING_IDS.highContrast, label: "High contrast", category, kind: "toggle", default: false },
+        { id: ACCESSIBILITY_SETTING_IDS.captions, label: "Captions", category, kind: "toggle", default: false },
+        { id: ACCESSIBILITY_SETTING_IDS.holdVsToggle, label: "Hold or toggle aim", category: "controls", kind: "select", default: "hold", options: HOLD_VS_TOGGLE_OPTIONS },
+    ];
+}
+/**
+ * The action's active state for one frame under a {@link HoldVsToggle} preference: `hold` follows the
+ * button, `toggle` latches on each press edge. Call with the previous result so toggle mode can flip
+ * without the caller keeping a second flag.
+ *
+ * @capability hold-vs-toggle resolve one action frame under a hold-or-toggle preference
+ */
+export function holdToggleActive(previous, input, mode) {
+    if (mode === "hold")
+        return input.held;
+    return input.pressed ? !previous : previous;
+}

package/dist/settings/graphicsProfile.d.ts

@@ -10,7 +10,10 @@ export interface GraphicsProfile {
     shadowMapSize: 512 | 1024 | 2048 | 4096;
     cascades: 1 | 2 | 3 | 4;
     drawDistance: number;
+    /** Largest pool one particle effect may allocate. */
     particleCap: number;
+    /** Live particles the whole scene may hold across every effect; the VFX library drops lowest-priority effects past it. */
+    particleBudget: number;
     /** Anisotropic texture filtering samples; clamped to the GPU maximum. 1 is plain trilinear. */
     anisotropy: 1 | 2 | 4 | 8 | 16;
     postStages: {

package/dist/settings/graphicsProfile.js

@@ -6,6 +6,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         cascades: 1,
         drawDistance: 120,
         particleCap: 128,
+        particleBudget: 1024,
         anisotropy: 2,
         postStages: { ao: false, bloom: true, dof: false, smaa: true },
         surfaceDetail: "lite",
@@ -16,6 +17,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         cascades: 2,
         drawDistance: 240,
         particleCap: 256,
+        particleBudget: 2048,
         anisotropy: 4,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
         surfaceDetail: "full",
@@ -26,6 +28,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         cascades: 4,
         drawDistance: 400,
         particleCap: 512,
+        particleBudget: 4096,
         anisotropy: 8,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
         surfaceDetail: "full",
@@ -36,6 +39,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         cascades: 4,
         drawDistance: 800,
         particleCap: 1024,
+        particleBudget: 8192,
         anisotropy: 16,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
         surfaceDetail: "full",

package/dist/settings/settingsModel.d.ts

@@ -1,7 +1,7 @@
 import type { GameContext } from "../runtime/gameContext.js";
 export type SettingValue = number | boolean | string;
 export type SettingKind = "slider" | "toggle" | "select";
-export type BuiltInSettingCategory = "sound" | "graphics" | "gameplay" | "controls";
+export type BuiltInSettingCategory = "sound" | "graphics" | "gameplay" | "controls" | "accessibility";
 /** Built-in category ids keep autocomplete; any other string makes a fresh category. */
 export type SettingCategory = BuiltInSettingCategory | (string & {});
 export declare const BUILT_IN_SETTING_CATEGORIES: readonly BuiltInSettingCategory[];

package/dist/settings/settingsModel.js

@@ -3,6 +3,7 @@ export const BUILT_IN_SETTING_CATEGORIES = [
     "sound",
     "graphics",
     "gameplay",
+    "accessibility",
     "controls",
 ];
 export const SETTINGS_STORAGE_PREFIX = "jgengine:setting:";

package/dist/sim/nearAgents.d.ts

@@ -1,5 +1,5 @@
 import type { Vec3 } from "../world/geometry.js";
-import { type NavCrowd, type NavCrowdOptions } from "../nav/navCrowd.js";
+import { type NavCrowd, type NavCrowdOptions, type NavCrowdSnapshot } from "../nav/navCrowd.js";
 import type { NavRuntime } from "../nav/navRuntime.js";
 import { type UtilityBrainSnapshot, type UtilityCandidate, type UtilityInterrupt, type UtilityOption } from "../ai/utilityBrain.js";
 import { type NeedDefinition, type NeedSnapshot } from "./needs.js";
@@ -51,11 +51,18 @@ export interface NearCrowdAgents extends NearAgents {
     decisions(): number;
     view(id: string): NearAgentView | null;
     crowd(): NavCrowd;
+    /**
+     * Serializable state: each agent's needs and held pick, plus the crowd's own routes. The crowd is
+     * part of the snapshot because a restored agent must resume the route it was walking, not re-plan a
+     * fresh one from wherever it stood.
+     */
     snapshot(): {
         agents: NearAgentSnapshot[];
+        crowd: NavCrowdSnapshot;
     };
     restore(next: {
         agents: readonly NearAgentSnapshot[];
+        crowd: NavCrowdSnapshot;
     }): void;
 }
 /**

package/dist/sim/nearAgents.js

@@ -33,16 +33,19 @@ export function createNearAgents(options) {
             needs: agent.needs.snapshot(),
         };
     }
+    function makeBrain(forNeeds) {
+        return createUtilityBrain({
+            needs: forNeeds,
+            options: options.options ?? [],
+            ...(options.interrupts === undefined ? {} : { interrupts: options.interrupts }),
+        });
+    }
     function mount(next, saved) {
         if (agents.has(next.id))
             return;
         const needs = createNeedSet(defs);
         needs.restore(saved === undefined ? { values: { ...next.needs }, rates: {}, modifiers: {} } : saved.needs);
-        const brain = createUtilityBrain({
-            needs,
-            options: options.options ?? [],
-            ...(options.interrupts === undefined ? {} : { interrupts: options.interrupts }),
-        });
+        const brain = makeBrain(needs);
         if (saved !== undefined)
             brain.restore(saved.brain);
         const goal = saved?.goal ?? next.goal;
@@ -120,25 +123,39 @@ export function createNearAgents(options) {
                     brain: agent.brain.snapshot(),
                 });
             }
-            return { agents: out };
+            return { agents: out, crowd: crowd.snapshot() };
         },
         restore(next) {
-            for (const id of [...agents.keys()]) {
-                crowd.remove(id);
-                agents.get(id)?.brain.dispose();
-                agents.delete(id);
-            }
+            for (const agent of agents.values())
+                agent.brain.dispose();
+            agents.clear();
+            // The crowd's own snapshot carries each agent's route, so a restored agent walks the corridor it
+            // was on rather than a fresh plan from its current spot.
+            crowd.restore(next.crowd);
             for (const saved of next.agents) {
-                mount({
+                const needs = createNeedSet(defs);
+                needs.restore(saved.needs);
+                const brain = makeBrain(needs);
+                brain.restore(saved.brain);
+                agents.set(saved.id, {
                     id: saved.id,
-                    position: saved.position,
+                    needs,
+                    brain,
+                    goal: saved.goal,
                     place: saved.place,
                     activity: saved.activity,
-                    needs: saved.needs.values,
-                    goal: saved.goal,
-                    stop: 0,
                     travelling: saved.travelling,
-                }, saved);
+                    spawned: {
+                        id: saved.id,
+                        position: saved.position,
+                        place: saved.place,
+                        activity: saved.activity,
+                        needs: saved.needs.values,
+                        goal: saved.goal,
+                        stop: 0,
+                        travelling: saved.travelling,
+                    },
+                });
             }
         },
         dispose() {

package/dist/sim/offScreen.d.ts

@@ -119,7 +119,8 @@ export interface OffScreenSnapshot {
         travelling: boolean;
         pinned: boolean;
         updatedAt: number;
-        staleAt: number;
+        /** Next cheap-state refresh; `null` for a resident that never goes stale (no routine). */
+        staleAt: number | null;
         needs: Record<string, number>;
     }[];
 }

package/dist/sim/offScreen.js

@@ -89,7 +89,18 @@ export function createOffScreenWorld(options) {
                     }
                 }
             }
-            resident.staleAt = resident.routine.nextChangeAfter(resident.updatedAt);
+            const next = resident.routine.nextChangeAfter(resident.updatedAt);
+            if (next > resident.updatedAt) {
+                resident.staleAt = next;
+            }
+            else {
+                // A schedule that cannot name a later change must not spin this catch-up loop; hold the
+                // phase, decay to `now` and try once more a cycle later.
+                resident.needs = decayMeters(resident.needs, defs, now - resident.updatedAt);
+                resident.updatedAt = now;
+                resident.staleAt = now + resident.routine.cycleSeconds;
+                break;
+            }
         }
     }
     /** Keep a near resident's routine phase current and walk it to the next place when the clock moves it. */
@@ -380,7 +391,7 @@ export function createOffScreenWorld(options) {
                     travelling: resident.travelling,
                     pinned: resident.pinned,
                     updatedAt: resident.updatedAt,
-                    staleAt: resident.staleAt,
+                    staleAt: Number.isFinite(resident.staleAt) ? resident.staleAt : null,
                     needs: { ...(live ?? resident.needs) },
                 };
             });
@@ -418,7 +429,7 @@ export function createOffScreenWorld(options) {
                     travelling: saved.travelling,
                     pinned: saved.pinned,
                     updatedAt: saved.updatedAt,
-                    staleAt: saved.staleAt,
+                    staleAt: saved.staleAt === null ? Infinity : saved.staleAt,
                     needs: { ...saved.needs },
                     distance: Infinity,
                 };