@jgengine/shell 0.31.0 → 0.33.0

package/dist/postfx/postfxOverlay.d.ts

@@ -15,10 +15,20 @@ export declare function isPostfxOverlay(object: {
     userData?: Record<string, unknown>;
 }): boolean;
 /**
- * Hide every currently visible marked object under `scene`, recording what was hidden into
- * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
- * undo exactly that set.
+ * Hide every currently visible object `scene`'s prepasses must skip, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can undo
+ * exactly that set. `withUnmodelled` also hides points and lines, which three's GTAO pass excludes
+ * from its normal buffer but a depth prepass keeps.
+ *
+ * The set is cached and rescanned only when the scene graph changes: walking the whole scene per
+ * prepass cost 2.4 ms/frame in Drift Foundry and 0.6 ms/frame in Harbor Heat, and the graph changes
+ * when something mounts, not between frames.
  */
-export declare function hidePostfxOverlays(scene: THREE.Object3D, out: THREE.Object3D[]): void;
+export declare function hidePostfxOverlays(scene: THREE.Object3D, out: THREE.Object3D[], withUnmodelled?: boolean): void;
 /** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
 export declare function restorePostfxOverlays(hidden: THREE.Object3D[]): void;
+/**
+ * Drop the cached set and its listeners for a scene that is going away, so a torn-down world does
+ * not keep its node graph reachable through this module.
+ */
+export declare function releasePostfxOverlayTracking(scene: THREE.Object3D): void;

package/dist/postfx/postfxOverlay.js

@@ -13,19 +13,84 @@ export const POSTFX_OVERLAY_USERDATA = {
 export function isPostfxOverlay(object) {
     return object.userData?.jgPostfxOverlay === true;
 }
+/** Whether a normal-material prepass must leave `object` out: three's AO pass cannot describe these. */
+function isUnmodelledDrawable(object) {
+    const drawable = object;
+    return drawable.isPoints === true || drawable.isLine === true || drawable.isLine2 === true;
+}
+const tracks = new WeakMap();
+function unwatchAll(track, node) {
+    track.listeners.get(node)?.();
+    track.listeners.delete(node);
+    for (const child of node.children)
+        unwatchAll(track, child);
+}
+function watch(track, node) {
+    if (track.listeners.has(node))
+        return;
+    const added = ({ child }) => {
+        track.revision += 1;
+        watch(track, child);
+    };
+    const removed = ({ child }) => {
+        track.revision += 1;
+        unwatchAll(track, child);
+    };
+    node.addEventListener("childadded", added);
+    node.addEventListener("childremoved", removed);
+    track.listeners.set(node, () => {
+        node.removeEventListener("childadded", added);
+        node.removeEventListener("childremoved", removed);
+    });
+    for (const child of node.children)
+        watch(track, child);
+}
+function trackFor(scene) {
+    const existing = tracks.get(scene);
+    if (existing !== undefined)
+        return existing;
+    const track = { revision: 0, scanned: -1, overlays: [], drawables: [], listeners: new Map() };
+    tracks.set(scene, track);
+    watch(track, scene);
+    return track;
+}
+function rescan(scene, track) {
+    track.overlays.length = 0;
+    track.drawables.length = 0;
+    scene.traverse((object) => {
+        if (isPostfxOverlay(object))
+            track.overlays.push(object);
+        else if (isUnmodelledDrawable(object))
+            track.drawables.push(object);
+    });
+    track.scanned = track.revision;
+}
+function hideAll(objects, out) {
+    for (const object of objects) {
+        if (!object.visible)
+            continue;
+        object.visible = false;
+        out.push(object);
+    }
+}
 /**
- * Hide every currently visible marked object under `scene`, recording what was hidden into
- * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
- * undo exactly that set.
+ * Hide every currently visible object `scene`'s prepasses must skip, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can undo
+ * exactly that set. `withUnmodelled` also hides points and lines, which three's GTAO pass excludes
+ * from its normal buffer but a depth prepass keeps.
+ *
+ * The set is cached and rescanned only when the scene graph changes: walking the whole scene per
+ * prepass cost 2.4 ms/frame in Drift Foundry and 0.6 ms/frame in Harbor Heat, and the graph changes
+ * when something mounts, not between frames.
  */
-export function hidePostfxOverlays(scene, out) {
+export function hidePostfxOverlays(scene, out, withUnmodelled = false) {
     out.length = 0;
-    scene.traverse((object) => {
-        if (object.visible && isPostfxOverlay(object)) {
-            object.visible = false;
-            out.push(object);
-        }
-    });
+    const track = trackFor(scene);
+    if (track.scanned !== track.revision)
+        rescan(scene, track);
+    hideAll(track.overlays, out);
+    if (withUnmodelled)
+        hideAll(track.drawables, out);
 }
 /** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
 export function restorePostfxOverlays(hidden) {
@@ -33,3 +98,18 @@ export function restorePostfxOverlays(hidden) {
         object.visible = true;
     hidden.length = 0;
 }
+/**
+ * Drop the cached set and its listeners for a scene that is going away, so a torn-down world does
+ * not keep its node graph reachable through this module.
+ */
+export function releasePostfxOverlayTracking(scene) {
+    const track = tracks.get(scene);
+    if (track === undefined)
+        return;
+    tracks.delete(scene);
+    for (const off of track.listeners.values())
+        off();
+    track.listeners.clear();
+    track.overlays.length = 0;
+    track.drawables.length = 0;
+}

package/dist/postfx/shadowPrepass.d.ts

@@ -6,5 +6,9 @@ import type * as THREE from "three";
  * @internal
  */
 export declare function renderWithCurrentMatrices<T>(scene: THREE.Object3D, render: () => T): T;
-/** Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass. @internal */
-export declare function renderShadowlessPrepass<T>(renderer: Pick<THREE.WebGLRenderer, "shadowMap">, scene: THREE.Object3D, hiddenOverlays: THREE.Object3D[], render: () => T): T;
+/**
+ * Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass.
+ * `withUnmodelled` also hides points and lines, which GTAO's normal buffer excludes anyway.
+ * @internal
+ */
+export declare function renderShadowlessPrepass<T>(renderer: Pick<THREE.WebGLRenderer, "shadowMap">, scene: THREE.Object3D, hiddenOverlays: THREE.Object3D[], render: () => T, withUnmodelled?: boolean): T;

package/dist/postfx/shadowPrepass.js

@@ -15,12 +15,16 @@ export function renderWithCurrentMatrices(scene, render) {
         scene.matrixWorldAutoUpdate = autoUpdate;
     }
 }
-/** Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass. @internal */
-export function renderShadowlessPrepass(renderer, scene, hiddenOverlays, render) {
+/**
+ * Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass.
+ * `withUnmodelled` also hides points and lines, which GTAO's normal buffer excludes anyway.
+ * @internal
+ */
+export function renderShadowlessPrepass(renderer, scene, hiddenOverlays, render, withUnmodelled = false) {
     const shadowMap = renderer.shadowMap;
     const autoUpdate = shadowMap.autoUpdate;
     const needsUpdate = shadowMap.needsUpdate;
-    hidePostfxOverlays(scene, hiddenOverlays);
+    hidePostfxOverlays(scene, hiddenOverlays, withUnmodelled);
     shadowMap.autoUpdate = false;
     shadowMap.needsUpdate = false;
     try {

package/dist/render/characterLod.js

@@ -94,6 +94,12 @@ export function noteCharacterPose(instanceId) {
 }
 /** Publish the clip and time a rig is posing at, so the crowd can continue the same pose at the swap. @internal */
 export function noteAnimationPhase(instanceId, clip, time) {
+    const published = phases.get(instanceId);
+    if (published !== undefined) {
+        published.clip = clip;
+        published.time = time;
+        return;
+    }
     phases.set(instanceId, { clip, time });
 }
 /** The clip phase a character was last posed at, or `undefined` when it never posed. @internal */

package/dist/render/useFootIk.js

@@ -174,6 +174,14 @@ function restoreFootIkPose(rig) {
             record.bone.position.copy(record.animated.p);
     }
 }
+/**
+ * Reused per frame by {@link applyFootIk}: the ground probes, their hits and the solver input are read
+ * synchronously inside one call, so a rig posing every frame allocates nothing.
+ */
+const probeInput = { origin: [0, 0, 0], direction: [0, -1, 0], maxDistance: 0 };
+const samplesScratch = [];
+const normalsScratch = [];
+const samplePool = [];
 /**
  * Applies one frame of foot IK after the animation mixer: probes the ground under each foot,
  * resolves targets with `placeFeet`, lowers the pelvis, solves each leg with `solveTwoBone` bending
@@ -187,8 +195,8 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
         record.animated.q.copy(record.bone.quaternion);
         record.animated.p.copy(record.bone.position);
     }
-    const samples = [];
-    const normals = [];
+    samplesScratch.length = 0;
+    normalsScratch.length = 0;
     let length = 0;
     let ankleHeight = 0;
     for (const leg of rig.legs) {
@@ -197,11 +205,19 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
         length = Math.max(length, legSize);
         ankleHeight = Math.max(ankleHeight, leg.ankleRatio * legSize);
         const from = Math.max(scratch.tip.y, originY) + legSize * 0.5;
-        const hit = probe({ origin: [scratch.tip.x, from, scratch.tip.z], direction: [0, -1, 0], maxDistance: legSize * 2 });
-        samples.push({ ankleY: scratch.tip.y, groundY: hit === null ? null : hit.point[1] });
-        normals.push(hit === null ? null : hit.normal);
+        probeInput.origin[0] = scratch.tip.x;
+        probeInput.origin[1] = from;
+        probeInput.origin[2] = scratch.tip.z;
+        probeInput.maxDistance = legSize * 2;
+        const hit = probe(probeInput);
+        const index = samplesScratch.length;
+        const sample = samplePool[index] ?? (samplePool[index] = { ankleY: 0, groundY: null });
+        sample.ankleY = scratch.tip.y;
+        sample.groundY = hit === null ? null : hit.point[1];
+        samplesScratch.push(sample);
+        normalsScratch.push(hit === null ? null : hit.normal);
     }
-    const placement = placeFeet({ feet: samples, originY, ankleHeight, maxAdjust: rig.maxAdjust * length, airborneGap: length * 0.3 });
+    const placement = placeFeet({ feet: samplesScratch, originY, ankleHeight, maxAdjust: rig.maxAdjust * length, airborneGap: length * 0.3 });
     const blend = Math.min(1, delta * (placement.grounded ? 12 : 6));
     state.weight += ((placement.grounded ? 1 : 0) - state.weight) * blend;
     state.pelvis += (placement.pelvisOffset - state.pelvis) * Math.min(1, delta * 15);
@@ -230,9 +246,9 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
         aimSegment(leg.root, root, mid, solved.mid);
         // Rotating the thigh also moved the tip; aim the shin from that updated pose.
         aimSegment(leg.mid, leg.mid.getWorldPosition(scratch.mid), leg.tip.getWorldPosition(scratch.tip), solved.tip);
-        const normal = normals[i];
+        const normal = normalsScratch[i];
         if (normal !== null && normal !== undefined && rig.alignToGround > 0) {
-            const planted = 1 - Math.min(1, Math.max(0, samples[i].ankleY - ankleHeight - samples[i].groundY) / Math.max(ankleHeight, length * 0.05));
+            const planted = 1 - Math.min(1, Math.max(0, samplesScratch[i].ankleY - ankleHeight - samplesScratch[i].groundY) / Math.max(ankleHeight, length * 0.05));
             const tilt = scratch.q.setFromUnitVectors(UP, scratch.b.set(normal[0], normal[1], normal[2]).normalize());
             const current = leg.tip.getWorldQuaternion(scratch.q2);
             writeWorldQuaternion(leg.tip, current.slerp(tilt.multiply(current), planted * weight * rig.alignToGround));
@@ -251,6 +267,8 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
     }
     return placement.grounded;
 }
+/** Materials a foot probe may hit: blocking physical objects and terrain, never the model's own entity. */
+const IK_FILTER = { entities: false, objects: true, walls: false, terrain: true };
 /**
  * Runs foot IK after the model's animation mixer for `ModelConfig.ik`. Ground probes hit terrain and
  * blocking physical objects, never the model's own entity. `groundOffset` is the model-space height
@@ -262,6 +280,16 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
     const state = useRef({ weight: 0, pelvis: 0 });
     const lookAtConfig = config === undefined || config === "auto" ? undefined : config.lookAt;
     const target = useRef(null);
+    // One probe input and one look-at triple per mount: a rig that poses every frame allocates nothing.
+    const probe = useMemo(() => ({
+        origin: [0, 0, 0],
+        direction: [0, -1, 0],
+        maxDistance: 0,
+        excludeInstanceIds: instanceId === undefined ? [] : [instanceId],
+        filter: IK_FILTER,
+        accept: (hit) => hit.blocks && hit.purpose === "physical",
+    }), [instanceId]);
+    const lookAtPoint = useMemo(() => [0, 0, 0], []);
     useLayoutEffect(() => {
         state.current = { weight: 0, pelvis: 0 };
         target.current = null;
@@ -277,15 +305,26 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
             return;
         const parent = scene.parent;
         const originY = parent === null ? scene.position.y : parent.localToWorld(scratch.a.set(0, groundOffset, 0)).y;
-        const exclude = [instanceId];
         const aim = resolveLookAtTarget(lookAtConfig?.target, ctx, target.current, lookAtConfig?.entityEyeHeight ?? DEFAULT_EYE_HEIGHT);
         target.current = aim;
-        applyFootIk(rig, originY, (input) => ctx.scene.raycast({
-            ...input,
-            excludeInstanceIds: exclude,
-            filter: { entities: false, objects: true, walls: false, terrain: true },
-            accept: (hit) => hit.blocks && hit.purpose === "physical",
-        }), state.current, delta, aim === null ? camera.getWorldPosition(scratch.b).toArray() : [aim.x, aim.y, aim.z]);
+        if (aim === null) {
+            const world = camera.getWorldPosition(scratch.b);
+            lookAtPoint[0] = world.x;
+            lookAtPoint[1] = world.y;
+            lookAtPoint[2] = world.z;
+        }
+        else {
+            lookAtPoint[0] = aim.x;
+            lookAtPoint[1] = aim.y;
+            lookAtPoint[2] = aim.z;
+        }
+        applyFootIk(rig, originY, (input) => {
+            probe.origin[0] = input.origin[0];
+            probe.origin[1] = input.origin[1];
+            probe.origin[2] = input.origin[2];
+            probe.maxDistance = input.maxDistance;
+            return ctx.scene.raycast(probe);
+        }, state.current, delta, lookAtPoint);
     });
 }
 const DEFAULT_EYE_HEIGHT = 1.5;

package/dist/render/useModelAnimation.js

@@ -187,13 +187,17 @@ function applyGraphClips(actions, clips) {
     }
 }
 /** The clip with the largest weight in one graph output: the pose the rig is mostly showing. */
-function dominantPhase(clips) {
+function dominantPhase(clips, out) {
     let best;
     for (const entry of clips) {
         if (entry.weight > 0 && (best === undefined || entry.weight > best.weight))
             best = entry;
     }
-    return best === undefined ? undefined : { clip: best.clip, time: best.time };
+    if (best === undefined)
+        return undefined;
+    out.clip = best.clip;
+    out.time = best.time;
+    return out;
 }
 /**
  * Binds a graph's clips to a rig exactly as `useModelAnimation` does (masked layers get filtered
@@ -282,6 +286,8 @@ function buildGraphPlayback(scene, mixer, graph, clips, rng) {
         lastYaw: null,
         smoothedSpeed: 0,
         params: {},
+        step: { dx: 0, dz: 0, dyaw: 0, seconds: 0 },
+        phase: { clip: "", time: 0 },
     };
 }
 /**
@@ -465,10 +471,21 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
                         else {
                             const instantSpeed = Math.hypot(dx, dz) / playbackDelta;
                             playback.smoothedSpeed += (instantSpeed - playback.smoothedSpeed) * Math.min(1, playbackDelta * 12);
-                            step = { dx, dz, dyaw: playback.lastYaw === null ? 0 : shortestAngle(yaw - playback.lastYaw), seconds: playbackDelta };
+                            const sample = playback.step;
+                            sample.dx = dx;
+                            sample.dz = dz;
+                            sample.dyaw = playback.lastYaw === null ? 0 : shortestAngle(yaw - playback.lastYaw);
+                            sample.seconds = playbackDelta;
+                            step = sample;
                         }
                     }
-                    playback.lastPos = [x, entity.position[1], z];
+                    if (playback.lastPos === null)
+                        playback.lastPos = [x, entity.position[1], z];
+                    else {
+                        playback.lastPos[0] = x;
+                        playback.lastPos[1] = entity.position[1];
+                        playback.lastPos[2] = z;
+                    }
                     playback.lastYaw = yaw;
                     readModelAnimationParams(ctx, instanceId, playback.smoothedSpeed, params, step);
                 }
@@ -487,7 +504,7 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             mixerRef.current.update(0);
             if (instanceId !== undefined) {
                 noteCharacterPose(instanceId);
-                const phase = dominantPhase(out.clips);
+                const phase = dominantPhase(out.clips, playback.phase);
                 if (phase !== undefined)
                     noteAnimationPhase(instanceId, phase.clip, phase.time);
             }

package/dist/settings/appliedSettings.js

@@ -3,6 +3,7 @@ import { busVolumeSettingId, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, SETTING_ID
 import { readGraphicsSettings } from "@jgengine/core/settings/graphicsSettings";
 import { readFrameRateLimit } from "@jgengine/core/settings/frameRateLimit";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANTS, TOUCH_STYLES, } from "@jgengine/core/input/touchScheme";
+import { busMuteSettingId, MASTER_MUTE_SETTING_ID } from "../audio/busMix.js";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
 export const TOUCH_STYLE_AUTO = "auto";
 /** Shell-internal: binds the SettingsStore touch-style choice to the touch renderer. @internal */
@@ -49,8 +50,10 @@ export function AudioSettingsBridge({ store, engine, buses, }) {
     const rev = useSettingsRevision(store);
     useEffect(() => {
         engine.setMasterGain(store.get(SETTING_IDS.masterVolume, DEFAULT_MASTER_VOLUME));
+        engine.setMasterMute(Boolean(store.get(MASTER_MUTE_SETTING_ID, false)));
         for (const bus of Object.values(buses ?? {})) {
             engine.setBusGain(bus.id, store.get(busVolumeSettingId(bus.id), bus.gain ?? 1));
+            engine.setBusMute(bus.id, Boolean(store.get(busMuteSettingId(bus.id), false)));
         }
     }, [store, engine, buses, rev]);
     return null;

package/dist/settings/settingsController.d.ts

@@ -1,8 +1,9 @@
 import { bindingLabel, type ActionCodesMap } from "@jgengine/core/input/actionBindings";
 import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
-import { type GameSettingDef, type SettingCategory, type SettingCategoryDef } from "@jgengine/core/settings/settingsModel";
+import { type GameSettingDef, type SettingCategory, type SettingCategoryDef, type SettingsStore } from "@jgengine/core/settings/settingsModel";
 import { type GraphicsProfileOverrides } from "@jgengine/core/settings/graphicsSettings";
+import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
 import { type SettingsActionView, type SettingsKeybindRow, type SettingsCategoryView, type SettingsController, type SettingsRow } from "@jgengine/react/settings";
 export type { SettingsActionView, SettingsKeybindRow, SettingsCategoryView, SettingsController, SettingsRow };
 export interface SettingsControllerInput {
@@ -14,6 +15,8 @@ export interface SettingsControllerInput {
     fovEnabled: boolean;
     /** The game's per-tier profile overrides (`defineGame({ graphics })`), so tier defaults match what renders. */
     graphics?: GraphicsProfileOverrides;
+    /** The post chain this game actually runs, so a stage row never outlives its pass. */
+    postProcessing?: PostProcessingConfig;
     hideBindings: readonly string[];
     /** Show the touch-controls skin selector in Controls (touch device with a dock). */
     touchStyle: boolean;
@@ -22,4 +25,10 @@ export interface SettingsControllerInput {
     resetBinding: (action: string) => void;
 }
 export declare function useSettingsCategories(config: SettingsControllerInput): SettingsCategoryView[];
+/**
+ * The built-in Graphics rows: tier, scale, filtering, shadows, one toggle per postfx stage this
+ * game's chain can build, then UI scale and FPS.
+ * @internal
+ */
+export declare function graphicsSettingRows(store: SettingsStore, overrides: GraphicsProfileOverrides | undefined, postProcessing: PostProcessingConfig | undefined): SettingsRow[];
 export { bindingLabel };

package/dist/settings/settingsController.js

@@ -1,8 +1,10 @@
 import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
 import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
-import { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, GRAPHICS_POST_STAGES, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
+import { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
 import { FRAME_RATE_LIMIT_DISPLAY, FRAME_RATE_LIMIT_OPTIONS } from "@jgengine/core/settings/frameRateLimit";
 import { accessibilitySettingRows } from "@jgengine/core/settings/accessibilitySettings";
+import { busMuteSettingId, MASTER_MUTE_SETTING_ID } from "../audio/busMix.js";
+import { availablePostfxStages } from "../postfx/PostProcessing.js";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANT_OPTIONS, TOUCH_STYLE_OPTIONS, } from "@jgengine/core/input/touchScheme";
 import { TOUCH_STYLE_AUTO, useSettingsRevision } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
@@ -63,77 +65,24 @@ export function useSettingsCategories(config) {
                 set: (value) => store.set(id, value),
             };
         }),
-        ...extrasFor("sound"),
-    ];
-    const graphics = readGraphicsSettings(store, config.graphics);
-    const graphicsRows = [
-        {
-            id: SETTING_IDS.graphicsQuality,
-            label: "Quality",
-            kind: "select",
-            value: graphics.quality,
-            options: GRAPHICS_QUALITY_OPTIONS,
-            set: (value) => applyGraphicsQuality(store, String(value), config.graphics),
-        },
-        {
-            id: SETTING_IDS.graphicsRenderScale,
-            label: "Render scale",
-            kind: "slider",
-            value: graphics.profile.renderScale,
-            min: RENDER_SCALE_MIN,
-            max: RENDER_SCALE_MAX,
-            step: RENDER_SCALE_STEP,
-            format: percent,
-            set: (value) => store.set(SETTING_IDS.graphicsRenderScale, value),
-        },
-        {
-            id: SETTING_IDS.graphicsFrameRateLimit,
-            label: "Frame rate limit",
-            kind: "select",
-            value: store.get(SETTING_IDS.graphicsFrameRateLimit, FRAME_RATE_LIMIT_DISPLAY),
-            options: FRAME_RATE_LIMIT_OPTIONS,
-            set: (value) => store.set(SETTING_IDS.graphicsFrameRateLimit, String(value)),
-        },
-        {
-            id: SETTING_IDS.graphicsAnisotropy,
-            label: "Texture filtering",
-            kind: "select",
-            value: String(graphics.profile.anisotropy),
-            options: ANISOTROPY_OPTIONS,
-            set: (value) => store.set(SETTING_IDS.graphicsAnisotropy, String(value)),
-        },
-        {
-            id: SETTING_IDS.graphicsShadows,
-            label: "Shadows",
+        ...Object.values(config.buses ?? {}).map((bus) => ({
+            id: busMuteSettingId(bus.id),
+            label: bus.id === "ui" ? "Mute UI" : `Mute ${bus.id}`,
             kind: "toggle",
-            value: store.get(SETTING_IDS.graphicsShadows, DEFAULT_GRAPHICS_SHADOWS),
-            set: (value) => store.set(SETTING_IDS.graphicsShadows, value),
-        },
-        ...GRAPHICS_POST_STAGES.map((stage) => ({
-            id: graphicsPostStageSettingId(stage),
-            label: GRAPHICS_POST_STAGE_LABELS[stage],
-            kind: "toggle",
-            value: graphics.profile.postStages[stage],
-            set: (value) => store.set(graphicsPostStageSettingId(stage), value),
+            value: Boolean(store.get(busMuteSettingId(bus.id), false)),
+            set: (value) => store.set(busMuteSettingId(bus.id), Boolean(value)),
         })),
         {
-            id: SETTING_IDS.graphicsUiScale,
-            label: "UI scale",
-            kind: "slider",
-            value: store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE),
-            min: UI_SCALE_MIN,
-            max: UI_SCALE_MAX,
-            step: 0.05,
-            format: percent,
-            set: (value) => store.set(SETTING_IDS.graphicsUiScale, value),
-        },
-        {
-            id: SETTING_IDS.graphicsShowFps,
-            label: "Show FPS",
+            id: MASTER_MUTE_SETTING_ID,
+            label: "Mute all",
             kind: "toggle",
-            value: store.get(SETTING_IDS.graphicsShowFps, false),
-            set: (value) => store.set(SETTING_IDS.graphicsShowFps, value),
+            value: Boolean(store.get(MASTER_MUTE_SETTING_ID, false)),
+            set: (value) => store.set(MASTER_MUTE_SETTING_ID, Boolean(value)),
         },
+        ...extrasFor("sound"),
+    ];
+    const graphicsRows = [
+        ...graphicsSettingRows(store, config.graphics, config.postProcessing),
         ...extrasFor("graphics"),
     ];
     const gameplayRows = [
@@ -225,6 +174,84 @@ export function useSettingsCategories(config) {
     views.sort((a, b) => (declaredOrder.get(a.id) ?? indexOrder(order, a.id)) - (declaredOrder.get(b.id) ?? indexOrder(order, b.id)));
     return views;
 }
+/**
+ * The built-in Graphics rows: tier, scale, filtering, shadows, one toggle per postfx stage this
+ * game's chain can build, then UI scale and FPS.
+ * @internal
+ */
+export function graphicsSettingRows(store, overrides, postProcessing) {
+    const graphics = readGraphicsSettings(store, overrides);
+    const stages = postProcessing === undefined || postProcessing.enabled === false ? [] : availablePostfxStages(postProcessing);
+    return [
+        {
+            id: SETTING_IDS.graphicsQuality,
+            label: "Quality",
+            kind: "select",
+            value: graphics.quality,
+            options: GRAPHICS_QUALITY_OPTIONS,
+            set: (value) => applyGraphicsQuality(store, String(value), overrides),
+        },
+        {
+            id: SETTING_IDS.graphicsRenderScale,
+            label: "Render scale",
+            kind: "slider",
+            value: graphics.profile.renderScale,
+            min: RENDER_SCALE_MIN,
+            max: RENDER_SCALE_MAX,
+            step: RENDER_SCALE_STEP,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.graphicsRenderScale, value),
+        },
+        {
+            id: SETTING_IDS.graphicsFrameRateLimit,
+            label: "Frame rate limit",
+            kind: "select",
+            value: store.get(SETTING_IDS.graphicsFrameRateLimit, FRAME_RATE_LIMIT_DISPLAY),
+            options: FRAME_RATE_LIMIT_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsFrameRateLimit, String(value)),
+        },
+        {
+            id: SETTING_IDS.graphicsAnisotropy,
+            label: "Texture filtering",
+            kind: "select",
+            value: String(graphics.profile.anisotropy),
+            options: ANISOTROPY_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsAnisotropy, String(value)),
+        },
+        {
+            id: SETTING_IDS.graphicsShadows,
+            label: "Shadows",
+            kind: "toggle",
+            value: store.get(SETTING_IDS.graphicsShadows, DEFAULT_GRAPHICS_SHADOWS),
+            set: (value) => store.set(SETTING_IDS.graphicsShadows, value),
+        },
+        ...stages.map((stage) => ({
+            id: graphicsPostStageSettingId(stage),
+            label: GRAPHICS_POST_STAGE_LABELS[stage],
+            kind: "toggle",
+            value: graphics.profile.postStages[stage],
+            set: (value) => store.set(graphicsPostStageSettingId(stage), value),
+        })),
+        {
+            id: SETTING_IDS.graphicsUiScale,
+            label: "UI scale",
+            kind: "slider",
+            value: store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE),
+            min: UI_SCALE_MIN,
+            max: UI_SCALE_MAX,
+            step: 0.05,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.graphicsUiScale, value),
+        },
+        {
+            id: SETTING_IDS.graphicsShowFps,
+            label: "Show FPS",
+            kind: "toggle",
+            value: store.get(SETTING_IDS.graphicsShowFps, false),
+            set: (value) => store.set(SETTING_IDS.graphicsShowFps, value),
+        },
+    ];
+}
 function indexOrder(order, id) {
     const index = order.indexOf(id);
     return index === -1 ? 999 : index;

package/dist/vision/RevealVision.d.ts

@@ -6,7 +6,7 @@ export interface RevealVisionOptions {
     tags: readonly string[];
     resolveTags: (entity: SceneEntity) => readonly string[];
 }
-/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene. */
+/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene and refreshed on render. */
 export declare function useRevealHits(options: RevealVisionOptions): readonly RevealHit[];
 export interface RevealHighlightsProps extends RevealVisionOptions {
     enabled: boolean;
@@ -17,6 +17,8 @@ export interface RevealHighlightsProps extends RevealVisionOptions {
  * occluders (Dark Sight / detective-vision / wallhack style). Renders with
  * `depthTest: false` so the highlight draws over any wall standing between
  * the origin and the revealed entity, rather than the usual depth-sorted scene.
+ * Highlights track the origin and their targets every frame while enabled, so
+ * a disabled mode costs no renders.
  */
 export declare function RevealHighlights(props: RevealHighlightsProps): import("react").JSX.Element | null;
 export interface RevealScreenTintProps {