@jgengine/core 0.18.1 → 0.21.0

package/dist/visibility/assetStreaming.js

@@ -1,14 +1,31 @@
 import { DEFAULT_STREAMING_SETTINGS, mergeStreamingSettings } from "./settings.js";
 import { nowMs } from "./diagnostics.js";
+/** Stream shared resources with bounded load concurrency, per-tick resident-byte eviction, and explicit inactive-history cleanup. */
 export function createAssetStreamingSystem(options) {
-    const settings = mergeStreamingSettings(DEFAULT_STREAMING_SETTINGS, options.settings ?? {});
+    function mergeSettings(base, patch) {
+        const next = mergeStreamingSettings(base, patch);
+        if (!Number.isSafeInteger(next.maxConcurrentLoads) || next.maxConcurrentLoads < 0) {
+            throw new RangeError("AssetStreamingSystem: maxConcurrentLoads must be a nonnegative safe integer");
+        }
+        if (next.maxResidentBytes !== Infinity && (!Number.isFinite(next.maxResidentBytes) || next.maxResidentBytes < 0)) {
+            throw new RangeError("AssetStreamingSystem: maxResidentBytes must be nonnegative and finite, or Infinity");
+        }
+        if (next.residentEvictionOrder !== "oldest" && next.residentEvictionOrder !== "largest") {
+            throw new RangeError("AssetStreamingSystem: residentEvictionOrder must be oldest or largest");
+        }
+        return next;
+    }
+    let settings = mergeSettings(DEFAULT_STREAMING_SETTINGS, options.settings ?? {});
     const clock = options.now ?? nowMs;
     const records = new Map();
     const queued = new Set();
+    const residents = new Set();
+    const unknownSizes = new Set();
     const signals = new Map();
     const inFlight = new Set();
     let unloadedTotal = 0;
     let cancelledTotal = 0;
+    let budgetEvictedTotal = 0;
     function ensure(id) {
         let record = records.get(id);
         if (record === undefined) {
@@ -31,29 +48,56 @@ export function createAssetStreamingSystem(options) {
         record.state = "loading";
         const signal = { cancelled: false };
         signals.set(record.id, signal);
-        const promise = options
-            .load(record.id, signal)
+        let loading;
+        try {
+            loading = options.load(record.id, signal);
+        }
+        catch (error) {
+            loading = Promise.reject(error);
+        }
+        const promise = loading
             .then((result) => {
-            signals.delete(record.id);
-            if (signal.cancelled || !records.has(record.id)) {
-                record.state = "unloaded";
+            if (signal.cancelled || records.get(record.id) !== record) {
+                options.unload?.(record.id);
                 return;
             }
             record.state = "loaded";
-            record.bytes = result.bytes ?? 0;
+            const knownSize = typeof result.bytes === "number" && Number.isFinite(result.bytes) && result.bytes >= 0;
+            record.bytes = knownSize ? result.bytes : 0;
+            if (!knownSize)
+                unknownSizes.add(record);
             record.value = result.value;
             record.lastActiveMs = clock();
+            residents.add(record);
         })
             .catch(() => {
-            signals.delete(record.id);
-            if (!signal.cancelled)
+            if (!signal.cancelled && records.get(record.id) === record)
                 record.state = "error";
         })
             .finally(() => {
+            if (signals.get(record.id) === signal)
+                signals.delete(record.id);
             inFlight.delete(promise);
         });
         inFlight.add(promise);
     }
+    function unprotected(record) {
+        return record.state === "loaded" && !record.pinned && record.refCount === 0;
+    }
+    function compareEviction(a, b) {
+        if (settings.residentEvictionOrder === "largest" && a.bytes !== b.bytes)
+            return b.bytes - a.bytes;
+        return a.lastActiveMs - b.lastActiveMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    }
+    function unload(record) {
+        options.unload?.(record.id);
+        residents.delete(record);
+        unknownSizes.delete(record);
+        record.state = "unloaded";
+        record.bytes = 0;
+        record.value = undefined;
+        unloadedTotal += 1;
+    }
     function evictable(record, now) {
         if (record.state !== "loaded")
             return false;
@@ -92,29 +136,45 @@ export function createAssetStreamingSystem(options) {
         },
         tick() {
             const now = clock();
-            if (queued.size > 0) {
+            if (queued.size > 0 && signals.size < settings.maxConcurrentLoads) {
                 const pending = [];
                 for (const id of queued) {
                     const record = records.get(id);
-                    if (record !== undefined)
+                    if (record !== undefined && !signals.has(id))
                         pending.push(record);
                 }
                 pending.sort((a, b) => b.priority - a.priority);
-                const budget = Math.min(settings.maxLoadsPerFrame, pending.length);
-                for (let i = 0; i < budget; i += 1)
-                    startLoad(pending[i]);
+                const budget = Math.min(settings.maxLoadsPerFrame, settings.maxConcurrentLoads - signals.size, pending.length);
+                for (let i = 0; i < budget && signals.size < settings.maxConcurrentLoads; i += 1) {
+                    const record = pending[i];
+                    if (queued.has(record.id) && records.get(record.id) === record && !signals.has(record.id))
+                        startLoad(record);
+                }
             }
+            let bytes = 0;
+            for (const record of residents)
+                bytes += record.bytes;
             let unloads = 0;
-            for (const record of records.values()) {
+            while (bytes > settings.maxResidentBytes && unloads < settings.maxUnloadsPerFrame) {
+                let candidate;
+                for (const record of residents) {
+                    if (record.bytes > 0 && unprotected(record) && (candidate === undefined || compareEviction(record, candidate) < 0))
+                        candidate = record;
+                }
+                if (candidate === undefined)
+                    break;
+                const releasedBytes = candidate.bytes;
+                unload(candidate);
+                bytes -= releasedBytes;
+                budgetEvictedTotal += 1;
+                unloads += 1;
+            }
+            for (const record of residents) {
                 if (unloads >= settings.maxUnloadsPerFrame)
                     break;
                 if (!evictable(record, now))
                     continue;
-                options.unload?.(record.id);
-                record.state = "unloaded";
-                record.bytes = 0;
-                record.value = undefined;
-                unloadedTotal += 1;
+                unload(record);
                 unloads += 1;
             }
         },
@@ -127,7 +187,7 @@ export function createAssetStreamingSystem(options) {
                 return;
             }
             const signal = signals.get(assetId);
-            if (signal !== undefined) {
+            if (signal !== undefined && !signal.cancelled) {
                 signal.cancelled = true;
                 const record = records.get(assetId);
                 if (record !== undefined)
@@ -135,6 +195,9 @@ export function createAssetStreamingSystem(options) {
                 cancelledTotal += 1;
             }
         },
+        retune(patch) {
+            settings = mergeSettings(settings, patch);
+        },
         stateOf(assetId) {
             return records.get(assetId)?.state;
         },
@@ -144,8 +207,16 @@ export function createAssetStreamingSystem(options) {
         record(assetId) {
             return records.get(assetId);
         },
+        forget(assetId) {
+            const record = records.get(assetId);
+            if (record === undefined || record.pinned || record.refCount > 0 || signals.has(assetId) || queued.has(assetId))
+                return false;
+            if (record.state !== "unloaded" && record.state !== "error")
+                return false;
+            return records.delete(assetId);
+        },
         stats() {
-            let queuedCount = 0, loading = 0, loaded = 0, errored = 0, bytes = 0;
+            let queuedCount = 0, loading = 0, loaded = 0, errored = 0, bytes = 0, protectedBytes = 0, unknownSizeLoaded = 0;
             for (const record of records.values()) {
                 switch (record.state) {
                     case "queued":
@@ -157,6 +228,10 @@ export function createAssetStreamingSystem(options) {
                     case "loaded":
                         loaded += 1;
                         bytes += record.bytes;
+                        if (record.pinned || record.refCount > 0)
+                            protectedBytes += record.bytes;
+                        if (unknownSizes.has(record))
+                            unknownSizeLoaded += 1;
                         break;
                     case "error":
                         errored += 1;
@@ -172,6 +247,11 @@ export function createAssetStreamingSystem(options) {
                 inFlight: inFlight.size,
                 cancelled: cancelledTotal,
                 bytes,
+                records: records.size,
+                protectedBytes,
+                unknownSizeLoaded,
+                overBudgetBytes: Math.max(0, bytes - settings.maxResidentBytes),
+                budgetEvicted: budgetEvictedTotal,
             };
         },
         applyTo(stats) {
@@ -190,12 +270,16 @@ export function createAssetStreamingSystem(options) {
         clear() {
             for (const signal of signals.values())
                 signal.cancelled = true;
+            const loaded = [...records.values()].filter((record) => record.state === "loaded").map((record) => record.id);
             records.clear();
             queued.clear();
-            signals.clear();
-            inFlight.clear();
+            residents.clear();
+            unknownSizes.clear();
+            budgetEvictedTotal = 0;
             unloadedTotal = 0;
             cancelledTotal = 0;
+            for (const id of loaded)
+                options.unload?.(id);
         },
     };
 }

package/dist/visibility/settings.d.ts

@@ -23,11 +23,17 @@ export interface StreamingSettings {
     readonly enabled: boolean;
     /** Extra world units around the camera whose assets are preloaded ahead of visibility. */
     readonly preloadMargin: number;
-    /** Seconds an asset must stay outside the active area before it is eligible for unload. */
+    /** Idle unload delay; resident-byte pressure can evict unprotected assets sooner. */
     readonly unloadGraceSeconds: number;
     readonly maxLoadsPerFrame: number;
+    /** Maximum unresolved loads, including cancelled work until its loader settles. Zero pauses new loads. */
+    readonly maxConcurrentLoads: number;
     readonly maxUnloadsPerFrame: number;
-    /** Assets at or below this byte size are kept resident once loaded (small shared assets). */
+    /** Resident-byte target, enforced on ticks within maxUnloadsPerFrame; protected assets may exceed it. */
+    readonly maxResidentBytes: number;
+    /** Budget eviction order. Ties use oldest activity then asset id for deterministic selection. */
+    readonly residentEvictionOrder: "oldest" | "largest";
+    /** Small shared assets survive idle unloading, but remain eligible under resident-byte pressure. */
     readonly keepResidentBytes: number;
 }
 export declare const DEFAULT_STREAMING_SETTINGS: StreamingSettings;

package/dist/visibility/settings.js

@@ -13,8 +13,11 @@ export const DEFAULT_STREAMING_SETTINGS = {
     preloadMargin: 32,
     unloadGraceSeconds: 10,
     maxLoadsPerFrame: 4,
+    maxConcurrentLoads: 4,
     maxUnloadsPerFrame: 2,
     keepResidentBytes: 64 * 1024,
+    maxResidentBytes: Infinity,
+    residentEvictionOrder: "oldest",
 };
 const EMPTY = {};
 /** Merge override layers by precedence: earlier arguments win. Pass object, then layer, then scene, then global. */

package/dist/visibility/simulationCulling.d.ts

@@ -1,4 +1,4 @@
-import type { LodBand } from "../world/lod.js";
+import type { LodBand, LodSchedulerState } from "../world/lod.js";
 /**
  * Simulation culling is a SEPARATE, opt-in system from render culling. Render culling only
  * decides what is drawn; this decides whether a low-priority off-screen entity updates this
@@ -23,6 +23,11 @@ export interface SimulationDecision {
     /** Seconds of accumulated time delivered when `update` is true (for catch-up integration). */
     elapsed: number;
 }
+/** Plain JSON state of a {@link SimulationCuller}: the enabled flag and each id's throttle accumulator. */
+export interface SimulationCullerState {
+    enabled: boolean;
+    scheduler: LodSchedulerState;
+}
 export interface SimulationCuller {
     enabled(): boolean;
     setEnabled(value: boolean): void;
@@ -30,5 +35,7 @@ export interface SimulationCuller {
     step(id: string, distance: number, dt: number): SimulationDecision;
     forget(id: string): void;
     clear(): void;
+    snapshot(): SimulationCullerState;
+    restore(next: SimulationCullerState): void;
 }
 export declare function createSimulationCuller(options?: SimulationCullingOptions): SimulationCuller;

package/dist/visibility/simulationCulling.js

@@ -32,5 +32,12 @@ export function createSimulationCuller(options = {}) {
         clear() {
             scheduler.clear();
         },
+        snapshot() {
+            return { enabled, scheduler: scheduler.snapshot() };
+        },
+        restore(next) {
+            enabled = next.enabled;
+            scheduler.restore(next.scheduler);
+        },
     };
 }

package/dist/visibility/spatialIndex.d.ts

@@ -10,6 +10,25 @@ export interface SpatialIndexOptions {
      */
     readonly maxCellSpan?: number;
 }
+/** Integer cell bounds an object covers, inclusive on both ends. */
+export interface SpatialCellRange {
+    x0: number;
+    y0: number;
+    z0: number;
+    x1: number;
+    y1: number;
+    z1: number;
+}
+/**
+ * Plain JSON state of a {@link SpatialIndex}. Cells and their ids keep insertion order, so a restored
+ * index returns query results in the same order.
+ */
+export interface SpatialIndexState {
+    /** Per object: its cell range (`null` when oversized) and whether it was inserted as dynamic. */
+    entries: [id: string, range: SpatialCellRange | null, dynamic: boolean][];
+    cells: [x: number, y: number, z: number, ids: string[]][];
+    oversized: string[];
+}
 /**
  * A uniform 3D spatial hash the renderer and streaming system query for potentially-visible
  * objects instead of scanning the whole scene. Objects are keyed by their world AABB into
@@ -39,6 +58,8 @@ export interface SpatialIndex {
     }[];
     cellSize(): number;
     clear(): void;
+    snapshot(): SpatialIndexState;
+    restore(next: SpatialIndexState): void;
 }
 export declare function createSpatialIndex(options?: SpatialIndexOptions): SpatialIndex;
 /** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */

package/dist/visibility/spatialIndex.js

@@ -206,6 +206,22 @@ export function createSpatialIndex(options = {}) {
             entries.clear();
             stamps.clear();
         },
+        snapshot() {
+            return {
+                entries: [...entries].map(([id, entry]) => [id, entry.range === null ? null : { ...entry.range }, entry.dynamic]),
+                cells: [...cells.values()].map((bucket) => [bucket.x, bucket.y, bucket.z, [...bucket.ids]]),
+                oversized: [...oversized],
+            };
+        },
+        restore(next) {
+            this.clear();
+            for (const [id, range, dynamic] of next.entries)
+                entries.set(id, { range: range === null ? null : { ...range }, dynamic });
+            for (const [x, y, z, ids] of next.cells)
+                cells.set(packCell(x, y, z), { x, y, z, ids: new Set(ids) });
+            for (const id of next.oversized)
+                oversized.add(id);
+        },
     };
 }
 /** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */

package/dist/visibility/visibilitySystem.js

@@ -68,6 +68,7 @@ export function createVisibilitySystem(options) {
             index.remove(id);
             bounds.delete(id);
             records.delete(id);
+            consideredStamp.delete(id);
         }
         return alwaysVisibleList;
     }

package/dist/work/expedition.d.ts

@@ -0,0 +1,110 @@
+import type { LootPipeline, LootResolution } from "../game/lootPipeline.js";
+import type { Drop } from "../game/lootTable.js";
+import { type RandomSeed } from "../random/rng.js";
+/** Timestamped serializable event. `at` is epoch milliseconds, compatible with `appendFeed`. */
+export interface ExpeditionEvent {
+    at: number;
+    /** Lifecycle kinds are loot/hazard/supply/death/recall/return; encounter notices may use caller kinds. */
+    kind: string;
+    text: string;
+    /** Accepted drops; `loot.drops` records the full roll before the item-unit capacity bound. */
+    drops?: readonly Drop[];
+    loot?: LootResolution;
+    hpDelta?: number;
+    exposureDelta?: number;
+    supply?: string;
+}
+/** Plain saveable expedition data. Persist this whole value, including the RNG cursor and tick frontier. */
+export interface ExpeditionState {
+    readonly id: string;
+    readonly status: "exploring" | "returning" | "home" | "dead";
+    readonly startedAtMs: number;
+    /** Last completed event tick (arrival time after return), never an unprocessed catch-up target. */
+    readonly lastSettledMs: number;
+    readonly elapsedMs: number;
+    readonly returnUntilMs: number | null;
+    readonly hp: number;
+    /** Caller-interpreted hazard meter; its meaning and effective max-HP policy are injected. */
+    readonly exposure: number;
+    readonly supplies: Readonly<Record<string, number>>;
+    /** Counts are merged by item/currency id; currency does not consume item capacity. */
+    readonly carried: readonly Drop[];
+    readonly log: readonly ExpeditionEvent[];
+    readonly seed: string;
+    readonly cursor: RandomSeed;
+}
+/** Dispatch data, detached from the caller's supply record. All timestamps are epoch milliseconds. */
+export interface ExpeditionDispatch {
+    id: string;
+    startAtMs: number;
+    hp: number;
+    exposure?: number;
+    supplies?: Readonly<Record<string, number>>;
+    seed: string;
+}
+/** One encounter's mechanical effects and optional caller-authored notices. */
+export interface ExpeditionHazard {
+    damage?: number;
+    exposure?: number;
+    notices?: readonly {
+        kind: string;
+        text: string;
+    }[];
+}
+/** Ordered auto-consumption rule: spends one finite supply only when its declared effect changes a vital. */
+export interface ExpeditionSupplyRule {
+    key: string;
+    when: (state: ExpeditionState) => boolean;
+    restoreHp?: number;
+    clearExposure?: number;
+}
+/** Runtime policy, supplied on each transition and never saved. Callbacks must be pure. */
+export interface ExpeditionConfig<TCtx> {
+    /** Positive whole milliseconds between events; cadence retuning anchors at the last completed tick. */
+    tickMs: number;
+    loot: LootPipeline<TCtx>;
+    lootCtx: (state: ExpeditionState) => TCtx;
+    maxHp: (state: ExpeditionState) => number;
+    hazard?: (state: ExpeditionState, rng: () => number) => ExpeditionHazard;
+    supplies?: readonly ExpeditionSupplyRule[];
+    /** Nonnegative fraction of exploring elapsed time spent returning. */
+    returnFraction: number;
+    /** Positive whole item units; currency is carried without consuming item slots. */
+    carryCap: number;
+    /** Bounded work per call, default 10,000; excess ticks remain unsettled for the next call. */
+    maxTicksPerSettle?: number;
+    /** Newest event count retained by appendFeed, default 200; rewards and RNG are retained separately. */
+    logLimit?: number;
+    /** Optional alternative persisted RNG recurrence; returns a [0,1) value and its next cursor. */
+    randomStep?: (cursor: RandomSeed) => readonly [number, RandomSeed];
+    /** All lifecycle prose is caller-authored; omit for headless logs with empty text. */
+    describe?: (event: Omit<ExpeditionEvent, "text">, state: ExpeditionState) => string;
+}
+/**
+ * Dispatch plain expedition state with a persisted seeded cursor; no clock, scheduler or storage is owned.
+ *
+ * @capability expedition-dispatch dispatch a saveable timed away mission with finite supplies and a seeded RNG cursor
+ */
+export declare function dispatchExpedition(input: ExpeditionDispatch): ExpeditionState;
+/**
+ * Replay due event ticks using the existing stepped catch-up primitive. Order is loot → hazard → ordered
+ * supplies → death → capacity recall. Unprocessed ticks retain their frontier; returning never rolls or
+ * takes damage. Auto-recall uses the triggering tick's time, including offline arrival in the same call.
+ *
+ * @capability expedition-settle settle bounded offline expedition ticks without losing supplies rewards or RNG continuity
+ */
+export declare function settleExpedition<TCtx>(config: ExpeditionConfig<TCtx>, state: ExpeditionState, nowMs: number): ExpeditionState;
+/**
+ * Settle first, then recall safely. If the catch-up budget leaves due exploring ticks, return that state
+ * without recalling; repeat at the same target until the frontier catches up. Dead state never revives.
+ *
+ * @capability expedition-recall begin a safe fractional-time return after settling the pending expedition frontier
+ */
+export declare function recallExpedition<TCtx>(config: ExpeditionConfig<TCtx>, state: ExpeditionState, nowMs: number): ExpeditionState;
+/**
+ * Settle first, then complete a live return instantly. Caller owns payment/authorization; pending ticks
+ * remain unsettled when the budget is exhausted, and dead/home state is never changed.
+ *
+ * @capability expedition-return complete an authorized instant return without skipping unsettled ticks or reviving death
+ */
+export declare function returnExpeditionNow<TCtx>(config: ExpeditionConfig<TCtx>, state: ExpeditionState, nowMs: number): ExpeditionState;