@jgengine/core 0.31.0 → 0.33.0

package/dist/movement/solidObstacles.js

@@ -48,34 +48,91 @@ export function solidObstacleReach(ctx) {
 }
 /** {@link solidObstacleReach} against a bare source and caller-owned cache. */
 export function sourceObstacleReach(source, cache) {
+    ensureSourceCache(source, cache);
+    return cache.value;
+}
+/** Coarse XZ cell for the obstacle index: a movement box spans tens of metres, so 1 m cells would be
+ * almost all empty lookups while a handful of these cover the whole query. */
+const INDEX_CELL_SIZE = 16;
+/** Beyond this many coarse cells a query walks the whole group list instead. */
+const INDEX_CELL_VOLUME_LIMIT = 4096;
+/** Two signed axis indices packed into one small-integer key (no string allocation, no boxing). */
+const INDEX_KEY_RADIX = 32768;
+const INDEX_KEY_BIAS = 16384;
+const INDEX_KEY_LIMIT = 16384;
+function indexCell(value) {
+    return Math.floor(value / INDEX_CELL_SIZE);
+}
+function indexKey(cx, cz) {
+    return (cx + INDEX_KEY_BIAS) * INDEX_KEY_RADIX + (cz + INDEX_KEY_BIAS);
+}
+/**
+ * Refresh `cache` for `source`: one scan resolves the broadphase reach and, when the source reports a
+ * version, every blocking object's obstacles into a coarse XZ index. A versioned source is scanned only
+ * when that version changes, so a per-frame query costs index lookups instead of a world scan.
+ */
+function ensureSourceCache(source, cache) {
+    const version = source.version?.();
+    if (version !== undefined) {
+        if (cache.version === version && cache.index !== undefined)
+            return;
+        cache.version = version;
+        cache.count = -1;
+        cache.index = undefined;
+        buildSourceCache(source, cache, source.list(), true);
+        return;
+    }
     const objects = source.list();
     if (cache.count === objects.length)
-        return cache.value;
+        return;
+    cache.count = objects.length;
+    cache.version = undefined;
+    cache.index = undefined;
+    buildSourceCache(source, cache, objects, false);
+}
+function buildSourceCache(source, cache, objects, index) {
+    const groups = index ? [] : EMPTY_GROUPS;
+    const cells = index ? new Map() : null;
     let horizontal = OBSTACLE_MAX_HALF_EXTENT;
     let vertical = OBSTACLE_VERTICAL_FLOOR;
     for (const object of objects) {
         const set = source.collidersOf(object.instanceId);
-        if (set === null)
-            continue;
-        for (const collider of resolveColliders(set)) {
-            if (!collider.blocks || collider.purpose !== "physical")
-                continue;
-            const shape = collider.shape;
-            const offset = shape.offset;
-            const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
-            const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
-            const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
-            if (shape.kind === "sphere") {
-                horizontal = Math.max(horizontal, ox + oz + shape.radius);
-                vertical = Math.max(vertical, oy + shape.radius);
-            }
-            else {
-                // Horizontal bound sums both axes so any yaw of the box stays covered.
-                const h = shape.halfExtents;
-                horizontal = Math.max(horizontal, ox + oz + h[0] + h[2]);
-                vertical = Math.max(vertical, oy + h[1]);
+        const obstacles = [];
+        if (set === null) {
+            // No resolved collider: preserve the default 1×1×1 box.
+            if (index)
+                obstacles.push({ position: object.position });
+        }
+        else {
+            for (const collider of resolveColliders(set)) {
+                if (!collider.blocks || collider.purpose !== "physical")
+                    continue;
+                const reach = blockingReach(collider);
+                horizontal = Math.max(horizontal, reach[0]);
+                vertical = Math.max(vertical, reach[1]);
+                if (index)
+                    obstacles.push(obstacleFromCollider(collider, object.position, object.rotationY));
             }
         }
+        if (!index || obstacles.length === 0)
+            continue;
+        const group = {
+            x: object.position[0],
+            y: object.position[1],
+            z: object.position[2],
+            obstacles,
+        };
+        groups.push(group);
+        const cx = indexCell(group.x);
+        const cz = indexCell(group.z);
+        if (cx <= -INDEX_KEY_LIMIT || cx >= INDEX_KEY_LIMIT || cz <= -INDEX_KEY_LIMIT || cz >= INDEX_KEY_LIMIT)
+            continue;
+        const key = indexKey(cx, cz);
+        const bucket = cells.get(key);
+        if (bucket === undefined)
+            cells.set(key, [group]);
+        else
+            bucket.push(group);
     }
     const value = {
         horizontal: Math.min(horizontal, OBSTACLE_HORIZONTAL_CAP),
@@ -83,7 +140,56 @@ export function sourceObstacleReach(source, cache) {
     };
     cache.count = objects.length;
     cache.value = value;
-    return value;
+    if (index)
+        cache.index = { cells: cells, groups };
+}
+const EMPTY_GROUPS = [];
+/** A blocking collider's center-to-face reach, split so tower height cannot inflate the XZ query. */
+function blockingReach(collider) {
+    const shape = collider.shape;
+    const offset = shape.offset;
+    const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
+    const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
+    const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
+    if (shape.kind === "sphere")
+        return [ox + oz + shape.radius, oy + shape.radius];
+    // Horizontal bound sums both axes so any yaw of the box stays covered.
+    const h = shape.halfExtents;
+    return [ox + oz + h[0] + h[2], oy + h[1]];
+}
+/** Every indexed obstacle whose object centre lies inside `min`..`max` — the set the broadphase promises. */
+function indexedObstaclesNear(index, min, max, out) {
+    const minCx = indexCell(min[0]);
+    const maxCx = indexCell(max[0]);
+    const minCz = indexCell(min[2]);
+    const maxCz = indexCell(max[2]);
+    const volume = Math.max(0, maxCx - minCx + 1) * Math.max(0, maxCz - minCz + 1);
+    if (volume > INDEX_CELL_VOLUME_LIMIT ||
+        minCx <= -INDEX_KEY_LIMIT || maxCx >= INDEX_KEY_LIMIT ||
+        minCz <= -INDEX_KEY_LIMIT || maxCz >= INDEX_KEY_LIMIT) {
+        for (const group of index.groups)
+            if (groupInBox(group, min, max))
+                pushGroup(group, out);
+        return;
+    }
+    for (let cx = minCx; cx <= maxCx; cx += 1) {
+        const rowBase = (cx + INDEX_KEY_BIAS) * INDEX_KEY_RADIX + minCz + INDEX_KEY_BIAS;
+        for (let cz = minCz; cz <= maxCz; cz += 1) {
+            const bucket = index.cells.get(rowBase + (cz - minCz));
+            if (bucket === undefined)
+                continue;
+            for (const group of bucket)
+                if (groupInBox(group, min, max))
+                    pushGroup(group, out);
+        }
+    }
+}
+function groupInBox(group, min, max) {
+    return group.x >= min[0] && group.x <= max[0] && group.y >= min[1] && group.y <= max[1] && group.z >= min[2] && group.z <= max[2];
+}
+function pushGroup(group, out) {
+    for (const obstacle of group.obstacles)
+        out.push(obstacle);
 }
 /** Yaw-rotate an entity-local AABB about the object origin and re-fit it to an axis-aligned box, expressed
  * as `min`/`max` relative to `position`. Conservative: the rotated box is grown to its enclosing AABB. */
@@ -188,7 +294,7 @@ export function obstacleFromSolid(solid) {
  * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
  */
 export function solidObstaclesNear(ctx, position, reachX, reachZ, height = WALKER_HEIGHT) {
-    const obstacles = sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
+    const obstacles = sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height, reachCache(ctx));
     appendWorldSolidObstacles(obstacles, ctx.world.solids, position, reachX, reachZ, height);
     return obstacles;
 }
@@ -199,8 +305,12 @@ function appendWorldSolidObstacles(obstacles, solids, position, reachX, reachZ,
         obstacles.push(obstacleFromSolid(solid));
     }
 }
-/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. */
-export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT) {
+/**
+ * {@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.
+ */
+export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT, cache) {
     const min = [
         position[0] - reachX - reach.horizontal,
         position[1] - reach.vertical,
@@ -212,6 +322,15 @@ export function sourceObstaclesNear(source, reach, position, reachX, reachZ, hei
         position[2] + reachZ + reach.horizontal,
     ];
     const obstacles = [];
+    if (cache !== undefined && source.version !== undefined) {
+        ensureSourceCache(source, cache);
+        const index = cache.index;
+        if (index !== undefined) {
+            indexedObstaclesNear(index, min, max, obstacles);
+            appendWorldSolidObstacles(obstacles, source.solids, position, reachX, reachZ, height);
+            return obstacles;
+        }
+    }
     for (const object of source.inBox(min, max)) {
         const set = source.collidersOf(object.instanceId);
         if (set === null) {
@@ -233,8 +352,8 @@ export function sourceObstaclesNear(source, reach, position, reachX, reachZ, hei
  * X/Z it may actually take this tick. A step into a wall is cut on the blocked axis and preserved on the
  * other, exactly as {@link stepPlayerMovement} resolves the player's.
  *
- * Bounded by the same broadphase as the player's gather: one `inBox` query sized to this step, never a
- * full-world scan, so it stays affordable per NPC per tick.
+ * Bounded by the same broadphase as the player's gather: one query sized to this step, answered from the
+ * source's obstacle index, never a full-world scan, so it stays affordable per NPC per tick.
  *
  * The sliding is already axis-separated: X and Z are resolved independently inside, so a caller that
  * also splits its own movement by axis must hand this exactly one axis per call (`stepZ: 0`, then
@@ -265,7 +384,7 @@ export function resolveSourceWalkerStep(source, cache, position, stepX, stepZ, o
     if (stepX === 0 && stepZ === 0)
         return { stepX, stepZ };
     const radius = options.radius ?? DEFAULT_OBSTACLE_PLAYER_RADIUS;
-    const obstacles = sourceObstaclesNear(source, sourceObstacleReach(source, cache), position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius);
+    const obstacles = sourceObstaclesNear(source, sourceObstacleReach(source, cache), position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius, WALKER_HEIGHT, cache);
     return slideStep(position, stepX, stepZ, obstacles, radius, options.stepUpHeight ?? 0);
 }
 /** {@link resolveWalkerStep} against an already-gathered obstacle set. */

package/dist/runtime/context/combat.js

@@ -68,6 +68,7 @@ export function createCombatSubsystem(d) {
                 absorbed: Math.max(0, application.incoming - application.dealt),
                 remaining: application.remaining,
                 lethal: application.lethal,
+                ...(application.at === undefined ? {} : { position: application.at }),
             });
         },
         onLethal(instanceId, lethalCtx) {

package/dist/runtime/context/scene.js

@@ -51,20 +51,22 @@ export function createSceneSubsystem(d) {
         return object === null ? undefined : content.objectById?.(object.catalogId);
     }
     // `moveToward` reads the same blocking colliders the player resolver does, so a chaser stops at the
-    // wall that stops the player rather than lerping through it.
+    // wall that stops the player rather than lerping through it. The obstacle index behind it rebuilds
+    // only when this version moves: an object placed, moved, rotated or re-collidered.
     const walkerReach = createObstacleReachCache();
     const solidSource = {
         solids: d.solids,
         list: () => objects.list(),
         inBox: (min, max) => objects.inBox(min, max),
         collidersOf: (instanceId) => objectCollidersOf(instanceId),
+        version: () => objects.version(),
     };
     const spatial = createSpatialApi({
         resolvePosition: (instanceId) => entities.get(instanceId)?.position,
         candidates: entities.ids,
         grid: { cellSize: 8 },
         incremental: true,
-        resolveStep: (position, stepX, stepZ) => slideStep(position, stepX, stepZ, sourceObstaclesNear(solidSource, sourceObstacleReach(solidSource, walkerReach), position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS)),
+        resolveStep: (position, stepX, stepZ) => slideStep(position, stepX, stepZ, sourceObstaclesNear(solidSource, sourceObstacleReach(solidSource, walkerReach), position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS, undefined, walkerReach)),
         ...(occluder !== undefined ? { occluder } : {}),
     });
     const entityColliders = new Map();
@@ -123,6 +125,7 @@ export function createSceneSubsystem(d) {
         return true;
     }
     function reportObjectCollisionMesh(catalogId, mesh) {
+        objects.markSpatialChange();
         if (mesh === null) {
             const existed = meshObjectByCatalogId.delete(catalogId);
             if (existed)
@@ -138,6 +141,7 @@ export function createSceneSubsystem(d) {
         return true;
     }
     function reportObjectBounds(catalogId, bounds) {
+        objects.markSpatialChange();
         if (bounds === null) {
             const existed = measuredObjectByCatalogId.delete(catalogId);
             if (existed)
@@ -350,6 +354,7 @@ export function createSceneSubsystem(d) {
                 objectColliders.delete(instanceId);
             else
                 objectColliders.set(instanceId, colliders);
+            objects.markSpatialChange();
             signalNotify();
         },
         collidersOf: objectCollidersOf,

package/dist/runtime/gameContext.js

@@ -505,6 +505,9 @@ export function createGameContext(options) {
                 setLoop: (id, params) => events.emit("audio.loopSet", { id, ...params }),
                 stopLoop: (id) => events.emit("audio.loopStop", { id }),
             },
+            feedback: {
+                cue: (cue, caption) => events.emit("feedback.cue", caption === undefined ? { cue } : { cue, caption }),
+            },
             feed: {
                 bind: (action) => feed.bind(action, events),
                 push(action, entry) {

package/dist/runtime/gameContextTypes.d.ts

@@ -1,5 +1,6 @@
 import type { AuthoredSimulationRuntime } from "../world/authoredSimulation.js";
 import type { Territory } from "../world/territory.js";
+import type { FeedbackCue } from "../audio/feedbackCues.js";
 import type { NoticeFeed } from "../game/notices.js";
 import type { CurrencyDefinition } from "../economy/currency.js";
 import type { CardPile, CardPileConfig } from "../cards/cardPile.js";
@@ -436,6 +437,15 @@ export interface GameContextRace {
     /** Lazily creates (on first call, `config` required) or returns the existing reactive race for `id` — discrete mutations and eventful `update` calls bump `ctx.version()`, so HUDs stop hand-managing `store.set` (#286.2). */
     state(id: string, config?: RaceStateConfig): RaceState;
 }
+/**
+ * The game-announced feel seam on `ctx.game`: name a moment the engine has no event for and the
+ * shell plays its cue's sound, rumble, camera kick and caption. The reaction table lives in the
+ * shell, so a game never encodes what a hit or a wave should sound like.
+ */
+export interface GameFeedback {
+    /** Raise `cue` (`"hit" | "hurt" | "kill" | "pickup" | "objective" | "wave" | "deny"`); `caption` replaces the cue's default caption text. Emits `feedback.cue`. */
+    cue(cue: FeedbackCue, caption?: string): void;
+}
 /** Reachable audio seam on `ctx.game`: `play`, `music`, and `resume` route through the `audio.play`/`audio.music`/`audio.resume` events the shell's audio engine listens on, so game code triggers sound without importing the shell. Retained `loop`/`setLoop`/`stopLoop` add id-keyed loops with live pitch/gain control over `audio.loopStart`/`audio.loopSet`/`audio.loopStop` (#1051). */
 export interface GameAudio {
     play(sound: string, at?: readonly [number, number, number]): void;
@@ -500,6 +510,12 @@ export interface GameContext {
          */
         notices: NoticeFeed;
         audio: GameAudio;
+        /**
+         * Announce a gameplay moment the engine has no event for (a wave starting, a scripted beat).
+         * The shell answers with the cue's sound, gamepad pulse, camera kick and caption, so a game
+         * never encodes the reaction itself.
+         */
+        feedback: GameFeedback;
         /** Play a model's one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an attack swing) — emits `entity.animation` for the shell to pick up. */
         playEntityAnimation(instanceId: string, event: string): void;
         feed: GameContextFeed;

package/dist/scene/objectStore.d.ts

@@ -69,6 +69,10 @@ export interface ObjectStore {
     ids(): readonly string[];
     at(x: number, y: number, z: number, tolerance?: number): SceneObject[];
     inBox(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
+    /** Bumps whenever membership, a position or a rotation changes — cheap cache key for consumers. */
+    version(): number;
+    /** Bump {@link version} for a change the store cannot see, such as a consumer-owned collider set. */
+    markSpatialChange(): void;
     clear(): void;
     subscribe(listener: () => void): () => void;
     /** Notified only when the object set changes (place/remove), never on move/rotate/setVisual — markers read live poses imperatively. */

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 {