@jgengine/core 0.26.0 → 0.28.0

package/dist/scene/builtinSceneKinds.js

@@ -13,6 +13,7 @@ import { registerWaterKind } from "../world/waterKind.js";
 import { registerGrassKind } from "../world/grassKind.js";
 import { registerSoilKind } from "../world/soilKind.js";
 import { registerPoleLineKind } from "../world/poleLineKind.js";
+import { registerDecalKind } from "../world/decalKind.js";
 import { registerBuildingGenerator } from "../world/buildingGenerator.js";
 import { registerCityKind } from "../world/cityKind.js";
 import { describeScatterCoverage, densityCoverage } from "../world/scatterCoverage.js";
@@ -80,5 +81,6 @@ export function registerBuiltinSceneKinds() {
     registerSoilKind();
     registerCityKind();
     registerPoleLineKind();
+    registerDecalKind();
     registerBuildingGenerator();
 }

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,
                 };

package/dist/sim/population.d.ts

@@ -0,0 +1,147 @@
+import type { Vec3 } from "../world/geometry.js";
+/** One visitor on site: the id its body, its needs and its money are keyed by. */
+export interface Visitor {
+    readonly id: string;
+    /** Game-second it arrived; a restored visitor keeps the original. */
+    readonly admittedAt: number;
+}
+/** What a flow policy reads to decide how many arrive and when one has had enough. */
+export interface VisitorFlow {
+    /** Visitors on site this tick — the member count, never a tally kept beside it. */
+    readonly onSite: number;
+    /** Most visitors the gates hold this tick, after resolving {@link VisitorPolicy.capacity}. */
+    readonly capacity: number;
+    /** Arrivals since {@link VisitorPopulation.rollDay}. */
+    readonly arrivalsToday: number;
+    readonly departuresToday: number;
+    readonly now: number;
+}
+/** The game's world behind every counted visitor: it creates and removes the body. */
+export interface VisitorWorld {
+    /**
+     * Create one visitor's body and its game-side record, and return where the body now stands.
+     * `null` means the world refused it — no room, no walkable spot — and a refused body is never
+     * counted as on site or as an arrival.
+     */
+    readonly admit: (visitor: Visitor) => Vec3 | null;
+    /** Remove one visitor's body and record. Called for every departure, refusal and reset. */
+    readonly release: (visitor: Visitor) => void;
+    /**
+     * True when the world currently holds a body for this id. `adopt` and `restore` refuse an id the
+     * world does not hold, so the count can never name a body that is not on the ground.
+     */
+    readonly has: (id: string) => boolean;
+}
+/** The game's flow policy: what draws visitors in, how many fit, and when one has had enough. */
+export interface VisitorPolicy {
+    /** Most visitors on site at once; a function lets the cap follow a rating, a level or a build. */
+    readonly capacity: number | ((now: number) => number);
+    /** Visitors arriving per second at this instant; `0` with the gates shut. */
+    readonly arrivalRate: (flow: VisitorFlow) => number;
+    /** True when this visitor should leave now. Omit for a population that only leaves when told. */
+    readonly shouldLeave?: (visitor: Visitor, flow: VisitorFlow) => boolean;
+}
+/** Flow policy fields a scenario can change in play. */
+export interface VisitorPolicyPatch {
+    readonly capacity?: number | ((now: number) => number);
+    readonly arrivalRate?: (flow: VisitorFlow) => number;
+    /** `null` removes the leaving rule, so visitors stay until {@link VisitorPopulation.leave}. */
+    readonly shouldLeave?: ((visitor: Visitor, flow: VisitorFlow) => boolean) | null;
+    readonly arrivalBudget?: number;
+    /** `null` counts every admitted body as on site. */
+    readonly inside?: ((position: Vec3) => boolean) | null;
+}
+/** Counters a HUD, a probe or a test reads. The on-site figure is the visitor list's length. */
+export interface VisitorPopulationStats {
+    onSite: number;
+    capacity: number;
+    arrivalsToday: number;
+    departuresToday: number;
+    /** Highest on-site count since the last {@link VisitorPopulation.rollDay}. */
+    peakToday: number;
+    /** Bodies the world or the bounds check refused. Never counted as arrivals. */
+    refused: number;
+    /** Arrival credit not yet spent. */
+    pending: number;
+}
+/** How a body the game made itself joins the population. */
+export interface VisitorAdoption {
+    /** Game-second it arrived; defaults to the current tick's clock. */
+    readonly admittedAt?: number;
+    /** True for a body that is a new arrival today; false for one a save or a seed restored. */
+    readonly arrival?: boolean;
+}
+/** Serializable state. No on-site count is stored: it is the restored visitor list. */
+export interface VisitorPopulationSnapshot {
+    visitors: {
+        id: string;
+        admittedAt: number;
+    }[];
+    arrivalsToday: number;
+    departuresToday: number;
+    peakToday: number;
+    pending: number;
+    /** Next id suffix, so a restored save does not reuse an id. */
+    sequence: number;
+}
+/** Options for {@link createVisitorPopulation}. */
+export interface VisitorPopulationOptions {
+    readonly world: VisitorWorld;
+    readonly policy: VisitorPolicy;
+    /** First half of every generated id. Default `"visitor#"`. */
+    readonly idPrefix?: string;
+    /** First suffix used after `idPrefix`. Default 1. */
+    readonly sequenceStart?: number;
+    /** Most bodies one tick may admit, so a long frame cannot flood the park. Default 4. */
+    readonly arrivalBudget?: number;
+    /** A body must stand here to count as on site; omit to count every admitted body. */
+    readonly inside?: (position: Vec3) => boolean;
+    /** Register a devtools probe under this name so the overlay shows the crowd and the day. */
+    readonly devtoolsName?: string;
+}
+/**
+ * The crowd a scene reports. Every visitor is a member with a body the game's world made, so the
+ * on-site figure is the member count and the daily figure is the sum of admissions the world
+ * accepted — there is no second tally to drift from what is on the ground. Arrivals, capacity and
+ * leaving are the game's policy; ids, day rollover and counting are this seam's.
+ */
+export interface VisitorPopulation {
+    /** Run the flow for `dt` seconds: leaving first, then arrivals within the budget and the cap. */
+    tick(dt: number, now: number): void;
+    /** Visitors on site. Reads the member count — no scan of the world, safe for a per-frame HUD. */
+    onSite(): number;
+    arrivalsToday(): number;
+    departuresToday(): number;
+    peakToday(): number;
+    /** Ids on site, arrival order. Allocates — HUD lists and tests. */
+    ids(): readonly string[];
+    has(id: string): boolean;
+    visitor(id: string): Visitor | null;
+    /** Send one visitor home now (it reached the exit, or the game evicted it). */
+    leave(id: string): boolean;
+    /**
+     * Take over a body the game created itself — one restored from a save, seeded at park open, or
+     * scripted. It is on site from now on; pass `arrival: true` when it is also a new arrival today.
+     */
+    adopt(id: string, adoption?: VisitorAdoption): boolean;
+    /** Close the day: arrivals, departures and peak reset. The crowd stays where it stands. */
+    rollDay(): void;
+    retune(patch: VisitorPolicyPatch): void;
+    stats(): VisitorPopulationStats;
+    snapshot(): VisitorPopulationSnapshot;
+    /**
+     * Replace the members with the saved ones. Only visitors the world already holds come back, so
+     * restore the bodies first (or `adopt` each one as it spawns); the rest count as refused.
+     */
+    restore(next: VisitorPopulationSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Create the population a scene reports, with the game owning arrival and leaving policy. A
+ * visitor only exists once the world has made its body, so the HUD's count and the bodies on
+ * screen are the same list: `admit` returning `null` is a refused arrival, not a number.
+ *
+ * @capability visitor-population a crowd whose on-site and daily counts are the bodies the game made
+ */
+export declare function createVisitorPopulation(options: VisitorPopulationOptions): VisitorPopulation;