@jgengine/shell 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/GamePlayerShell.js

@@ -10,6 +10,7 @@ import { localPlayers } from "@jgengine/core/runtime/localPlayers";
 import { actionContextStack, activeActionCodes } from "@jgengine/core/game/controlGate";
 import { useDisplayProfile } from "@jgengine/react/display";
 import { RotateDeviceScreen } from "@jgengine/react/rotateDevice";
+import { canvasCover } from "@jgengine/react/canvasCover";
 import { createSettingsStore } from "@jgengine/core/settings/settingsModel";
 import { parseGraphicsQuality, withGraphicsQualityOverride } from "@jgengine/core/settings/graphicsSettings";
 import { applyBindingOverrides, clearBindingOverride, loadBindingOverrides, saveBindingOverride, } from "@jgengine/core/input/bindingOverrides";
@@ -45,6 +46,8 @@ import { installPlayFocusReclaim } from "./playSurfaceFocus.js";
 const DEV_USER_ID = "dev-player";
 /** The query param that mirrors the devtools overlay into the URL — present = open. */
 const DEBUG_PARAM = "debug";
+/** The query param that pins the canvas cover, so a perf run can measure a covered frame. */
+const COVER_PARAM = "cover";
 const NO_SUBSCRIBE = () => () => undefined;
 const ZERO_VERSION = () => 0;
 function shellRootSnapshot(ctx, userId) {
@@ -88,6 +91,10 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
             return;
         return subscribeUrlChange(() => setDevtoolsOpen(readUrlFlag(DEBUG_PARAM)));
     }, [devtoolsEnabled]);
+    // `?cover=1` holds the canvas cover for the page, so a perf run can measure a covered frame on
+    // any game without a menu. Games declare the same hold from their own covering surface.
+    const coverPinned = readUrlFlag(COVER_PARAM);
+    useEffect(() => (coverPinned ? canvasCover.hold() : undefined), [coverPinned]);
     useEffect(() => installAgentBridge({
         playable,
         devtoolsEnabled,

package/dist/Shell3dPresentation.js

@@ -48,6 +48,7 @@ import { resolvePlayableAudio } from "./audio/playableAudio.js";
 import { AudioSettingsBridge } from "./settings/appliedSettings.js";
 import { TextureFiltering } from "./render/TextureFiltering.js";
 import { FrameRateLimiter } from "./drivers/FrameRateLimiter.js";
+import { CanvasCoverFrameloop } from "./drivers/CanvasCoverFrameloop.js";
 import { FpsCounter, FpsProbe } from "./diagnostics/FpsCounter.js";
 import { ConfiguredLighting, BackdropFog } from "./render/SceneLighting.js";
 import { IrradianceVolumeLighting } from "./render/IrradianceVolumeLighting.js";
@@ -356,6 +357,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
             run: () => action.run(ctx),
         }));
     const touchScale = compact ? 0.88 : 1;
+    const canvasFrameloop = poster && posterFrozen ? "demand" : graphics.frameRateLimit > 0 && !poster ? "never" : "always";
     // The frame carries the player's colour-vision mode; the HUD and menu text above it stay unfiltered.
     const colorblind = useColorblindMode(settingsStore);
     const dockMounted = !poster &&
@@ -372,7 +374,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
         controlsActive: () => playControlsActive(ctx),
         exitPointerLockOnDevtools: true,
     });
-    return (_jsx(SettingsProvider, { store: settingsStore, children: _jsxs(PlayerFovProvider, { config: playable.camera, orthographic: orthographic, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: resolvePlayableAudio(playable).buses }), _jsx(SettingsRuntime, { variant: settingsVariant, surface: settingsSurface, actions: settingsActions, input: playable.game.input ?? {}, buses: resolvePlayableAudio(playable).buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: hideCategories, fovEnabled: fovControlEnabled, graphics: playable.graphics, hideBindings: settingsConfig.hideBindings ?? [], touchStyle: coarsePointer &&
+    return (_jsx(SettingsProvider, { store: settingsStore, children: _jsxs(PlayerFovProvider, { config: playable.camera, orthographic: orthographic, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: resolvePlayableAudio(playable).buses }), _jsx(SettingsRuntime, { variant: settingsVariant, surface: settingsSurface, actions: settingsActions, input: playable.game.input ?? {}, buses: resolvePlayableAudio(playable).buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: hideCategories, fovEnabled: fovControlEnabled, graphics: playable.graphics, postProcessing: resolvedLook.postProcessing, hideBindings: settingsConfig.hideBindings ?? [], touchStyle: coarsePointer &&
                         touchScheme !== null &&
                         (touchScheme.joystick !== null || touchScheme.buttons.length > 0), overrides: bindingOverrides, rebind: rebindAction, resetBinding: resetActionBinding, children: _jsx("div", { ref: wrapperRef, tabIndex: 0, ...(poster && posterFrozen ? { "data-poster-ready": "" } : {}), className: "relative h-full w-full bg-neutral-950 outline-none", style: {
                             "--jg-hud-dock-clearance": `${dockMounted ? touchDockClearance(touchScheme, touchScale) : 0}px`,
@@ -391,7 +393,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                                 return;
                                             ktx2SupportDetected.current = true;
                                             detectKtx2Support(gl);
-                                        }, frameloop: poster && posterFrozen ? "demand" : graphics.frameRateLimit > 0 && !poster ? "never" : "always", orthographic: orthographic, camera: orthographic
+                                        }, frameloop: canvasFrameloop, orthographic: orthographic, camera: orthographic
                                             ? {
                                                 zoom: playable.camera?.frustum?.zoom ?? CAMERA_FRUSTUM_DEFAULTS.zoom,
                                                 near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
@@ -401,7 +403,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                                 fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
                                                 near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
                                                 far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                            }, shadows: graphics.shadows ? "percentage" : false, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true, powerPreference: "high-performance" }, style: { touchAction: "none" }, children: [_jsx(TextureFiltering, { anisotropy: graphics.profile.anisotropy }), graphics.frameRateLimit > 0 && !poster ? _jsx(FrameRateLimiter, { fps: graphics.frameRateLimit }) : null, graphics.showFps ? _jsx(FpsProbe, { tally: frameTally }) : null, orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: sceneLighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: sceneLighting?.hemisphere?.groundColor ?? "#3d4a38", horizonTint: sceneLighting?.ambient?.color, sunDirection: sceneLighting?.directional?.[0]?.position, sunColor: sceneLighting?.directional?.[0]?.color ?? "#fff2d6", ...(authoredDaylight ? { daylight: daylightModulation } : {}) })) : null, sceneLighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: sceneLighting, profile: graphics.profile, ...(authoredDaylight ? { modulation: daylightModulation } : {}) })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: cinematicLook ? 0.3 : 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, authoredDaylight && effectiveSky !== undefined ? (_jsx(AuthoredDaylight, { sky: effectiveSky, clock: ctx.time, modulation: daylightModulation })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)), fogRange: backdrop?.fog })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)), fogRange: backdrop?.fog }))) : null, irradianceVolumes.length > 0 ? _jsx(IrradianceVolumeLighting, { volumes: irradianceVolumes }) : null, effectiveSky === undefined ? _jsx(BackdropFog, { fog: backdrop?.fog }) : null, _jsx(GameProvider, { context: ctx, children: _jsx(TerrainQualityContext.Provider, { value: graphics.quality, children: _jsxs(BuildingRenderBudget, { drawDistance: graphics.profile.drawDistance, visibility: playable.visibility, cullingDisabled: splitScreen, children: [_jsxs(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson, editorLayers: playable.editorLayers }), bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxSamples === undefined ? {} : { maxSamples: bars.maxSamples }), ...(bars.tickMs === undefined ? {} : { tickMs: bars.tickMs }), ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxSamples === undefined ? {} : { maxSamples: nameplates.maxSamples }), ...(nameplates.tickMs === undefined ? {} : { tickMs: nameplates.tickMs }), ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), occlude: nameplates.occlude, ...(nameplates.resolveName === undefined ? {} : { resolveName: nameplates.resolveName }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null] }), _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap, particleBudget: graphics.profile.particleBudget, diagnostics: devtoolsEnabled }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine, anchor: playable.camera?.rig === "rts" || playable.camera?.rig === "topDown" ? "ground" : "camera" }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
+                                            }, shadows: graphics.shadows ? "percentage" : false, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true, powerPreference: "high-performance" }, style: { touchAction: "none" }, children: [_jsx(CanvasCoverFrameloop, { authored: canvasFrameloop }), _jsx(TextureFiltering, { anisotropy: graphics.profile.anisotropy }), graphics.frameRateLimit > 0 && !poster ? _jsx(FrameRateLimiter, { fps: graphics.frameRateLimit }) : null, graphics.showFps ? _jsx(FpsProbe, { tally: frameTally }) : null, orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: sceneLighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: sceneLighting?.hemisphere?.groundColor ?? "#3d4a38", horizonTint: sceneLighting?.ambient?.color, sunDirection: sceneLighting?.directional?.[0]?.position, sunColor: sceneLighting?.directional?.[0]?.color ?? "#fff2d6", ...(authoredDaylight ? { daylight: daylightModulation } : {}) })) : null, sceneLighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: sceneLighting, profile: graphics.profile, ...(authoredDaylight ? { modulation: daylightModulation } : {}) })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: cinematicLook ? 0.3 : 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, authoredDaylight && effectiveSky !== undefined ? (_jsx(AuthoredDaylight, { sky: effectiveSky, clock: ctx.time, modulation: daylightModulation })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)), fogRange: backdrop?.fog })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)), fogRange: backdrop?.fog }))) : null, irradianceVolumes.length > 0 ? _jsx(IrradianceVolumeLighting, { volumes: irradianceVolumes }) : null, effectiveSky === undefined ? _jsx(BackdropFog, { fog: backdrop?.fog }) : null, _jsx(GameProvider, { context: ctx, children: _jsx(TerrainQualityContext.Provider, { value: graphics.quality, children: _jsxs(BuildingRenderBudget, { drawDistance: graphics.profile.drawDistance, visibility: playable.visibility, cullingDisabled: splitScreen, children: [_jsxs(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson, editorLayers: playable.editorLayers }), bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxSamples === undefined ? {} : { maxSamples: bars.maxSamples }), ...(bars.tickMs === undefined ? {} : { tickMs: bars.tickMs }), ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxSamples === undefined ? {} : { maxSamples: nameplates.maxSamples }), ...(nameplates.tickMs === undefined ? {} : { tickMs: nameplates.tickMs }), ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), occlude: nameplates.occlude, ...(nameplates.resolveName === undefined ? {} : { resolveName: nameplates.resolveName }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null] }), _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap, particleBudget: graphics.profile.particleBudget, diagnostics: devtoolsEnabled }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine, anchor: playable.camera?.rig === "rts" || playable.camera?.rig === "topDown" ? "ground" : "camera" }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
                                                                     cameraDraggingRef.current = dragging;
                                                                 } }), _jsx(PointerProbe, { service: pointerService })] }) }) }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled, authoritativeFrameRef: authoritativeFrameRef }), _jsx(GamepadSource, { tracker: tracker, bindings: inputBindings ?? {}, analogRef: analogRef, input: ctx.input, feel: playable.gamepad, seats: localPlayers(ctx), onSeatJoin: (slot) => {
                                                     try {

package/dist/audio/AudioComponents.js

@@ -2,15 +2,18 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { Quaternion, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
+import { createEmitterTracker } from "./emitterTracking.js";
 import { groundFocusListener } from "./listenerAnchor.js";
 import { createListenerVelocityTrack, stepListenerVelocity } from "./loopParams.js";
 export function AudioListener({ engine, anchor = "camera" }) {
     const camera = useThree((state) => state.camera);
     const ctx = useGameContext();
     const trackRef = useRef(createListenerVelocityTrack());
+    const scratchRef = useRef({ direction: new Vector3(), up: new Vector3(), quaternion: new Quaternion() });
     useFrame((_, dt) => {
-        const direction = camera.getWorldDirection(new Vector3());
-        const up = camera.up.clone().applyQuaternion(camera.getWorldQuaternion(new Quaternion()));
+        const { direction, up, quaternion } = scratchRef.current;
+        camera.getWorldDirection(direction);
+        up.copy(camera.up).applyQuaternion(camera.getWorldQuaternion(quaternion));
         const eye = { x: camera.position.x, y: camera.position.y, z: camera.position.z };
         const position = anchor === "ground" ? groundFocusListener(eye, direction, ctx.world.groundHeightAt(eye.x, eye.z)) : eye;
         engine.setListenerPose({
@@ -22,63 +25,70 @@ export function AudioListener({ engine, anchor = "camera" }) {
     });
     return null;
 }
-function useTrackedEmitters(engine, soundByKey, readEntries) {
-    const handles = useRef(new Map());
-    const lastPose = useRef(new Map());
+/**
+ * Keep one loop per sounding entity/object. The tracker retains the loops and only reads the
+ * emitters it already plays, so a still world stops paying a per-frame rebuild (#2209).
+ */
+function useTrackedEmitters(engine, soundByKey, sources) {
+    const soundsRef = useRef(soundByKey);
+    soundsRef.current = soundByKey;
+    const stateRef = useRef(null);
+    const current = stateRef.current;
+    if (current === null || current.engine !== engine) {
+        // `sources` closes over the session's game context, which outlives the engine it was built with.
+        current?.tracker.dispose();
+        stateRef.current = {
+            engine,
+            tracker: createEmitterTracker({
+                sources,
+                sounds: () => soundsRef.current,
+                play: (soundId, position) => engine.playLoop(soundId, position),
+            }),
+        };
+    }
     useEffect(() => () => {
-        for (const handle of handles.current.values())
-            handle.stop();
-        handles.current.clear();
-        lastPose.current.clear();
+        stateRef.current?.tracker.dispose();
+        stateRef.current = null;
     }, [engine]);
-    useFrame(() => {
-        if (soundByKey === undefined)
-            return;
-        const live = new Set();
-        for (const entry of readEntries()) {
-            const soundId = soundByKey[entry.key];
-            if (soundId === undefined)
-                continue;
-            live.add(entry.id);
-            let handle = handles.current.get(entry.id);
-            if (handle === undefined) {
-                handle = engine.playLoop(soundId, { x: entry.position[0], y: entry.position[1], z: entry.position[2] }) ?? undefined;
-                if (handle !== undefined) {
-                    handles.current.set(entry.id, handle);
-                    lastPose.current.set(entry.id, entry.position);
-                }
-                continue;
-            }
-            const prev = lastPose.current.get(entry.id);
-            if (prev !== undefined &&
-                prev[0] === entry.position[0] &&
-                prev[1] === entry.position[1] &&
-                prev[2] === entry.position[2]) {
-                continue;
-            }
-            handle.setPosition({ x: entry.position[0], y: entry.position[1], z: entry.position[2] });
-            lastPose.current.set(entry.id, entry.position);
-        }
-        for (const [id, handle] of handles.current) {
-            if (!live.has(id)) {
-                handle.stop();
-                handles.current.delete(id);
-                lastPose.current.delete(id);
-            }
-        }
-    });
+    useFrame(() => stateRef.current?.tracker.step());
+}
+function entitySources(ctx) {
+    return {
+        ids: () => ctx.scene.entity.ids(),
+        read(id, pose) {
+            const entity = ctx.scene.entity.get(id);
+            if (entity === null)
+                return false;
+            pose.key = entity.name;
+            pose.position = entity.position;
+            return true;
+        },
+    };
+}
+function objectSources(ctx) {
+    return {
+        ids: () => ctx.scene.object.ids(),
+        read(id, pose) {
+            const object = ctx.scene.object.get(id);
+            if (object === null)
+                return false;
+            pose.key = object.catalogId;
+            pose.position = object.position;
+            return true;
+        },
+    };
 }
 export function EntityAudioEmitters({ engine, entitySounds, }) {
     const ctx = useGameContext();
-    useTrackedEmitters(engine, entitySounds, () => ctx.scene.entity.list().map((entity) => ({ id: entity.id, key: entity.name, position: entity.position })));
+    const sourcesRef = useRef(null);
+    sourcesRef.current ??= entitySources(ctx);
+    useTrackedEmitters(engine, entitySounds, sourcesRef.current);
     return null;
 }
 export function ObjectAudioEmitters({ engine, objectSounds, }) {
     const ctx = useGameContext();
-    useTrackedEmitters(engine, objectSounds, () => ctx.scene.object.list().map((object) => ({
-        id: object.instanceId,
-        key: object.catalogId,
-        position: object.position,
-    })));
+    const sourcesRef = useRef(null);
+    sourcesRef.current ??= objectSources(ctx);
+    useTrackedEmitters(engine, objectSounds, sourcesRef.current);
     return null;
 }

package/dist/audio/FeedbackHost.js

@@ -7,6 +7,7 @@ import { CaptionOverlay } from "./CaptionOverlay.js";
 import { createCaptionFeed } from "./captions.js";
 import { attachEventFeedback, createEventFeedback } from "./eventFeedback.js";
 import { installGestureResume } from "./gestureResume.js";
+import { createHapticsRoute } from "./hapticsRoute.js";
 /**
  * Mounts the engine's feel layer for one game: announced events become a sound, a gamepad pulse, a
  * camera kick and a caption line; the audio context unlocks on the first gesture; and the caption
@@ -19,22 +20,25 @@ export function FeedbackHost({ ctx, engine }) {
     const feed = useMemo(() => createCaptionFeed(), []);
     const motionScale = useRef(accessibility.reducedMotion ? 0 : 1);
     motionScale.current = accessibility.reducedMotion ? 0 : 1;
+    const haptics = useMemo(() => createHapticsRoute((pulse) => ctx.input.haptics(ctx.player.userId).pulse("feedback", pulse, 2)), [ctx]);
     const feedback = useMemo(() => {
-        const haptics = () => ctx.input.haptics(ctx.player.userId);
         return createEventFeedback({
-            play: (sound) => ctx.game.audio.play(sound),
+            play: (sound, at) => ctx.game.audio.play(sound, at),
             shake: (amount) => cameraShake(amount),
-            haptics: (pulse) => haptics().pulse("feedback", pulse, 2),
+            haptics: (pulse) => {
+                haptics.deliver(pulse);
+            },
             caption: (text, cue) => feed.push(text, cue),
             localUserId: () => ctx.player.userId,
             localEntityId: () => ctx.player.possession.active(ctx.player.userId),
             motionScale: () => motionScale.current,
         }, { captions: accessibility.captions });
-    }, [ctx, feed, accessibility.captions]);
+    }, [ctx, feed, accessibility.captions, haptics]);
     useEffect(() => {
         feedback.retune({ captions: accessibility.captions });
     }, [feedback, accessibility.captions]);
     useEffect(() => attachEventFeedback(ctx.game.events, feedback), [ctx, feedback]);
+    useEffect(() => () => haptics.dispose(), [haptics]);
     useEffect(() => installGestureResume(engine), [engine]);
     useEffect(() => installAudioProbe(engine), [engine]);
     useEffect(() => () => feed.clear(), [feed]);

package/dist/audio/audioEngine.js

@@ -204,6 +204,16 @@ export function createAudioEngine(config = {}) {
     let listenerVelocity = { x: 0, y: 0, z: 0 };
     const nyquist = context.sampleRate / 2;
     const activeSpatialUpdaters = new Set();
+    // A Web Audio setter costs real time per call, so a listener pose that has not moved writes nothing (#2174).
+    const listenerWritten = [NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN];
+    const listenerVelocityWritten = [NaN, NaN, NaN];
+    function writeChanged(slot, index, param, value) {
+        if (slot[index] === value)
+            return false;
+        slot[index] = value;
+        setAudioParam(param, value);
+        return true;
+    }
     // Browser autoplay: until the first user gesture the context stays suspended and a played cue
     // would vanish. Hold a bounded FIFO of ids (preallocated slots) and flush it on resume.
     const pendingCues = Array.from({ length: MAX_PENDING_CUES }, () => ({
@@ -330,12 +340,17 @@ export function createAudioEngine(config = {}) {
             let panner = null;
             let playback = null;
             let stopped = false;
+            let writtenCueGain = NaN;
             function updateGain() {
                 if (cueGain === null)
                     return;
-                cueGain.gain.value = panner === null
+                const gain = panner === null
                     ? resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1)
                     : sound.gain ?? 1;
+                if (gain === writtenCueGain)
+                    return;
+                writtenCueGain = gain;
+                cueGain.gain.value = gain;
             }
             function stop() {
                 if (stopped)
@@ -393,6 +408,15 @@ export function createAudioEngine(config = {}) {
         let userGainNode = null;
         let falloffGain = null;
         let pannerNode = null;
+        // Last value written or scheduled per param: an unchanged emitter writes nothing (#2174).
+        let writtenFalloff = NaN;
+        let writtenPannerX = NaN;
+        let writtenPannerY = NaN;
+        let writtenPannerZ = NaN;
+        let writtenRate = NaN;
+        let writtenGain = NaN;
+        let writtenLowpass = NaN;
+        let writtenHighpass = NaN;
         function effectiveRate() {
             if (dopplerFactor === 0)
                 return currentRate;
@@ -400,15 +424,36 @@ export function createAudioEngine(config = {}) {
             return clampLoopRate(currentRate * shift);
         }
         function applyRate() {
-            if (sourceNode !== null)
-                sourceNode.playbackRate.setTargetAtTime(effectiveRate(), context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            if (sourceNode === null)
+                return;
+            const rate = effectiveRate();
+            if (rate === writtenRate)
+                return;
+            writtenRate = rate;
+            sourceNode.playbackRate.setTargetAtTime(rate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
         }
         function updateFalloff() {
             if (falloffGain !== null && spatial === undefined) {
-                falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+                const gain = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+                if (gain !== writtenFalloff) {
+                    writtenFalloff = gain;
+                    falloffGain.gain.value = gain;
+                }
+            }
+            if (pannerNode !== null) {
+                if (writtenPannerX !== currentPosition.x) {
+                    writtenPannerX = currentPosition.x;
+                    setAudioParam(pannerNode.positionX, currentPosition.x);
+                }
+                if (writtenPannerY !== currentPosition.y) {
+                    writtenPannerY = currentPosition.y;
+                    setAudioParam(pannerNode.positionY, currentPosition.y);
+                }
+                if (writtenPannerZ !== currentPosition.z) {
+                    writtenPannerZ = currentPosition.z;
+                    setAudioParam(pannerNode.positionZ, currentPosition.z);
+                }
             }
-            if (pannerNode !== null)
-                setPannerPosition(pannerNode, currentPosition);
             if (dopplerFactor !== 0)
                 applyRate();
         }
@@ -444,23 +489,28 @@ export function createAudioEngine(config = {}) {
             sourceNode = src;
             src.buffer = buffer;
             src.loop = loop || (sound.loop ?? false);
-            src.playbackRate.value = effectiveRate();
+            writtenRate = effectiveRate();
+            src.playbackRate.value = writtenRate;
             // Spatial panners own distance attenuation; the scalar stage keeps only authored gain.
             const uGain = context.createGain();
             userGainNode = uGain;
-            uGain.gain.value = currentUserGain;
+            writtenGain = currentUserGain;
+            uGain.gain.value = writtenGain;
             const fGain = context.createGain();
             falloffGain = fGain;
-            fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            writtenFalloff = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            fGain.gain.value = writtenFalloff;
             if (loop) {
                 const lp = context.createBiquadFilter();
                 lowpassNode = lp;
                 lp.type = "lowpass";
-                lp.frequency.value = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
+                writtenLowpass = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
+                lp.frequency.value = writtenLowpass;
                 const hp = context.createBiquadFilter();
                 highpassNode = hp;
                 hp.type = "highpass";
-                hp.frequency.value = clampLoopCutoff(currentHighpass, MIN_LOOP_CUTOFF, nyquist);
+                writtenHighpass = clampLoopCutoff(currentHighpass, MIN_LOOP_CUTOFF, nyquist);
+                hp.frequency.value = writtenHighpass;
                 src.connect(lp);
                 lp.connect(hp);
                 hp.connect(uGain);
@@ -472,6 +522,9 @@ export function createAudioEngine(config = {}) {
             if (spatial !== undefined) {
                 const panner = createPanner(context, spatial, currentPosition);
                 pannerNode = panner;
+                writtenPannerX = currentPosition.x;
+                writtenPannerY = currentPosition.y;
+                writtenPannerZ = currentPosition.z;
                 fGain.gain.value = sound.gain ?? 1;
                 fGain.connect(panner);
                 panner.connect(bus);
@@ -488,7 +541,9 @@ export function createAudioEngine(config = {}) {
             setPosition(next) {
                 if (stopped)
                     return;
-                currentPosition = { ...next };
+                currentPosition.x = next.x;
+                currentPosition.y = next.y;
+                currentPosition.z = next.z;
                 updateFalloff();
             },
             setRate(rate) {
@@ -497,21 +552,32 @@ export function createAudioEngine(config = {}) {
             },
             setLowpass(hz) {
                 currentLowpass = clampLoopCutoff(hz, MAX_LOOP_CUTOFF, nyquist);
+                if (currentLowpass === writtenLowpass)
+                    return;
+                writtenLowpass = currentLowpass;
                 if (lowpassNode !== null)
                     lowpassNode.frequency.setTargetAtTime(currentLowpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             setHighpass(hz) {
                 currentHighpass = clampLoopCutoff(hz, MIN_LOOP_CUTOFF, nyquist);
+                if (currentHighpass === writtenHighpass)
+                    return;
+                writtenHighpass = currentHighpass;
                 if (highpassNode !== null)
                     highpassNode.frequency.setTargetAtTime(currentHighpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             setVelocity(velocity) {
-                currentVelocity = { ...velocity };
+                currentVelocity.x = velocity.x;
+                currentVelocity.y = velocity.y;
+                currentVelocity.z = velocity.z;
                 if (dopplerFactor !== 0)
                     applyRate();
             },
             setGain(gain) {
                 currentUserGain = clampLoopGain(gain);
+                if (currentUserGain === writtenGain)
+                    return;
+                writtenGain = currentUserGain;
                 if (userGainNode !== null)
                     userGainNode.gain.setTargetAtTime(currentUserGain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
@@ -539,18 +605,29 @@ export function createAudioEngine(config = {}) {
             if (disposed)
                 return;
             const pose = "position" in position ? position : { position, forward: { x: 0, y: 0, z: -1 }, up: { x: 0, y: 1, z: 0 } };
-            listenerPosition = { ...pose.position };
-            listenerVelocity = "velocity" in pose && pose.velocity !== undefined ? { ...pose.velocity } : ZERO_VELOCITY;
+            listenerPosition.x = pose.position.x;
+            listenerPosition.y = pose.position.y;
+            listenerPosition.z = pose.position.z;
+            const velocity = "velocity" in pose && pose.velocity !== undefined ? pose.velocity : ZERO_VELOCITY;
+            listenerVelocity.x = velocity.x;
+            listenerVelocity.y = velocity.y;
+            listenerVelocity.z = velocity.z;
             const listener = context.listener;
-            setAudioParam(listener.positionX, pose.position.x);
-            setAudioParam(listener.positionY, pose.position.y);
-            setAudioParam(listener.positionZ, pose.position.z);
-            setAudioParam(listener.forwardX, pose.forward.x);
-            setAudioParam(listener.forwardY, pose.forward.y);
-            setAudioParam(listener.forwardZ, pose.forward.z);
-            setAudioParam(listener.upX, pose.up.x);
-            setAudioParam(listener.upY, pose.up.y);
-            setAudioParam(listener.upZ, pose.up.z);
+            let listenerMoved = writeChanged(listenerWritten, 0, listener.positionX, pose.position.x);
+            listenerMoved = writeChanged(listenerWritten, 1, listener.positionY, pose.position.y) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 2, listener.positionZ, pose.position.z) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 3, listener.forwardX, pose.forward.x) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 4, listener.forwardY, pose.forward.y) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 5, listener.forwardZ, pose.forward.z) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 6, listener.upX, pose.up.x) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 7, listener.upY, pose.up.y) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 8, listener.upZ, pose.up.z) || listenerMoved;
+            // Doppler loops alone read listener velocity, so only a changed velocity needs the per-voice pass.
+            let velocityChanged = writeChanged(listenerVelocityWritten, 0, undefined, velocity.x);
+            velocityChanged = writeChanged(listenerVelocityWritten, 1, undefined, velocity.y) || velocityChanged;
+            velocityChanged = writeChanged(listenerVelocityWritten, 2, undefined, velocity.z) || velocityChanged;
+            if (!listenerMoved && !velocityChanged)
+                return;
             for (const updateGain of activeSpatialUpdaters)
                 updateGain();
         },

package/dist/audio/emitterTracking.d.ts

@@ -0,0 +1,40 @@
+import type { AudioEmitterHandle, Vec3 } from "./audioEngine.js";
+/** One emitter's live key and position, written in place so a steady frame reads every source without allocating. @internal */
+export interface EmitterPose {
+    key: string;
+    position: readonly [number, number, number];
+}
+/** Read side of the emitters a game declares sounds for. @internal */
+export interface EmitterSources {
+    /**
+     * Every candidate id. Identity changes only on spawn/despawn (`ids()` in the entity and object
+     * stores), so the tracker reconciles membership by comparing the array it last saw.
+     */
+    ids(): readonly string[];
+    /** Fill `pose` for `id`; `false` when the source is gone. Called once per tracked emitter per frame, never per candidate. */
+    read(id: string, pose: EmitterPose): boolean;
+}
+/** Retained loops for one sound map, maintained by membership and pose events instead of rebuilt per frame. @internal */
+export interface EmitterTracker {
+    /** Advance one frame: pick up spawned/moved/despawned emitters and write nothing when nothing moved. */
+    step(): void;
+    /** Live emitters, for probes and assertions. */
+    count(): number;
+    dispose(): void;
+}
+/**
+ * Track one sound map's positional loops.
+ *
+ * Membership is reconciled only when `sources.ids()` returns a new array, and each frame then reads
+ * just the tracked emitters — so a game with hundreds of props and a handful of sounding ones pays
+ * for the handful, and a still frame allocates nothing. An emitter that gains a sounding key through
+ * a rename is picked up on the next membership change, not per frame; catalog ids never change, and a
+ * spawned entity already carries the name its sound map is keyed by.
+ * @internal
+ */
+export declare function createEmitterTracker(options: {
+    sources: EmitterSources;
+    /** Read per frame so a remount or a replaced sound map takes effect without rebuilding the tracker. */
+    sounds: () => Record<string, string> | undefined;
+    play: (soundId: string, position: Vec3) => AudioEmitterHandle | null;
+}): EmitterTracker;