@jgengine/core 0.25.0 → 0.27.0

package/dist/render/postProcessing.d.ts

@@ -1,5 +1,27 @@
-/** Renderer tone-mapping curve applied by the post chain's output stage. */
+import type { AutoExposureConfig } from "./colorPipeline.js";
+/**
+ * Renderer tone-mapping curve applied by the post chain's output stage. `"agx"` is the pipeline
+ * default: it keeps hue in saturated highlights and rolls a sun-lit surface off gradually, where
+ * `"aces"` skews bright colours toward white.
+ */
 export type ToneMappingMode = "aces" | "agx" | "reinhard" | "cineon" | "linear" | "none";
+/**
+ * A baked display-space LUT cube: `size³` RGB entries with red varying fastest, three bytes per entry
+ * in 0..255. Kept as plain data so a scene document can author one and a test can assert on it.
+ */
+export interface LutCube {
+    /** Edge length of the cube, 2..16. */
+    size: number;
+    /** `size³ × 3` bytes, red fastest, then green, then blue. */
+    data: Uint8Array;
+}
+/** A grade's LUT: a strip PNG (one `size`-wide tile per blue slice) or a baked cube. */
+export type GradeLut = {
+    url: string;
+    size?: number;
+} | {
+    cube: LutCube;
+};
 /** UnrealBloom stage — soft HDR glow around bright pixels (sun, glints, emissive). */
 export interface BloomConfig {
     /** Glow intensity. Default 0.32. */
@@ -26,11 +48,12 @@ export interface AoConfig {
 }
 /** Final colour-grade stage: lift/gain/gamma, saturation, vignette, film grain — applied in display space after tone mapping. */
 export interface GradeConfig {
-    /** Optional 2D strip LUT URL. The strip contains size square tiles, one tile per blue slice. */
-    lut?: {
-        url: string;
-        size?: number;
-    };
+    /**
+     * Colour LUT applied after the numeric grade, in display space. Either a strip PNG (one
+     * `size`-wide tile per blue slice, trilinearly sampled) or a baked {@link LutCube} such as the one
+     * a scene document's authored grading produces.
+     */
+    lut?: GradeLut;
     /** Additive shadow tint (RGB, ~0..0.1). Default cool [0.012, 0.010, 0.018]. */
     lift?: readonly [number, number, number];
     /** Multiplicative highlight tint (RGB, ~1). Default warm [1.05, 1.02, 0.98]. */
@@ -99,10 +122,19 @@ export type PostAaMode = "smaa" | "msaa" | false;
 export interface PostProcessingConfig {
     /** Master switch; a config object with `enabled: false` mounts nothing. Default true. */
     enabled?: boolean;
-    /** Tone-mapping curve the output stage applies. Default "aces". */
+    /** Tone-mapping curve the output stage applies. Default "agx". */
     toneMapping?: ToneMappingMode;
-    /** Exposure multiplier applied before tone mapping. Default 1. */
+    /**
+     * Exposure multiplier applied before tone mapping. Default 1. With `autoExposure` on this is the
+     * baseline the meter corrects around, not a fixed value.
+     */
     exposure?: number;
+    /**
+     * Clamped auto-exposure: meters the rendered frame and adapts exposure toward
+     * {@link import("./colorPipeline.js").MID_GREY}, bounded by `min`/`max`. Omitted uses
+     * {@link import("./colorPipeline.js").DEFAULT_AUTO_EXPOSURE} on every tier; `false` pins `exposure`.
+     */
+    autoExposure?: AutoExposureConfig | false;
     /**
      * Antialiasing. Default `"smaa"` (plus a light MSAA resolve on the beauty target).
      * Set `"msaa"` to skip the SMAA pass, or `false` for neither.

package/dist/render/postProcessing.js

@@ -7,7 +7,7 @@ export const DEFAULT_AO = { radius: 1.3, intensity: 1.3, distanceFalloff: 2.8, b
  * is left off by default (it needs a per-scene focus distance); set `dof` to enable it.
  */
 export const STUDIO_STAGE_POST = {
-    toneMapping: "aces",
+    toneMapping: "agx",
     exposure: 1.05,
     bloom: { strength: 0.28, radius: 0.6, threshold: 0.8 },
     ao: { radius: 1.1, intensity: 1.5, distanceFalloff: 3, blend: 1 },

package/dist/render/skyOwnedLighting.d.ts

@@ -0,0 +1,31 @@
+import type { LightingConfig } from "../game/playableGame.js";
+import type { SkyEnvironmentConfig } from "../world/features.js";
+/**
+ * Which half of a game's authored `lighting` a time-of-day sky takes over.
+ *
+ * A time-of-day sky has to move the sun or the whole world stays lit like noon after dark: the
+ * dome turns black while the ground keeps its midday key light. So under a day cycle the first
+ * directional light is the **sun**, and `ambient`/`hemisphere` are the **noon keyframes** of the
+ * ambient fill — the same convention the sky already uses for `horizonColor`/`zenithColor`. Every
+ * other light (fill directionals, point and spot lamps) stays exactly as authored.
+ */
+export interface SkyOwnedLighting {
+    /** Sun + ambient terms the sky now drives from the day cycle; intensities read as noon values. */
+    sky: LightingConfig;
+    /** Lights the sky does not own; mounted as authored. */
+    rest: LightingConfig;
+}
+/**
+ * Splits authored lighting into the sun/ambient terms a time-of-day sky drives and the rest.
+ * Returns an empty `sky` when the game authored no lighting, so callers can keep engine defaults.
+ * @capability day-night-sky hand the sun and ambient fill to the day cycle while authored lamps keep running
+ */
+export declare function splitSkyOwnedLighting(lighting: LightingConfig | undefined): SkyOwnedLighting;
+/**
+ * The authored `lighting` as the day cycle's **noon keyframes**, filling only the sky fields the
+ * game left unset. A game's midday sun, fill and fog therefore become the peak the cycle scales
+ * and cross-fades from, so an authored world gets a sunset and a night without re-authoring the
+ * same numbers in the sky. Authored sky fields always win over the lighting config.
+ * @capability day-night-sky read authored lighting as the day cycle's noon keyframe
+ */
+export declare function skyNoonKeyframes<T extends SkyEnvironmentConfig>(sky: T, lighting: LightingConfig | undefined, fogColor?: string): T;

package/dist/render/skyOwnedLighting.js

@@ -0,0 +1,46 @@
+/**
+ * Splits authored lighting into the sun/ambient terms a time-of-day sky drives and the rest.
+ * Returns an empty `sky` when the game authored no lighting, so callers can keep engine defaults.
+ * @capability day-night-sky hand the sun and ambient fill to the day cycle while authored lamps keep running
+ */
+export function splitSkyOwnedLighting(lighting) {
+    if (lighting === undefined)
+        return { sky: {}, rest: {} };
+    const directional = lighting.directional ?? [];
+    const [sun, ...fill] = directional;
+    const sky = {
+        ...(sun === undefined ? {} : { directional: [sun] }),
+        ...(lighting.ambient === undefined ? {} : { ambient: lighting.ambient }),
+        ...(lighting.hemisphere === undefined ? {} : { hemisphere: lighting.hemisphere }),
+    };
+    const rest = {
+        ...(fill.length === 0 ? {} : { directional: fill }),
+        ...(lighting.point === undefined ? {} : { point: lighting.point }),
+        ...(lighting.spot === undefined ? {} : { spot: lighting.spot }),
+        ...(lighting.maxDynamicLights === undefined ? {} : { maxDynamicLights: lighting.maxDynamicLights }),
+        ...(lighting.iblAmbientScale === undefined ? {} : { iblAmbientScale: lighting.iblAmbientScale }),
+        ...(lighting.fallbackKey === undefined ? {} : { fallbackKey: lighting.fallbackKey }),
+    };
+    return { sky, rest };
+}
+/**
+ * The authored `lighting` as the day cycle's **noon keyframes**, filling only the sky fields the
+ * game left unset. A game's midday sun, fill and fog therefore become the peak the cycle scales
+ * and cross-fades from, so an authored world gets a sunset and a night without re-authoring the
+ * same numbers in the sky. Authored sky fields always win over the lighting config.
+ * @capability day-night-sky read authored lighting as the day cycle's noon keyframe
+ */
+export function skyNoonKeyframes(sky, lighting, fogColor) {
+    const sun = lighting?.directional?.[0];
+    const fill = lighting?.hemisphere?.intensity ?? lighting?.ambient?.intensity;
+    const noon = { ...sky };
+    if (noon.sunIntensity === undefined && sun?.intensity !== undefined)
+        noon.sunIntensity = sun.intensity;
+    if (noon.ambientIntensity === undefined && fill !== undefined)
+        noon.ambientIntensity = fill;
+    if (noon.sunColor === undefined && sun?.color !== undefined)
+        noon.sunColor = sun.color;
+    if (noon.fogColor === undefined && fogColor !== undefined)
+        noon.fogColor = fogColor;
+    return noon;
+}

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/sensor/perception.d.ts

@@ -25,11 +25,17 @@ export interface PerceptionCandidate {
 /** A remembered target and its linearly decaying confidence. */
 export interface PerceptionMemory {
     targetId: string;
+    /** When the fact was observed, on the same clock `observe` is given; its age is `now − lastSeenAt`. */
     lastSeenAt: number;
     lastKnownPos: PerceptionPosition;
+    /** 1 at the moment of the sighting, falling to 0 across `memorySeconds`. */
     confidence: number;
+    /** Whose senses produced the fact: this observer's id for its own sighting, a squadmate's for a shared one. */
+    sourceId: string;
+    /** Observe pass that recorded the fact, so a shared sighting is attributable to the tick it arrived. */
+    sourceTick: number;
 }
-/** Configuration for sight, hearing, memory decay, and optional occlusion. */
+/** Configuration for sight, hearing, memory decay, squad sharing and optional occlusion. */
 export interface PerceptionConfig {
     sightRange: number;
     sightConeDeg: number;
@@ -37,7 +43,43 @@ export interface PerceptionConfig {
     memorySeconds: number;
     /** Most stimuli retained at once; the oldest are dropped first. Default 256. */
     maxStimuli?: number;
-    occluded?: (from: PerceptionPosition, to: PerceptionPosition) => boolean;
+    /**
+     * Cheap "nothing blocks the segment from `from` to `to`" test, supplied by the game's collision
+     * layer. Only called for pairs already inside range and cone, so the costly test sees the pruned
+     * set. Omit for open ground.
+     */
+    isSegmentClear?: (from: PerceptionPosition, to: PerceptionPosition) => boolean;
+    /**
+     * The other members of an observer's squad, by id. A sighting one member makes is written into
+     * each mate's memory with the seeing member's id and the pass it happened on. Omit for lone
+     * observers. Keep the returned set small — the roster is the caller's, so the caller bounds it.
+     */
+    squadMates?: (observerId: string) => Iterable<string>;
+    /** Most sighting shares one pass may write, so a large squad cannot blow the tick budget. Default 64. */
+    maxSharesPerTick?: number;
+    /** Register a devtools probe under this name so the overlay shows perception work and memory. */
+    devtoolsName?: string;
+}
+/** Counters a perf test or a devtools probe reads. Reset with {@link PerceptionService.resetStats}. */
+export interface PerceptionStats {
+    /** Observe passes run. Keeps counting across `resetStats`, since it is also the recorded tick. */
+    passes: number;
+    /** `(observer, candidate)` pairs examined — one check per pair per pass. */
+    pairChecks: number;
+    /** Pairs rejected by distance before any cone or occlusion work. */
+    rangeCulled: number;
+    /** Pairs inside sight range, so they paid the cone test. */
+    coneTests: number;
+    /** Calls into the injected `isSegmentClear`. */
+    occlusionChecks: number;
+    /** Pairs that produced the observer's own sighting. */
+    sightings: number;
+    /** Sound and damage stimuli an observer resolved inside its hearing range. */
+    heard: number;
+    /** Sightings written into a squadmate's memory. */
+    shares: number;
+    /** Sightings the per-pass share cap kept from being broadcast. */
+    shareDropped: number;
 }
 /** Serializable state for a perception service. */
 export interface PerceptionSnapshot {
@@ -52,19 +94,38 @@ export interface PerceptionSnapshot {
     /** Per observer, the last stimulus sequence number it has already judged. Absent in older saves. */
     heard?: Record<string, number>;
     nextSeq?: number;
+    /** Observe passes recorded, which is also the tick a memory carries. Absent in older saves. */
+    passes?: number;
 }
 /** Stateful perception API with retuning and save/restore support. */
 export interface PerceptionService {
     pushStimulus(stimulus: PerceptionStimulus): void;
     observe(observer: PerceptionObserver, candidates: readonly PerceptionCandidate[], nowMs: number): void;
     memory(observerId: string): PerceptionMemory[];
+    /** One remembered target with its confidence now, or `null` when never seen or already faded. */
+    memoryOf(observerId: string, targetId: string): PerceptionMemory | null;
     /** Drop one remembered target, or everything an observer remembers (despawn, reset, disguise). */
     forget(observerId: string, targetId?: string): void;
-    retune(patch: Partial<PerceptionConfig>): void;
+    stats(): PerceptionStats;
+    /** Zero the work counters, keeping the pass count that memories are stamped with. */
+    resetStats(): void;
+    retune(patch: Partial<Omit<PerceptionConfig, "devtoolsName">>): void;
     snapshot(): PerceptionSnapshot;
     restore(snapshot: PerceptionSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
 }
-/** 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
+/**
+ * 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 declare function createPerception(initial: PerceptionConfig): PerceptionService;

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;