@jgengine/core 0.25.0 → 0.26.0

package/dist/sensor/perception.js

@@ -1,24 +1,10 @@
+import { devtools } from "../devtools/devtools.js";
 function distance(a, b) {
     return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 }
 function confidenceAt(memory, nowMs, memoryMs) {
     return memory.confidence * Math.max(0, 1 - Math.max(0, nowMs - memory.lastSeenAt) / memoryMs);
 }
-function inSight(observer, target, config) {
-    const dx = target[0] - observer.position[0];
-    const dz = target[2] - observer.position[2];
-    const range = Math.hypot(dx, dz);
-    if (range > config.sightRange)
-        return false;
-    if (range < 1e-9)
-        return true;
-    let delta = Math.atan2(dx, dz) - observer.yaw;
-    while (delta > Math.PI)
-        delta -= Math.PI * 2;
-    while (delta < -Math.PI)
-        delta += Math.PI * 2;
-    return Math.abs(delta) <= (config.sightConeDeg * Math.PI) / 360;
-}
 function validate(config) {
     if (!Number.isFinite(config.sightRange) || config.sightRange < 0)
         throw new Error("sightRange must be non-negative.");
@@ -30,20 +16,48 @@ function validate(config) {
         throw new Error("memorySeconds must be positive.");
     if (config.maxStimuli !== undefined && (!Number.isInteger(config.maxStimuli) || config.maxStimuli < 1))
         throw new Error("maxStimuli must be a positive integer.");
+    if (config.maxSharesPerTick !== undefined && (!Number.isInteger(config.maxSharesPerTick) || config.maxSharesPerTick < 0)) {
+        throw new Error("maxSharesPerTick must be a non-negative integer.");
+    }
 }
 const DEFAULT_MAX_STIMULI = 256;
-/** Creates a deterministic sight, sound, and damage perception service with expiring target memory.
- * @capability perception-service retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
+const DEFAULT_MAX_SHARES = 64;
+/**
+ * Creates a deterministic sight, sound, and damage perception service with expiring target memory.
+ * Signals are judged in the order the caller supplies them, never from the wall clock.
+ *
+ * A sighting needs range, cone and a clear line; a sound carries `hearingRange × loudness` and
+ * fades with the distance it crossed, so a distant footstep is inaudible while a near gunshot is
+ * not. Memory is the only record of "seen recently": each fact fades linearly over `memorySeconds`
+ * and is then gone. With `squadMates` injected, a sighting one member makes lands in every mate's
+ * memory stamped with the seeing member and the pass, which is what lets a squad react to one pair
+ * of eyes without each member re-seeing anything.
+ *
+ * @capability perception-service retain sightings, sounds and damage with cone, range, occlusion, decaying memory and shared squad knowledge
  */
 export function createPerception(initial) {
     validate(initial);
     let config = { ...initial };
+    let maxShares = config.maxSharesPerTick ?? DEFAULT_MAX_SHARES;
     let nowMs = 0;
+    let passes = 0;
     const stimuli = [];
     const heard = new Map();
     let nextSeq = 1;
     const memories = new Map();
-    function remember(observerId, targetId, position, at, confidence) {
+    const stats = {
+        passes: 0,
+        pairChecks: 0,
+        rangeCulled: 0,
+        coneTests: 0,
+        occlusionChecks: 0,
+        sightings: 0,
+        heard: 0,
+        shares: 0,
+        shareDropped: 0,
+    };
+    const fresh = [];
+    function remember(observerId, targetId, position, at, confidence, sourceId, sourceTick) {
         if (confidence <= 0)
             return;
         let observerMemories = memories.get(observerId);
@@ -53,26 +67,61 @@ export function createPerception(initial) {
         }
         const previous = observerMemories.get(targetId);
         if (previous === undefined || at >= previous.lastSeenAt) {
-            observerMemories.set(targetId, { targetId, lastSeenAt: at, lastKnownPos: [...position], confidence });
+            observerMemories.set(targetId, {
+                targetId,
+                lastSeenAt: at,
+                lastKnownPos: [...position],
+                confidence,
+                sourceId,
+                sourceTick,
+            });
         }
     }
-    function prune() {
+    function pruneObserver(observerId) {
+        const observerMemories = memories.get(observerId);
+        if (observerMemories === undefined)
+            return;
         const memoryMs = config.memorySeconds * 1000;
-        for (const [observerId, observerMemories] of memories) {
-            for (const [targetId, memory] of observerMemories) {
-                if (confidenceAt(memory, nowMs, memoryMs) <= 0)
-                    observerMemories.delete(targetId);
-            }
-            if (observerMemories.size === 0)
-                memories.delete(observerId);
+        for (const [targetId, memory] of observerMemories) {
+            if (confidenceAt(memory, nowMs, memoryMs) <= 0)
+                observerMemories.delete(targetId);
         }
-        const cutoff = nowMs - memoryMs;
+        if (observerMemories.size === 0)
+            memories.delete(observerId);
+    }
+    function pruneStimuli() {
+        const cutoff = nowMs - config.memorySeconds * 1000;
         let drop = Math.max(0, stimuli.length - (config.maxStimuli ?? DEFAULT_MAX_STIMULI));
         while (drop < stimuli.length && stimuli[drop].at < cutoff)
             drop += 1;
         if (drop > 0)
             stimuli.splice(0, drop);
     }
+    /** Every observer's memory, not just the one that just observed — saving, retuning and restoring only. */
+    function pruneAll() {
+        for (const observerId of memories.keys())
+            pruneObserver(observerId);
+        pruneStimuli();
+    }
+    function share(mateId, sighting, seerId, tick) {
+        const existing = memories.get(mateId)?.get(sighting.id);
+        // The mate's own sighting at or after this instant is better evidence than a hand-off.
+        if (existing !== undefined && existing.lastSeenAt >= nowMs)
+            return;
+        remember(mateId, sighting.id, sighting.position, nowMs, 1, seerId, tick);
+    }
+    function rememberedCount() {
+        let total = 0;
+        for (const observerMemories of memories.values())
+            total += observerMemories.size;
+        return total;
+    }
+    function debugLine() {
+        const work = `${stats.pairChecks} pairs ${stats.rangeCulled} culled ${stats.occlusionChecks} los ${stats.sightings} sights ${stats.heard} heard`;
+        const squad = stats.shareDropped > 0 ? `${stats.shares} shared ${stats.shareDropped} dropped` : `${stats.shares} shared`;
+        return `${memories.size} observers ${rememberedCount()} remembered · ${work} · ${squad}`;
+    }
+    const unregister = config.devtoolsName === undefined ? null : devtools.probes.register(config.devtoolsName, () => debugLine());
     return {
         pushStimulus(stimulus) {
             if (!Number.isFinite(stimulus.at))
@@ -85,21 +134,65 @@ export function createPerception(initial) {
                 index -= 1;
             stimuli.splice(index, 0, { ...stimulus, position: [...stimulus.position], seq: nextSeq++ });
             nowMs = Math.max(nowMs, stimulus.at);
-            prune();
+            pruneStimuli();
         },
         observe(observer, candidates, observedAt) {
             if (!Number.isFinite(observedAt))
                 throw new Error("nowMs must be finite.");
             nowMs = observedAt;
+            passes += 1;
+            stats.passes = passes;
+            const tick = passes;
+            const halfAngle = (config.sightConeDeg * Math.PI) / 360;
+            const isClear = config.isSegmentClear;
+            fresh.length = 0;
             for (const candidate of candidates) {
-                if (!inSight(observer, candidate.position, config))
+                stats.pairChecks += 1;
+                const dx = candidate.position[0] - observer.position[0];
+                const dz = candidate.position[2] - observer.position[2];
+                const range = Math.sqrt(dx * dx + dz * dz);
+                if (range > config.sightRange) {
+                    stats.rangeCulled += 1;
                     continue;
-                if (config.occluded?.(observer.position, candidate.position))
-                    continue;
-                remember(observer.id, candidate.id, candidate.position, nowMs, 1);
+                }
+                stats.coneTests += 1;
+                if (range >= 1e-9) {
+                    let delta = Math.atan2(dx, dz) - observer.yaw;
+                    while (delta > Math.PI)
+                        delta -= Math.PI * 2;
+                    while (delta < -Math.PI)
+                        delta += Math.PI * 2;
+                    if (Math.abs(delta) > halfAngle)
+                        continue;
+                }
+                if (isClear !== undefined) {
+                    stats.occlusionChecks += 1;
+                    if (!isClear(observer.position, candidate.position))
+                        continue;
+                }
+                stats.sightings += 1;
+                remember(observer.id, candidate.id, candidate.position, nowMs, 1, observer.id, tick);
+                fresh.push(candidate);
             }
-            // Each observer judges a stimulus once, from where it stood when it first observed after the stimulus;
-            // re-judging every tick would make an old noise louder as the observer walks toward it.
+            const mates = config.squadMates;
+            if (mates !== undefined && fresh.length > 0) {
+                let budget = maxShares;
+                for (const sighting of fresh) {
+                    for (const mateId of mates(observer.id)) {
+                        if (mateId === observer.id)
+                            continue;
+                        if (budget <= 0) {
+                            stats.shareDropped += 1;
+                            continue;
+                        }
+                        budget -= 1;
+                        stats.shares += 1;
+                        share(mateId, sighting, observer.id, tick);
+                    }
+                }
+            }
+            // Each observer judges a stimulus once, from where it stood when it first observed after the
+            // stimulus; re-judging every tick would make an old noise louder as the observer walks toward it.
             const judgedThrough = heard.get(observer.id) ?? 0;
             let judged = judgedThrough;
             let firstFuture = Number.POSITIVE_INFINITY;
@@ -118,14 +211,16 @@ export function createPerception(initial) {
                     const audible = config.hearingRange * (stimulus.loudness ?? 1);
                     if (range >= audible)
                         continue;
-                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1 - range / audible);
+                    stats.heard += 1;
+                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1 - range / audible, observer.id, tick);
                 }
                 else if (stimulus.kind === "damage") {
-                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1);
+                    stats.heard += 1;
+                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1, observer.id, tick);
                 }
             }
             heard.set(observer.id, Math.min(judged, firstFuture - 1));
-            prune();
+            pruneObserver(observer.id);
         },
         memory(observerId) {
             const observerMemories = memories.get(observerId);
@@ -140,6 +235,15 @@ export function createPerception(initial) {
             }
             return result;
         },
+        memoryOf(observerId, targetId) {
+            const memory = memories.get(observerId)?.get(targetId);
+            if (memory === undefined)
+                return null;
+            const confidence = confidenceAt(memory, nowMs, config.memorySeconds * 1000);
+            if (confidence <= 0)
+                return null;
+            return { ...memory, lastKnownPos: [...memory.lastKnownPos], confidence };
+        },
         forget(observerId, targetId) {
             if (targetId === undefined) {
                 memories.delete(observerId);
@@ -150,18 +254,32 @@ export function createPerception(initial) {
             if (observerMemories?.size === 0)
                 memories.delete(observerId);
         },
+        stats: () => ({ ...stats }),
+        resetStats() {
+            stats.pairChecks = 0;
+            stats.rangeCulled = 0;
+            stats.coneTests = 0;
+            stats.occlusionChecks = 0;
+            stats.sightings = 0;
+            stats.heard = 0;
+            stats.shares = 0;
+            stats.shareDropped = 0;
+        },
         retune(patch) {
             config = { ...config, ...patch };
             validate(config);
-            prune();
+            maxShares = config.maxSharesPerTick ?? DEFAULT_MAX_SHARES;
+            pruneAll();
         },
         snapshot() {
+            pruneAll();
             const result = {
                 memories: [],
                 stimuli: stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })),
                 nowMs,
                 heard: Object.fromEntries(heard),
                 nextSeq,
+                passes,
             };
             for (const [observerId, observerMemories] of memories)
                 for (const memory of observerMemories.values())
@@ -172,6 +290,8 @@ export function createPerception(initial) {
             memories.clear();
             stimuli.length = 0;
             nowMs = snapshot.nowMs;
+            passes = snapshot.passes ?? 0;
+            stats.passes = passes;
             heard.clear();
             for (const [observerId, seq] of Object.entries(snapshot.heard ?? {}))
                 heard.set(observerId, seq);
@@ -181,9 +301,14 @@ export function createPerception(initial) {
                 stimuli.push({ ...stimulus, position: [...stimulus.position], seq });
             }
             nextSeq = Math.max(snapshot.nextSeq ?? 0, seq + 1);
-            for (const entry of snapshot.memories)
-                remember(entry.observerId, entry.memory.targetId, entry.memory.lastKnownPos, entry.memory.lastSeenAt, entry.memory.confidence);
-            prune();
+            for (const entry of snapshot.memories) {
+                const saved = entry.memory;
+                remember(entry.observerId, saved.targetId, saved.lastKnownPos, saved.lastSeenAt, saved.confidence, saved.sourceId ?? entry.observerId, saved.sourceTick ?? 0);
+            }
+            pruneAll();
+        },
+        dispose() {
+            unregister?.();
         },
     };
 }

package/dist/sim/nearAgents.d.ts

@@ -0,0 +1,68 @@
+import type { Vec3 } from "../world/geometry.js";
+import { type NavCrowd, type NavCrowdOptions } 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";
+import type { NearAgents } from "./offScreen.js";
+/** Serializable state of one near agent: where it walks, what it needs, what it last chose. */
+export interface NearAgentSnapshot {
+    id: string;
+    position: Vec3;
+    goal: Vec3;
+    place: string | null;
+    activity: string | null;
+    travelling: boolean;
+    needs: NeedSnapshot;
+    brain: UtilityBrainSnapshot;
+}
+/** Everything a near agent is doing, for a HUD, a probe or a test. Allocates. */
+export interface NearAgentView {
+    id: string;
+    position: Vec3;
+    goal: Vec3;
+    place: string | null;
+    activity: string | null;
+    travelling: boolean;
+    /** The utility pick for this tick; `null` before the first decision or with no candidates. */
+    pick: string | null;
+    needs: NeedSnapshot;
+}
+/** What the near side needs from the game: a nav mesh, the shared need definitions, and what agents can do. */
+export interface NearAgentsOptions {
+    nav: NavRuntime;
+    /** Need definitions shared with the off-screen world, so a far decay and a near tick agree. */
+    needs: readonly NeedDefinition[];
+    /** Utility options each brain scores; omit for agents that only carry needs and walk. */
+    options?: readonly UtilityOption[];
+    interrupts?: readonly UtilityInterrupt[];
+    /** Candidates the agent may pick this tick (where it stands, or anything the game offers). */
+    candidates?: (agent: NearAgentView) => readonly UtilityCandidate[];
+    crowd?: NavCrowdOptions;
+    /** Register a devtools probe under this name so the overlay shows near-agent decisions. */
+    devtoolsName?: string;
+}
+/**
+ * The near half of the off-screen world: one nav crowd for movement, one need set and utility brain
+ * per agent for what it wants. Resident identity survives the handoff because the off-screen world
+ * spawns and despawns through this seam and keeps the saved state.
+ */
+export interface NearCrowdAgents extends NearAgents {
+    /** Utility decisions taken since creation — near agents run brains, far ones do not exist here. */
+    decisions(): number;
+    view(id: string): NearAgentView | null;
+    crowd(): NavCrowd;
+    snapshot(): {
+        agents: NearAgentSnapshot[];
+    };
+    restore(next: {
+        agents: readonly NearAgentSnapshot[];
+    }): void;
+}
+/**
+ * Create the near-side simulation: agents on a nav mesh with decaying needs and a utility brain each.
+ * The off-screen world decides which agents exist here, so a resident beyond its radius costs this
+ * seam nothing at all — no path, no need tick, no decision.
+ *
+ * @capability near-agents nav crowd plus per-agent needs and utility brains for on-screen residents
+ */
+export declare function createNearAgents(options: NearAgentsOptions): NearCrowdAgents;

package/dist/sim/nearAgents.js

@@ -0,0 +1,152 @@
+import { devtools } from "../devtools/devtools.js";
+import { createNavCrowd } from "../nav/navCrowd.js";
+import { createUtilityBrain, } from "../ai/utilityBrain.js";
+import { createNeedSet } from "./needs.js";
+/**
+ * Create the near-side simulation: agents on a nav mesh with decaying needs and a utility brain each.
+ * The off-screen world decides which agents exist here, so a resident beyond its radius costs this
+ * seam nothing at all — no path, no need tick, no decision.
+ *
+ * @capability near-agents nav crowd plus per-agent needs and utility brains for on-screen residents
+ */
+export function createNearAgents(options) {
+    const crowd = createNavCrowd({ nav: options.nav, ...options.crowd });
+    const defs = options.needs.map((definition) => ({ ...definition }));
+    const agents = new Map();
+    let decisions = 0;
+    function probeLine() {
+        const title = agents.size === 1 ? "1 agent" : `${agents.size} agents`;
+        const stats = crowd.stats();
+        return `${title} ${decisions} decisions ${stats.plans} plans ${stats.arrived} arrived`;
+    }
+    const unregister = options.devtoolsName === undefined ? null : devtools.probes.register(options.devtoolsName, () => probeLine());
+    function viewOf(agent) {
+        const body = crowd.agent(agent.id);
+        return {
+            id: agent.id,
+            position: body?.position ?? [0, 0, 0],
+            goal: agent.goal,
+            place: agent.place,
+            activity: agent.activity,
+            travelling: agent.travelling,
+            pick: agent.brain.chosen(),
+            needs: agent.needs.snapshot(),
+        };
+    }
+    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 }),
+        });
+        if (saved !== undefined)
+            brain.restore(saved.brain);
+        const goal = saved?.goal ?? next.goal;
+        const agent = {
+            id: next.id,
+            needs,
+            brain,
+            goal,
+            place: next.place,
+            activity: next.activity,
+            travelling: next.travelling,
+            spawned: next,
+        };
+        agents.set(next.id, agent);
+        crowd.add(next.id, { position: saved?.position ?? next.position, goal });
+    }
+    return {
+        spawn(next) {
+            mount(next);
+        },
+        despawn(id) {
+            const agent = agents.get(id);
+            if (agent === undefined)
+                return null;
+            const body = crowd.agent(id);
+            const handoff = {
+                position: body?.position ?? agent.spawned.position,
+                needs: agent.needs.snapshot().values,
+            };
+            crowd.remove(id);
+            agent.brain.dispose();
+            agents.delete(id);
+            return handoff;
+        },
+        position(id) {
+            return crowd.agent(id)?.position ?? null;
+        },
+        needs(id) {
+            return agents.get(id)?.needs.snapshot().values ?? null;
+        },
+        setGoal(id, goal) {
+            const agent = agents.get(id);
+            if (agent === undefined)
+                return;
+            agent.goal = goal;
+            crowd.setGoal(id, goal);
+        },
+        tick(dt, _now) {
+            for (const agent of agents.values()) {
+                agent.brain.advance(dt);
+                const candidates = options.candidates === undefined ? [] : options.candidates(viewOf(agent));
+                agent.brain.decide(candidates);
+                decisions += 1;
+            }
+            crowd.tick(dt);
+        },
+        decisions: () => decisions,
+        view(id) {
+            const agent = agents.get(id);
+            return agent === undefined ? null : viewOf(agent);
+        },
+        crowd: () => crowd,
+        snapshot() {
+            const out = [];
+            for (const agent of agents.values()) {
+                const body = crowd.agent(agent.id);
+                out.push({
+                    id: agent.id,
+                    position: body?.position ?? agent.spawned.position,
+                    goal: agent.goal,
+                    place: agent.place,
+                    activity: agent.activity,
+                    travelling: agent.travelling,
+                    needs: agent.needs.snapshot(),
+                    brain: agent.brain.snapshot(),
+                });
+            }
+            return { agents: out };
+        },
+        restore(next) {
+            for (const id of [...agents.keys()]) {
+                crowd.remove(id);
+                agents.get(id)?.brain.dispose();
+                agents.delete(id);
+            }
+            for (const saved of next.agents) {
+                mount({
+                    id: saved.id,
+                    position: saved.position,
+                    place: saved.place,
+                    activity: saved.activity,
+                    needs: saved.needs.values,
+                    goal: saved.goal,
+                    stop: 0,
+                    travelling: saved.travelling,
+                }, saved);
+            }
+        },
+        dispose() {
+            unregister?.();
+            for (const agent of agents.values())
+                agent.brain.dispose();
+            agents.clear();
+            crowd.dispose();
+        },
+    };
+}

package/dist/sim/needs.d.ts

@@ -0,0 +1,60 @@
+import { type DecayMeterConfig } from "../survival/decayMeter.js";
+/**
+ * A decaying need is a survival decay meter (`max`/`min`/`start`/`rate`, optional moodle
+ * thresholds) whose satisfaction an agent brain reads to score actions. The meter owns the
+ * numbers; per-need appeal lives in the game's utility options.
+ */
+export type NeedDefinition = DecayMeterConfig;
+/** One need's current satisfaction, worst-first ready: `fraction` is 0 (empty) … 1 (full). */
+export interface NeedReading {
+    id: string;
+    value: number;
+    fraction: number;
+}
+/** Serializable need state: values plus any in-play retuning, so a save keeps the dials. */
+export interface NeedSnapshot {
+    /** Satisfaction per need id; undeclared ids are ignored on restore. */
+    values: Record<string, number>;
+    /** Base rates after `setRate`; absent entries keep the definition's rate. */
+    rates: Record<string, number>;
+    /** Active per-need rate multipliers from `setRateModifier`. */
+    modifiers: Record<string, number>;
+}
+/**
+ * Named needs that drain or recover on game time — hunger, energy, hygiene, bladder, fun.
+ * Reads are index-addressed (`indexOf` once, `fractionAt` per tick) so a thousand-agent loop
+ * never re-resolves ids; the whole set round-trips through {@link NeedSnapshot}.
+ */
+export interface NeedSet {
+    /** Drain every need by `rate * modifier * dt` in place. Call once per game tick. */
+    tick(dt: number): void;
+    /** Declared ids in definition order. */
+    ids(): readonly string[];
+    /** Stable index for a declared need, or `-1`. Resolve once, then use the `*At` readers. */
+    indexOf(id: string): number;
+    /** Raw value at `indexOf(id)` — no allocation, no lookup. */
+    valueAt(index: number): number;
+    /** 0..1 fill at `indexOf(id)` — what response curves sample. */
+    fractionAt(index: number): number;
+    value(id: string): number;
+    fraction(id: string): number;
+    /** Consumable/action refill; negative drains. Throws on an unknown id. */
+    refill(id: string, amount: number): void;
+    /** Overwrite one need's base rate (a harsher game mode). Throws on an unknown id. */
+    setRate(id: string, rate: number): void;
+    /** Multiply one need's drain until cleared with `1`; `null` sets every need at once. */
+    setRateModifier(id: string | null, multiplier: number): void;
+    /** Least-satisfied need by fraction, declared order breaking ties; `null` when none declared. */
+    mostUrgent(): NeedReading | null;
+    snapshot(): NeedSnapshot;
+    restore(next: NeedSnapshot): void;
+}
+/**
+ * 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 declare function createNeedSet(definitions: readonly NeedDefinition[]): NeedSet;