@jgengine/core 0.24.0 → 0.26.0

package/dist/sim/needs.js

@@ -0,0 +1,108 @@
+import { decayMeters, initDecayMeters, } from "../survival/decayMeter.js";
+import { clamp } from "../math/scalar.js";
+/**
+ * Create the needs an agent or a park guest carries. Decay reuses the survival meter formulas
+ * (`survival/decayMeter`), so moodle thresholds, clamping and rate modifiers behave exactly like
+ * every other meter; this set adds index-addressed reads and single-need retuning for hot AI loops.
+ * Score these needs into an action with `createUtilityBrain` (`@jgengine/core/world`).
+ *
+ * @capability needs decaying needs an agent reads by index to decide what it wants next
+ */
+export function createNeedSet(definitions) {
+    const defs = definitions.map((definition) => ({ ...definition }));
+    const index = new Map();
+    const ids = [];
+    const spans = new Float64Array(defs.length);
+    for (let i = 0; i < defs.length; i += 1) {
+        const def = defs[i];
+        index.set(def.id, i);
+        ids.push(def.id);
+        spans[i] = def.max - (def.min ?? 0);
+    }
+    let values = initDecayMeters(defs);
+    let modifiers = {};
+    const lookup = (id) => {
+        const at = index.get(id);
+        if (at === undefined)
+            throw new Error(`unknown need "${id}"`);
+        return at;
+    };
+    const readValue = (at) => {
+        const current = values[ids[at]];
+        return current === undefined ? defs[at].start ?? defs[at].max : current;
+    };
+    const readFraction = (at) => {
+        const span = spans[at];
+        return span > 0 ? clamp((readValue(at) - (defs[at].min ?? 0)) / span, 0, 1) : 0;
+    };
+    return {
+        tick(dt) {
+            if (dt > 0)
+                values = decayMeters(values, defs, dt, modifiers);
+        },
+        ids: () => ids,
+        indexOf: (id) => index.get(id) ?? -1,
+        valueAt: (at) => (at >= 0 && at < defs.length ? readValue(at) : 0),
+        fractionAt: (at) => (at >= 0 && at < defs.length ? readFraction(at) : 0),
+        value: (id) => readValue(lookup(id)),
+        fraction: (id) => readFraction(lookup(id)),
+        refill(id, amount) {
+            const at = lookup(id);
+            const def = defs[at];
+            const min = def.min ?? 0;
+            values = { ...values, [id]: clamp(readValue(at) + amount, min, def.max) };
+        },
+        setRate(id, rate) {
+            defs[lookup(id)].rate = rate;
+        },
+        setRateModifier(id, multiplier) {
+            if (id === null) {
+                for (const needId of ids)
+                    modifiers[needId] = multiplier;
+                return;
+            }
+            lookup(id);
+            modifiers = { ...modifiers, [id]: multiplier };
+        },
+        mostUrgent() {
+            let worst = -1;
+            let worstFraction = Infinity;
+            for (let at = 0; at < defs.length; at += 1) {
+                const fraction = readFraction(at);
+                if (fraction < worstFraction) {
+                    worst = at;
+                    worstFraction = fraction;
+                }
+            }
+            if (worst < 0)
+                return null;
+            const id = ids[worst];
+            return { id, value: readValue(worst), fraction: worstFraction };
+        },
+        snapshot() {
+            const out = {};
+            const rates = {};
+            for (let at = 0; at < defs.length; at += 1) {
+                const id = ids[at];
+                out[id] = readValue(at);
+                rates[id] = defs[at].rate;
+            }
+            return { values: out, rates, modifiers: { ...modifiers } };
+        },
+        restore(next) {
+            const restored = {};
+            for (let at = 0; at < defs.length; at += 1) {
+                const def = defs[at];
+                const id = ids[at];
+                const min = def.min ?? 0;
+                const saved = next.values[id];
+                restored[id] = saved === undefined || !Number.isFinite(saved) ? readValue(at) : clamp(saved, min, def.max);
+                const rate = next.rates[id];
+                if (rate !== undefined && Number.isFinite(rate))
+                    def.rate = rate;
+            }
+            values = restored;
+            modifiers = { ...next.modifiers };
+        },
+    };
+}

package/dist/sim/offScreen.d.ts

@@ -0,0 +1,181 @@
+import type { Vec3 } from "../world/geometry.js";
+import type { NeedDefinition } from "./needs.js";
+import type { RoutineTimeline } from "./routine.js";
+/** Which side of the distance policy a resident is on: simulated near the viewer, or cheap state. */
+export type OffScreenMode = "near" | "far";
+/**
+ * Where the near/far boundary is and what it costs. The radius, the cost model and the budget are
+ * the game's call — a city block and a haunted-house hallway do not share a number.
+ */
+export interface OffScreenPolicy {
+    /** Distance at or below which a resident is simulated near the viewer. */
+    readonly nearRadius: number;
+    /** Distance past which a near resident becomes cheap state. Defaults to `nearRadius` (no band). */
+    readonly farRadius?: number;
+    /**
+     * Estimated per-tick cost of keeping one resident near, in the caller's own units. Only read when
+     * `nearBudget` is set.
+     */
+    readonly costModel?: (id: string, distance: number) => number;
+    /** Ceiling on the summed near cost; over-budget residents nearest the boundary go cheap first. */
+    readonly nearBudget?: number;
+    /** Most spawn/despawn switches one tick may perform, so a teleporting viewer cannot hitch a frame. Default 32. */
+    readonly switchBudget?: number;
+}
+/** Everything a near-side simulator is told when a resident crosses into range. */
+export interface NearSpawn {
+    readonly id: string;
+    /** Cheap-state position, so the agent appears where it already was — never at the origin. */
+    readonly position: Vec3;
+    /** Place the resident occupies, `null` for a resident with no authored routine. */
+    readonly place: string | null;
+    readonly activity: string | null;
+    /** Current need values from the cheap state; the near side resumes from these. */
+    readonly needs: Readonly<Record<string, number>>;
+    /** Where it should walk in the current phase (its place, or the place it is walking to). */
+    readonly goal: Vec3;
+    readonly stop: number;
+    readonly travelling: boolean;
+}
+/** What a near-side simulator hands back when a resident leaves range. */
+export interface NearHandoff {
+    readonly position: Vec3;
+    readonly needs: Readonly<Record<string, number>>;
+}
+/**
+ * The near half of the world: the game's real simulation. Only residents inside the radius are ever
+ * spawned here, which is what keeps far agents free of navigation and utility scoring.
+ */
+export interface NearAgents {
+    spawn(next: NearSpawn): void;
+    /** Remove a near resident and hand back its live position and needs for the cheap state. */
+    despawn(id: string): NearHandoff | null;
+    /** Live position, or `null` when the resident is not spawned. */
+    position(id: string): Vec3 | null;
+    /** Live need values, when the near side keeps them; the cheap state takes these on handoff. */
+    needs?(id: string): Readonly<Record<string, number>> | null;
+    /** Retarget a near resident when its routine moves on to another place. */
+    setGoal(id: string, goal: Vec3): void;
+    /** Advance every near resident by `dt` seconds. */
+    tick(dt: number, now: number): void;
+    /** Utility decisions taken since creation, when the near side keeps brains. */
+    decisions?(): number;
+    dispose?(): void;
+}
+/** One resident of the world: an identity, where it belongs, and the day it follows. */
+export interface OffScreenResidentSpec {
+    readonly id: string;
+    /** Where the resident stands when its routine says nothing; also the fallback for a missing place. */
+    readonly home: Vec3;
+    /** Authored day; omitted means it stays home. */
+    readonly routine?: RoutineTimeline;
+    /** Saved need values; omitted needs start at their definition's `start ?? max`. */
+    readonly needs?: Readonly<Record<string, number>>;
+    /** Force this resident near regardless of distance (a cutscene, a quest NPC). */
+    readonly pinned?: boolean;
+}
+/** A resident as a game or the devtools overlay reads it. Allocates a need copy — debug and tests. */
+export interface OffScreenAgentView {
+    readonly id: string;
+    readonly mode: OffScreenMode;
+    readonly position: Vec3;
+    readonly place: string | null;
+    readonly activity: string | null;
+    readonly stop: number;
+    readonly travelling: boolean;
+    readonly needs: Readonly<Record<string, number>>;
+    readonly pinned: boolean;
+    /** Distance from the viewer at the last tick. */
+    readonly distance: number;
+}
+/** Counters a devtools probe or a test reads to prove far agents cost nothing. */
+export interface OffScreenStats {
+    agents: number;
+    near: number;
+    far: number;
+    promotions: number;
+    demotions: number;
+    /** Cheap-state boundary updates — the only per-tick work a far resident can cause. */
+    farRefreshes: number;
+    /** Near-side utility decisions, summed across the near residents' brains. */
+    decisions: number;
+}
+/** Serializable world state: the policy and every resident, near ones included. */
+export interface OffScreenSnapshot {
+    policy: {
+        nearRadius: number;
+        farRadius: number;
+        nearBudget: number | null;
+        switchBudget: number;
+    };
+    residents: {
+        id: string;
+        home: Vec3;
+        mode: OffScreenMode;
+        position: Vec3;
+        place: string | null;
+        activity: string | null;
+        stop: number;
+        travelling: boolean;
+        pinned: boolean;
+        updatedAt: number;
+        staleAt: number;
+        needs: Record<string, number>;
+    }[];
+}
+/** A policy change that stays reachable in play. */
+export interface OffScreenPolicyPatch {
+    readonly nearRadius?: number;
+    readonly farRadius?: number;
+    readonly costModel?: (id: string, distance: number) => number;
+    readonly nearBudget?: number;
+    readonly switchBudget?: number;
+}
+/** Options for {@link createOffScreenWorld}. */
+export interface OffScreenOptions {
+    /** Routine place id → world anchor. Every place a resident's routine names must exist here. */
+    readonly places: Readonly<Record<string, Vec3>>;
+    /** Need definitions every resident shares; the far model decays these closed-form. */
+    readonly needs: readonly NeedDefinition[];
+    readonly policy: OffScreenPolicy;
+    /** The game's near simulation. Far residents never touch it. */
+    readonly near: NearAgents;
+    readonly residents?: readonly OffScreenResidentSpec[];
+    /** Register a devtools probe under this name so the overlay shows near/far counts. */
+    readonly devtoolsName?: string;
+}
+/**
+ * The off-screen world: every resident exists, but only the ones within the policy radius are
+ * simulated. The rest are a position, a routine phase and a needs record that only move when the
+ * clock crosses a routine boundary — no navigation, no utility scoring, no per-frame need decay.
+ *
+ * Crossing the boundary is a handoff, not a respawn: a resident arrives where the cheap state says
+ * it is, with its schedule progress and needs intact, and leaves with the same identity.
+ */
+export interface OffScreenWorld {
+    add(spec: OffScreenResidentSpec): boolean;
+    remove(id: string): boolean;
+    has(id: string): boolean;
+    count(): number;
+    ids(): readonly string[];
+    agent(id: string): OffScreenAgentView | null;
+    /** Keep a resident near regardless of distance; `false` clears the pin. */
+    pin(id: string, pinned?: boolean): boolean;
+    /** Cheap-state needs as of `now`, resolved through any routine boundary since the last tick. */
+    needsAt(id: string, now: number): Readonly<Record<string, number>> | null;
+    /** Split the world by distance, run the near simulation, and advance cheap routine phase. */
+    tick(dt: number, now: number, viewer: Vec3): void;
+    stats(): OffScreenStats;
+    retune(patch: OffScreenPolicyPatch): void;
+    snapshot(): OffScreenSnapshot;
+    restore(next: OffScreenSnapshot): void;
+    dispose(): void;
+}
+/**
+ * Create the world that decides which agents deserve a simulation. Residents are cheap state until
+ * they come near, and cheap again when they leave; the cheap state is the schedule, the needs and
+ * the last place, so a returning resident never pops in at the origin.
+ *
+ * @capability offscreen-world schedules agents near the player as real state and far ones as cheap state
+ */
+export declare function createOffScreenWorld(options: OffScreenOptions): OffScreenWorld;