@jgengine/core 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -26,6 +26,64 @@ 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.34.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.34.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.31.0`; `@jgengine/github` is `0.21.0`.
+
+### Added
+
+- `createRunLoop` (`@jgengine/core/run/runLoop`) holds a run's at-risk haul, banks it scaled by the line or loses it on a failure, and draws one authored change for each next run from a seeded table, so the same seed and run history replay the same sequence. State round-trips through `snapshot`/`restore`; the money stays in `progression/careerBank`.
+
+## 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/ai/driver.d.ts

@@ -28,7 +28,44 @@ export interface DriverGoal {
     stopAtGoal?: boolean;
     /** Cap on desired speed for this goal (a speed limit, a formation speed); default unlimited. */
     speedLimit?: number;
+    /**
+     * This car's catch-up pacing band, applied to the goal's pace. The caller measures {@link paceGap}
+     * (it owns the spatial query) and tunes the band; {@link paceBandFactor} is the rule.
+     */
+    paceBand?: PaceBand;
+    /** Signed gap to the band's reference: positive when this car is ahead of it; default `0`. */
+    paceGap?: number;
 }
+/**
+ * Catch-up pacing for one car in a field: the gap it tries to hold to a reference car (a rival, the
+ * player, a convoy lead) and how its pace bends when it drifts off that gap. Past `margin` by
+ * `tolerance` it sheds up to `ease` of its pace; short of it by `tolerance` it gains up to `push`;
+ * inside that tolerance it leaves the car alone. The push never outdrives `DriverTuning.maxSpeed`,
+ * so a band changes how hard a car tries, never what it is built to do.
+ */
+export interface PaceBand {
+    /** Gap to the reference this car aims to hold, world units; default `0` (level with it). */
+    margin?: number;
+    /** Gap error either side of `margin` the car leaves alone; default `0`. */
+    tolerance?: number;
+    /** Gap error past `tolerance` where the ease reaches full strength; default `0` (at once). */
+    easeAt?: number;
+    /** Fraction of the goal's pace shed at full ease; default `0`. */
+    ease?: number;
+    /** Gap error past `tolerance` where the push reaches full strength; default `0` (at once). */
+    pushAt?: number;
+    /** Fraction of the goal's pace added at full push; default `0`. */
+    push?: number;
+    /** Share of the band this car accepts, `0..1`; default `1`. */
+    scale?: number;
+}
+/**
+ * The pace multiplier a {@link PaceBand} asks for at `gap`: `1` inside the tolerance, `1 - ease *
+ * scale` fully ahead of it, `1 + push * scale` fully behind it, ramped linearly across `easeAt` /
+ * `pushAt` in between. Pure scalar math, so a band is deterministic and costs no allocation per
+ * step; the result never goes negative.
+ */
+export declare function paceBandFactor(band: PaceBand, gap: number): number;
 /** Vehicle-feel numbers the game supplies; everything has a sensible default except `maxSpeed`. */
 export interface DriverTuning {
     /** Top desired speed on a straight, world units/second. */
@@ -86,8 +123,10 @@ export interface DriverStep extends AxisInput {
  * `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper
  * margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`,
  * so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut
- * toward where the target *was*. When throttle produces no motion for a tier-scaled while the
- * driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+ * toward where the target *was*. A {@link PaceBand} on the goal eases a car ahead of its margin and
+ * pushes one behind it, bounded by the car's own top speed. When throttle produces no motion for a
+ * tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared
+ * sim's reverse).
  *
  * @capability ai-driver difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
  */

package/dist/ai/driver.js

@@ -1,4 +1,30 @@
 import { executionError } from "./difficulty.js";
+/**
+ * The pace multiplier a {@link PaceBand} asks for at `gap`: `1` inside the tolerance, `1 - ease *
+ * scale` fully ahead of it, `1 + push * scale` fully behind it, ramped linearly across `easeAt` /
+ * `pushAt` in between. Pure scalar math, so a band is deterministic and costs no allocation per
+ * step; the result never goes negative.
+ */
+export function paceBandFactor(band, gap) {
+    const scale = band.scale ?? 1;
+    if (scale <= 0)
+        return 1;
+    const error = gap - (band.margin ?? 0);
+    const tolerance = band.tolerance ?? 0;
+    if (error > tolerance) {
+        const ease = band.ease ?? 0;
+        if (ease <= 0)
+            return 1;
+        return Math.max(0, 1 - ease * scale * Math.min(1, (error - tolerance) / (band.easeAt ?? 0)));
+    }
+    if (error < -tolerance) {
+        const push = band.push ?? 0;
+        if (push <= 0)
+            return 1;
+        return Math.max(0, 1 + push * scale * Math.min(1, (-error - tolerance) / (band.pushAt ?? 0)));
+    }
+    return 1;
+}
 /**
  * Fresh driver state committed to an initial target (usually the spawn-time goal or the spawn
  * position itself).
@@ -32,8 +58,10 @@ const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
  * `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper
  * margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`,
  * so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut
- * toward where the target *was*. When throttle produces no motion for a tier-scaled while the
- * driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+ * toward where the target *was*. A {@link PaceBand} on the goal eases a car ahead of its margin and
+ * pushes one behind it, bounded by the car's own top speed. When throttle produces no motion for a
+ * tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared
+ * sim's reverse).
  *
  * @capability ai-driver difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
  */
@@ -75,6 +103,9 @@ export function driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleA
     const cornerSlowdown = tuning.cornerSlowdown ?? 0.75;
     const cornerFactor = 1 - cornerSlowdown * Math.min(1, Math.abs(headingError) / (Math.PI / 2));
     let desiredSpeed = Math.min(tuning.maxSpeed, goal.speedLimit ?? Number.POSITIVE_INFINITY);
+    if (goal.paceBand !== undefined) {
+        desiredSpeed = Math.min(tuning.maxSpeed, desiredSpeed * paceBandFactor(goal.paceBand, goal.paceGap ?? 0));
+    }
     desiredSpeed *= cornerFactor;
     if (goal.stopAtGoal === true) {
         // Ease in over the last stretch so the stop lands inside the radius instead of overshooting.

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.34.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,60 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.32.0";
+export const VERSION = "0.34.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.34.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.34.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.31.0`; `@jgengine/github` is `0.21.0`.",
+        ],
+        added: [
+            "`createRunLoop` (`@jgengine/core/run/runLoop`) holds a run's at-risk haul, banks it scaled by the line or loses it on a failure, and draws one authored change for each next run from a seeded table, so the same seed and run history replay the same sequence. State round-trips through `snapshot`/`restore`; the money stays in `progression/careerBank`.",
+        ],
+        changed: [],
+        removed: [],
+    },
+    "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 {};