@jgengine/core 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -26,6 +26,73 @@ 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
+
+- **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`.
+
+### Added
+
+- Audio mixing grew a mute that composes with gain: `AudioEngine.setBusMute` / `setMasterMute` keep the player's volume while silencing a bus, `masterLevel()` / `busLevel()` report the composed value, and Settings carries a mute row per bus plus "Mute all" (`sound.muted`, `sound.bus.<id>.muted`). `AudioEngine.play` and `playOneShot` hold cues in a bounded 16-slot queue while the browser keeps the context suspended and play them on the first gesture instead of dropping them; `installGestureResume` wires that gesture for both presentation paths.
+- `AudioEngine.measure()` reads master RMS and peak from a lazily built analyser, and `installAudioProbe` publishes `window.__jgengineAudio` so a headless capture can prove sound with a measured level rather than a screenshot.
+- `@jgengine/core/audio/feedbackCues` ships seven procedural reactions - `hit`, `hurt`, `kill`, `pickup`, `objective`, `wave`, `deny` - on an `sfx` bus, merged into every game's catalog as `feel.<cue>`. A game sound with that id replaces one; `audio.feedbackCues` replaces or silences them.
+- `@jgengine/shell/audio/eventFeedback` maps the events the engine already announces to those reactions: `combat.damage` (local player reads as hurt, anything else as a hit), `entity.died`, `worldItem.picked_up`, `quest.completed`, `stat.levelUp` and `command.refused`. Each row carries a sound, a gamepad pulse, camera trauma and a caption; the mapping and reactions are data (`DEFAULT_FEEDBACK_BINDINGS`, `DEFAULT_FEEDBACK_REACTIONS`) a game can replace, cooldowns fold a burst into one impact, reduced motion keeps sound and rumble but drops the camera kick, and the resolved reaction is pooled so handling an event allocates nothing per frame. `attachWaveFeedback(runner, ctx.game.feedback)` announces each new wave.
+- `ctx.game.feedback.cue(cue, caption?)` announces a moment no engine event covers and emits `feedback.cue`.
+- `@jgengine/shell/audio/captions` and `CaptionOverlay` render a bounded, deduping, self-expiring caption line under the accessibility captions setting; `FeedbackHost` mounts the whole layer - feedback mapping, gesture resume, audio probe and captions - for both the 3D and HUD presentation paths.
+
+### Changed
+
+- The CI gate runs nine test shards instead of ten, and a `types` job whose stages overlap, so a docs-only pull request fits the account's 20-job runner cap with room for another run beside it. `scripts/test-shard.ts` owns which files each shard runs and what it prepares first; `bun scripts/type-shard.ts` runs the `check-types` plan two stages at a time and then the tsc fan-out alone.
+
 ## 0.31.0
 
 ### Migrate

package/dist/audio/feedbackCues.d.ts

@@ -0,0 +1,30 @@
+import type { AudioBusDef, SoundDef } from "./audioFalloff.js";
+/**
+ * A gameplay moment the engine reacts to: taking or dealing a hit, a kill, a pickup, an objective,
+ * a wave starting, or a refused action. The game names the moment; the engine owns the reaction.
+ */
+export type FeedbackCue = "hit" | "hurt" | "kill" | "pickup" | "objective" | "wave" | "deny";
+/** Every {@link FeedbackCue}, in a stable order. */
+export declare const FEEDBACK_CUES: readonly FeedbackCue[];
+/** Bus the default feedback cues mix through; the settings menu shows its volume and mute. */
+export declare const FEEDBACK_CUE_BUS = "sfx";
+/** Catalog id a cue plays under: `feel.hit`, `feel.kill`, ... A game sound with that id replaces the default. */
+export declare function feedbackCueSoundId(cue: FeedbackCue): string;
+/**
+ * Short procedural reactions - no samples to load, so every game has impact feedback without
+ * authoring audio. Loud enough to read, quiet enough to sit under a weapon's own sound.
+ */
+export declare const DEFAULT_FEEDBACK_CUE_SOUNDS: Readonly<Record<FeedbackCue, SoundDef>>;
+/** Per-cue override: a replacement sound, or `false` to silence that cue. `false` for the whole map silences all. */
+export type FeedbackCueOverrides = false | Partial<Record<FeedbackCue, SoundDef | false>>;
+/**
+ * Merge the default feedback reactions into a game's sound catalog. A game sound already named
+ * `feel.<cue>` wins, then `overrides`, then the default. Adds the `sfx` bus (gain 0.9) when the game
+ * did not declare one, so the impact layer has its own volume and mute row.
+ *
+ * @capability feedback-cue-sounds default procedural hit/hurt/kill/pickup/objective/wave/deny reactions on an "sfx" bus, overridable per game
+ */
+export declare function withFeedbackCueSounds(sounds: Readonly<Record<string, SoundDef>> | undefined, buses: Readonly<Record<string, AudioBusDef>> | undefined, overrides?: FeedbackCueOverrides): {
+    sounds: Record<string, SoundDef>;
+    buses: Record<string, AudioBusDef> | undefined;
+};

package/dist/audio/feedbackCues.js

@@ -0,0 +1,119 @@
+/** Every {@link FeedbackCue}, in a stable order. */
+export const FEEDBACK_CUES = ["hit", "hurt", "kill", "pickup", "objective", "wave", "deny"];
+/** Bus the default feedback cues mix through; the settings menu shows its volume and mute. */
+export const FEEDBACK_CUE_BUS = "sfx";
+/** Catalog id a cue plays under: `feel.hit`, `feel.kill`, ... A game sound with that id replaces the default. */
+export function feedbackCueSoundId(cue) {
+    return `feel.${cue}`;
+}
+function feelSound(cue, def) {
+    return { id: feedbackCueSoundId(cue), bus: FEEDBACK_CUE_BUS, positional: false, priority: 5, ...def };
+}
+/**
+ * Short procedural reactions - no samples to load, so every game has impact feedback without
+ * authoring audio. Loud enough to read, quiet enough to sit under a weapon's own sound.
+ */
+export const DEFAULT_FEEDBACK_CUE_SOUNDS = {
+    hit: feelSound("hit", {
+        gain: 0.55,
+        maxVoices: 4,
+        synth: {
+            voices: [
+                { kind: "noise", filterType: "bandpass", filterFreq: 1800, duration: 0.05, gain: 0.3 },
+                { kind: "tone", wave: "triangle", freq: 210, slideTo: 150, duration: 0.07, gain: 0.24, attack: 0.002 },
+            ],
+        },
+    }),
+    hurt: feelSound("hurt", {
+        gain: 0.65,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 165, slideTo: 110, duration: 0.16, gain: 0.32, attack: 0.003 },
+                { kind: "noise", filterType: "lowpass", filterFreq: 900, duration: 0.1, gain: 0.14 },
+            ],
+        },
+    }),
+    kill: feelSound("kill", {
+        gain: 0.6,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "noise", filterType: "lowpass", filterFreq: 1400, duration: 0.12, gain: 0.24 },
+                { kind: "tone", wave: "sawtooth", freq: 330, slideTo: 220, duration: 0.14, gain: 0.18 },
+                { kind: "tone", wave: "sine", freq: 110, slideTo: 78, duration: 0.2, gain: 0.22, delay: 0.03 },
+            ],
+        },
+    }),
+    pickup: feelSound("pickup", {
+        gain: 0.5,
+        maxVoices: 3,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "sine", freq: 880, duration: 0.09, gain: 0.2, attack: 0.003 },
+                { kind: "tone", wave: "sine", freq: 1320, duration: 0.11, gain: 0.16, delay: 0.05, attack: 0.003 },
+            ],
+        },
+    }),
+    objective: feelSound("objective", {
+        gain: 0.55,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 523, duration: 0.14, gain: 0.22 },
+                { kind: "tone", wave: "triangle", freq: 659, duration: 0.14, gain: 0.2, delay: 0.08 },
+                { kind: "tone", wave: "triangle", freq: 784, duration: 0.26, gain: 0.2, delay: 0.16 },
+            ],
+        },
+    }),
+    wave: feelSound("wave", {
+        gain: 0.6,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "sawtooth", freq: 98, duration: 0.5, gain: 0.16, attack: 0.04, sustain: 0.24 },
+                { kind: "tone", wave: "sawtooth", freq: 147, duration: 0.5, gain: 0.12, attack: 0.05, sustain: 0.24 },
+                { kind: "noise", filterType: "lowpass", filterFreq: 600, duration: 0.45, gain: 0.12, decay: 1 },
+            ],
+        },
+    }),
+    deny: feelSound("deny", {
+        gain: 0.5,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "square", freq: 196, slideTo: 170, duration: 0.07, gain: 0.16, attack: 0.002 },
+                { kind: "tone", wave: "square", freq: 155, slideTo: 130, duration: 0.1, gain: 0.16, delay: 0.07, attack: 0.002 },
+            ],
+        },
+    }),
+};
+/**
+ * Merge the default feedback reactions into a game's sound catalog. A game sound already named
+ * `feel.<cue>` wins, then `overrides`, then the default. Adds the `sfx` bus (gain 0.9) when the game
+ * did not declare one, so the impact layer has its own volume and mute row.
+ *
+ * @capability feedback-cue-sounds default procedural hit/hurt/kill/pickup/objective/wave/deny reactions on an "sfx" bus, overridable per game
+ */
+export function withFeedbackCueSounds(sounds, buses, overrides) {
+    if (overrides === false)
+        return { sounds: { ...sounds }, buses: buses === undefined ? undefined : { ...buses } };
+    const merged = {};
+    let usesBus = false;
+    for (const cue of FEEDBACK_CUES) {
+        const id = feedbackCueSoundId(cue);
+        if (sounds?.[id] !== undefined)
+            continue;
+        const override = overrides?.[cue];
+        if (override === false)
+            continue;
+        const def = override ?? DEFAULT_FEEDBACK_CUE_SOUNDS[cue];
+        merged[id] = { ...def, id };
+        if (def.bus === FEEDBACK_CUE_BUS)
+            usesBus = true;
+    }
+    const nextBuses = usesBus && buses?.[FEEDBACK_CUE_BUS] === undefined
+        ? { ...buses, [FEEDBACK_CUE_BUS]: { id: FEEDBACK_CUE_BUS, gain: 0.9 } }
+        : buses;
+    return { sounds: { ...merged, ...sounds }, buses: nextBuses };
+}

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

@@ -2,6 +2,7 @@ import type { EffectResult } from "../combat/effects.js";
 import type { DeathReason } from "../combat/deathReason.js";
 import type { TelegraphShape } from "../combat/telegraph.js";
 import type { CameraShake } from "../combat/hitReaction.js";
+import type { FeedbackCue } from "../audio/feedbackCues.js";
 import type { CombatVfxInstanceEvent } from "./vfxInstance.js";
 export type { DeathReason };
 export interface EntityDiedEvent {
@@ -38,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 {
@@ -242,6 +249,15 @@ export interface AudioPlayEvent {
 }
 /** Request that the shell's audio engine resume its (browser-gesture-suspended) context; carries no payload. */
 export type AudioResumeEvent = Record<string, never>;
+/**
+ * A gameplay moment the game announces itself, for the moments no engine event covers (a wave
+ * starting, a scripted beat). The shell reacts with the cue's sound, rumble, camera kick and caption.
+ */
+export interface FeedbackCueEvent {
+    cue: FeedbackCue;
+    /** Caption text that replaces the cue's default label ("WAVE 3"). */
+    caption?: string;
+}
 /** Crossfade the procedural soundtrack to `theme` (null fades out), optionally transposing the incoming theme by `transpose` semitones. */
 export interface AudioMusicEvent {
     theme: string | null;
@@ -325,6 +341,7 @@ export interface GameEventMap {
     "audio.loopStop": AudioLoopStopEvent;
     "entity.animation": EntityAnimationEvent;
     "animation.event": AnimationClipEvent;
+    "feedback.cue": FeedbackCueEvent;
     "command.refused": CommandRefusedEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;

package/dist/game/playableGame.d.ts

@@ -2,6 +2,7 @@ import type { AnimGraph } from "../anim/animGraph.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { MusicTheme } from "../audio/music.js";
 import type { UiCueOverrides } from "../audio/uiCues.js";
+import type { FeedbackCueOverrides } from "../audio/feedbackCues.js";
 import type { NoticeFeedConfig } from "./notices.js";
 import type { MaterialAsset, MaterialAssignment, MaterialSurfaceParameters, MaterialTextureRole } from "../material/materialAsset.js";
 import type { EditorCatalogDefinition, EditorDocument } from "../editor/types.js";
@@ -786,6 +787,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         hudCues?: boolean;
         /** Default UI cues (`ui.click`, `ui.deny`, ...) on a "ui" bus. A sound named `ui.<cue>` in `sounds` replaces one; a map entry replaces or (`false`) silences one; `false` silences all. */
         uiCues?: UiCueOverrides;
+        /** Default gameplay reactions (`feel.hit`, `feel.kill`, `feel.pickup`, ...) on an "sfx" bus, played by the shell from the events the engine announces. A sound named `feel.<cue>` in `sounds` replaces one; a map entry replaces or (`false`) silences one; `false` silences all. */
+        feedbackCues?: FeedbackCueOverrides;
     };
     /** Continuous positional emitter keyed by entity kind name: while a matching entity exists, the shell plays and repositions the mapped `audio.sounds` id (looping engine hum, campfire crackle, footstep loop) with listener-distance falloff. */
     entitySounds?: Record<string, string>;

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.31.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,67 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.31.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`.",
+        ],
+        added: [
+            "Audio mixing grew a mute that composes with gain: `AudioEngine.setBusMute` / `setMasterMute` keep the player's volume while silencing a bus, `masterLevel()` / `busLevel()` report the composed value, and Settings carries a mute row per bus plus \"Mute all\" (`sound.muted`, `sound.bus.<id>.muted`). `AudioEngine.play` and `playOneShot` hold cues in a bounded 16-slot queue while the browser keeps the context suspended and play them on the first gesture instead of dropping them; `installGestureResume` wires that gesture for both presentation paths.",
+            "`AudioEngine.measure()` reads master RMS and peak from a lazily built analyser, and `installAudioProbe` publishes `window.__jgengineAudio` so a headless capture can prove sound with a measured level rather than a screenshot.",
+            "`@jgengine/core/audio/feedbackCues` ships seven procedural reactions - `hit`, `hurt`, `kill`, `pickup`, `objective`, `wave`, `deny` - on an `sfx` bus, merged into every game's catalog as `feel.<cue>`. A game sound with that id replaces one; `audio.feedbackCues` replaces or silences them.",
+            "`@jgengine/shell/audio/eventFeedback` maps the events the engine already announces to those reactions: `combat.damage` (local player reads as hurt, anything else as a hit), `entity.died`, `worldItem.picked_up`, `quest.completed`, `stat.levelUp` and `command.refused`. Each row carries a sound, a gamepad pulse, camera trauma and a caption; the mapping and reactions are data (`DEFAULT_FEEDBACK_BINDINGS`, `DEFAULT_FEEDBACK_REACTIONS`) a game can replace, cooldowns fold a burst into one impact, reduced motion keeps sound and rumble but drops the camera kick, and the resolved reaction is pooled so handling an event allocates nothing per frame. `attachWaveFeedback(runner, ctx.game.feedback)` announces each new wave.",
+            "`ctx.game.feedback.cue(cue, caption?)` announces a moment no engine event covers and emits `feedback.cue`.",
+            "`@jgengine/shell/audio/captions` and `CaptionOverlay` render a bounded, deduping, self-expiring caption line under the accessibility captions setting; `FeedbackHost` mounts the whole layer - feedback mapping, gesture resume, audio probe and captions - for both the 3D and HUD presentation paths.",
+        ],
+        changed: [
+            "The CI gate runs nine test shards instead of ten, and a `types` job whose stages overlap, so a docs-only pull request fits the account's 20-job runner cap with room for another run beside it. `scripts/test-shard.ts` owns which files each shard runs and what it prepares first; `bun scripts/type-shard.ts` runs the `check-types` plan two stages at a time and then the tsc fan-out alone.",
+        ],
+        removed: [],
+    },
     "0.31.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.31.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.28.0`; `@jgengine/github` is `0.18.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 {};