@jgengine/core 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -26,6 +26,54 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.33.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.33.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.30.0`; `@jgengine/github` is `0.20.0`.
+- `useSceneObjects` (`@jgengine/react/hooks`) keeps one list identity across `move` and `rotate`, so a record's `position`/`rotationY` is what it was at the last render. Read the live placement with `ctx.scene.object.get(instanceId)` (a `useFrame` loop or a rAF-ticked HUD) when a mesh or readout must follow a moving object.
+- A read of a mismatched stored value now converts losslessly where it can (a number as its digits, a boolean as `"true"`/`"false"`, those strings back) and throws where it cannot. No in-repo caller relied on the old fallback; `useSetting` (`@jgengine/react/settings`) is the generic path that could, so a game that stored a number under a key it reads with a string fallback now gets the digits.
+
+### Added
+
+- `releasePostfxOverlayTracking(scene)` (`@jgengine/shell/postfx/postfxOverlay`) drops the cached prepass overlay set and its listeners for a scene that is being torn down.
+- `canvasCover` (`@jgengine/react/canvasCover`): one page-wide hold a covering surface takes, plus `useCanvasCover(declared)` for a React overlay. While it is held the shell stops drawing the world, its shadow passes and postfx; input, audio and the DOM HUD keep running, and the first frame after release draws the untouched scene. A scrim or side panel must not take it.
+- `MenuScreen` and `TitleMenu` take `coversCanvas` (default false) to declare that the screen paints over the whole canvas. A menu with only a translucent scrim leaves the live scene drawing.
+- The dev runner pins the cover with `?cover=1`, and the devtools agent bridge answers `canvas_cover`, so a perf run or `bun run drive` can measure a covered frame on any game.
+- `combat.damage` carries an optional `position`: the effect path fills it from the target's own spot, and `createDamageRuntime` takes one per hit (`hit({ position })`) or from a `positionOf` reader, so a status tick is placed too. A cue with a position pans and attenuates; one without stays centred.
+- `createHapticsRoute` (`@jgengine/shell/audio/hapticsRoute`) sends a feedback pulse to a connected gamepad, and to `navigator.vibrate` on a phone with no pad. `FeedbackHost` wires it; reduced motion still drops the camera shake only.
+- `PerfReport.render.drawsFrame` is every draw a frame issues — shadow, main, postfx prepasses, AO and DOF together — as the 95th percentile of the measured window, with `drawsFrames` naming how many frames it covers. `bun run perf:gate` compares it against each game's re-based `drawsFrame` budget; the renderer's own single-sample `draws` is printed beside it and is no longer gated.
+- `ObjectStore.version()` / `ObjectStore.markSpatialChange()` (`ctx.scene.object`) — a counter that moves whenever membership, a position, a rotation or a consumer-owned collider set changes, so derived spells spatial data can share one cache key.
+- `SolidObstacleSource.version?()` (`@jgengine/core/movement/solidObstacles`) — a source that reports one gets its blocking obstacles resolved once per version into a coarse XZ index; a source without it keeps the per-query `inBox` gather.
+- `SettingsTypeError` and `asSettingType` (`@jgengine/core/settings/settingsModel`) report and resolve a stored setting read as another type.
+
+### Changed
+
+- `bun run land` queues landings on one lock per repo instead of running them beside each other, so two lanes no longer stack two pull requests' sixteen jobs against the account's 20-job cap. A waiting landing names the branch and pid it waits on; a lock whose process died, or that is older than 30 minutes, is broken with a warning.
+- The scene io browser test skips Playwright's two-frame click stability check and lets three rendered frames pass instead of ten: on a runner its second test went from 53s to 11-24s and the file from 76s to 50s, of which 16-36s is the fixture's own start.
+- `check-game-front-end` recognizes the shipped `CreditsPanel`, so a game that renders credits through the engine's panel is no longer flagged as having no credits screen.
+- The shell's frame loop switches to `frameloop="never"` under a cover instead of drawing a world nobody can see (measured on Brightway Park's pause menu: 1,095 whole-frame draws and 5.2 ms/frame before, 0 draws and 0.11 ms/frame covered). A frame-rate cap no longer advances a covered canvas.
+- `FeedbackDeps.play` takes an optional `position`, which `FeedbackHost` forwards to `ctx.game.audio.play`, so a positioned damage or death cue reaches the spatial engine.
+- Each game's `perf-budget.json` entry now budgets `drawsFrame` and records the budget it replaced as `previousDraws`; an entry that still carries only `draws` fails by name instead of gating a count from a different measurement.
+- The in-page report reads the devtools render probe's frame sample instead of the live renderer counter, so `window.__JG.report()` and the devtools panel no longer report a mid-frame partial count.
+- Movement gathers obstacles from that index instead of re-resolving every nearby object every frame. On Harbor Heat the query fell from 0.62-0.65 ms to 0.10 ms a frame (2.0-2.1 ms to 1.4 ms of simulation a frame).
+- `objectStore.inBox` walks a coarse grid for big boxes instead of scanning every placed object; a 1 m cell lookup costs a string hash, so the switch happens past 32 cells rather than 4096.
+- Ambient occlusion reads the beauty pass's depth buffer instead of rendering the scene a second time for its normal/depth GBuffer. That prepass cost 537 extra draws and 2.6-2.9 ms/frame in Harbor Heat and 2,105 extra draws in Drift Foundry at 1600x900; AO now draws nothing of its own. A post chain whose antialiasing is `"smaa"` (the default) keeps SMAA and drops the beauty target's extra MSAA resolve, because WebGL2 cannot sample a multisampled depth texture; `"msaa"` chains keep the old prepass. Fixed-viewpoint captures differ only on geometry edges (#2173).
+
+### Fixed
+
+- Postfx prepasses no longer walk the whole scene twice a frame to hide overlays, points and lines: the set is cached per scene and rescanned when the scene graph changes. Drift Foundry 2.11 ms/frame and Harbor Heat 0.66 ms/frame of `traverse` removed.
+- A rig posed from an animation graph no longer allocates a motion sample, a position triple and a fresh pose record every frame, and foot IK no longer allocates a probe input, filter, closure and per-leg records every frame.
+- The Graphics tab lists a post-processing stage toggle only when the game's resolved chain can build that stage. Depth of field, which no reference game authors, hid behind a row that switched a pass the composer never created, so the toggle changed nothing. The rule covers every stage: a chain with `ao: false`, `bloom: false` or `aa: "msaa"`/`false` no longer offers those rows, and a game with no post chain gets none of them. Every other settings row is unchanged (`@jgengine/shell/settings/settingsController`, `availablePostfxStages` in `@jgengine/shell/postfx/PostProcessing`).
+- Positional loops declared through `entitySounds`/`objectSounds` are tracked instead of rebuilt: spawn, despawn and a moved emitter update one retained loop each, and a frame where nothing moved reads only the emitters that already sound. On scrap-signal's 560 placed props (69 sounding), the tracking path drops from 16.7 µs to 1.2 µs per frame and a steady frame allocates no Set, array or record.
+- `useAccessibilitySettings`, `useHoldVsToggle` and `useAccessibilityRows` show a setting written before the component subscribed — a saved profile or the demo path seeding values before first paint — instead of waiting for the player's next change (#2180).
+- `useFeed`, `useQuestJournal` and `useFriends` (`@jgengine/react/hooks`) keep one list identity while membership holds instead of allocating a new array on every store write and comparing it with `Object.is`, so a HUD reading them no longer re-renders on every entity pose write. A pushed feed entry, an accepted, progressed or abandoned quest, and an accepted or removed friend each re-render once. Measured on the three read sites (`ToastStack`, `FriendsList`, `JournalQuestTracker`) with 15 quests, 20 friends and 20 feed rows: 900 renders → 0 across 300 pose writes, 0.14 ms/frame → 0.04 ms/frame.
+- `useWorldItems` (`@jgengine/react/hooks`) keeps one list identity until an item spawns, is picked up or is removed. It read `worldItem.list()`, which allocates a new array per call, against a store signal that also fires on every entity pose write, so a HUD re-rendered every dropped-item marker each frame (0.97 ms/frame of React work in Harbor Heat).
+- `WorldItems` (`@jgengine/shell`) reads each marker's live pose in `useFrame` instead of taking it as a prop, so a moving item still follows without re-rendering its marker.
+- `useSceneEntities` and `useSceneObjects` (`@jgengine/react/hooks`) keep one list identity while membership holds, instead of allocating a new array on every store write and comparing it with `Object.is`. A pose write no longer re-renders every HUD that reads them (30-entity roster: 0.066 ms/frame → 0; the whole loop 0.24 → 0.05 ms/frame), while a spawn, despawn, replace, place or remove still re-renders. Non-pose object writes (state, visual, animation, slots, catalog id) still re-render.
+- `RevealHighlights` (`@jgengine/shell/vision`) drives its own per-frame refresh only while Dark Sight is enabled, so a disabled reveal overlay no longer re-renders (0.019 ms/frame → 0) and an enabled one still follows the origin and its targets.
+- `createSettingsStore().get` returns a stored setting of another type instead of quietly returning the fallback, so a numeric setting read with a string fallback applies instead of vanishing (#2189). Root cause: `coerce` treated the fallback's type as the stored type and replaced every other type with the fallback. A stored value that cannot be read as the asked-for type now throws `SettingsTypeError` naming the key, the stored type and the fallback type.
+
 ## 0.32.0
 
 ### Migrate

package/dist/combat/damageRuntime.d.ts

@@ -27,6 +27,8 @@ export interface DamageRuntimeHitInput {
     zone?: string;
     source?: string;
     statuses?: readonly (string | DamageStatusRequest)[];
+    /** Where the blow landed, when the caller knows it; overridable per hit. */
+    position?: readonly [number, number, number];
 }
 /** Every stage of one resolved hit, so a UI or a test can read why the final number is what it is. */
 export interface DamageRuntimeResolution {
@@ -87,6 +89,12 @@ export interface DamageRuntimeConfig {
      * reader and every event reports `remaining: null` and `lethal: false`.
      */
     healthOf?: (targetId: string) => number | null;
+    /**
+     * Where a target stands, read once per application. Gives the event a `position` so a cue pans
+     * and attenuates, including status ticks and hits whose input named none; omit it and the event
+     * carries no position and feedback stays centred.
+     */
+    positionOf?: (targetId: string) => readonly [number, number, number] | null | undefined;
     /** Register a one-line devtools probe under this name. */
     devtoolsName?: string;
 }
@@ -156,7 +164,8 @@ export declare class UnknownTargetProfileError extends Error {
  * `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.
+ * 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.
  *
  * @capability damage-runtime resolve hits through a damage table, hit zones, and armor, and tick data-defined statuses with declared stacking
  */

package/dist/combat/damageRuntime.js

@@ -23,7 +23,8 @@ export class UnknownTargetProfileError extends Error {
  * `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.
+ * 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.
  *
  * @capability damage-runtime resolve hits through a damage table, hit zones, and armor, and tick data-defined statuses with declared stacking
  */
@@ -33,6 +34,7 @@ export function createDamageRuntime(config) {
     const rng = resolveRng(config.rng, "createDamageRuntime");
     const bus = config.events;
     const healthOf = config.healthOf;
+    const positionOf = config.positionOf;
     let table = config.table;
     let zones = config.zones;
     let armorStat = config.armorStat ?? "armor";
@@ -77,6 +79,7 @@ export function createDamageRuntime(config) {
             dealt,
             ...(tick.source !== undefined ? { source: tick.source } : {}),
             status: tick.status,
+            ...(positionOf === undefined ? {} : { position: positionOf(tick.target) ?? undefined }),
         });
         return dealt;
     }
@@ -92,6 +95,7 @@ export function createDamageRuntime(config) {
             remaining,
             lethal: remaining !== null && remaining <= 0,
             ...(input.status !== undefined ? { status: input.status } : {}),
+            ...(input.position === undefined ? {} : { position: input.position }),
         };
         recent.push(event);
         if (recent.length > RECENT_DAMAGE_LIMIT)
@@ -160,6 +164,9 @@ export function createDamageRuntime(config) {
                 incoming,
                 dealt: damage,
                 ...(input.source !== undefined ? { source: input.source } : {}),
+                ...(input.position !== undefined
+                    ? { position: input.position }
+                    : positionOf === undefined ? {} : { position: positionOf(input.target) ?? undefined }),
             });
             return {
                 target: input.target,

package/dist/combat/effects.d.ts

@@ -93,6 +93,8 @@ export interface EffectDamageApplication {
     remaining: number | null;
     /** True when the last pool reached its minimum. */
     lethal: boolean;
+    /** The target's position when the spatial seam knows it, for a panned cue or a decal at the hit. */
+    at?: EntityPosition;
 }
 export interface EffectSystemDeps {
     resolveReceive(instanceId: string): ReceiveMap | null | undefined;

package/dist/combat/effects.js

@@ -109,6 +109,7 @@ export function createEffectSystem(deps) {
                 if (delta.delta < 0)
                     dealt -= delta.delta;
             const lastStatId = rule.order[rule.order.length - 1];
+            const at = deps.spatial.positionOf(instanceId);
             deps.onDamage({
                 target: instanceId,
                 source: from,
@@ -117,6 +118,7 @@ export function createEffectSystem(deps) {
                 dealt,
                 remaining: statPools.get(instanceId, lastStatId)?.current ?? null,
                 lethal: result.lethal,
+                ...(at === undefined ? {} : { at }),
             });
         }
         if (result.lethal) {

package/dist/devtools/report.d.ts

@@ -22,7 +22,20 @@ export interface FrameWindow {
 }
 /** Renderer-side counts for the measured window; `null` where the source could not read them. */
 export interface RenderReport {
+    /**
+     * The renderer's own draw counter as the devtools probe samples it. three accumulates this across
+     * every pass in a frame (the probe sets `info.autoReset = false`), but one sample is one frame, so
+     * two runs of the same build can differ by a pass that runs on a cadence.
+     */
     draws: number | null;
+    /**
+     * Every draw issued in a frame, all passes (shadow, main, postfx, AO, DOF), as the 95th percentile
+     * of the measured window: the count the budget gate compares. Only the CDP harness can wrap the
+     * draw calls, so the in-page sampler reports `null` here.
+     */
+    drawsFrame: number | null;
+    /** Frames the whole-frame count was taken over; 0 where nothing measured it. */
+    drawsFrames: number;
     triangles: number | null;
     geometries: number | null;
     textures: number | null;

package/dist/game/events.d.ts

@@ -39,6 +39,12 @@ export interface DamageAppliedEvent {
     lethal: boolean;
     /** The status that ticked, when the damage came from a carried status rather than a direct hit. */
     status?: string;
+    /**
+     * Where the blow landed, for spatial feedback (a panned cue, a decal, a floating number that
+     * belongs on the body rather than on screen). Omitted by an emitter that knows no position, so a
+     * listener must fall back to a centred, unattenuated reaction.
+     */
+    position?: readonly [number, number, number];
 }
 /** Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state. With an `animation.graph`, `event` arms the trigger of that name. */
 export interface EntityAnimationEvent {

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.32.0";
+export declare const VERSION = "0.33.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,50 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.32.0";
+export const VERSION = "0.33.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.33.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.33.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.30.0`; `@jgengine/github` is `0.20.0`.",
+            "`useSceneObjects` (`@jgengine/react/hooks`) keeps one list identity across `move` and `rotate`, so a record's `position`/`rotationY` is what it was at the last render. Read the live placement with `ctx.scene.object.get(instanceId)` (a `useFrame` loop or a rAF-ticked HUD) when a mesh or readout must follow a moving object.",
+            "A read of a mismatched stored value now converts losslessly where it can (a number as its digits, a boolean as `\"true\"`/`\"false\"`, those strings back) and throws where it cannot. No in-repo caller relied on the old fallback; `useSetting` (`@jgengine/react/settings`) is the generic path that could, so a game that stored a number under a key it reads with a string fallback now gets the digits.",
+        ],
+        added: [
+            "`releasePostfxOverlayTracking(scene)` (`@jgengine/shell/postfx/postfxOverlay`) drops the cached prepass overlay set and its listeners for a scene that is being torn down.",
+            "`canvasCover` (`@jgengine/react/canvasCover`): one page-wide hold a covering surface takes, plus `useCanvasCover(declared)` for a React overlay. While it is held the shell stops drawing the world, its shadow passes and postfx; input, audio and the DOM HUD keep running, and the first frame after release draws the untouched scene. A scrim or side panel must not take it.",
+            "`MenuScreen` and `TitleMenu` take `coversCanvas` (default false) to declare that the screen paints over the whole canvas. A menu with only a translucent scrim leaves the live scene drawing.",
+            "The dev runner pins the cover with `?cover=1`, and the devtools agent bridge answers `canvas_cover`, so a perf run or `bun run drive` can measure a covered frame on any game.",
+            "`combat.damage` carries an optional `position`: the effect path fills it from the target's own spot, and `createDamageRuntime` takes one per hit (`hit({ position })`) or from a `positionOf` reader, so a status tick is placed too. A cue with a position pans and attenuates; one without stays centred.",
+            "`createHapticsRoute` (`@jgengine/shell/audio/hapticsRoute`) sends a feedback pulse to a connected gamepad, and to `navigator.vibrate` on a phone with no pad. `FeedbackHost` wires it; reduced motion still drops the camera shake only.",
+            "`PerfReport.render.drawsFrame` is every draw a frame issues — shadow, main, postfx prepasses, AO and DOF together — as the 95th percentile of the measured window, with `drawsFrames` naming how many frames it covers. `bun run perf:gate` compares it against each game's re-based `drawsFrame` budget; the renderer's own single-sample `draws` is printed beside it and is no longer gated.",
+            "`ObjectStore.version()` / `ObjectStore.markSpatialChange()` (`ctx.scene.object`) — a counter that moves whenever membership, a position, a rotation or a consumer-owned collider set changes, so derived spells spatial data can share one cache key.",
+            "`SolidObstacleSource.version?()` (`@jgengine/core/movement/solidObstacles`) — a source that reports one gets its blocking obstacles resolved once per version into a coarse XZ index; a source without it keeps the per-query `inBox` gather.",
+            "`SettingsTypeError` and `asSettingType` (`@jgengine/core/settings/settingsModel`) report and resolve a stored setting read as another type.",
+        ],
+        changed: [
+            "`bun run land` queues landings on one lock per repo instead of running them beside each other, so two lanes no longer stack two pull requests' sixteen jobs against the account's 20-job cap. A waiting landing names the branch and pid it waits on; a lock whose process died, or that is older than 30 minutes, is broken with a warning.",
+            "The scene io browser test skips Playwright's two-frame click stability check and lets three rendered frames pass instead of ten: on a runner its second test went from 53s to 11-24s and the file from 76s to 50s, of which 16-36s is the fixture's own start.",
+            "`check-game-front-end` recognizes the shipped `CreditsPanel`, so a game that renders credits through the engine's panel is no longer flagged as having no credits screen.",
+            "The shell's frame loop switches to `frameloop=\"never\"` under a cover instead of drawing a world nobody can see (measured on Brightway Park's pause menu: 1,095 whole-frame draws and 5.2 ms/frame before, 0 draws and 0.11 ms/frame covered). A frame-rate cap no longer advances a covered canvas.",
+            "`FeedbackDeps.play` takes an optional `position`, which `FeedbackHost` forwards to `ctx.game.audio.play`, so a positioned damage or death cue reaches the spatial engine.",
+            "Each game's `perf-budget.json` entry now budgets `drawsFrame` and records the budget it replaced as `previousDraws`; an entry that still carries only `draws` fails by name instead of gating a count from a different measurement.",
+            "The in-page report reads the devtools render probe's frame sample instead of the live renderer counter, so `window.__JG.report()` and the devtools panel no longer report a mid-frame partial count.",
+            "Movement gathers obstacles from that index instead of re-resolving every nearby object every frame. On Harbor Heat the query fell from 0.62-0.65 ms to 0.10 ms a frame (2.0-2.1 ms to 1.4 ms of simulation a frame).",
+            "`objectStore.inBox` walks a coarse grid for big boxes instead of scanning every placed object; a 1 m cell lookup costs a string hash, so the switch happens past 32 cells rather than 4096.",
+            "Ambient occlusion reads the beauty pass's depth buffer instead of rendering the scene a second time for its normal/depth GBuffer. That prepass cost 537 extra draws and 2.6-2.9 ms/frame in Harbor Heat and 2,105 extra draws in Drift Foundry at 1600x900; AO now draws nothing of its own. A post chain whose antialiasing is `\"smaa\"` (the default) keeps SMAA and drops the beauty target's extra MSAA resolve, because WebGL2 cannot sample a multisampled depth texture; `\"msaa\"` chains keep the old prepass. Fixed-viewpoint captures differ only on geometry edges (#2173).",
+            "Postfx prepasses no longer walk the whole scene twice a frame to hide overlays, points and lines: the set is cached per scene and rescanned when the scene graph changes. Drift Foundry 2.11 ms/frame and Harbor Heat 0.66 ms/frame of `traverse` removed.",
+            "A rig posed from an animation graph no longer allocates a motion sample, a position triple and a fresh pose record every frame, and foot IK no longer allocates a probe input, filter, closure and per-leg records every frame.",
+            "The Graphics tab lists a post-processing stage toggle only when the game's resolved chain can build that stage. Depth of field, which no reference game authors, hid behind a row that switched a pass the composer never created, so the toggle changed nothing. The rule covers every stage: a chain with `ao: false`, `bloom: false` or `aa: \"msaa\"`/`false` no longer offers those rows, and a game with no post chain gets none of them. Every other settings row is unchanged (`@jgengine/shell/settings/settingsController`, `availablePostfxStages` in `@jgengine/shell/postfx/PostProcessing`).",
+            "Positional loops declared through `entitySounds`/`objectSounds` are tracked instead of rebuilt: spawn, despawn and a moved emitter update one retained loop each, and a frame where nothing moved reads only the emitters that already sound. On scrap-signal's 560 placed props (69 sounding), the tracking path drops from 16.7 µs to 1.2 µs per frame and a steady frame allocates no Set, array or record.",
+            "`useAccessibilitySettings`, `useHoldVsToggle` and `useAccessibilityRows` show a setting written before the component subscribed — a saved profile or the demo path seeding values before first paint — instead of waiting for the player's next change (#2180).",
+            "`useFeed`, `useQuestJournal` and `useFriends` (`@jgengine/react/hooks`) keep one list identity while membership holds instead of allocating a new array on every store write and comparing it with `Object.is`, so a HUD reading them no longer re-renders on every entity pose write. A pushed feed entry, an accepted, progressed or abandoned quest, and an accepted or removed friend each re-render once. Measured on the three read sites (`ToastStack`, `FriendsList`, `JournalQuestTracker`) with 15 quests, 20 friends and 20 feed rows: 900 renders → 0 across 300 pose writes, 0.14 ms/frame → 0.04 ms/frame.",
+            "`useWorldItems` (`@jgengine/react/hooks`) keeps one list identity until an item spawns, is picked up or is removed. It read `worldItem.list()`, which allocates a new array per call, against a store signal that also fires on every entity pose write, so a HUD re-rendered every dropped-item marker each frame (0.97 ms/frame of React work in Harbor Heat).",
+            "`WorldItems` (`@jgengine/shell`) reads each marker's live pose in `useFrame` instead of taking it as a prop, so a moving item still follows without re-rendering its marker.",
+            "`useSceneEntities` and `useSceneObjects` (`@jgengine/react/hooks`) keep one list identity while membership holds, instead of allocating a new array on every store write and comparing it with `Object.is`. A pose write no longer re-renders every HUD that reads them (30-entity roster: 0.066 ms/frame → 0; the whole loop 0.24 → 0.05 ms/frame), while a spawn, despawn, replace, place or remove still re-renders. Non-pose object writes (state, visual, animation, slots, catalog id) still re-render.",
+            "`RevealHighlights` (`@jgengine/shell/vision`) drives its own per-frame refresh only while Dark Sight is enabled, so a disabled reveal overlay no longer re-renders (0.019 ms/frame → 0) and an enabled one still follows the origin and its targets.",
+            "`createSettingsStore().get` returns a stored setting of another type instead of quietly returning the fallback, so a numeric setting read with a string fallback applies instead of vanishing (#2189). Root cause: `coerce` treated the fallback's type as the stored type and replaced every other type with the fallback. A stored value that cannot be read as the asked-for type now throws `SettingsTypeError` naming the key, the stored type and the fallback type.",
+        ],
+        removed: [],
+    },
     "0.32.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.32.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.29.0`; `@jgengine/github` is `0.19.0`.",

package/dist/movement/solidObstacles.d.ts

@@ -29,11 +29,35 @@ export interface SolidObstacleSource {
         rotationY: number;
     }[];
     collidersOf(instanceId: string): Parameters<typeof resolveColliders>[0] | null;
+    /**
+     * Bumps whenever membership, a position, a rotation or a collider set changes. A source that reports
+     * one is indexed once per version instead of re-resolving every object on every query.
+     */
+    version?(): number;
 }
-/** Mutable reach cache; one per source, invalidated by object count. */
+/** A placed object's blocking geometry, resolved once per index build and shared read-only by queries. */
+interface ObstacleGroup {
+    x: number;
+    y: number;
+    z: number;
+    obstacles: CollisionObstacle[];
+}
+/**
+ * Version-keyed obstacle index: object centre → its prebuilt obstacles, bucketed in coarse XZ cells so
+ * a city-scale movement box walks a few populated cells rather than every object in the world.
+ */
+interface ObstacleIndex {
+    cells: Map<number, ObstacleGroup[]>;
+    groups: ObstacleGroup[];
+}
+/** Mutable reach cache; one per source, invalidated by object count or by the source's version. */
 export interface ObstacleReachCache {
     count: number;
     value: ObstacleReach;
+    /** Version the value and index were built from; absent for a source that reports none. */
+    version?: number | undefined;
+    /** Built index, present only for a versioned source. */
+    index?: ObstacleIndex | undefined;
 }
 /** A fresh {@link ObstacleReachCache} for a caller that owns its own source. */
 export declare function createObstacleReachCache(): ObstacleReachCache;
@@ -71,15 +95,19 @@ export declare function obstacleFromSolid(solid: WorldSolid): CollisionObstacle;
  * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
  */
 export declare function solidObstaclesNear(ctx: GameContext, position: EntityPosition, reachX: number, reachZ: number, height?: number): CollisionObstacle[];
-/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. */
-export declare function sourceObstaclesNear(source: SolidObstacleSource, reach: ObstacleReach, position: EntityPosition, reachX: number, reachZ: number, height?: number): 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.
+ */
+export declare function sourceObstaclesNear(source: SolidObstacleSource, reach: ObstacleReach, position: EntityPosition, reachX: number, reachZ: number, height?: number, cache?: ObstacleReachCache): CollisionObstacle[];
 /**
  * Slide a walker's horizontal step against the same solid geometry that stops the player, returning the
  * 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
@@ -118,3 +146,4 @@ export declare function slideStep(position: EntityPosition, stepX: number, stepZ
     stepX: number;
     stepZ: number;
 };
+export {};

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/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 {

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.33.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.33.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.33.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.

package/skills/jgengine-world/api.md

@@ -1001,7 +1001,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 +1010,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 +2037,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 +2782,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.