@jgengine/shell 0.19.0 → 0.22.0

package/dist/audio/audioEngine.js

@@ -1,6 +1,7 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
 import { dopplerRate } from "@jgengine/core/audio/doppler";
 import { patchDuration } from "@jgengine/core/audio/synth";
+import { createVoiceAllocator } from "@jgengine/core/audio/voiceAllocator";
 import { createDisposer } from "@jgengine/core/game/defineGame";
 import { clampLoopCutoff, clampLoopGain, clampLoopRate, MIN_LOOP_CUTOFF, MAX_LOOP_CUTOFF } from "./loopParams.js";
 import { MusicDirector } from "./musicDirector.js";
@@ -11,6 +12,7 @@ const ZERO_VELOCITY = { x: 0, y: 0, z: 0 };
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
+        setVoiceLimit: () => undefined,
         playOneShot: () => undefined,
         playLoop: () => null,
         playMusic: () => undefined,
@@ -44,25 +46,38 @@ function setPannerPosition(panner, position) {
 }
 function createPanner(context, spatial, position) {
     const panner = context.createPanner();
-    panner.panningModel = spatial.panning === "hrtf" ? "HRTF" : "equalpower";
-    panner.distanceModel = "inverse";
-    if (spatial.refDistance !== undefined)
-        panner.refDistance = spatial.refDistance;
-    if (spatial.maxDistance !== undefined)
-        panner.maxDistance = spatial.maxDistance;
-    if (spatial.rolloff !== undefined)
-        panner.rolloffFactor = spatial.rolloff;
-    if (spatial.coneInner !== undefined)
-        panner.coneInnerAngle = spatial.coneInner;
-    if (spatial.coneOuter !== undefined)
-        panner.coneOuterAngle = spatial.coneOuter;
-    if (spatial.coneOuterGain !== undefined)
-        panner.coneOuterGain = spatial.coneOuterGain;
-    setPannerPosition(panner, position);
+    try {
+        panner.panningModel = spatial.panning === "hrtf" ? "HRTF" : "equalpower";
+        panner.distanceModel = "inverse";
+        if (spatial.refDistance !== undefined)
+            panner.refDistance = spatial.refDistance;
+        if (spatial.maxDistance !== undefined)
+            panner.maxDistance = spatial.maxDistance;
+        if (spatial.rolloff !== undefined)
+            panner.rolloffFactor = spatial.rolloff;
+        if (spatial.coneInner !== undefined)
+            panner.coneInnerAngle = spatial.coneInner;
+        if (spatial.coneOuter !== undefined)
+            panner.coneOuterAngle = spatial.coneOuter;
+        if (spatial.coneOuterGain !== undefined)
+            panner.coneOuterGain = spatial.coneOuterGain;
+        setPannerPosition(panner, position);
+    }
+    catch (error) {
+        panner.disconnect();
+        throw error;
+    }
     return panner;
 }
+/**
+ * Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
+ * @capability bounded-spatial-audio play positional or flat cues with listener orientation, voice budgets, and per-source cleanup
+ */
 export function createAudioEngine(config = {}) {
     const sounds = config.sounds ?? {};
+    const allocator = config.voiceAllocator ?? createVoiceAllocator({ maxTotal: config.maxVoices, overflow: config.voiceOverflow });
+    let disposed = false;
+    const activeVoices = new Map();
     const busDefs = config.buses ?? {};
     const AudioContextCtor = resolveAudioContextCtor();
     if (AudioContextCtor === undefined)
@@ -82,9 +97,15 @@ export function createAudioEngine(config = {}) {
         let node = busGains.get(busId);
         if (node === undefined) {
             node = context.createGain();
-            node.gain.value = busDefs[busId]?.gain ?? 1;
-            node.connect(masterGain);
-            busGains.set(busId, node);
+            try {
+                node.gain.value = busDefs[busId]?.gain ?? 1;
+                node.connect(masterGain);
+                busGains.set(busId, node);
+            }
+            catch (error) {
+                node.disconnect();
+                throw error;
+            }
         }
         return node;
     }
@@ -145,38 +166,66 @@ export function createAudioEngine(config = {}) {
     let listenerVelocity = { x: 0, y: 0, z: 0 };
     const nyquist = context.sampleRate / 2;
     const activeSpatialUpdaters = new Set();
-    const activeLoops = new Set();
-    const NOOP_HANDLE = {
-        setPosition: () => undefined,
-        setRate: () => undefined,
-        setGain: () => undefined,
-        setLowpass: () => undefined,
-        setHighpass: () => undefined,
-        setVelocity: () => undefined,
-        stop: () => undefined,
-    };
     function playInternal(soundId, position, loop) {
+        if (disposed)
+            return null;
         const sound = sounds[soundId];
-        if (sound === undefined)
+        if (sound === undefined || (sound.synth === undefined && sound.url === undefined))
             return null;
-        const bus = busGainNode(sound.bus);
-        const currentPosition = position ?? listenerPosition;
-        // A one-shot synth cue realises its decaying voices live and is fire-and-forget.
+        const allocation = allocator.request(soundId, sound.priority, sound.maxVoices);
+        if (!allocation.ok)
+            return null;
+        for (const id of allocation.stolen)
+            activeVoices.get(id)?.();
+        const voiceId = allocation.voiceId;
+        let bus;
+        try {
+            bus = busGainNode(sound.bus);
+        }
+        catch {
+            allocator.release(voiceId);
+            return null;
+        }
+        const currentPosition = { ...(position ?? listenerPosition) };
         if (sound.synth !== undefined && !loop) {
-            const cueGain = context.createGain();
-            cueGain.gain.value = sound.spatial === undefined
-                ? resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1)
-                : sound.gain ?? 1;
-            if (sound.spatial !== undefined) {
-                const panner = createPanner(context, sound.spatial, currentPosition);
-                cueGain.connect(panner);
-                panner.connect(bus);
+            let cueGain = null;
+            let panner = null;
+            let playback = null;
+            let stopped = false;
+            function updateGain() {
+                if (cueGain === null)
+                    return;
+                cueGain.gain.value = panner === null
+                    ? resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1)
+                    : sound.gain ?? 1;
             }
-            else {
-                cueGain.connect(bus);
+            function stop() {
+                if (stopped)
+                    return;
+                stopped = true;
+                activeVoices.delete(voiceId);
+                activeSpatialUpdaters.delete(updateGain);
+                allocator.release(voiceId);
+                playback?.stop();
+                cueGain?.disconnect();
+                panner?.disconnect();
             }
-            realizeSynthPatch(context, cueGain, sharedNoiseBuffer(), sound.synth);
-            return NOOP_HANDLE;
+            activeVoices.set(voiceId, stop);
+            try {
+                cueGain = context.createGain();
+                const spatial = sound.positional === false ? undefined : sound.spatial;
+                panner = spatial === undefined ? null : createPanner(context, spatial, currentPosition);
+                updateGain();
+                cueGain.connect(panner ?? bus);
+                panner?.connect(bus);
+                playback = realizeSynthPatch(context, cueGain, sharedNoiseBuffer(), sound.synth);
+                activeSpatialUpdaters.add(updateGain);
+                playback.onEnded(stop);
+            }
+            catch {
+                stop();
+            }
+            return null;
         }
         // Everything else resolves to one AudioBuffer we loop/play: sample URL, or a synth patch rendered once.
         let bufferPromise;
@@ -186,11 +235,13 @@ export function createAudioEngine(config = {}) {
             bufferPromise = loadBuffer(sound.url);
         else
             return null;
-        return playBufferSource(sound, bus, bufferPromise, currentPosition, loop);
+        return playBufferSource(sound, bus, bufferPromise, currentPosition, loop, voiceId);
     }
-    function playBufferSource(sound, bus, bufferPromise, initialPosition, loop) {
+    function playBufferSource(sound, bus, bufferPromise, initialPosition, loop, voiceId) {
         const disposer = createDisposer();
-        let currentPosition = initialPosition;
+        let currentPosition = { ...initialPosition };
+        let stopped = false;
+        const spatial = sound.positional === false ? undefined : sound.spatial;
         // Live control state, applied on source creation so updates that race the async buffer load stick.
         let currentRate = 1;
         let currentUserGain = 1;
@@ -215,7 +266,7 @@ export function createAudioEngine(config = {}) {
                 sourceNode.playbackRate.setTargetAtTime(effectiveRate(), context.currentTime, LOOP_PARAM_SMOOTH_TC);
         }
         function updateFalloff() {
-            if (falloffGain !== null && sound.spatial === undefined) {
+            if (falloffGain !== null && spatial === undefined) {
                 falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             }
             if (pannerNode !== null)
@@ -223,73 +274,83 @@ export function createAudioEngine(config = {}) {
             if (dopplerFactor !== 0)
                 applyRate();
         }
+        disposer.onDispose(() => {
+            if (sourceNode !== null)
+                sourceNode.onended = null;
+            try {
+                sourceNode?.stop();
+            }
+            catch {
+            }
+            sourceNode?.disconnect();
+            lowpassNode?.disconnect();
+            highpassNode?.disconnect();
+            userGainNode?.disconnect();
+            falloffGain?.disconnect();
+            pannerNode?.disconnect();
+            sourceNode = null;
+            lowpassNode = null;
+            highpassNode = null;
+            userGainNode = null;
+            falloffGain = null;
+            pannerNode = null;
+        });
         void bufferPromise.then((buffer) => {
-            if (buffer === null)
+            if (stopped || disposed)
+                return;
+            if (buffer === null) {
+                handle.stop();
                 return;
+            }
             const src = context.createBufferSource();
+            sourceNode = src;
             src.buffer = buffer;
             src.loop = loop || (sound.loop ?? false);
             src.playbackRate.value = effectiveRate();
-            // source → [lowpass → highpass, loops only] → per-loop user gain (setGain) → distance falloff → bus
+            // Spatial panners own distance attenuation; the scalar stage keeps only authored gain.
             const uGain = context.createGain();
+            userGainNode = uGain;
             uGain.gain.value = currentUserGain;
             const fGain = context.createGain();
+            falloffGain = fGain;
             fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             if (loop) {
                 const lp = context.createBiquadFilter();
+                lowpassNode = lp;
                 lp.type = "lowpass";
                 lp.frequency.value = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
                 const hp = context.createBiquadFilter();
+                highpassNode = hp;
                 hp.type = "highpass";
                 hp.frequency.value = clampLoopCutoff(currentHighpass, MIN_LOOP_CUTOFF, nyquist);
                 src.connect(lp);
                 lp.connect(hp);
                 hp.connect(uGain);
-                lowpassNode = lp;
-                highpassNode = hp;
             }
             else {
                 src.connect(uGain);
             }
             uGain.connect(fGain);
-            if (sound.spatial !== undefined) {
-                const panner = createPanner(context, sound.spatial, currentPosition);
-                fGain.gain.value = 1;
+            if (spatial !== undefined) {
+                const panner = createPanner(context, spatial, currentPosition);
+                pannerNode = panner;
+                fGain.gain.value = sound.gain ?? 1;
                 fGain.connect(panner);
                 panner.connect(bus);
-                pannerNode = panner;
             }
             else {
                 fGain.connect(bus);
             }
+            src.onended = () => handle.stop();
             src.start();
-            sourceNode = src;
-            userGainNode = uGain;
-            falloffGain = fGain;
-            disposer.onDispose(() => {
-                try {
-                    src.stop();
-                }
-                catch {
-                }
-                src.disconnect();
-                lowpassNode?.disconnect();
-                highpassNode?.disconnect();
-                uGain.disconnect();
-                fGain.disconnect();
-                pannerNode?.disconnect();
-                sourceNode = null;
-                lowpassNode = null;
-                highpassNode = null;
-                userGainNode = null;
-                falloffGain = null;
-            });
-        });
-        if (loop)
-            activeSpatialUpdaters.add(updateFalloff);
+        }).catch(() => handle.stop());
+        activeSpatialUpdaters.add(updateFalloff);
         const handle = {
+            isPlaying: () => !stopped,
             setPosition(next) {
-                currentPosition = next;
+                if (stopped)
+                    return;
+                currentPosition = { ...next };
                 updateFalloff();
             },
             setRate(rate) {
@@ -307,7 +368,7 @@ export function createAudioEngine(config = {}) {
                     highpassNode.frequency.setTargetAtTime(currentHighpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             setVelocity(velocity) {
-                currentVelocity = velocity;
+                currentVelocity = { ...velocity };
                 if (dopplerFactor !== 0)
                     applyRate();
             },
@@ -317,20 +378,31 @@ export function createAudioEngine(config = {}) {
                     userGainNode.gain.setTargetAtTime(currentUserGain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             stop() {
+                if (stopped)
+                    return;
+                stopped = true;
                 activeSpatialUpdaters.delete(updateFalloff);
-                activeLoops.delete(handle);
+                activeVoices.delete(voiceId);
+                allocator.release(voiceId);
                 disposer.dispose();
             },
         };
-        if (loop)
-            activeLoops.add(handle);
+        activeVoices.set(voiceId, () => handle.stop());
         return handle;
     }
     return {
+        setVoiceLimit(maxTotal, overflow) {
+            if (disposed)
+                return;
+            for (const id of allocator.retune({ maxTotal, overflow }))
+                activeVoices.get(id)?.();
+        },
         setListenerPose(position) {
+            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 = { ...pose.position };
+            listenerVelocity = "velocity" in pose && pose.velocity !== undefined ? { ...pose.velocity } : ZERO_VELOCITY;
             const listener = context.listener;
             setAudioParam(listener.positionX, pose.position.x);
             setAudioParam(listener.positionY, pose.position.y);
@@ -345,6 +417,8 @@ export function createAudioEngine(config = {}) {
                 updateGain();
         },
         playOneShot(soundId, position) {
+            if (disposed)
+                return;
             void context.resume().catch(() => undefined);
             playInternal(soundId, position, false);
         },
@@ -352,23 +426,38 @@ export function createAudioEngine(config = {}) {
             return playInternal(soundId, position, true);
         },
         playMusic(themeId, options) {
+            if (disposed)
+                return;
             void context.resume().catch(() => undefined);
             musicDirector()?.crossfadeTo(themeId, options);
         },
         setBusGain(busId, gain) {
+            if (disposed)
+                return;
             busGainNode(busId).gain.value = gain;
         },
         setMasterGain(gain) {
+            if (disposed)
+                return;
             masterGain.gain.value = gain;
         },
         resume() {
+            if (disposed)
+                return;
             void context.resume().catch(() => undefined);
         },
         dispose() {
-            for (const handle of [...activeLoops])
-                handle.stop();
+            if (disposed)
+                return;
+            disposed = true;
+            for (const stop of [...activeVoices.values()])
+                stop();
             activeSpatialUpdaters.clear();
             director?.dispose();
+            for (const node of busGains.values())
+                node.disconnect();
+            busGains.clear();
+            masterGain.disconnect();
             void context.close().catch(() => undefined);
         },
     };

package/dist/audio/audioWire.js

@@ -19,8 +19,8 @@ export function attachAudioEventWire(events, audioEngine) {
     const offLoopStart = events.on("audio.loopStart", ({ id, sound, at }) => {
         const existing = loops.get(id);
         if (existing !== undefined) {
-            // Same sound: idempotent — keep the running source so a per-tick re-issue never clicks.
-            if (existing.sound === sound)
+            // Keep active/pending loops; a stolen voice can retry on the next explicit start.
+            if (existing.sound === sound && existing.handle.isPlaying?.() !== false)
                 return;
             existing.handle.stop();
             loops.delete(id);

package/dist/audio/synthEngine.d.ts

@@ -1,9 +1,15 @@
 import type { SynthPatch } from "@jgengine/core/audio/synth";
 /** Build the shared 1-second mono white-noise buffer every noise voice samples from. */
 export declare function createNoiseBuffer(ctx: BaseAudioContext): AudioBuffer;
+/** Scheduled procedural sources; stopping releases their source/filter/envelope graph. */
+export interface SynthPlayback {
+    stop(): void;
+    /** Called once after every source ends; late subscribers are notified immediately. */
+    onEnded(callback: () => void): void;
+}
 /**
  * Realise a procedural cue on Web Audio: every voice is scheduled at
  * `ctx.currentTime + delay` into `out`, summed into one one-shot. `noiseBuf` is
  * the shared buffer from {@link createNoiseBuffer}.
  */
-export declare function realizeSynthPatch(ctx: BaseAudioContext, out: AudioNode, noiseBuf: AudioBuffer, patch: SynthPatch): void;
+export declare function realizeSynthPatch(ctx: BaseAudioContext, out: AudioNode, noiseBuf: AudioBuffer, patch: SynthPatch): SynthPlayback;

package/dist/audio/synthEngine.js

@@ -7,48 +7,90 @@ export function createNoiseBuffer(ctx) {
         data[i] = Math.random() * 2 - 1;
     return buf;
 }
-function realizeTone(ctx, out, voice, cueGain, at) {
+function realizeTone(ctx, out, voice, cueGain, at, ended) {
     const t = at + (voice.delay ?? 0);
     const peak = (voice.gain ?? 1) * cueGain;
     const attack = voice.attack ?? 0.012;
     const osc = ctx.createOscillator();
-    osc.type = voice.wave ?? "sine";
-    osc.frequency.setValueAtTime(voice.freq, t);
-    if (voice.slideTo !== undefined)
-        osc.frequency.exponentialRampToValueAtTime(Math.max(1, voice.slideTo), t + voice.duration);
-    const sustainEnd = Math.max(attack, voice.sustain ?? 0);
-    const g = ctx.createGain();
-    g.gain.setValueAtTime(0, t);
-    g.gain.linearRampToValueAtTime(peak, t + attack);
-    if (sustainEnd > attack)
-        g.gain.setValueAtTime(peak, t + sustainEnd);
-    g.gain.exponentialRampToValueAtTime(0.001, t + Math.max(voice.duration, sustainEnd + 0.001));
-    osc.connect(g).connect(out);
-    osc.start(t);
-    osc.stop(t + voice.duration + 0.05);
+    const nodes = [];
+    const stop = trackVoice(osc, nodes, ended);
+    try {
+        osc.type = voice.wave ?? "sine";
+        osc.frequency.setValueAtTime(voice.freq, t);
+        if (voice.slideTo !== undefined)
+            osc.frequency.exponentialRampToValueAtTime(Math.max(1, voice.slideTo), t + voice.duration);
+        const sustainEnd = Math.max(attack, voice.sustain ?? 0);
+        const g = ctx.createGain();
+        nodes.push(g);
+        g.gain.setValueAtTime(0, t);
+        g.gain.linearRampToValueAtTime(peak, t + attack);
+        if (sustainEnd > attack)
+            g.gain.setValueAtTime(peak, t + sustainEnd);
+        g.gain.exponentialRampToValueAtTime(0.001, t + Math.max(voice.duration, sustainEnd + 0.001));
+        osc.connect(g).connect(out);
+        osc.start(t);
+        osc.stop(t + voice.duration + 0.05);
+        return stop;
+    }
+    catch (error) {
+        stop();
+        throw error;
+    }
 }
-function realizeNoise(ctx, out, noiseBuf, voice, cueGain, at) {
+function realizeNoise(ctx, out, noiseBuf, voice, cueGain, at, ended) {
     const t = at + (voice.delay ?? 0);
     const peak = (voice.gain ?? 1) * cueGain;
     const decay = voice.decay ?? 0.9;
     const src = ctx.createBufferSource();
-    src.buffer = noiseBuf;
-    src.playbackRate.value = 0.8 + Math.random() * 0.4;
-    // The shared buffer is 1 s and playback starts at a random offset inside it, so any voice longer
-    // than the remainder used to run off the end and go silent early. Wrapping keeps it noise throughout;
-    // the `duration` argument to start() still ends the voice on time.
-    src.loop = true;
-    const filter = ctx.createBiquadFilter();
-    filter.type = voice.filterType ?? "lowpass";
-    filter.frequency.value = voice.filterFreq;
-    const sustain = Math.max(0, voice.sustain ?? 0);
-    const g = ctx.createGain();
-    g.gain.setValueAtTime(peak, t);
-    if (sustain > 0)
-        g.gain.setValueAtTime(peak, t + sustain);
-    g.gain.exponentialRampToValueAtTime(0.001, t + Math.max(voice.duration * decay, sustain + 0.001));
-    src.connect(filter).connect(g).connect(out);
-    src.start(t, Math.random() * 0.5, voice.duration);
+    const nodes = [];
+    const stop = trackVoice(src, nodes, ended);
+    try {
+        src.buffer = noiseBuf;
+        src.playbackRate.value = 0.8 + Math.random() * 0.4;
+        // Loop the shared 1-second buffer so a random offset cannot truncate a longer voice.
+        src.loop = true;
+        const filter = ctx.createBiquadFilter();
+        nodes.push(filter);
+        filter.type = voice.filterType ?? "lowpass";
+        filter.frequency.value = voice.filterFreq;
+        const sustain = Math.max(0, voice.sustain ?? 0);
+        const g = ctx.createGain();
+        nodes.push(g);
+        g.gain.setValueAtTime(peak, t);
+        if (sustain > 0)
+            g.gain.setValueAtTime(peak, t + sustain);
+        g.gain.exponentialRampToValueAtTime(0.001, t + Math.max(voice.duration * decay, sustain + 0.001));
+        src.connect(filter).connect(g).connect(out);
+        src.start(t, Math.random() * 0.5, voice.duration);
+        return stop;
+    }
+    catch (error) {
+        stop();
+        throw error;
+    }
+}
+function trackVoice(source, nodes, ended) {
+    let disposed = false;
+    function cleanup() {
+        if (disposed)
+            return;
+        disposed = true;
+        source.onended = null;
+        source.disconnect();
+        for (const node of nodes)
+            node.disconnect();
+        ended();
+    }
+    source.onended = cleanup;
+    return () => {
+        if (disposed)
+            return;
+        try {
+            source.stop();
+        }
+        catch { }
+        cleanup();
+    };
 }
 /**
  * Realise a procedural cue on Web Audio: every voice is scheduled at
@@ -58,10 +100,33 @@ function realizeNoise(ctx, out, noiseBuf, voice, cueGain, at) {
 export function realizeSynthPatch(ctx, out, noiseBuf, patch) {
     const cueGain = patch.gain ?? 1;
     const at = ctx.currentTime;
-    for (const voice of patch.voices) {
-        if (voice.kind === "tone")
-            realizeTone(ctx, out, voice, cueGain, at);
-        else
-            realizeNoise(ctx, out, noiseBuf, voice, cueGain, at);
+    let remaining = patch.voices.length;
+    const callbacks = [];
+    const stops = [];
+    function ended() {
+        remaining -= 1;
+        if (remaining === 0)
+            for (const callback of callbacks.splice(0))
+                callback();
+    }
+    try {
+        for (const voice of patch.voices) {
+            stops.push(voice.kind === "tone"
+                ? realizeTone(ctx, out, voice, cueGain, at, ended)
+                : realizeNoise(ctx, out, noiseBuf, voice, cueGain, at, ended));
+        }
     }
+    catch (error) {
+        for (const stop of stops)
+            stop();
+        throw error;
+    }
+    return {
+        stop() { for (const stop of stops)
+            stop(); },
+        onEnded(callback) { if (remaining === 0)
+            callback();
+        else
+            callbacks.push(callback); },
+    };
 }

package/dist/camera/GameCameraRig.js

@@ -5,10 +5,11 @@ import { GameFirstPersonCamera } from "./GameFirstPersonCamera.js";
 import { GameInspectionCamera } from "./GameInspectionCamera.js";
 import { GameOrbitCamera } from "./GameOrbitCamera.js";
 import { resolveDirectedCamera } from "./rigMath.js";
-import { resolveRigKind, turntableAsObserver } from "./rigResolve.js";
+import { resolveRigKind, resolveRuntimeCameraConfig, turntableAsObserver } from "./rigResolve.js";
 import { CameraShakeContext, createCameraShakeChannel } from "./shakeChannel.js";
 export { resolveRigKind } from "./rigResolve.js";
 export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, viewmodel, }) {
+    config = resolveRuntimeCameraConfig(config, director?.rig());
     const channel = useMemo(() => createCameraShakeChannel(config?.shake?.decayPerSecond), [config?.shake?.decayPerSecond]);
     const directorVersionRef = useRef(0);
     const subscribeDirector = useCallback((onStoreChange) => {

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -2,8 +2,8 @@ import { type ComponentType, type MutableRefObject } from "react";
 import * as THREE from "three";
 import type { CameraWeaponView, FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
 import type { EntityRenderCues } from "@jgengine/core/combat/renderCues";
-/** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
-export declare function readFirstPersonMuzzle(target: THREE.Vector3): boolean;
+/** Presentation muzzle in world space; camera-scoped when supplied, false leaves target unchanged. */
+export declare function readFirstPersonMuzzle(target: THREE.Vector3, camera?: THREE.Camera): boolean;
 /** Props handed to a custom viewmodel component (#542): a live cue ref (velocity/bob/firing/reloading/recoil/hit) for the followed entity, driven from your own `useFrame` — read `cuesRef.current` there rather than storing it as render state. */
 export interface ViewmodelProps {
     cuesRef: MutableRefObject<EntityRenderCues>;