@jgengine/core 0.32.0 → 0.34.0

package/dist/scene/objectStore.js

@@ -1,15 +1,34 @@
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 const CELL_SIZE = 1;
 /**
- * When an `inBox` query spans more than this many 1 m cells, walk the object list instead of the
- * cell grid. Tall/wide colliders (city buildings) can inflate movement broadphase to hundreds of
- * metres on each axis — at 1 m cells that is O(10⁶) empty `Map.get`s per frame and freezes `pose`.
- * Linear scan over a few hundred objects is cheaper the moment the cell volume exceeds the scene.
+ * Queries above this many 1 m cells walk the coarse grid instead. A 1 m cell lookup hashes a fresh
+ * string while an object test is a few comparisons, so the crossover is tens of cells — not the
+ * thousands a "scan every object instead" comparison implied. A city movement box is hundreds.
  */
-const IN_BOX_CELL_VOLUME_LIMIT = 4096;
+const IN_BOX_CELL_VOLUME_LIMIT = 32;
+/**
+ * Second index level for those big queries: coarse XZ columns hold the same centre points as the 1 m
+ * grid, so a city-scale box walks a few populated columns instead of every object in the world.
+ * Beyond {@link COARSE_CELL_VOLUME_LIMIT} (a world-sized query) a list walk is cheaper.
+ */
+const COARSE_CELL_SIZE = 16;
+const COARSE_CELL_VOLUME_LIMIT = 4096;
+/**
+ * Two signed coarse axes packed into one small-integer key (no string allocation, no heap-number
+ * hash): ±16384 cells covers ±262 km at 16 m and the key stays inside a 32-bit SMI.
+ */
+const COARSE_KEY_RADIX = 32768;
+const COARSE_KEY_BIAS = 16384;
+const COARSE_KEY_LIMIT = 16384;
 function cellIndexOf(value) {
     return Math.floor(value / CELL_SIZE);
 }
+function coarseIndexOf(value) {
+    return Math.floor(value / COARSE_CELL_SIZE);
+}
+function coarseKey(cx, cz) {
+    return (cx + COARSE_KEY_BIAS) * COARSE_KEY_RADIX + (cz + COARSE_KEY_BIAS);
+}
 function cellKey(cx, cy, cz) {
     return `${cx}:${cy}:${cz}`;
 }
@@ -23,7 +42,9 @@ function objectInAabb(object, min, max) {
 export function createObjectStore() {
     const store = createObservableKeyedStore();
     const cellIndex = new Map();
+    const coarseIndex = new Map();
     let nextCounter = 1;
+    let revision = 0;
     function generateId() {
         let id = `object-${nextCounter}`;
         while (store.has(id)) {
@@ -33,6 +54,32 @@ export function createObjectStore() {
         nextCounter += 1;
         return id;
     }
+    function coarseAdd(instanceId, position) {
+        const cx = coarseIndexOf(position[0]);
+        const cz = coarseIndexOf(position[2]);
+        if (cx <= -COARSE_KEY_LIMIT || cx >= COARSE_KEY_LIMIT || cz <= -COARSE_KEY_LIMIT || cz >= COARSE_KEY_LIMIT)
+            return;
+        const key = coarseKey(cx, cz);
+        let bucket = coarseIndex.get(key);
+        if (bucket === undefined) {
+            bucket = new Set();
+            coarseIndex.set(key, bucket);
+        }
+        bucket.add(instanceId);
+    }
+    function coarseRemove(instanceId, position) {
+        const cx = coarseIndexOf(position[0]);
+        const cz = coarseIndexOf(position[2]);
+        if (cx <= -COARSE_KEY_LIMIT || cx >= COARSE_KEY_LIMIT || cz <= -COARSE_KEY_LIMIT || cz >= COARSE_KEY_LIMIT)
+            return;
+        const key = coarseKey(cx, cz);
+        const bucket = coarseIndex.get(key);
+        if (bucket === undefined)
+            return;
+        bucket.delete(instanceId);
+        if (bucket.size === 0)
+            coarseIndex.delete(key);
+    }
     function indexAdd(instanceId, position) {
         const key = cellKeyOf(position);
         let bucket = cellIndex.get(key);
@@ -41,15 +88,17 @@ export function createObjectStore() {
             cellIndex.set(key, bucket);
         }
         bucket.add(instanceId);
+        coarseAdd(instanceId, position);
     }
     function indexRemove(instanceId, position) {
         const key = cellKeyOf(position);
         const bucket = cellIndex.get(key);
-        if (bucket === undefined)
-            return;
-        bucket.delete(instanceId);
-        if (bucket.size === 0)
-            cellIndex.delete(key);
+        if (bucket !== undefined) {
+            bucket.delete(instanceId);
+            if (bucket.size === 0)
+                cellIndex.delete(key);
+        }
+        coarseRemove(instanceId, position);
     }
     return {
         place(catalogId, x, y, z, options = {}) {
@@ -76,6 +125,7 @@ export function createObjectStore() {
                 ...(options.slots !== undefined ? { slots: options.slots } : {}),
             });
             indexAdd(instanceId, position);
+            revision += 1;
             return instanceId;
         },
         remove(instanceId) {
@@ -84,6 +134,7 @@ export function createObjectStore() {
                 return false;
             store.delete(instanceId);
             indexRemove(instanceId, current.position);
+            revision += 1;
             return true;
         },
         move(instanceId, x, y, z) {
@@ -94,6 +145,7 @@ export function createObjectStore() {
             store.set(instanceId, { ...current, position });
             indexRemove(instanceId, current.position);
             indexAdd(instanceId, position);
+            revision += 1;
             return true;
         },
         rotate(instanceId, rotationY) {
@@ -101,6 +153,7 @@ export function createObjectStore() {
             if (!current)
                 return false;
             store.set(instanceId, { ...current, rotationY });
+            revision += 1;
             return true;
         },
         setVisual(instanceId, visual) {
@@ -194,13 +247,39 @@ export function createObjectStore() {
             const cellsY = Math.max(0, maxCy - minCy + 1);
             const cellsZ = Math.max(0, maxCz - minCz + 1);
             const cellVolume = cellsX * cellsY * cellsZ;
-            // Huge queries (city-scale movement broadphase inflated by tall building colliders): scanning
-            // every empty 1 m cell is far more expensive than testing the few hundred placed objects.
+            // Huge queries (city-scale movement broadphase inflated by tall building colliders): walking
+            // every 1 m cell is all empty lookups, so walk the coarse grid instead.
             if (cellVolume > IN_BOX_CELL_VOLUME_LIMIT) {
+                const coarseMinX = coarseIndexOf(min[0]);
+                const coarseMaxX = coarseIndexOf(max[0]);
+                const coarseMinZ = coarseIndexOf(min[2]);
+                const coarseMaxZ = coarseIndexOf(max[2]);
+                const coarseVolume = Math.max(0, coarseMaxX - coarseMinX + 1) * Math.max(0, coarseMaxZ - coarseMinZ + 1);
+                if (coarseVolume > COARSE_CELL_VOLUME_LIMIT ||
+                    coarseMinX <= -COARSE_KEY_LIMIT || coarseMaxX >= COARSE_KEY_LIMIT ||
+                    coarseMinZ <= -COARSE_KEY_LIMIT || coarseMaxZ >= COARSE_KEY_LIMIT) {
+                    const hits = [];
+                    for (const object of store.arraySnapshot()) {
+                        if (objectInAabb(object, min, max))
+                            hits.push(object);
+                    }
+                    return hits;
+                }
                 const hits = [];
-                for (const object of store.arraySnapshot()) {
-                    if (objectInAabb(object, min, max))
-                        hits.push(object);
+                for (let cx = coarseMinX; cx <= coarseMaxX; cx += 1) {
+                    const rowBase = (cx + COARSE_KEY_BIAS) * COARSE_KEY_RADIX + coarseMinZ + COARSE_KEY_BIAS;
+                    for (let cz = coarseMinZ; cz <= coarseMaxZ; cz += 1) {
+                        const bucket = coarseIndex.get(rowBase + (cz - coarseMinZ));
+                        if (bucket === undefined)
+                            continue;
+                        for (const instanceId of bucket) {
+                            const object = store.get(instanceId);
+                            if (object === undefined)
+                                continue;
+                            if (objectInAabb(object, min, max))
+                                hits.push(object);
+                        }
+                    }
                 }
                 return hits;
             }
@@ -228,6 +307,8 @@ export function createObjectStore() {
                 store.delete(object.instanceId);
             }
             cellIndex.clear();
+            coarseIndex.clear();
+            revision += 1;
         },
         subscribe(listener) {
             return store.subscribe(listener);
@@ -238,6 +319,12 @@ export function createObjectStore() {
         snapshot() {
             return store.arraySnapshot();
         },
+        version() {
+            return revision;
+        },
+        markSpatialChange() {
+            revision += 1;
+        },
         hydrate(objects) {
             const incoming = new Set(objects.map((object) => object.instanceId));
             for (const current of store.arraySnapshot()) {
@@ -253,6 +340,7 @@ export function createObjectStore() {
                 store.set(object.instanceId, object);
                 indexAdd(object.instanceId, object.position);
             }
+            revision += 1;
         },
     };
 }

package/dist/settings/graphicsSettings.js

@@ -1,5 +1,5 @@
 import { resolveGraphicsProfile } from "./graphicsProfile.js";
-import { DEFAULT_GRAPHICS_QUALITY, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, } from "./settingsModel.js";
+import { asSettingType, DEFAULT_GRAPHICS_QUALITY, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, } from "./settingsModel.js";
 /** Ordered stage list used to build settings rows. */
 export const GRAPHICS_POST_STAGES = ["ao", "bloom", "dof", "smaa"];
 /** Player-facing labels for each post stage. */
@@ -95,7 +95,8 @@ export function withGraphicsQualityOverride(store, quality, overrides) {
     ]);
     return {
         get(id, fallback) {
-            return pinned.has(id) ? pinned.get(id) : store.get(id, fallback);
+            const pinnedValue = pinned.get(id);
+            return pinnedValue === undefined ? store.get(id, fallback) : asSettingType(id, pinnedValue, fallback);
         },
         set(id, value) {
             pinned.delete(id);

package/dist/settings/settingsModel.d.ts

@@ -95,6 +95,24 @@ interface WebStorageLike {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
 }
+/** A stored setting holds a value the read asked for as another type, so no honest value exists. */
+export declare class SettingsTypeError extends Error {
+    readonly settingId: string;
+    readonly storedType: string;
+    readonly fallbackType: string;
+    constructor(settingId: string, storedType: string, fallbackType: string);
+}
+/**
+ * Read a stored value as the type the caller asked for. A value of another primitive type converts
+ * when the result is the same value in the asked-for type (a number as its digits, a boolean as
+ * `"true"`/`"false"`); otherwise it throws {@link SettingsTypeError}, naming the key and both types,
+ * instead of handing back the fallback as if nothing were stored.
+ */
+export declare function asSettingType<T extends SettingValue>(id: string, stored: unknown, fallback: T): T;
+/**
+ * Read one persisted setting as `fallback`'s type. An absent or unreadable cell yields the
+ * fallback; a stored value of an incompatible type throws {@link SettingsTypeError}.
+ */
 export declare function loadSettingValue<T extends SettingValue>(id: string, fallback: T, storage?: Pick<WebStorageLike, "getItem"> | null | undefined): T;
 export declare function saveSettingValue(id: string, value: SettingValue, storage?: Pick<WebStorageLike, "setItem"> | null | undefined): void;
 export interface SettingsStore {

package/dist/settings/settingsModel.js

@@ -60,30 +60,81 @@ function defaultStorage() {
     }
     return null;
 }
-function coerce(raw, fallback) {
-    if (typeof fallback === "number") {
-        const n = typeof raw === "number" ? raw : Number(raw);
-        return (Number.isFinite(n) ? n : fallback);
+/** A stored setting holds a value the read asked for as another type, so no honest value exists. */
+export class SettingsTypeError extends Error {
+    settingId;
+    storedType;
+    fallbackType;
+    constructor(settingId, storedType, fallbackType) {
+        super(`Setting "${settingId}" stores ${storedType} but was read as ${fallbackType}.`);
+        this.name = "SettingsTypeError";
+        this.settingId = settingId;
+        this.storedType = storedType;
+        this.fallbackType = fallbackType;
     }
-    if (typeof fallback === "boolean") {
-        if (typeof raw === "boolean")
-            return raw;
-        return (raw === "true" ? true : raw === "false" ? false : fallback);
+}
+function storedTypeName(raw) {
+    if (raw === null)
+        return "null";
+    if (Array.isArray(raw))
+        return "array";
+    return typeof raw;
+}
+/**
+ * Read a stored value as the type the caller asked for. A value of another primitive type converts
+ * when the result is the same value in the asked-for type (a number as its digits, a boolean as
+ * `"true"`/`"false"`); otherwise it throws {@link SettingsTypeError}, naming the key and both types,
+ * instead of handing back the fallback as if nothing were stored.
+ */
+export function asSettingType(id, stored, fallback) {
+    const wanted = typeof fallback;
+    const storedType = storedTypeName(stored);
+    if (storedType === wanted) {
+        if (wanted === "number" && !Number.isFinite(stored)) {
+            throw new SettingsTypeError(id, storedType, wanted);
+        }
+        return stored;
+    }
+    if (wanted === "number" && storedType === "string") {
+        const text = stored.trim();
+        const parsed = text === "" ? Number.NaN : Number(text);
+        if (Number.isFinite(parsed))
+            return parsed;
     }
-    return (typeof raw === "string" ? raw : fallback);
+    else if (wanted === "string" && (storedType === "number" || storedType === "boolean")) {
+        return String(stored);
+    }
+    else if (wanted === "boolean" && storedType === "string" && (stored === "true" || stored === "false")) {
+        return (stored === "true");
+    }
+    throw new SettingsTypeError(id, storedType, wanted);
 }
+/**
+ * Read one persisted setting as `fallback`'s type. An absent or unreadable cell yields the
+ * fallback; a stored value of an incompatible type throws {@link SettingsTypeError}.
+ */
 export function loadSettingValue(id, fallback, storage = defaultStorage()) {
     if (storage == null)
         return fallback;
+    let raw;
     try {
-        const raw = storage.getItem(settingStorageKey(id));
-        if (raw === null)
-            return fallback;
-        return coerce(JSON.parse(raw), fallback);
+        raw = storage.getItem(settingStorageKey(id));
     }
     catch {
         return fallback;
     }
+    if (raw === null)
+        return fallback;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+    if (parsed === null)
+        return fallback;
+    return asSettingType(id, parsed, fallback);
 }
 export function saveSettingValue(id, value, storage = defaultStorage()) {
     if (storage == null)
@@ -100,8 +151,9 @@ export function createSettingsStore(storage = defaultStorage()) {
     const mem = createObservableKeyedStore();
     return {
         get(id, fallback) {
-            if (mem.has(id))
-                return coerce(mem.get(id), fallback);
+            const stored = mem.get(id);
+            if (stored !== undefined)
+                return asSettingType(id, stored, fallback);
             return loadSettingValue(id, fallback, storage ?? undefined);
         },
         set(id, value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.34.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.34.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-combat/api.md

@@ -243,7 +243,7 @@
 - `createCoverField` (function): function createCoverField(options: CoverFieldOptions): CoverField — Cover over authored boxes: derive the stand points once, re-derive them after an edit, and answer bounded nearest-cover queries. `walkable` is injected, so the seam checks the game's own ground test (`nav.findPolygon(point) !== null`) instead of assuming a flat floor.
 - `createDamageClamp` (function): function createDamageClamp(config: DamageClampConfig): DamageInterceptor — A stateless interceptor that caps any single application at `maxPerHit`.
 - `createDamagePipeline` (function): function createDamagePipeline(initial?: readonly DamageInterceptor[]): DamagePipeline — Create a mutable damage interception chain that state transitions install into and remove from — e.g. add an invulnerability interceptor on phase enter and drop it on phase exit. Evaluation order is install order.
-- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet. Every application — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type, amount, absorbed, remaining health and a lethal flag, so a HUD names the blow instead of guessing.
+- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet. Every application — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type, amount, absorbed, remaining health, a lethal flag and, when `positionOf` or the hit names one, where the blow landed, so a HUD names the blow and a cue pans instead of guessing.
 - `createDeathSystem` (function): function createDeathSystem(deps: DeathSystemDeps): DeathSystem — Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
 - `createDefensiveWindow` (function): function createDefensiveWindow(config: DefensiveWindowConfig): DefensiveWindow — Open a timed defensive window — block, parry, or i-frames — and test incoming hits against it.
 - `createDotField` (function): function createDotField(): DotField — Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`.
@@ -462,7 +462,7 @@
 - `TargetProfile` (interface): interface TargetProfile — What a target presents to the table: one resistance class and its armor points.
 - `TimeToKill` (interface): interface TimeToKill — A quoted time to kill for one fixed hit against one health pool.
 - `UnknownTargetProfileError` (class): class UnknownTargetProfileError extends Error — Raised when a hit names a target that was never registered — a wiring error, not a 0-damage hit.
-- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet. Every application — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type, amount, absorbed, remaining health and a lethal flag, so a HUD names the blow instead of guessing.
+- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet. Every application — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type, amount, absorbed, remaining health, a lethal flag and, when `positionOf` or the hit names one, where the blow landed, so a HUD names the blow and a cue pans instead of guessing.
 
 ## @jgengine/core/combat/damageTable
 

package/skills/jgengine-gameplay/api.md

@@ -1073,7 +1073,7 @@
 - `EmoteSpatialLookup` (interface): interface EmoteSpatialLookup { inRadius(center: readonly [number, number, number], radius: number, filter?: (id: string) => boolean): readonly string[] } — ⚠ undocumented
 - `Emotes` (interface): interface Emotes { play(fromUserId: string, emoteId: string, radius?: number): EmoteBroadcastResult | {reason: string} } — ⚠ undocumented
 - `EmotesDeps` (interface): interface EmotesDeps { entities: EmoteEntityLookup; spatial: EmoteSpatialLookup } — ⚠ undocumented
-- `FriendEntry` (interface): interface FriendEntry { userId: string; online: boolean } — ⚠ undocumented
+- `FriendEntry` (interface): interface FriendEntry { userId: string; online: boolean } — ⚠ undocumented · used by `useFriends` (@jgengine/react): The local player's friends with their presence: the list keeps one identity until a request is accepted, a friend is removed or a friend's p…
 - `FriendRequestEntry` (interface): interface FriendRequestEntry { requestId: string; fromUserId: string } — ⚠ undocumented
 - `Friends` (interface): interface Friends { canRequest(fromUserId: string, toUserId: string): {reason: string} | null; request(fromUserId: string, toUserId: string): {requestId: string} | {reason: string}; accept(userId: string, requestId: string): {reason: string} | null; decline(… — ⚠ undocumented
 - `FriendsSnapshot` (interface): interface FriendsSnapshot { friends: string[]; blocked: string[] } — ⚠ undocumented
@@ -1351,7 +1351,7 @@
 - `FirstPersonCameraConfig` (interface): interface FirstPersonCameraConfig { eyeHeight?: number; sensitivity?: number; maxPitch?: number; reticle?: boolean; viewmodel?: boolean; collision?: false | FirstPersonCollisionConfig } — ⚠ undocumented
 - `FirstPersonCollisionConfig` (interface): interface FirstPersonCollisionConfig — Clearance tuning for the first-person camera's collision pull-in.
 - `ForbidRule` (interface): interface ForbidRule — A rule that forbids a combination — e.g. "an incendiary barrel cannot pair with a cryo core". A forbid rule can never become satisfiable by adding more parts, so it is the check a backtracking generator runs on each candidate.
-- `FriendEntry` (interface): interface FriendEntry { userId: string; online: boolean } — ⚠ undocumented
+- `FriendEntry` (interface): interface FriendEntry { userId: string; online: boolean } — ⚠ undocumented · used by `useFriends` (@jgengine/react): The local player's friends with their presence: the list keeps one identity until a request is accepted, a friend is removed or a friend's p…
 - `FriendRequestEntry` (interface): interface FriendRequestEntry { requestId: string; fromUserId: string } — ⚠ undocumented
 - `Friends` (interface): interface Friends { canRequest(fromUserId: string, toUserId: string): {reason: string} | null; request(fromUserId: string, toUserId: string): {requestId: string} | {reason: string}; accept(userId: string, requestId: string): {reason: string} | null; decline(… — ⚠ undocumented
 - `GAME_SAVE_VERSION` (const): const GAME_SAVE_VERSION: 1 — Current save-format version of {@link GameSaveDocument}. Bump it with {@link GameSaveConfig.migrate} when the shape changes.
@@ -2653,6 +2653,17 @@
 - `TriggeredRuleState` (interface): interface TriggeredRuleState — Serializable runtime state — everything that changes future triggers. Rules travel with it.
 - `createTriggeredRuleEngine` (function): function createTriggeredRuleEngine(rules: readonly TriggeredRule[] = []): TriggeredRuleEngine — Create an empty triggered-rule engine. Rules are added as data; dispatching an event returns the firings the caller applies to its own effect system. Time is caller-supplied (`now` in ms), so the engine is deterministic and drives equally from a fixed-step loop or a save-restored timeline.
 
+## @jgengine/core/run/runLoop
+
+- `RunChange` (interface): interface RunChange<T> — One change the next run can open with. `T` is the game's own payload (a tighter rival line, an unlocked part, a route modifier) - the loop only draws and remembers which id was drawn.
+- `RunLoop` (interface): interface RunLoop<T> — A run's lifecycle: what it carries and can lose, and the change it hands the next run.
+- `RunLoopConfig` (interface): interface RunLoopConfig<T> — Configuration for {@link createRunLoop}.
+- `RunLoopState` (interface): interface RunLoopState — Everything a run loop stores as plain JSON: the run in progress plus lifetime totals.
+- `RunOffer` (interface): interface RunOffer<T> — The change a run opens with, and which run it is.
+- `RunOutcome` (type): type RunOutcome = "banked" | "lost" — How a run ended: what it carried reached the bank, or it was lost.
+- `RunSettlement` (interface): interface RunSettlement<T> — What one closed run banked or lost, and what the next run changes.
+- `createRunLoop` (function): function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T> — Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
+
 ## @jgengine/core/session/contestedChannel
 
 - `ContestReaction` (type): type ContestReaction = "pause" | "decay" — ⚠ undocumented

package/skills/jgengine-gameplay/capabilities.md

@@ -648,6 +648,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `rerollRules` (function) · `import { rerollRules } from "@jgengine/core/gameplay"`
 - `selectRules` (function) · `import { selectRules } from "@jgengine/core/gameplay"`
 
+## run-loop — bank or lose what a run carries, with one deterministic change per run
+
+- `createRunLoop` (function) · `import { createRunLoop } from "@jgengine/core/run/runLoop"`
+
 ## run-modifiers — a roguelike run built from stacking drafted modifier picks
 
 - `createRunDraft` (function) · `import { createRunDraft } from "@jgengine/core/gameplay"`

package/skills/jgengine-world/api.md

@@ -106,8 +106,10 @@
 - `DriverState` (interface): interface DriverState — Serializable per-driver state advanced in place by {@link driveStep}.
 - `DriverStep` (interface): interface DriverStep extends AxisInput — {@link driveStep}'s result: the axis sample to feed the vehicle sim, plus arrival.
 - `DriverTuning` (interface): interface DriverTuning — Vehicle-feel numbers the game supplies; everything has a sensible default except `maxSpeed`.
+- `PaceBand` (interface): interface PaceBand — Catch-up pacing for one car in a field: the gap it tries to hold to a reference car (a rival, the player, a convoy lead) and how its pace bends when it drifts off that gap. Past `margin` by `tolerance` it sheds up to `ease` of its pace; short of it by `tolerance` it gains up to `push`; inside that tolerance it leaves the car alone. The push never outdrives `DriverTuning.maxSpeed`, so a band changes how hard a car tries, never what it is built to do.
 - `createDriverState` (function): function createDriverState(targetX = 0, targetZ = 0): DriverState — Fresh driver state committed to an initial target (usually the spawn-time goal or the spawn position itself).
-- `driveStep` (function): function driveStep(state: DriverState, dt: number, pose: DriverPose, goal: DriverGoal, profile: DifficultyProfile, tuning: DriverTuning, rng: () => number, obstacleAhead: number | null = null): DriverStep — Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving corridor this step (`null`/omitted when clear) — the driver perceives it late by `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`, so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut toward where the target *was*. When throttle produces no motion for a tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+- `driveStep` (function): function driveStep(state: DriverState, dt: number, pose: DriverPose, goal: DriverGoal, profile: DifficultyProfile, tuning: DriverTuning, rng: () => number, obstacleAhead: number | null = null): DriverStep — Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving corridor this step (`null`/omitted when clear) — the driver perceives it late by `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`, so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut toward where the target *was*. A {@link PaceBand} on the goal eases a car ahead of its margin and pushes one behind it, bounded by the car's own top speed. When throttle produces no motion for a tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+- `paceBandFactor` (function): function paceBandFactor(band: PaceBand, gap: number): number — The pace multiplier a {@link PaceBand} asks for at `gap`: `1` inside the tolerance, `1 - ease * scale` fully ahead of it, `1 + push * scale` fully behind it, ramped linearly across `easeAt` / `pushAt` in between. Pure scalar math, so a band is deterministic and costs no allocation per step; the result never goes negative.
 - `pathTargetAhead` (function): function pathTargetAhead(path: readonly DrivePathPoint[], x: number, z: number, lookahead: number, loop = false): DrivePathPoint | null — The pure-pursuit target for street/route following: the point `lookahead` meters further along the polyline from wherever the vehicle currently projects onto it. Feed the result to {@link driveStep} as the goal each tick and the driver follows the road; `loop` wraps a circuit (traffic block, race lap) instead of pinning at the final point. Returns `null` for a degenerate path. Give sharper tiers a longer `lookahead` to cut corners cleanly and duller tiers a short one so they steer segment-to-segment.
 
 ## @jgengine/core/ai/flock
@@ -1001,7 +1003,7 @@
 ## @jgengine/core/movement/solidObstacles
 
 - `ObstacleReach` (interface): interface ObstacleReach — Largest blocking-collider extent in the scene, split so tower height cannot inflate the XZ query.
-- `ObstacleReachCache` (interface): interface ObstacleReachCache — Mutable reach cache; one per source, invalidated by object count.
+- `ObstacleReachCache` (interface): interface ObstacleReachCache — Mutable reach cache; one per source, invalidated by object count or by the source's version.
 - `SolidObstacleSource` (interface): interface SolidObstacleSource — The slice of the scene's object store this query needs. Narrow on purpose: the scene context wires its own store here while it is still being constructed, `ctx.scene.object` satisfies it as-is, and a pure rules package with no `GameContext` to import can satisfy it from its own object list.
 - `createObstacleReachCache` (function): function createObstacleReachCache(): ObstacleReachCache — A fresh {@link ObstacleReachCache} for a caller that owns its own source.
 - `obstacleFromSolid` (function): function obstacleFromSolid(solid: WorldSolid): CollisionObstacle — A {@link WorldSolid} as a {@link CollisionObstacle}. Axis-aligned solids are one box; a yawed solid is cut into strips along its long axis, each fitted with an AABB, so a turned building does not block the street beside it the way a single enclosing box would.
@@ -1010,7 +1012,7 @@
 - `slideStep` (function): function slideStep(position: EntityPosition, stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], radius = DEFAULT_OBSTACLE_PLAYER_RADIUS, stepUpHeight = 0): { stepX: number; stepZ: number } — {@link resolveWalkerStep} against an already-gathered obstacle set.
 - `solidObstaclesNear` (function): function solidObstaclesNear(ctx: GameContext, position: EntityPosition, reachX: number, reachZ: number, height = WALKER_HEIGHT): CollisionObstacle[] — Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the scene's resolved colliders and `ctx.world.solids`.
 - `sourceObstacleReach` (function): function sourceObstacleReach(source: SolidObstacleSource, cache: ObstacleReachCache): ObstacleReach — {@link solidObstacleReach} against a bare source and caller-owned cache.
-- `sourceObstaclesNear` (function): function sourceObstaclesNear(source: SolidObstacleSource, reach: ObstacleReach, position: EntityPosition, reachX: number, reachZ: number, height = WALKER_HEIGHT): CollisionObstacle[] — {@link solidObstaclesNear} against a bare source and an already-resolved reach.
+- `sourceObstaclesNear` (function): function sourceObstaclesNear(source: SolidObstacleSource, reach: ObstacleReach, position: EntityPosition, reachX: number, reachZ: number, height = WALKER_HEIGHT, cache?: ObstacleReachCache): CollisionObstacle[] — {@link solidObstaclesNear} against a bare source and an already-resolved reach. Pass the source's {@link ObstacleReachCache} to use the version-keyed obstacle index; a source that reports no `version()` keeps the per-query `inBox` gather.
 
 ## @jgengine/core/movement/steering
 
@@ -2037,7 +2039,7 @@
 
 ## @jgengine/core/sensor/revealQuery
 
-- `RevealHit` (interface): interface RevealHit { instanceId: string; distance: number; tags: readonly string[] } — ⚠ undocumented · used by `useRevealHits` (@jgengine/shell/vision/RevealVision): Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene.
+- `RevealHit` (interface): interface RevealHit { instanceId: string; distance: number; tags: readonly string[] } — ⚠ undocumented · used by `useRevealHits` (@jgengine/shell/vision/RevealVision): Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene and refreshed on render.
 - `RevealQuery` (interface): interface RevealQuery { inRadius(center: EntityPosition | string, radius: number, tags: readonly string[]): RevealHit[] } — ⚠ undocumented
 - `RevealQueryOptions` (interface): interface RevealQueryOptions { resolvePosition: (instanceId: string) => EntityPosition | undefined; resolveTags: (instanceId: string) => readonly string[]; candidates: () => string[] } — ⚠ undocumented
 
@@ -2782,7 +2784,7 @@
 - `ResolvedTerrainDetail` (type): type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel" | "material" | "sweeps">> & { waterLevel: number; material?: ResolvedTerrainDetailMaterial; sweeps: { dry: readonly [number, number, number]; wet: readonly [number, number, number] }; } — A {@link TerrainDetailConfig} with every field resolved to a concrete value — the shape the shell's detail material consumes.
 - `ResolvedWeather` (interface): interface ResolvedWeather { grip: number; visibility: number; structureDamage: number; chill: number; ignition: number; spread: number } — ⚠ undocumented
 - `ResponseCurve` (type): type ResponseCurve = | { readonly kind: "linear"; readonly from: number; readonly to: number } /** Same shape as `linear`, raised to `exponent` (default `2`), so appeal stays flat until it matters. */ | { readonly kind: "quadratic"; readonly from: number; readonly to: number; readonly exponent?: num… — How one need's satisfaction maps to an option's appeal: `1` at `from`, `0` at `to`, clamped outside. Read satisfaction `1` as a full meter; pair with {@link UtilityTerm.invert} when a full meter is what makes the option attractive.
-- `RevealHit` (interface): interface RevealHit { instanceId: string; distance: number; tags: readonly string[] } — ⚠ undocumented · used by `useRevealHits` (@jgengine/shell/vision/RevealVision): Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene.
+- `RevealHit` (interface): interface RevealHit { instanceId: string; distance: number; tags: readonly string[] } — ⚠ undocumented · used by `useRevealHits` (@jgengine/shell/vision/RevealVision): Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene and refreshed on render.
 - `RevealQuery` (interface): interface RevealQuery { inRadius(center: EntityPosition | string, radius: number, tags: readonly string[]): RevealHit[] } — ⚠ undocumented
 - `RoadCut` (interface): interface RoadCut — One trim of a ribbon end back to a junction boundary — the seam the welded surface attaches to.
 - `RoadEnvironmentDescriptor` (type): type RoadEnvironmentDescriptor = { kind: "road" } & Required< Pick<RoadEnvironmentConfig, "path" | "width" | "color" | "markings" | "markingColor" | "elevation"> > & { /** Resolved sidewalk band, or `false` when the road has none. */ sidewalk: { width: number; color: string } | false; /** Procedural… — Resolved road descriptor produced by {@link road} and rendered by the shell environment scene.

package/skills/jgengine-world/reference.md

@@ -413,7 +413,7 @@ Replace behavior data through `ctx.scene.entity.update(id, { behaviors })` or en
 
 Compose, don't replace: scale `MobBrainConfig.aggroRadius` by `perceptionScale`, route `acquireTarget` scoring through `pickScored`, gate `advancePursuit` target swaps behind the reaction gate.
 
-**Drive** — `ai/driver` is the vehicle consumer of the profile: `driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleAhead?)` turns a pose + goal into the shared `AxisInput` (`throttle`/`brake`/`steer`) for `tickDrivableVehicle`. The profile decides how well the car drives: the steering target is a delay-line resampled every `reactionSeconds` (easy chasers cut to where the target *was*), corners shed speed instead of orbiting at full throttle, obstacle distance is perceived late by `speed × reactionSeconds`, the wheel wobbles by `executionJitter` (resampled on an interval, so it reads as a loose wheel), and a car grinding a wall backs out with counter-steer after a tier-scaled delay (brake past standstill is the sim's reverse). `createDriverState` is one small serializable object; the caller owns the sim, collision, and all spatial queries. For streets and circuits, `pathTargetAhead(path, x, z, lookahead, loop?)` walks a road/route polyline to the pure-pursuit point ahead — feed it back in as the goal each tick and the same brain follows authored roads; give sharper tiers a longer lookahead.
+**Drive** — `ai/driver` is the vehicle consumer of the profile: `driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleAhead?)` turns a pose + goal into the shared `AxisInput` (`throttle`/`brake`/`steer`) for `tickDrivableVehicle`. The profile decides how well the car drives: the steering target is a delay-line resampled every `reactionSeconds` (easy chasers cut to where the target *was*), corners shed speed instead of orbiting at full throttle, obstacle distance is perceived late by `speed × reactionSeconds`, the wheel wobbles by `executionJitter` (resampled on an interval, so it reads as a loose wheel), and a car grinding a wall backs out with counter-steer after a tier-scaled delay (brake past standstill is the sim's reverse). `createDriverState` is one small serializable object; the caller owns the sim, collision, and all spatial queries. For streets and circuits, `pathTargetAhead(path, x, z, lookahead, loop?)` walks a road/route polyline to the pure-pursuit point ahead — feed it back in as the goal each tick and the same brain follows authored roads; give sharper tiers a longer lookahead. Catch-up pacing is a `PaceBand` on the goal: the caller measures `paceGap` (positive = ahead of the reference) and the band's `margin`/`tolerance` leave a dead zone, `ease` sheds pace for a leader over `easeAt`, `push` adds it for a chaser over `pushAt`, and `scale` is the per-car share. `paceBandFactor(band, gap)` is the same rule on its own; the push never outdrives `tuning.maxSpeed`.
 
 ### Snapshot and restore on movement and visibility handles