@jgengine/shell 0.30.0 → 0.32.0

package/dist/audio/captions.js

@@ -0,0 +1,77 @@
+const DEFAULT_CAP = 3;
+const DEFAULT_TTL_MS = 2400;
+/**
+ * The caption list the feedback seam writes to and the HUD overlay reads: bounded, self-expiring, and
+ * deduped so three hits read as "Hit x3" rather than three copies. Pure state with an injected clock,
+ * so it runs headless.
+ *
+ * @capability caption-feed bounded, self-expiring, deduped caption lines for the accessibility captions overlay
+ */
+export function createCaptionFeed(config = {}) {
+    const now = config.now ?? Date.now;
+    let cap = Math.max(1, config.cap ?? DEFAULT_CAP);
+    let ttlMs = Math.max(0, config.ttlMs ?? DEFAULT_TTL_MS);
+    let captions = [];
+    let counter = 0;
+    const listeners = new Set();
+    function set(next) {
+        if (next === captions)
+            return;
+        captions = next;
+        for (const listener of [...listeners])
+            listener();
+    }
+    function live(time) {
+        return captions.every((caption) => caption.expiresAt > time)
+            ? captions
+            : captions.filter((caption) => caption.expiresAt > time);
+    }
+    return {
+        push(text, kind = "default") {
+            const time = now();
+            const current = live(time);
+            const index = current.findIndex((caption) => caption.text === text);
+            if (index >= 0) {
+                const previous = current[index];
+                const next = [...current];
+                next[index] = { ...previous, kind, count: previous.count + 1, at: time, expiresAt: time + ttlMs };
+                set(next);
+                return next[index];
+            }
+            const caption = { id: counter, text, kind, count: 1, at: time, expiresAt: time + ttlMs };
+            counter += 1;
+            const appended = [...current, caption];
+            set(appended.length > cap ? appended.slice(appended.length - cap) : appended);
+            return caption;
+        },
+        list() {
+            return live(now());
+        },
+        prune(nowMs) {
+            set(live(nowMs ?? now()));
+        },
+        clear() {
+            if (captions.length > 0)
+                set([]);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        retune(next) {
+            if (next.cap !== undefined)
+                cap = Math.max(1, next.cap);
+            if (next.ttlMs !== undefined)
+                ttlMs = Math.max(0, next.ttlMs);
+            set(live(now()));
+        },
+        snapshot() {
+            return { captions: [...captions], counter };
+        },
+        restore(state) {
+            captions = [...state.captions];
+            counter = state.counter;
+            set(live(now()));
+        },
+    };
+}

package/dist/audio/eventFeedback.d.ts

@@ -0,0 +1,127 @@
+import type { FeedbackCue } from "@jgengine/core/audio/feedbackCues";
+import type { GameEventMap, GameEvents } from "@jgengine/core/game/events";
+import type { HapticPulse } from "@jgengine/core/input/haptics";
+import type { WaveRunner } from "@jgengine/core/ai/waveRunner";
+/** One cue's reaction: what plays, what the hand feels, what the screen does, and what a caption says. */
+export interface FeedbackReaction {
+    /** Catalog id played for the cue. Defaults to `feel.<cue>`; a game sound with that id replaces it. */
+    sound: string;
+    /** Gamepad pulse, `0..1` per motor. Omitted cues do not rumble. */
+    haptics?: HapticPulse;
+    /** Camera trauma `0..1`, scaled by the player's motion setting (`0` under reduced motion). */
+    shake?: number;
+    /** Caption text when the accessibility captions setting is on. */
+    caption?: string;
+    /** Minimum ms between two plays of this cue, so a burst of hits reads as one impact. Default 40. */
+    cooldownMs?: number;
+}
+/**
+ * The default reactions. They are data: a game overrides one through `audio.feedbackCues` (sound) or
+ * `createEventFeedback({ reactions })` (haptics, shake, caption), and replaces the mapping through
+ * `bindings` without touching the shell.
+ */
+export declare const DEFAULT_FEEDBACK_REACTIONS: Readonly<Record<FeedbackCue, FeedbackReaction>>;
+/** Which side of an event a binding reacts to: the local player's, someone else's, or either. */
+export type FeedbackScope = "local" | "remote" | "any";
+/** Event names the default mapping listens to; a game may add its own through `bindings`. */
+export type FeedbackEventName = "combat.damage" | "entity.died" | "worldItem.picked_up" | "quest.completed" | "stat.levelUp" | "command.refused";
+/** One row of the event mapping: `event` announces, `cue` reacts. */
+export type FeedbackBinding<Name extends FeedbackEventName = FeedbackEventName> = {
+    event: Name;
+    cue: FeedbackCue;
+    /** Default `"any"`. `"local"` only fires for the local player's own target/user/refusal. */
+    scope?: FeedbackScope;
+    /** Overrides the cue's caption for this event, e.g. "You died". */
+    caption?: string;
+    /** Reads extra caption detail out of the payload, e.g. the damage amount. */
+    detail?: (payload: GameEventMap[Name]) => string | undefined;
+};
+/** Any row of the event mapping, whichever event it binds. */
+export type AnyFeedbackBinding = {
+    [Name in FeedbackEventName]: FeedbackBinding<Name>;
+}[FeedbackEventName];
+/**
+ * The default mapping: each engine-announced gameplay event to the cue it raises. Damage to the
+ * local player reads as hurt, damage anywhere else as a hit; a wave start has no event of its own,
+ * so a game announces it through `notify("wave")` or `attachWaveFeedback`.
+ */
+export declare const DEFAULT_FEEDBACK_BINDINGS: readonly AnyFeedbackBinding[];
+/** A resolved trigger: pooled per binding, so a busy event stream allocates nothing to decide. */
+export interface ResolvedFeedback {
+    event: FeedbackEventName;
+    cue: FeedbackCue;
+    sound: string;
+    caption: string | undefined;
+    haptics: HapticPulse | undefined;
+    shake: number;
+    cooldownMs: number;
+}
+/** Everything the feedback seam reaches outside itself. Injected so it runs headless. */
+export interface FeedbackDeps {
+    /** Play one catalog sound through the game's audio seam. */
+    play(sound: string): void;
+    /** Add camera trauma `0..1`; called with `shake x motionScale`. */
+    shake?(amount: number): void;
+    haptics?(pulse: HapticPulse): void; /** Show a caption line for `cue`; only called when captions are on. */
+    caption?(text: string, cue: FeedbackCue): void;
+    /** The local player, for `scope: "local"`. */
+    localUserId(): string | null;
+    /** The entity the local player currently controls, for damage/death scope. */
+    localEntityId(): string | null;
+    /** Engine motion scale: `0` under reduced motion, `1` normally. Default `1`. */
+    motionScale?(): number;
+    now?(): number;
+}
+/** Options a game or host may override. */
+export interface EventFeedbackOptions {
+    reactions?: Partial<Record<FeedbackCue, FeedbackReaction>>;
+    bindings?: readonly AnyFeedbackBinding[];
+    /** Whether captions reach `deps.caption` at all. Default true. */
+    captions?: boolean;
+}
+/** The event-to-reaction seam. One instance per running world. */
+export interface EventFeedback {
+    /** React to one announced event. Returns the cue fired, or null when nothing mapped or it was muted by cooldown. */
+    handle<Name extends FeedbackEventName>(event: Name, payload: GameEventMap[Name]): FeedbackCue | null;
+    /** Fire a cue the game announces itself (a wave starting, a custom moment); `caption` overrides the cue's text. */
+    notify(cue: FeedbackCue, caption?: string): boolean;
+    /** Map without firing - the pooled reaction for an event, for devtools and tests. */
+    resolve<Name extends FeedbackEventName>(event: Name, payload: GameEventMap[Name]): ResolvedFeedback | null;
+    /** How many triggers a cue's cooldown folded away since the last reset. */
+    suppressed(cue: FeedbackCue): number;
+    /** Replace reactions or bindings at runtime. */
+    retune(options: Partial<EventFeedbackOptions>): void;
+    /** Clear cooldowns and suppressed counters. */
+    reset(): void;
+}
+/**
+ * Build the event-to-sound/haptic/shake/caption seam. The mapping is data
+ * ({@link DEFAULT_FEEDBACK_BINDINGS}), reactions are data ({@link DEFAULT_FEEDBACK_REACTIONS}), and the
+ * resolved trigger for each binding is allocated once - handling an event allocates only the caption
+ * string it actually shows, never per frame.
+ *
+ * @capability event-feedback map announced gameplay events (damage, kill, pickup, objective, wave, refusal) to a sound, gamepad pulse, camera shake and caption through one data mapping
+ */
+export declare function createEventFeedback(deps: FeedbackDeps, options?: EventFeedbackOptions): EventFeedback;
+/**
+ * Subscribe the feedback seam to a game's event bus, including `feedback.cue` for moments the game
+ * announces itself. Returns the detach function; the mapping and reactions stay override-able
+ * through the seam's `retune`.
+ *
+ * @capability attach-event-feedback one call wires every announced combat/loot/objective/refusal event to its reaction
+ */
+export declare function attachEventFeedback(events: Pick<GameEvents, "on">, feedback: EventFeedback, eventsToBind?: readonly FeedbackEventName[]): () => void;
+/** The slice of `ctx.game.feedback` a wave runner needs, so this runs headless in a test. */
+export interface FeedbackAnnouncer {
+    cue(cue: FeedbackCue, caption?: string): void;
+}
+/**
+ * Announce each new wave a {@link WaveRunner} starts as the `wave` cue, once per boundary. A wave
+ * has no event of its own, so this is the engine-side hookup for tower defense and wave survival
+ * games: `attachWaveFeedback(runner, ctx.game.feedback)`. Nothing is polled, the runner's own
+ * notification drives it, and one `update` that crosses two waves still fires once - the cue has a
+ * cooldown and the next boundary is announced by the next crossing.
+ *
+ * @capability attach-wave-feedback fire the wave cue once whenever a wave runner crosses into a new wave
+ */
+export declare function attachWaveFeedback(runner: Pick<WaveRunner, "state" | "subscribe">, announce: FeedbackAnnouncer): () => void;

package/dist/audio/eventFeedback.js

@@ -0,0 +1,268 @@
+import { feedbackCueSoundId } from "@jgengine/core/audio/feedbackCues";
+/**
+ * The default reactions. They are data: a game overrides one through `audio.feedbackCues` (sound) or
+ * `createEventFeedback({ reactions })` (haptics, shake, caption), and replaces the mapping through
+ * `bindings` without touching the shell.
+ */
+export const DEFAULT_FEEDBACK_REACTIONS = {
+    hit: {
+        sound: feedbackCueSoundId("hit"),
+        haptics: { strong: 0.18, weak: 0.3, ms: 70 },
+        shake: 0.14,
+        caption: "Hit",
+        cooldownMs: 55,
+    },
+    hurt: {
+        sound: feedbackCueSoundId("hurt"),
+        haptics: { strong: 0.45, weak: 0.35, ms: 140 },
+        shake: 0.4,
+        caption: "Hurt",
+        cooldownMs: 140,
+    },
+    kill: {
+        sound: feedbackCueSoundId("kill"),
+        haptics: { strong: 0.3, weak: 0.45, ms: 110 },
+        shake: 0.22,
+        caption: "Enemy down",
+        cooldownMs: 90,
+    },
+    pickup: {
+        sound: feedbackCueSoundId("pickup"),
+        haptics: { strong: 0.06, weak: 0.14, ms: 45 },
+        caption: "Picked up",
+        cooldownMs: 80,
+    },
+    objective: {
+        sound: feedbackCueSoundId("objective"),
+        haptics: { strong: 0.12, weak: 0.2, ms: 120 },
+        caption: "Objective complete",
+        cooldownMs: 500,
+    },
+    wave: {
+        sound: feedbackCueSoundId("wave"),
+        haptics: { strong: 0.2, weak: 0.1, ms: 180 },
+        shake: 0.1,
+        caption: "Wave incoming",
+        cooldownMs: 1500,
+    },
+    deny: {
+        sound: feedbackCueSoundId("deny"),
+        haptics: { strong: 0.1, weak: 0.25, ms: 60 },
+        caption: "Not possible",
+        cooldownMs: 350,
+    },
+};
+/**
+ * The default mapping: each engine-announced gameplay event to the cue it raises. Damage to the
+ * local player reads as hurt, damage anywhere else as a hit; a wave start has no event of its own,
+ * so a game announces it through `notify("wave")` or `attachWaveFeedback`.
+ */
+export const DEFAULT_FEEDBACK_BINDINGS = [
+    { event: "combat.damage", cue: "hurt", scope: "local", detail: (event) => `${Math.round(event.amount)}` },
+    { event: "combat.damage", cue: "hit", scope: "remote", detail: (event) => `${Math.round(event.amount)}` },
+    { event: "entity.died", cue: "hurt", scope: "local", caption: "You died" },
+    { event: "entity.died", cue: "kill", scope: "remote", detail: (event) => event.displayName ?? event.catalogId },
+    { event: "worldItem.picked_up", cue: "pickup", scope: "local", detail: (event) => (event.count > 1 ? `${event.itemId} x${event.count}` : event.itemId) },
+    { event: "quest.completed", cue: "objective", scope: "local", detail: (event) => event.questId },
+    { event: "stat.levelUp", cue: "objective", scope: "local", detail: (event) => `${event.stat} ${event.level}` },
+    { event: "command.refused", cue: "deny", scope: "local", detail: (event) => event.message ?? event.reason },
+];
+const DEFAULT_COOLDOWN_MS = 40;
+/**
+ * Build the event-to-sound/haptic/shake/caption seam. The mapping is data
+ * ({@link DEFAULT_FEEDBACK_BINDINGS}), reactions are data ({@link DEFAULT_FEEDBACK_REACTIONS}), and the
+ * resolved trigger for each binding is allocated once - handling an event allocates only the caption
+ * string it actually shows, never per frame.
+ *
+ * @capability event-feedback map announced gameplay events (damage, kill, pickup, objective, wave, refusal) to a sound, gamepad pulse, camera shake and caption through one data mapping
+ */
+export function createEventFeedback(deps, options = {}) {
+    const reactions = { ...DEFAULT_FEEDBACK_REACTIONS };
+    let bindings = options.bindings ?? DEFAULT_FEEDBACK_BINDINGS;
+    let captionsOn = options.captions ?? true;
+    for (const [cue, reaction] of Object.entries(options.reactions ?? {})) {
+        if (reaction !== undefined)
+            reactions[cue] = reaction;
+    }
+    const now = deps.now ?? Date.now;
+    const lastPlayed = { hit: -Infinity, hurt: -Infinity, kill: -Infinity, pickup: -Infinity, objective: -Infinity, wave: -Infinity, deny: -Infinity };
+    const suppressed = { hit: 0, hurt: 0, kill: 0, pickup: 0, objective: 0, wave: 0, deny: 0 };
+    function triggerFor(binding) {
+        const reaction = reactions[binding.cue];
+        return {
+            event: binding.event,
+            cue: binding.cue,
+            sound: reaction.sound,
+            caption: undefined,
+            haptics: reaction.haptics,
+            shake: reaction.shake ?? 0,
+            cooldownMs: reaction.cooldownMs ?? DEFAULT_COOLDOWN_MS,
+        };
+    }
+    // One pooled resolution per binding row plus one per cue (for `notify`), so a busy event stream
+    // allocates nothing to decide what to play.
+    let resolved = bindings.map(triggerFor);
+    const cueTriggers = Object.fromEntries(["hit", "hurt", "kill", "pickup", "objective", "wave", "deny"].map((cue) => [cue, triggerFor({ event: "combat.damage", cue })]));
+    function rebuild() {
+        resolved = bindings.map(triggerFor);
+        for (const cue of Object.keys(cueTriggers)) {
+            const reaction = reactions[cue];
+            const trigger = cueTriggers[cue];
+            trigger.sound = reaction.sound;
+            trigger.haptics = reaction.haptics;
+            trigger.shake = reaction.shake ?? 0;
+            trigger.cooldownMs = reaction.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+        }
+    }
+    function isLocal(event, payload) {
+        switch (event) {
+            case "combat.damage":
+                return payload.target === deps.localEntityId();
+            case "entity.died": {
+                const died = payload;
+                const userId = deps.localUserId();
+                return (userId !== null && died.userId === userId) || died.instanceId === deps.localEntityId();
+            }
+            case "worldItem.picked_up":
+                return payload.userId === deps.localUserId();
+            case "quest.completed":
+            case "stat.levelUp": {
+                const userId = deps.localUserId();
+                return userId !== null && payload.userId === userId;
+            }
+            case "command.refused": {
+                const actor = payload.actor;
+                return actor === null || actor === deps.localUserId();
+            }
+            default:
+                return true;
+        }
+    }
+    function fire(trigger, captionText) {
+        deps.play(trigger.sound);
+        if (trigger.haptics !== undefined)
+            deps.haptics?.(trigger.haptics);
+        if (trigger.shake > 0) {
+            const scale = deps.motionScale?.() ?? 1;
+            if (scale > 0)
+                deps.shake?.(trigger.shake * scale);
+        }
+        if (captionsOn && captionText !== undefined)
+            deps.caption?.(captionText, trigger.cue);
+    }
+    function react(cue, captionText) {
+        const reaction = reactions[cue];
+        const trigger = cueTriggers[cue];
+        const time = now();
+        const cooldown = trigger.cooldownMs;
+        if (time - lastPlayed[cue] < cooldown) {
+            suppressed[cue] += 1;
+            return false;
+        }
+        lastPlayed[cue] = time;
+        const text = captionText ?? trigger.caption ?? reaction.caption;
+        fire(trigger, text);
+        return true;
+    }
+    return {
+        handle(event, payload) {
+            for (let index = 0; index < bindings.length; index += 1) {
+                const binding = bindings[index];
+                if (binding.event !== event)
+                    continue;
+                const scope = binding.scope ?? "any";
+                if (scope !== "any" && isLocal(event, payload) !== (scope === "local"))
+                    continue;
+                const detail = binding.detail?.(payload);
+                const base = binding.caption ?? reactions[binding.cue].caption;
+                const captionText = base === undefined ? detail : detail === undefined ? base : `${base} ${detail}`;
+                return react(binding.cue, captionText) ? binding.cue : null;
+            }
+            return null;
+        },
+        notify(cue, caption) {
+            return react(cue, caption);
+        },
+        resolve(event, payload) {
+            for (let index = 0; index < bindings.length; index += 1) {
+                const binding = bindings[index];
+                if (binding.event !== event)
+                    continue;
+                const scope = binding.scope ?? "any";
+                if (scope !== "any" && isLocal(event, payload) !== (scope === "local"))
+                    continue;
+                const trigger = resolved[index];
+                const detail = binding.detail?.(payload);
+                const base = binding.caption ?? reactions[binding.cue].caption;
+                trigger.caption = base === undefined ? detail : detail === undefined ? base : `${base} ${detail}`;
+                return trigger;
+            }
+            return null;
+        },
+        suppressed(cue) {
+            return suppressed[cue];
+        },
+        retune(next) {
+            if (next.captions !== undefined)
+                captionsOn = next.captions;
+            if (next.bindings !== undefined) {
+                bindings = next.bindings;
+                rebuild();
+            }
+            if (next.reactions !== undefined) {
+                for (const [cue, reaction] of Object.entries(next.reactions)) {
+                    if (reaction !== undefined)
+                        reactions[cue] = reaction;
+                }
+                rebuild();
+            }
+        },
+        reset() {
+            for (const cue of Object.keys(lastPlayed)) {
+                lastPlayed[cue] = -Infinity;
+                suppressed[cue] = 0;
+            }
+        },
+    };
+}
+/**
+ * Subscribe the feedback seam to a game's event bus, including `feedback.cue` for moments the game
+ * announces itself. Returns the detach function; the mapping and reactions stay override-able
+ * through the seam's `retune`.
+ *
+ * @capability attach-event-feedback one call wires every announced combat/loot/objective/refusal event to its reaction
+ */
+export function attachEventFeedback(events, feedback, eventsToBind = Object.keys(DEFAULT_FEEDBACK_BINDINGS.reduce((names, binding) => {
+    names[binding.event] = true;
+    return names;
+}, {}))) {
+    const offs = eventsToBind.map((name) => events.on(name, (payload) => {
+        feedback.handle(name, payload);
+    }));
+    offs.push(events.on("feedback.cue", ({ cue, caption }) => {
+        feedback.notify(cue, caption);
+    }));
+    return () => {
+        for (const off of offs)
+            off();
+    };
+}
+/**
+ * Announce each new wave a {@link WaveRunner} starts as the `wave` cue, once per boundary. A wave
+ * has no event of its own, so this is the engine-side hookup for tower defense and wave survival
+ * games: `attachWaveFeedback(runner, ctx.game.feedback)`. Nothing is polled, the runner's own
+ * notification drives it, and one `update` that crosses two waves still fires once - the cue has a
+ * cooldown and the next boundary is announced by the next crossing.
+ *
+ * @capability attach-wave-feedback fire the wave cue once whenever a wave runner crosses into a new wave
+ */
+export function attachWaveFeedback(runner, announce) {
+    let lastWave = runner.state().wave;
+    return runner.subscribe(() => {
+        const wave = runner.state().wave;
+        if (wave === lastWave)
+            return;
+        lastWave = wave;
+        announce.cue("wave", `Wave ${wave + 1}`);
+    });
+}

package/dist/audio/gestureResume.d.ts

@@ -0,0 +1,10 @@
+import type { AudioEngine } from "./audioEngine.js";
+/**
+ * Resume the audio context on the first real user gesture. Chrome keeps a freshly created
+ * `AudioContext` suspended until the page sees a trusted input, so pressing a key, tapping or clicking
+ * is the only moment sound may start; the engine then flushes any cue it held. One listener set per
+ * game, removed on unmount.
+ *
+ * @capability gesture-resume unlock the audio context on the first pointer/key/touch gesture, so pre-gesture cues play instead of vanishing
+ */
+export declare function installGestureResume(engine: Pick<AudioEngine, "resume">, target?: Pick<Document, "addEventListener" | "removeEventListener"> | null): () => void;

package/dist/audio/gestureResume.js

@@ -0,0 +1,25 @@
+/**
+ * Resume the audio context on the first real user gesture. Chrome keeps a freshly created
+ * `AudioContext` suspended until the page sees a trusted input, so pressing a key, tapping or clicking
+ * is the only moment sound may start; the engine then flushes any cue it held. One listener set per
+ * game, removed on unmount.
+ *
+ * @capability gesture-resume unlock the audio context on the first pointer/key/touch gesture, so pre-gesture cues play instead of vanishing
+ */
+export function installGestureResume(engine, target = typeof document === "undefined" ? null : document) {
+    if (target === null)
+        return () => undefined;
+    const resume = () => {
+        engine.resume();
+        detach();
+    };
+    const detach = () => {
+        target.removeEventListener("pointerdown", resume, true);
+        target.removeEventListener("keydown", resume, true);
+        target.removeEventListener("touchstart", resume, true);
+    };
+    target.addEventListener("pointerdown", resume, true);
+    target.addEventListener("keydown", resume, true);
+    target.addEventListener("touchstart", resume, true);
+    return detach;
+}

package/dist/audio/playableAudio.d.ts

@@ -1,6 +1,6 @@
 import type { AudioBusDef, SoundDef } from "@jgengine/core/audio/audioFalloff";
 import type { PlayableGame } from "../registry.js";
-/** A playable's sound catalog and buses with the default UI cues merged in. @internal */
+/** A playable's sound catalog and buses with the default UI and gameplay feedback cues merged in. @internal */
 export interface ResolvedPlayableAudio {
     sounds: Record<string, SoundDef>;
     buses: Record<string, AudioBusDef> | undefined;

package/dist/audio/playableAudio.js

@@ -1,10 +1,12 @@
+import { withFeedbackCueSounds } from "@jgengine/core/audio/feedbackCues";
 import { withUiCueSounds } from "@jgengine/core/audio/uiCues";
 const cache = new WeakMap();
 /** Resolve once per playable so the engine, the volume bridge and the settings rows share one bus list. @internal */
 export function resolvePlayableAudio(playable) {
     let resolved = cache.get(playable);
     if (resolved === undefined) {
-        resolved = withUiCueSounds(playable.audio?.sounds, playable.audio?.buses, playable.audio?.uiCues);
+        const ui = withUiCueSounds(playable.audio?.sounds, playable.audio?.buses, playable.audio?.uiCues);
+        resolved = withFeedbackCueSounds(ui.sounds, ui.buses, playable.audio?.feedbackCues);
         cache.set(playable, resolved);
     }
     return resolved;

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

@@ -3,6 +3,7 @@ import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_SHADO
 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 { 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 { 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,6 +64,20 @@ export function useSettingsCategories(config) {
                 set: (value) => store.set(id, value),
             };
         }),
+        ...Object.values(config.buses ?? {}).map((bus) => ({
+            id: busMuteSettingId(bus.id),
+            label: bus.id === "ui" ? "Mute UI" : `Mute ${bus.id}`,
+            kind: "toggle",
+            value: Boolean(store.get(busMuteSettingId(bus.id), false)),
+            set: (value) => store.set(busMuteSettingId(bus.id), Boolean(value)),
+        })),
+        {
+            id: MASTER_MUTE_SETTING_ID,
+            label: "Mute all",
+            kind: "toggle",
+            value: Boolean(store.get(MASTER_MUTE_SETTING_ID, false)),
+            set: (value) => store.set(MASTER_MUTE_SETTING_ID, Boolean(value)),
+        },
         ...extrasFor("sound"),
     ];
     const graphics = readGraphicsSettings(store, config.graphics);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.30.0",
-    "@jgengine/react": "^0.30.0",
-    "@jgengine/ws": "^0.30.0"
+    "@jgengine/core": "^0.32.0",
+    "@jgengine/react": "^0.32.0",
+    "@jgengine/ws": "^0.32.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -410,6 +410,7 @@
 - `GameContextRace` (interface): interface GameContextRace { state(id: string, config?: RaceStateConfig): RaceState } — ⚠ undocumented
 - `GameContextTurn` (interface): interface GameContextTurn { loop(id: string, config?: TurnLoopConfig): TurnLoop } — ⚠ undocumented
 - `GameContextWorld` (interface): interface GameContextWorld { ground: TerrainField; groundHeightAt(x: number, z: number): number; solids: WorldSolids } — ⚠ undocumented
+- `GameFeedback` (interface): interface GameFeedback — The game-announced feel seam on `ctx.game`: name a moment the engine has no event for and the shell plays its cue's sound, rumble, camera kick and caption. The reaction table lives in the shell, so a game never encodes what a hit or a wave should sound like.
 - `HitReactionInput` (interface): interface HitReactionInput { from: string; to: string; config: HitReactionConfig | ImpactPresetName; power?: number } — ⚠ undocumented · used by `resolveHitReaction` (@jgengine/core/combat): Resolves hit feel (hitstop, knockback impulse, camera shake) from either a named `impactPresets` event (`resolveHitReaction("explosion", inp…
 - `MoveTowardCommitOptions` (interface): interface MoveTowardCommitOptions extends MoveTowardOptions — Options for {@link SceneEntityContext.moveTowardCommit}: {@link MoveTowardOptions} plus an optional facing turn.
 - `SceneEntityContext` (interface): interface SceneEntityContext { spawn(name: string, options?: SpawnOptions): string; despawn(instanceId: string): boolean; update: EntityStore["update"]; setPose(instanceId: string, pose: EntityPose): boolean; setVelocity: EntityStore["setVelocity"]; setPoseConstraint: … — ⚠ undocumented
@@ -728,7 +729,7 @@
 - `GameLoop` (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
 - `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: … — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
 - `HudCanvas` (function): function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: { layout: HudLayoutStore; editChord?: HudEditChord | false; /** Zoom applied to the whole HUD on compact displays. Default 0.85. */ compactScale?: number; /** Opt-in play-phase gate: render the HUD only … — Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine anchor regions and stack automatically with a gap — no per-panel pixel offsets, no manual clearance for sibling panels, the touch-control dock (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the whole surface scales down and each panel applies its `compact` behavior.
-- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
+- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
 - `PlayableGame` (type): type PlayableGame = EnginePlayableGame< ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps> > & { /** HUD theme the shell applies at the `GameUI` root. Unset uses `defaultHudTheme`; `false` opts out of the default theme and the en… — The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle.
 - `StatBar` (function): function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }: { statId?: string; entityId?: string; tone?: StatTone; label?: string; showValue?: boolean; width?: number; icon?: ReactNode; style?: CSSProperties; className?: string; }… — A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player). Renders nothing until the stat exists.
 - `StoreHandle` (interface): interface StoreHandle<T> — A typed, cast-free handle onto one slot of the reactive game store (`ctx.game.store`). The single type parameter is fixed at definition; `read`/`write`/`update` never widen to `unknown`, so no call site repeats `store.get(key) as T`. Writes flow through the engine store, so they bump `ctx.version()`, serialize into a {@link WorldSnapshot}, and replay under host authority — the same guarantees a hand-rolled `store.get`/`store.set` pair gives up the moment it forks run state into a module-level singleton.