@jgengine/core 0.17.0 → 0.18.1

package/dist/runtime/transport.d.ts

@@ -1,10 +1,38 @@
 import type { ChatSync } from "../multiplayer/chatContract.js";
 import type { PlayerPose } from "../multiplayer/poseSyncGate.js";
 import type { PresenceTransport } from "../multiplayer/presenceContract.js";
+import type { WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/** A revision-stamped world baseline or compact diff sent to a server-authoritative client. */
+export type WorldSyncFrame = {
+    kind: "baseline";
+    revision: number;
+    snapshot: WorldSnapshot;
+} | {
+    kind: "diff";
+    revision: number;
+    diff: WorldDiff;
+};
+/** A short-lived credential allowing a disconnected client to reclaim one server membership. */
+export type ResumeTicket = {
+    userId: string;
+    serverId: string;
+    token: string;
+};
 export type JoinServerResult = {
     serverId: string;
     isNew: boolean;
+    resumeTicket?: ResumeTicket;
+};
+/** Join failures are returned to the caller so the triggering surface can offer retry. */
+export type JoinServerOutcome = (JoinServerResult & {
+    ok: true;
+}) | {
+    ok: false;
+    reason: "full" | "closed" | "unauthorized";
 };
+/** Connection role used for authoritative world access; spectators are read-only. */
+export type MultiplayerRole = "player" | "spectator";
 export type RunCommandArgs = {
     serverId: string;
     command: string;
@@ -21,7 +49,7 @@ export type GameRuntimeServerView = {
     gameId: string;
     revision: number;
     memberUserIds: string[];
-    serverState: unknown;
+    serverState: unknown | WorldSyncFrame;
     updatedAt: number;
 };
 export type GameRuntimePlayerView = {
@@ -38,7 +66,8 @@ export type GameRuntimeTransport = {
     joinServer: (args: {
         gameId: string;
         serverId?: string;
-    }) => Promise<JoinServerResult>;
+        role?: MultiplayerRole;
+    }) => Promise<JoinServerOutcome>;
     leaveServer: (args: {
         serverId: string;
     }) => Promise<void>;
@@ -54,6 +83,7 @@ export type GameRuntimeFeeds = {
         serverId: string;
         action: string;
     }, onChange: (view: GameRuntimeFeedView) => void) => FeedUnsubscribe;
+    requestServerBaseline?: (serverId: string) => void;
 };
 export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = {
     transport: GameRuntimeTransport;
@@ -62,6 +92,12 @@ export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGa
 };
 export type PresencePoseRow = {
     userId: string;
+    /** Set when the host tracks presence per session, so one user can hold two rows. */
+    sessionId?: string;
+    /** Actor class, e.g. `"player"` / `"agent"` — a host may clamp each differently. */
+    kind?: string;
+    /** Display name carried on the row, so a nameplate needs no second lookup. */
+    label?: string;
     position: {
         x: number;
         y: number;

package/dist/runtime/worldChunks.d.ts

@@ -37,3 +37,5 @@ export declare function setChunk(snapshot: GameRuntimeSnapshot, chunkKey: string
 export declare function updateChunk(snapshot: GameRuntimeSnapshot, chunkKey: string, update: (chunk: RuntimeChunkRow) => RuntimeChunkRow): GameRuntimeSnapshot;
 /** Drop a chunk from a snapshot and mark the key dirty so the host deletes its stored row. */
 export declare function deleteChunk(snapshot: GameRuntimeSnapshot, chunkKey: string): GameRuntimeSnapshot;
+/** Square chunk neighborhood around a world position, including its own chunk. */
+export declare function chunkKeysAround(position: readonly [number, number, number], rings?: number, size?: number): string[];

package/dist/runtime/worldChunks.js

@@ -81,3 +81,17 @@ export function deleteChunk(snapshot, chunkKey) {
         dirty: { ...snapshot.dirty, server: true, chunks: withChunkDirty(snapshot, chunkKey) },
     };
 }
+/** Square chunk neighborhood around a world position, including its own chunk. */
+export function chunkKeysAround(position, rings = 1, size = DEFAULT_CHUNK_SIZE) {
+    if (!Number.isSafeInteger(rings) || rings < 0 || rings > 128)
+        throw new RangeError("rings must be an integer from 0 to 128");
+    if (!Number.isFinite(size) || size <= 0 || !position.every(Number.isFinite))
+        throw new RangeError("Invalid chunk position or size");
+    const center = chunkCoordAt(position, size);
+    const keys = [];
+    for (let cx = center.cx - rings; cx <= center.cx + rings; cx++) {
+        for (let cz = center.cz - rings; cz <= center.cz + rings; cz++)
+            keys.push(chunkKeyOf({ cx, cz }));
+    }
+    return keys;
+}

package/dist/runtime/worldProjection.d.ts

@@ -8,6 +8,11 @@ import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
  * growing a per-feature branch.
  */
 export interface ReplicationPolicy {
+    /** Decimal places used for replicated positions and angles. */
+    quantize?: {
+        position?: number;
+        angle?: number;
+    };
     /**
      * Replicate each player's private per-user state (inventory) only to that player — other viewers
      * receive none of it. Off by default so existing games keep broadcasting every player's state.
@@ -24,6 +29,10 @@ export interface ReplicationPolicy {
  * @internal host projection plumbing — games set ReplicationPolicy; the runtime applies it.
  */
 export declare function policyProjectsViewers(policy: ReplicationPolicy | undefined): boolean;
+/** Quantize replicated entity poses according to a host projection policy.
+ * @internal host projection plumbing
+ */
+export declare function quantizeWorldForReplication(world: WorldSnapshot, policy: ReplicationPolicy | undefined): WorldSnapshot;
 /**
  * Cull an entity list to a viewer's area of interest: keep the viewer's own entity plus every entity
  * within `radius` of it. When the viewer has no locatable entity the full list is returned (fail-open —

package/dist/runtime/worldProjection.js

@@ -4,7 +4,23 @@
 export function policyProjectsViewers(policy) {
     if (policy === undefined)
         return false;
-    return policy.privatePerUser === true || policy.aoiRadius !== undefined;
+    return policy.privatePerUser === true || policy.aoiRadius !== undefined || policy.quantize !== undefined;
+}
+/** Quantize replicated entity poses according to a host projection policy.
+ * @internal host projection plumbing
+ */
+export function quantizeWorldForReplication(world, policy) {
+    if (policy?.quantize?.position === undefined && policy?.quantize?.angle === undefined)
+        return world;
+    const digits = (value, places) => places === undefined ? value : Number(value.toFixed(Math.max(0, places)));
+    const entities = world["entities"]?.map((entity) => ({
+        ...entity,
+        position: entity.position.map((value) => digits(value, policy.quantize?.position)),
+        rotationY: digits(entity.rotationY, policy.quantize?.angle),
+        rotationX: digits(entity.rotationX, policy.quantize?.angle),
+        rotationZ: digits(entity.rotationZ, policy.quantize?.angle),
+    }));
+    return entities === undefined ? world : { ...world, entities };
 }
 function distanceSquared(a, b) {
     const dx = a[0] - b[0];

package/dist/runtime/worldSnapshot.d.ts

@@ -1,6 +1,10 @@
 /** Who a host→client snapshot is being projected for — the identity a {@link SnapshotModule.project} filters against. */
 export interface SnapshotViewer {
     readonly userId: string;
+    /** A read-only connection role; spectators receive snapshots but cannot mutate the world. */
+    readonly role?: "player" | "spectator";
+    /** Host tick used by {@link SnapshotModule.priority} to throttle low-priority modules. */
+    readonly tick?: number;
 }
 /**
  * The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the
@@ -37,6 +41,8 @@ export interface SnapshotModule<T = unknown> {
     project?(data: T, viewer: SnapshotViewer, world: WorldSnapshot): T;
     /** Monotone change counter; unchanged between host commits means this module didn't mutate and need not re-serialize. */
     version?(): number;
+    /** Return the host tick interval for this module; values greater than one omit it on intervening ticks. */
+    priority?(data: T, viewer: SnapshotViewer): number;
 }
 /** Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem. */
 export type WorldSnapshot = Record<string, unknown>;

package/dist/runtime/worldSnapshot.js

@@ -13,6 +13,9 @@ export function composeWorldSnapshot(modules, viewer) {
     const snapshot = {};
     for (const module of modules) {
         const value = raw[module.key];
+        const interval = viewer?.tick === undefined ? 1 : Math.max(1, Math.floor(module.priority?.(value, viewer) ?? 1));
+        if (viewer?.tick !== undefined && interval > 1 && viewer.tick % interval !== 0)
+            continue;
         snapshot[module.key] =
             module.project !== undefined ? module.project(value, viewer, raw) : value;
     }

package/dist/scene/behaviorRuntime.d.ts

@@ -1,8 +1,22 @@
+import type { DecisionAction, DecisionGraphRuntime } from "../ai/decisionGraph.js";
+import { type InterestGateState } from "../ai/interestScheduler.js";
 import { type PathFollowState, type PathProgress, type Waypoint } from "../nav/pathFollow.js";
 import type { GameContext } from "../runtime/gameContext.js";
 /** Whether a behavior instance advances and writes pose (`active`), is temporarily suspended retaining
  * state (`paused`), or is held off until re-enabled (`disabled`). */
 export type BehaviorStatus = "active" | "paused" | "disabled";
+/** Context supplied to a registered decision graph action. */
+export interface BehaviorActionContext {
+    ctx: GameContext;
+    entityId: string;
+    dt: number;
+}
+/** Callback used by a registered decision graph behavior action. */
+export type BehaviorAction = DecisionAction<BehaviorActionContext>;
+/** Register the named actions used by decision graph behavior descriptors.
+ * @capability behavior-actions register named callbacks for decision graph behavior descriptors
+ */
+export declare function registerBehaviorActions(id: string, actions: Record<string, BehaviorAction>): () => void;
 /**
  * Catch-up policy applied when a paused instance resumes. `freeze` (default, deterministic) discards
  * the time spent paused; `advance` silently fast-forwards the instance by the paused duration without
@@ -18,11 +32,15 @@ export type BehaviorSnapshot = {
     readonly kind: "wander";
     readonly origin: Waypoint;
     readonly target: Waypoint | null;
+} | {
+    readonly kind: "decisionGraph";
+    readonly graph: ReturnType<DecisionGraphRuntime["snapshot"]>;
+    readonly gate: InterestGateState;
 };
 /** Inspection readout for editor/debug tooling, from {@link BehaviorControl.inspect}/{@link BehaviorControl.list}. */
 export interface BehaviorInspection {
     id: string;
-    kind: "patrol" | "wander";
+    kind: "patrol" | "wander" | "decisionGraph";
     status: BehaviorStatus;
     reason: string | null;
 }

package/dist/scene/behaviorRuntime.js

@@ -1,4 +1,5 @@
-import { seededRng } from "../random/rng.js";
+import { createDecisionGraphRuntime } from "../ai/decisionGraph.js";
+import { advanceInterestGate, createInterestGateState } from "../ai/interestScheduler.js";
 import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
 import { resolveWalkerStep } from "../movement/solidObstacles.js";
 import { perContext } from "../runtime/perContext.js";
@@ -6,12 +7,27 @@ const DEFAULT_WANDER_SPEED = 1.5;
 const WANDER_ARRIVAL = 0.6;
 /** Below this share of its intended step a wanderer counts as blocked and re-rolls its target. */
 const WANDER_BLOCKED_FRACTION = 0.25;
+const behaviorActions = new Map();
+/** Register the named actions used by decision graph behavior descriptors.
+ * @capability behavior-actions register named callbacks for decision graph behavior descriptors
+ */
+export function registerBehaviorActions(id, actions) {
+    behaviorActions.set(id, actions);
+    return () => {
+        if (behaviorActions.get(id) === actions)
+            behaviorActions.delete(id);
+    };
+}
+const DECISION_GRAPH_CADENCE = { wakeRadius: Number.POSITIVE_INFINITY, activeInterval: 0 };
 function patrolOf(entity) {
     return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
 }
 function wanderOf(entity) {
     return entity.behaviors.find((b) => b.kind === "wander") ?? null;
 }
+function decisionGraphOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "decisionGraph") ?? null;
+}
 const runtimeOf = perContext((ctx) => {
     const nav = new Map();
     const refresh = () => {
@@ -41,7 +57,23 @@ const runtimeOf = perContext((ctx) => {
                     radius: wander.radius,
                     origin: entity.position,
                     target: null,
-                    roll: seededRng(`wander:${entity.id}`),
+                    roll: () => ctx.rng(),
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+                continue;
+            }
+            const decisionGraph = decisionGraphOf(entity);
+            if (decisionGraph !== null) {
+                const actions = behaviorActions.get(decisionGraph.actions);
+                if (actions === undefined)
+                    continue;
+                nav.set(entity.id, {
+                    kind: "decisionGraph",
+                    behavior: decisionGraph,
+                    runtime: createDecisionGraphRuntime(decisionGraph.graph, actions),
+                    gate: createInterestGateState(DECISION_GRAPH_CADENCE, ctx.rng()),
                     status: "active",
                     reason: null,
                     pausedElapsed: 0,
@@ -135,9 +167,21 @@ export function advanceBehaviors(ctx, dt) {
             entry.state = advancePathFollow(entry.config, entry.state, dt);
             posePatrol(ctx, id, entry, dt);
         }
-        else {
+        else if (entry.kind === "wander") {
             stepWander(ctx, id, entry, dt);
         }
+        else {
+            const entity = ctx.scene.entity.get(id);
+            if (entity === null)
+                continue;
+            const step = advanceInterestGate(entry.gate, DECISION_GRAPH_CADENCE, dt, { proximity: 0 });
+            if (!step.active)
+                continue;
+            const blackboard = {};
+            const status = entry.runtime.tick({ ctx, entityId: id, dt }, blackboard, dt);
+            if (status === "done" || status === "failed")
+                entry.runtime.restore({ runningPath: null });
+        }
     }
 }
 /**
@@ -206,7 +250,9 @@ export function behaviorControl(ctx) {
                 return null;
             if (entry.kind === "patrol")
                 return { kind: "patrol", state: { ...entry.state } };
-            return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+            if (entry.kind === "wander")
+                return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+            return { kind: "decisionGraph", graph: entry.runtime.snapshot(), gate: { ...entry.gate } };
         },
         restore: (id, snapshot) => {
             const entry = nav.get(id);
@@ -216,6 +262,11 @@ export function behaviorControl(ctx) {
                 entry.state = { ...snapshot.state };
                 return true;
             }
+            if (entry.kind === "decisionGraph" && snapshot.kind === "decisionGraph") {
+                entry.runtime.restore(snapshot.graph);
+                entry.gate = { ...snapshot.gate };
+                return true;
+            }
             if (entry.kind === "wander" && snapshot.kind === "wander") {
                 entry.origin = [...snapshot.origin];
                 entry.target = snapshot.target === null ? null : [...snapshot.target];

package/dist/scene/behaviors.d.ts

@@ -1,5 +1,6 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
 import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
+import type { DecisionGraph } from "../ai/decisionGraph.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -27,7 +28,13 @@ export interface PromptableBehavior {
 export interface PlayerBehavior {
     kind: "player";
 }
-export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior;
+/** Decision graph behavior descriptor using a named registered action set. */
+export interface DecisionGraphBehavior {
+    kind: "decisionGraph";
+    graph: DecisionGraph;
+    actions: string;
+}
+export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior | DecisionGraphBehavior;
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;

package/dist/scene/builtinSceneKinds.js

@@ -37,6 +37,15 @@ export const SCATTER_SCHEMA = {
         { type: "seed", key: "seed", label: "seed", default: "" },
     ],
 };
+const LIGHT_SCHEMA = {
+    fields: [
+        { type: "select", key: "type", label: "type", options: [{ value: "point", label: "Point" }, { value: "spot", label: "Spot" }], default: "point" },
+        { type: "color", key: "color", label: "color", default: "#ffd6a0" },
+        { type: "number", key: "intensity", label: "intensity", min: 0, step: 0.1, default: 2 },
+        { type: "number", key: "range", label: "range", min: 0, step: 0.5, default: 12 },
+        { type: "bool", key: "castShadow", label: "cast shadow", default: false },
+    ],
+};
 let registered = false;
 /** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
 export function registerBuiltinSceneKinds() {
@@ -65,6 +74,7 @@ export function registerBuiltinSceneKinds() {
             return describeScatterCoverage(densityCoverage("scatter", area, density));
         },
     });
+    registerSceneKind({ kind: "light", target: "marker", label: "Light", addCategory: "Environment", accent: "#fbbf24", schema: LIGHT_SCHEMA });
     registerWaterKind();
     registerGrassKind();
     registerSoilKind();

package/dist/sensor/perception.d.ts

@@ -0,0 +1,60 @@
+/** A world position used by perception, in `[x, y, z]` order. */
+export type PerceptionPosition = readonly [number, number, number];
+/** The kinds of stimulus the perception service can retain. */
+export type PerceptionStimulusKind = "sight" | "sound" | "damage";
+/** An event that can seed an observer's memory. */
+export interface PerceptionStimulus {
+    kind: PerceptionStimulusKind;
+    sourceId: string;
+    position: PerceptionPosition;
+    loudness?: number;
+    at: number;
+}
+/** The observer pose used for a sight check. */
+export interface PerceptionObserver {
+    id: string;
+    position: PerceptionPosition;
+    yaw: number;
+}
+/** A candidate target considered by a sight check. */
+export interface PerceptionCandidate {
+    id: string;
+    position: PerceptionPosition;
+}
+/** A remembered target and its linearly decaying confidence. */
+export interface PerceptionMemory {
+    targetId: string;
+    lastSeenAt: number;
+    lastKnownPos: PerceptionPosition;
+    confidence: number;
+}
+/** Configuration for sight, hearing, memory decay, and optional occlusion. */
+export interface PerceptionConfig {
+    sightRange: number;
+    sightConeDeg: number;
+    hearingRange: number;
+    memorySeconds: number;
+    occluded?: (from: PerceptionPosition, to: PerceptionPosition) => boolean;
+}
+/** Serializable state for a perception service. */
+export interface PerceptionSnapshot {
+    memories: Array<{
+        observerId: string;
+        memory: PerceptionMemory;
+    }>;
+    stimuli: PerceptionStimulus[];
+    nowMs: 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[];
+    retune(patch: Partial<PerceptionConfig>): void;
+    snapshot(): PerceptionSnapshot;
+    restore(snapshot: PerceptionSnapshot): 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
+ */
+export declare function createPerception(initial: PerceptionConfig): PerceptionService;

package/dist/sensor/perception.js

@@ -0,0 +1,142 @@
+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.");
+    if (!Number.isFinite(config.sightConeDeg) || config.sightConeDeg < 0 || config.sightConeDeg > 360)
+        throw new Error("sightConeDeg must be between 0 and 360.");
+    if (!Number.isFinite(config.hearingRange) || config.hearingRange < 0)
+        throw new Error("hearingRange must be non-negative.");
+    if (!Number.isFinite(config.memorySeconds) || config.memorySeconds <= 0)
+        throw new Error("memorySeconds must be positive.");
+}
+/** 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
+ */
+export function createPerception(initial) {
+    validate(initial);
+    let config = { ...initial };
+    let nowMs = 0;
+    const stimuli = [];
+    const memories = new Map();
+    function remember(observerId, targetId, position, at, confidence) {
+        if (confidence <= 0)
+            return;
+        let observerMemories = memories.get(observerId);
+        if (observerMemories === undefined) {
+            observerMemories = new Map();
+            memories.set(observerId, observerMemories);
+        }
+        const previous = observerMemories.get(targetId);
+        if (previous === undefined || at >= previous.lastSeenAt) {
+            observerMemories.set(targetId, { targetId, lastSeenAt: at, lastKnownPos: [...position], confidence });
+        }
+    }
+    function prune() {
+        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);
+        }
+        const cutoff = nowMs - memoryMs;
+        while (stimuli.length > 0 && stimuli[0].at < cutoff)
+            stimuli.shift();
+    }
+    return {
+        pushStimulus(stimulus) {
+            if (!Number.isFinite(stimulus.at))
+                throw new Error("stimulus.at must be finite.");
+            if (stimulus.kind === "sound" && stimulus.loudness !== undefined && (!Number.isFinite(stimulus.loudness) || stimulus.loudness < 0)) {
+                throw new Error("stimulus.loudness must be non-negative.");
+            }
+            stimuli.push({ ...stimulus, position: [...stimulus.position] });
+            stimuli.sort((a, b) => a.at - b.at);
+            nowMs = Math.max(nowMs, stimulus.at);
+            prune();
+        },
+        observe(observer, candidates, observedAt) {
+            if (!Number.isFinite(observedAt))
+                throw new Error("nowMs must be finite.");
+            nowMs = observedAt;
+            for (const candidate of candidates) {
+                if (!inSight(observer, candidate.position, config))
+                    continue;
+                if (config.occluded?.(observer.position, candidate.position))
+                    continue;
+                remember(observer.id, candidate.id, candidate.position, nowMs, 1);
+            }
+            for (const stimulus of stimuli) {
+                if (stimulus.at > nowMs || stimulus.sourceId === observer.id)
+                    continue;
+                const range = distance(observer.position, stimulus.position);
+                if (stimulus.kind === "sound") {
+                    if (range > config.hearingRange)
+                        continue;
+                    const falloff = 1 - range / Math.max(config.hearingRange, 1e-9);
+                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, falloff * (stimulus.loudness ?? 1));
+                }
+                else if (stimulus.kind === "damage") {
+                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1);
+                }
+            }
+            prune();
+        },
+        memory(observerId) {
+            const observerMemories = memories.get(observerId);
+            if (observerMemories === undefined)
+                return [];
+            const memoryMs = config.memorySeconds * 1000;
+            const result = [];
+            for (const memory of observerMemories.values()) {
+                const confidence = confidenceAt(memory, nowMs, memoryMs);
+                if (confidence > 0)
+                    result.push({ ...memory, lastKnownPos: [...memory.lastKnownPos], confidence });
+            }
+            return result;
+        },
+        retune(patch) {
+            config = { ...config, ...patch };
+            validate(config);
+            prune();
+        },
+        snapshot() {
+            const result = { memories: [], stimuli: stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })), nowMs };
+            for (const [observerId, observerMemories] of memories)
+                for (const memory of observerMemories.values())
+                    result.memories.push({ observerId, memory: { ...memory, lastKnownPos: [...memory.lastKnownPos] } });
+            return result;
+        },
+        restore(snapshot) {
+            memories.clear();
+            stimuli.length = 0;
+            nowMs = snapshot.nowMs;
+            stimuli.push(...snapshot.stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })));
+            for (const entry of snapshot.memories)
+                remember(entry.observerId, entry.memory.targetId, entry.memory.lastKnownPos, entry.memory.lastSeenAt, entry.memory.confidence);
+            prune();
+        },
+    };
+}

package/dist/settings/graphicsProfile.d.ts

@@ -0,0 +1,19 @@
+import type { GraphicsQuality } from "./settingsModel.js";
+/** Serializable renderer budget selected by the player's graphics tier. */
+export interface GraphicsProfile {
+    renderScale: number;
+    shadowMapSize: 512 | 1024 | 2048 | 4096;
+    cascades: 1 | 2 | 3 | 4;
+    drawDistance: number;
+    particleCap: number;
+    postStages: {
+        ao: boolean;
+        bloom: boolean;
+        dof: boolean;
+        smaa: boolean;
+    };
+}
+/** Conservative defaults that preserve the existing high-quality shell behavior. */
+export declare const DEFAULT_GRAPHICS_PROFILES: Record<GraphicsQuality, GraphicsProfile>;
+/** Resolve one tier and apply game-authored field and post-stage overrides. */
+export declare function resolveGraphicsProfile(quality: GraphicsQuality, overrides?: Partial<GraphicsProfile>): GraphicsProfile;

package/dist/settings/graphicsProfile.js

@@ -0,0 +1,36 @@
+/** Conservative defaults that preserve the existing high-quality shell behavior. */
+export const DEFAULT_GRAPHICS_PROFILES = {
+    low: {
+        renderScale: 1,
+        shadowMapSize: 512,
+        cascades: 1,
+        drawDistance: 120,
+        particleCap: 128,
+        postStages: { ao: false, bloom: true, dof: false, smaa: true },
+    },
+    medium: {
+        renderScale: 1.5,
+        shadowMapSize: 1024,
+        cascades: 2,
+        drawDistance: 240,
+        particleCap: 256,
+        postStages: { ao: true, bloom: true, dof: true, smaa: true },
+    },
+    high: {
+        renderScale: 2,
+        shadowMapSize: 2048,
+        cascades: 4,
+        drawDistance: 400,
+        particleCap: 512,
+        postStages: { ao: true, bloom: true, dof: true, smaa: true },
+    },
+};
+/** Resolve one tier and apply game-authored field and post-stage overrides. */
+export function resolveGraphicsProfile(quality, overrides) {
+    const base = DEFAULT_GRAPHICS_PROFILES[quality];
+    return {
+        ...base,
+        ...overrides,
+        postStages: { ...base.postStages, ...overrides?.postStages },
+    };
+}

package/dist/time/accrueSince.d.ts

@@ -0,0 +1,10 @@
+/** Elapsed duration and the next anchor to persist with accrued effects. */
+export interface Accrual {
+    elapsedMs: number;
+    elapsedSeconds: number;
+    anchorMs: number;
+}
+/** Elapsed time since a persisted anchor, capped once; persist anchorMs with the accrued result. */
+export declare function accrueSince(anchorMs: number, nowMs: number, options?: {
+    capMs?: number;
+}): Accrual;

package/dist/time/accrueSince.js

@@ -0,0 +1,9 @@
+/** Elapsed time since a persisted anchor, capped once; persist anchorMs with the accrued result. */
+export function accrueSince(anchorMs, nowMs, options = {}) {
+    const cap = options.capMs ?? Infinity;
+    if (!Number.isFinite(anchorMs) || !Number.isFinite(nowMs) || Number.isNaN(cap) || cap < 0) {
+        throw new RangeError("Accrual requires finite anchors and a nonnegative cap");
+    }
+    const elapsedMs = Math.min(cap, Math.max(0, nowMs - anchorMs));
+    return { elapsedMs, elapsedSeconds: elapsedMs / 1000, anchorMs: Math.max(anchorMs, nowMs) };
+}