@jgengine/shell 0.10.0 → 0.12.0

package/dist/audio/audioEngine.js

@@ -1,6 +1,11 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { patchDuration } from "@jgengine/core/audio/synth";
+import { createDisposer } from "@jgengine/core/game/defineGame";
+import { clampLoopGain, clampLoopRate } from "./loopParams.js";
 import { MusicDirector } from "./musicDirector.js";
 import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
+/** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
+const LOOP_PARAM_SMOOTH_TC = 0.02;
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
@@ -19,6 +24,12 @@ function resolveAudioContextCtor() {
     return (window.AudioContext ??
         window.webkitAudioContext);
 }
+function resolveOfflineAudioContextCtor() {
+    if (typeof window === "undefined")
+        return undefined;
+    return (window.OfflineAudioContext ??
+        window.webkitOfflineAudioContext);
+}
 export function createAudioEngine(config = {}) {
     const sounds = config.sounds ?? {};
     const busDefs = config.buses ?? {};
@@ -73,51 +84,144 @@ export function createAudioEngine(config = {}) {
         }
         return pending;
     }
+    // Retained synth loops render the procedural patch to one cached buffer, then loop it as a plain
+    // BufferSource — so live pitch is `playbackRate` and live gain is a gain node, exactly like sample loops (#1051).
+    const synthBufferCache = new Map();
+    function renderSynthBuffer(soundId, patch) {
+        let pending = synthBufferCache.get(soundId);
+        if (pending === undefined) {
+            const OfflineCtor = resolveOfflineAudioContextCtor();
+            if (OfflineCtor === undefined) {
+                pending = Promise.resolve(null);
+            }
+            else {
+                try {
+                    const seconds = Math.max(patchDuration(patch), 0.05);
+                    const frames = Math.max(1, Math.ceil(seconds * context.sampleRate));
+                    const offline = new OfflineCtor(1, frames, context.sampleRate);
+                    realizeSynthPatch(offline, offline.destination, createNoiseBuffer(offline), patch);
+                    pending = offline.startRendering().catch(() => null);
+                }
+                catch {
+                    pending = Promise.resolve(null);
+                }
+            }
+            synthBufferCache.set(soundId, pending);
+        }
+        return pending;
+    }
     let listenerPosition = { x: 0, y: 0, z: 0 };
+    const activeSpatialUpdaters = new Set();
+    const activeLoops = new Set();
+    const NOOP_HANDLE = {
+        setPosition: () => undefined,
+        setRate: () => undefined,
+        setGain: () => undefined,
+        stop: () => undefined,
+    };
     function playInternal(soundId, position, loop) {
         const sound = sounds[soundId];
         if (sound === undefined)
             return null;
         const bus = busGainNode(sound.bus);
-        let currentPosition = position ?? listenerPosition;
-        if (sound.synth !== undefined) {
+        const currentPosition = position ?? listenerPosition;
+        // A one-shot synth cue realises its decaying voices live and is fire-and-forget.
+        if (sound.synth !== undefined && !loop) {
             const cueGain = context.createGain();
             cueGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             cueGain.connect(bus);
             realizeSynthPatch(context, cueGain, sharedNoiseBuffer(), sound.synth);
-            return { setPosition: () => undefined, stop: () => undefined };
+            return NOOP_HANDLE;
         }
-        if (sound.url === undefined)
+        // Everything else resolves to one AudioBuffer we loop/play: sample URL, or a synth patch rendered once.
+        let bufferPromise;
+        if (sound.synth !== undefined)
+            bufferPromise = renderSynthBuffer(soundId, sound.synth);
+        else if (sound.url !== undefined)
+            bufferPromise = loadBuffer(sound.url);
+        else
             return null;
-        let gainNode = null;
-        let stopped = false;
-        void loadBuffer(sound.url).then((buffer) => {
-            if (stopped || buffer === null)
+        return playBufferSource(sound, bus, bufferPromise, currentPosition, loop);
+    }
+    function playBufferSource(sound, bus, bufferPromise, initialPosition, loop) {
+        const disposer = createDisposer();
+        let currentPosition = initialPosition;
+        // Live control state, applied on source creation so updates that race the async buffer load stick.
+        let currentRate = 1;
+        let currentUserGain = 1;
+        let sourceNode = null;
+        let userGainNode = null;
+        let falloffGain = null;
+        function updateFalloff() {
+            if (falloffGain !== null) {
+                falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            }
+        }
+        void bufferPromise.then((buffer) => {
+            if (buffer === null)
                 return;
-            const sourceNode = context.createBufferSource();
-            sourceNode.buffer = buffer;
-            sourceNode.loop = loop || (sound.loop ?? false);
-            gainNode = context.createGain();
-            gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-            sourceNode.connect(gainNode);
-            gainNode.connect(bus);
-            sourceNode.start();
+            const src = context.createBufferSource();
+            src.buffer = buffer;
+            src.loop = loop || (sound.loop ?? false);
+            src.playbackRate.value = currentRate;
+            // source → per-loop user gain (setGain) → distance falloff → bus
+            const uGain = context.createGain();
+            uGain.gain.value = currentUserGain;
+            const fGain = context.createGain();
+            fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            src.connect(uGain);
+            uGain.connect(fGain);
+            fGain.connect(bus);
+            src.start();
+            sourceNode = src;
+            userGainNode = uGain;
+            falloffGain = fGain;
+            disposer.onDispose(() => {
+                try {
+                    src.stop();
+                }
+                catch {
+                }
+                src.disconnect();
+                uGain.disconnect();
+                fGain.disconnect();
+                sourceNode = null;
+                userGainNode = null;
+                falloffGain = null;
+            });
         });
-        return {
+        if (loop)
+            activeSpatialUpdaters.add(updateFalloff);
+        const handle = {
             setPosition(next) {
                 currentPosition = next;
-                if (gainNode !== null) {
-                    gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-                }
+                updateFalloff();
+            },
+            setRate(rate) {
+                currentRate = clampLoopRate(rate);
+                if (sourceNode !== null)
+                    sourceNode.playbackRate.setTargetAtTime(currentRate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            },
+            setGain(gain) {
+                currentUserGain = clampLoopGain(gain);
+                if (userGainNode !== null)
+                    userGainNode.gain.setTargetAtTime(currentUserGain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             stop() {
-                stopped = true;
+                activeSpatialUpdaters.delete(updateFalloff);
+                activeLoops.delete(handle);
+                disposer.dispose();
             },
         };
+        if (loop)
+            activeLoops.add(handle);
+        return handle;
     }
     return {
         setListenerPose(position) {
             listenerPosition = position;
+            for (const updateGain of activeSpatialUpdaters)
+                updateGain();
         },
         playOneShot(soundId, position) {
             void context.resume().catch(() => undefined);
@@ -140,6 +244,9 @@ export function createAudioEngine(config = {}) {
             void context.resume().catch(() => undefined);
         },
         dispose() {
+            for (const handle of [...activeLoops])
+                handle.stop();
+            activeSpatialUpdaters.clear();
             director?.dispose();
             void context.close().catch(() => undefined);
         },

package/dist/audio/audioWire.d.ts

@@ -0,0 +1,40 @@
+import type { AudioEngine } from "./audioEngine.js";
+type AudioPlayPayload = {
+    sound: string;
+    at?: readonly [number, number, number];
+};
+type AudioMusicPayload = {
+    theme: string | null;
+    transpose?: number;
+};
+type AudioLoopStartPayload = {
+    id: string;
+    sound: string;
+    at?: readonly [number, number, number];
+};
+type AudioLoopSetPayload = {
+    id: string;
+    rate?: number;
+    gain?: number;
+    at?: readonly [number, number, number];
+};
+type AudioLoopStopPayload = {
+    id: string;
+};
+/** Minimal event bus the shell wires to the audio engine, including retained id-keyed loops (#1051). @internal */
+export type AudioEventBus = {
+    on(event: "audio.play", handler: (payload: AudioPlayPayload) => void): () => void;
+    on(event: "audio.music", handler: (payload: AudioMusicPayload) => void): () => void;
+    on(event: "audio.resume", handler: () => void): () => void;
+    on(event: "audio.loopStart", handler: (payload: AudioLoopStartPayload) => void): () => void;
+    on(event: "audio.loopSet", handler: (payload: AudioLoopSetPayload) => void): () => void;
+    on(event: "audio.loopStop", handler: (payload: AudioLoopStopPayload) => void): () => void;
+};
+/**
+ * Subscribe game audio events to the shell audio engine. Manages the retained-loop registry
+ * (`audio.loopStart`/`audio.loopSet`/`audio.loopStop`), keyed by stable id. Returns a single
+ * unsubscribe that tears every listener down and stops any loops still playing.
+ * @internal
+ */
+export declare function attachAudioEventWire(events: AudioEventBus, audioEngine: Pick<AudioEngine, "playOneShot" | "playLoop" | "playMusic" | "resume">): () => void;
+export {};

package/dist/audio/audioWire.js

@@ -0,0 +1,62 @@
+function toVec(at) {
+    return at === undefined ? undefined : { x: at[0], y: at[1], z: at[2] };
+}
+/**
+ * Subscribe game audio events to the shell audio engine. Manages the retained-loop registry
+ * (`audio.loopStart`/`audio.loopSet`/`audio.loopStop`), keyed by stable id. Returns a single
+ * unsubscribe that tears every listener down and stops any loops still playing.
+ * @internal
+ */
+export function attachAudioEventWire(events, audioEngine) {
+    const loops = new Map();
+    const offPlay = events.on("audio.play", ({ sound, at }) => {
+        audioEngine.playOneShot(sound, toVec(at));
+    });
+    const offMusic = events.on("audio.music", ({ theme, transpose }) => {
+        audioEngine.playMusic(theme, transpose === undefined ? undefined : { transpose });
+    });
+    const offResume = events.on("audio.resume", () => audioEngine.resume());
+    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)
+                return;
+            existing.handle.stop();
+            loops.delete(id);
+        }
+        const handle = audioEngine.playLoop(sound, toVec(at));
+        if (handle !== null)
+            loops.set(id, { sound, handle });
+    });
+    const offLoopSet = events.on("audio.loopSet", ({ id, rate, gain, at }) => {
+        const entry = loops.get(id);
+        // Unknown id: a live update may race a stop — silently drop it.
+        if (entry === undefined)
+            return;
+        if (rate !== undefined)
+            entry.handle.setRate(rate);
+        if (gain !== undefined)
+            entry.handle.setGain(gain);
+        if (at !== undefined)
+            entry.handle.setPosition({ x: at[0], y: at[1], z: at[2] });
+    });
+    const offLoopStop = events.on("audio.loopStop", ({ id }) => {
+        const entry = loops.get(id);
+        if (entry === undefined)
+            return;
+        entry.handle.stop();
+        loops.delete(id);
+    });
+    return () => {
+        offPlay();
+        offMusic();
+        offResume();
+        offLoopStart();
+        offLoopSet();
+        offLoopStop();
+        for (const { handle } of loops.values())
+            handle.stop();
+        loops.clear();
+    };
+}

package/dist/audio/loopParams.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure clamps for retained-loop live control (#1051). Kept dependency-free so the
+ * playback-rate/gain windows are one testable source of truth the audio engine reads.
+ */
+/** Lowest live playback-rate multiplier (two octaves below authored pitch). */
+export declare const MIN_LOOP_RATE = 0.25;
+/** Highest live playback-rate multiplier (two octaves above authored pitch). */
+export declare const MAX_LOOP_RATE = 4;
+/**
+ * Clamp a loop playback-rate multiplier into the safe pitch window `MIN_LOOP_RATE`–`MAX_LOOP_RATE`
+ * (1 = authored pitch). Non-finite input (NaN/±Infinity) falls back to the authored `1`.
+ * @internal — the audio engine applies this; game code sets rate through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopRate(rate: number): number;
+/**
+ * Clamp a loop gain multiplier into `0`–`1`. Non-finite input falls back to `0` (silence) so a
+ * stray NaN never blasts a loop to full volume.
+ * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopGain(gain: number): number;

package/dist/audio/loopParams.js

@@ -0,0 +1,28 @@
+/**
+ * Pure clamps for retained-loop live control (#1051). Kept dependency-free so the
+ * playback-rate/gain windows are one testable source of truth the audio engine reads.
+ */
+/** Lowest live playback-rate multiplier (two octaves below authored pitch). */
+export const MIN_LOOP_RATE = 0.25;
+/** Highest live playback-rate multiplier (two octaves above authored pitch). */
+export const MAX_LOOP_RATE = 4;
+/**
+ * Clamp a loop playback-rate multiplier into the safe pitch window `MIN_LOOP_RATE`–`MAX_LOOP_RATE`
+ * (1 = authored pitch). Non-finite input (NaN/±Infinity) falls back to the authored `1`.
+ * @internal — the audio engine applies this; game code sets rate through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopRate(rate) {
+    if (!Number.isFinite(rate))
+        return 1;
+    return Math.min(MAX_LOOP_RATE, Math.max(MIN_LOOP_RATE, rate));
+}
+/**
+ * Clamp a loop gain multiplier into `0`–`1`. Non-finite input falls back to `0` (silence) so a
+ * stray NaN never blasts a loop to full volume.
+ * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopGain(gain) {
+    if (!Number.isFinite(gain))
+        return 0;
+    return Math.min(1, Math.max(0, gain));
+}

package/dist/behaviour.d.ts

@@ -8,5 +8,6 @@ export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.
- */
+  * @internal
+  */
 export declare function useBehaviourWorld(world: BehaviourWorld, scaleDt?: (rawDt: number) => number): void;

package/dist/behaviour.js

@@ -10,7 +10,8 @@ export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.
- */
+  * @internal
+  */
 export function useBehaviourWorld(world, scaleDt) {
     const driverRef = useRef(createBehaviourWorldDriver(world));
     useEffect(() => {

package/dist/behaviourAttach.d.ts

@@ -1,5 +1,6 @@
 import type { Object3D } from "three";
 import { Behaviour, type BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+/** @internal */
 export declare class Object3DBehaviour extends Behaviour {
     /** @internal */ _object: Object3D | null;
     get object(): Object3D;

package/dist/behaviourAttach.js

@@ -1,4 +1,5 @@
 import { Behaviour } from "@jgengine/core/behaviour/behaviour";
+/** @internal */
 export class Object3DBehaviour extends Behaviour {
     /** @internal */ _object = null;
     get object() {

package/dist/behaviourDriver.d.ts

@@ -1,4 +1,5 @@
 import type { BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+/** @internal */
 export declare function createBehaviourWorldDriver(world: BehaviourWorld): {
     start(): void;
     stop(): void;

package/dist/behaviourDriver.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createBehaviourWorldDriver(world) {
     let running = false;
     return {

package/dist/boundActionDispatch.d.ts

@@ -0,0 +1,13 @@
+import { type ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { ActionCodesMap } from "@jgengine/core/input/actionBindings";
+import { type CommandSink } from "./commandSink.js";
+/** Actions the shell consumes natively and never routes to a same-named command. @internal */
+export declare const RESERVED_INPUT_ACTIONS: ReadonlySet<string>;
+/** Actions from `input` currently held down, for `ctx.input.publish` (#164.1); includes reserved movement/jump actions. @internal */
+export declare function heldActionsFor(tracker: Pick<ActionStateTracker<string>, "isDown">, actions: readonly string[]): string[];
+/** Whether a bound action should fire this frame: on press, or on repeat interval while held (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export declare function shouldFireBoundAction(tracker: Pick<ActionStateTracker<string>, "isDown" | "wasPressed">, action: string, input: ActionCodesMap | undefined, repeatFiredAt: ReadonlyMap<string, number>, now: number): boolean;
+/** Resolves and runs the command bound to `action` via the shell's action→command convention (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export declare function dispatchBoundAction(ctx: GameContext, action: string, yaw: number, pitch: number, aim: Aim, reserved?: ReadonlySet<string>, sink?: CommandSink): void;

package/dist/boundActionDispatch.js

@@ -0,0 +1,37 @@
+import { actionRepeatMs, resolveActionCommand, shouldDispatchAction, } from "@jgengine/core/input/actionBindings";
+import { localCommandSink } from "./commandSink.js";
+/** Actions the shell consumes natively and never routes to a same-named command. @internal */
+export const RESERVED_INPUT_ACTIONS = new Set([
+    "moveForward",
+    "moveBack",
+    "moveLeft",
+    "moveRight",
+    "turnLeft",
+    "turnRight",
+    "sprint",
+    "jump",
+    "tabTarget",
+    "clearTarget",
+    "useAbility",
+    "interact",
+]);
+/** Actions from `input` currently held down, for `ctx.input.publish` (#164.1); includes reserved movement/jump actions. @internal */
+export function heldActionsFor(tracker, actions) {
+    return actions.filter((action) => tracker.isDown(action));
+}
+/** Whether a bound action should fire this frame: on press, or on repeat interval while held (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export function shouldFireBoundAction(tracker, action, input, repeatFiredAt, now) {
+    return shouldDispatchAction({
+        pressed: tracker.wasPressed(action),
+        down: tracker.isDown(action),
+        repeatMs: actionRepeatMs(input?.[action]),
+        lastFiredAt: repeatFiredAt.get(action) ?? null,
+        now,
+    });
+}
+/** Resolves and runs the command bound to `action` via the shell's action→command convention (shared by `FrameDriver` and `HudOnlyDriver`). @internal */
+export function dispatchBoundAction(ctx, action, yaw, pitch, aim, reserved = RESERVED_INPUT_ACTIONS, sink = localCommandSink(ctx)) {
+    const command = resolveActionCommand(action, (name) => ctx.game.commands.has(name), reserved);
+    if (command !== null)
+        sink.run(command, { yaw, pitch, aim });
+}

package/dist/camera/GameCameraRig.d.ts

@@ -1,6 +1,7 @@
-import { type MutableRefObject } from "react";
+import { type ComponentType, type MutableRefObject } from "react";
 import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
 import type { CameraDirector } from "@jgengine/core/runtime/cameraDirector";
+import { type ViewmodelProps } from "./GameFirstPersonCamera.js";
 export { resolveRigKind } from "./rigResolve.js";
 export interface GameCameraRigProps {
     yawRef: MutableRefObject<number>;
@@ -12,5 +13,7 @@ export interface GameCameraRigProps {
     panKeysEnabled?: boolean;
     /** Runtime follow/cinematic override (#196.2). While present it wins over the static `config` for any field it reports non-`undefined`/non-`null`; absent (or an all-`undefined` snapshot) is a no-op. */
     director?: CameraDirector;
+    /** Custom first-person viewmodel (#542); read only when the resolved rig is `"first"`. */
+    viewmodel?: ComponentType<ViewmodelProps>;
 }
-export declare function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, }: GameCameraRigProps): import("react").JSX.Element;
+export declare function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, viewmodel, }: GameCameraRigProps): import("react").JSX.Element;

package/dist/camera/GameCameraRig.js

@@ -8,7 +8,7 @@ import { resolveDirectedCamera } from "./rigMath.js";
 import { resolveRigKind, 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, }) {
+export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerControls, panKeysEnabled, director, viewmodel, }) {
     const channel = useMemo(() => createCameraShakeChannel(config?.shake?.decayPerSecond), [config?.shake?.decayPerSecond]);
     const [, notifyDirectorChange] = useReducer((count) => count + 1, 0);
     useEffect(() => {
@@ -22,12 +22,17 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
     const followEntityId = directed.followEntityId;
     const rig = (() => {
         if (directed.cinematic !== undefined) {
-            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true }));
+            // A director-set cinematic auto-clears when its keyframe path completes, so a
+            // one-shot flyover can never strand the camera if a game-side clear timer drifts
+            // (the rig plays in real time; sim-clock timers do not). Static config cinematics
+            // hold their final frame as before.
+            const owner = director !== undefined && director.cinematic() !== null ? director : undefined;
+            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true, ...(owner === undefined ? {} : { onComplete: () => owner.setCinematic(null) }) }));
         }
         const kind = resolveRigKind(config);
         switch (kind) {
             case "first":
-                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined }));
+                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined, viewmodel: viewmodel }));
             case "topDown":
                 return _jsx(TopDownRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
             case "rts":

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -1,12 +1,19 @@
-import { type MutableRefObject } from "react";
+import { type ComponentType, type MutableRefObject } from "react";
 import * as THREE from "three";
 import type { 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;
+/** 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>;
+}
 export interface GameFirstPersonCameraProps {
     yawRef: MutableRefObject<number>;
     pitchRef: MutableRefObject<number>;
     config?: FirstPersonCameraConfig;
     followEntityId?: string;
+    /** Custom viewmodel component replacing the built-in three-mesh gun, rendered inside the same camera-locked, muzzle-tracked anchor. Ignored when `config.viewmodel === false`. */
+    viewmodel?: ComponentType<ViewmodelProps>;
 }
-export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;
+export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;

package/dist/camera/GameFirstPersonCamera.js

@@ -5,6 +5,7 @@ import * as THREE from "three";
 import { DEFAULT_EYE_HEIGHT } from "@jgengine/core/combat/shotOrigin";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
+import { useEntityRenderCues } from "../render/useEntityRenderCues.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
 const DEFAULT_SENSITIVITY = 0.0025;
@@ -21,7 +22,7 @@ export function readFirstPersonMuzzle(target) {
     target.copy(muzzleWorld);
     return true;
 }
-export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }) {
+export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }) {
     const eyeHeight = config?.eyeHeight ?? DEFAULT_EYE_HEIGHT;
     const sensitivity = config?.sensitivity ?? DEFAULT_SENSITIVITY;
     const maxPitch = config?.maxPitch ?? DEFAULT_MAX_PITCH;
@@ -32,6 +33,7 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     const domElement = useThree((state) => state.gl.domElement);
     const followId = followEntityId ?? userId;
     const seededRef = useRef(false);
+    const cuesRef = useEntityRenderCues(followId);
     useEffect(() => {
         const requestLock = () => {
             if (window.matchMedia?.("(pointer: coarse)").matches)
@@ -73,9 +75,9 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     }, ORBIT_CAMERA_FRAME_PRIORITY);
     if (config?.viewmodel === false)
         return null;
-    return _jsx(FirstPersonViewmodel, { camera: camera });
+    return _jsx(FirstPersonViewmodel, { camera: camera, viewmodel: viewmodel, cuesRef: cuesRef });
 }
-function FirstPersonViewmodel({ camera }) {
+function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, }) {
     const groupRef = useRef(null);
     useEffect(() => () => {
         muzzleTracked = false;
@@ -92,5 +94,8 @@ function FirstPersonViewmodel({ camera }) {
         muzzleWorld.copy(MUZZLE_OFFSET).applyQuaternion(camera.quaternion).add(camera.position);
         muzzleTracked = true;
     }, GAME_SIM_FRAME_PRIORITY);
+    if (Viewmodel !== undefined) {
+        return (_jsx("group", { ref: groupRef, children: _jsx(Viewmodel, { cuesRef: cuesRef }) }));
+    }
     return (_jsxs("group", { ref: groupRef, children: [_jsxs("mesh", { position: [0, 0, -0.22], children: [_jsx("boxGeometry", { args: [0.09, 0.11, 0.55] }), _jsx("meshStandardMaterial", { color: "#22262d", metalness: 0.6, roughness: 0.35 })] }), _jsxs("mesh", { position: [0, -0.13, 0.04], rotation: [0.35, 0, 0], children: [_jsx("boxGeometry", { args: [0.08, 0.18, 0.11] }), _jsx("meshStandardMaterial", { color: "#33373f", metalness: 0.4, roughness: 0.5 })] }), _jsxs("mesh", { position: [0, 0.03, -0.52], rotation: [Math.PI / 2, 0, 0], children: [_jsx("cylinderGeometry", { args: [0.022, 0.022, 0.18, 10] }), _jsx("meshStandardMaterial", { color: "#0e0f12", metalness: 0.7, roughness: 0.3 })] })] }));
 }

package/dist/camera/GameInspectionCamera.d.ts

@@ -2,5 +2,5 @@ import { type InspectionCameraConfig } from "./inspectionCameraMath.js";
 export interface GameInspectionCameraProps {
     config?: InspectionCameraConfig;
 }
-/** Model-viewer style rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
+/** Model-viewer / editor rig (#207.7, #866): left-click selects (editor), middle-drag pans, right-drag orbits, scroll zooms toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
 export declare function GameInspectionCamera({ config: configPatch }: GameInspectionCameraProps): import("react").JSX.Element;

package/dist/camera/GameInspectionCamera.js

@@ -4,7 +4,7 @@ import { useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { MOUSE } from "three";
 import { resolveInspectionCameraConfig, resolveInspectionZoomToCursor, seedInspectionCamera, } from "./inspectionCameraMath.js";
-/** Model-viewer style rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
+/** Model-viewer / editor rig (#207.7, #866): left-click selects (editor), middle-drag pans, right-drag orbits, scroll zooms toward a configurable anchor. Orbits a fixed `target`; never reads player/entity state. */
 export function GameInspectionCamera({ config: configPatch }) {
     const config = resolveInspectionCameraConfig(configPatch);
     const controlsRef = useRef(null);
@@ -31,5 +31,5 @@ export function GameInspectionCamera({ config: configPatch }) {
         camera.position.add(controls.target.clone().sub(previous));
         controls.update();
     }, [camera, config.target.x, config.target.y, config.target.z]);
-    return (_jsx(OrbitControls, { ref: controlsRef, makeDefault: true, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, zoomToCursor: resolveInspectionZoomToCursor(config.anchor), enablePan: config.pan, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, minPolarAngle: config.minPolarAngle, maxPolarAngle: config.maxPolarAngle, screenSpacePanning: true, mouseButtons: { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.PAN, RIGHT: MOUSE.PAN } }));
+    return (_jsx(OrbitControls, { ref: controlsRef, makeDefault: true, enableDamping: true, dampingFactor: config.dampingFactor, rotateSpeed: config.rotateSpeed, zoomSpeed: config.zoomSpeed, zoomToCursor: resolveInspectionZoomToCursor(config.anchor), enablePan: config.pan, enableRotate: true, enableZoom: true, minDistance: config.minDistance, maxDistance: config.maxDistance, minPolarAngle: config.minPolarAngle, maxPolarAngle: config.maxPolarAngle, screenSpacePanning: true, mouseButtons: { LEFT: undefined, MIDDLE: MOUSE.PAN, RIGHT: MOUSE.ROTATE } }));
 }