@jgengine/shell 0.9.0 → 0.11.0

package/dist/audio/musicVoices.js

@@ -0,0 +1,338 @@
+import { mtof } from "@jgengine/core/audio/music";
+function adsr(ctx, when, dur, peak, attack, release) {
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(peak, when + attack);
+    g.gain.setValueAtTime(peak, Math.max(when + attack, when + dur - release));
+    g.gain.exponentialRampToValueAtTime(0.0001, when + dur + release);
+    return g;
+}
+function stack(ctx, when, freq, dur, out, type, dets, tail) {
+    for (const det of dets) {
+        const o = ctx.createOscillator();
+        o.type = type;
+        o.frequency.value = freq;
+        o.detune.value = det;
+        o.connect(out);
+        o.start(when);
+        o.stop(when + dur + tail);
+    }
+}
+function strings(ctx, when, freq, dur, vel, out, attack = 0.3) {
+    const g = adsr(ctx, when, dur, vel * 0.16, attack, 0.7);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 750 + freq * 2;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-6, 5], 0.9);
+}
+function pad(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.11, 0.6, 1.1);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 520 + freq * 1.4;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-9, -3, 4, 10], 1.2);
+}
+function reed(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.14, 0.08, 0.25);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 1600 + freq;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-3, 4], 0.35);
+}
+function horn(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.15, 0.09, 0.3);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 900 + freq * 1.5;
+    lp.Q.value = 0.6;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-4, 3], 0.4);
+    const sub = ctx.createOscillator();
+    sub.type = "sine";
+    sub.frequency.value = freq;
+    const sg = ctx.createGain();
+    sg.gain.value = 0.4;
+    sub.connect(sg).connect(lp);
+    sub.start(when);
+    sub.stop(when + dur + 0.4);
+}
+function brassStab(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, Math.min(dur, 0.4), vel * 0.17, 0.02, 0.14);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 1400 + freq * 2;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, Math.min(dur, 0.4), lp, "sawtooth", [-5, 6], 0.2);
+}
+function flute(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.15, 0.06, 0.2);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2600;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = "sine";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + dur + 0.25);
+    const breath = ctx.createBufferSource();
+    const len = Math.floor(ctx.sampleRate * Math.min(dur, 0.4));
+    const buf = ctx.createBuffer(1, len, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < len; i += 1)
+        data[i] = (Math.random() * 2 - 1) * 0.5;
+    breath.buffer = buf;
+    const bp = ctx.createBiquadFilter();
+    bp.type = "bandpass";
+    bp.frequency.value = freq * 2;
+    const bg = ctx.createGain();
+    bg.gain.value = vel * 0.02;
+    breath.connect(bp).connect(bg).connect(out);
+    breath.start(when);
+}
+function pipe(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.13, 0.03, 0.15);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 3000;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "triangle", [0, 7], 0.2);
+}
+function squareLead(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.1, 0.02, 0.12);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2200 + freq;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = "square";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + dur + 0.2);
+}
+function choir(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.12, 0.25, 0.6);
+    const formant = ctx.createBiquadFilter();
+    formant.type = "bandpass";
+    formant.frequency.value = Math.min(1800, 500 + freq * 1.6);
+    formant.Q.value = 0.7;
+    formant.connect(g).connect(out);
+    stack(ctx, when, freq, dur, formant, "sawtooth", [-8, -2, 6], 0.8);
+    stack(ctx, when, freq * 2, dur, formant, "triangle", [3], 0.8);
+}
+function oboe(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.17, 0.055, 0.22);
+    const formant = ctx.createBiquadFilter();
+    formant.type = "bandpass";
+    formant.frequency.value = Math.min(2400, 600 + freq * 2.2);
+    formant.Q.value = 0.9;
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2800;
+    formant.connect(lp).connect(g).connect(out);
+    const vib = ctx.createOscillator();
+    vib.frequency.value = 5.2;
+    const vibGain = ctx.createGain();
+    vibGain.gain.setValueAtTime(0, when);
+    vibGain.gain.linearRampToValueAtTime(freq * 0.004, when + 0.3);
+    vib.connect(vibGain);
+    for (const det of [-5, 4]) {
+        const o = ctx.createOscillator();
+        o.type = "sawtooth";
+        o.frequency.value = freq;
+        o.detune.value = det;
+        vibGain.connect(o.frequency);
+        o.connect(formant);
+        o.start(when);
+        o.stop(when + dur + 0.4);
+    }
+    vib.start(when);
+    vib.stop(when + dur + 0.4);
+}
+function pluck(ctx, when, freq, vel, out, decay, bassy = false) {
+    const g = ctx.createGain();
+    const peak = vel * (bassy ? 0.26 : 0.2);
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(peak, when + 0.004);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + decay);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = bassy ? 900 : 2600 + freq;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = bassy ? "triangle" : "sawtooth";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + decay + 0.1);
+    if (!bassy) {
+        const o2 = ctx.createOscillator();
+        o2.type = "triangle";
+        o2.frequency.value = freq * 2.001;
+        const g2 = ctx.createGain();
+        g2.gain.setValueAtTime(peak * 0.4, when);
+        g2.gain.exponentialRampToValueAtTime(0.0001, when + decay * 0.6);
+        o2.connect(g2).connect(out);
+        o2.start(when);
+        o2.stop(when + decay);
+    }
+}
+function bell(ctx, when, freq, vel, out, decay = 1.8) {
+    for (const [ratio, amp] of [[1, 1], [2.76, 0.5], [5.4, 0.25], [8.9, 0.12]]) {
+        const g = ctx.createGain();
+        g.gain.setValueAtTime(0.0001, when);
+        g.gain.linearRampToValueAtTime(vel * 0.14 * amp, when + 0.005);
+        g.gain.exponentialRampToValueAtTime(0.0001, when + decay * (1 - (ratio - 1) * 0.06));
+        const o = ctx.createOscillator();
+        o.type = "sine";
+        o.frequency.value = freq * ratio;
+        o.connect(g).connect(out);
+        o.start(when);
+        o.stop(when + decay + 0.2);
+    }
+}
+function piano(ctx, when, freq, dur, vel, out) {
+    const naturalDecay = Math.min(5.2, Math.max(1.2, 380 / freq));
+    const body = ctx.createBiquadFilter();
+    body.type = "lowpass";
+    body.frequency.value = Math.min(5600, 1400 + freq * 4);
+    body.Q.value = 0.35;
+    body.connect(out);
+    const partials = [
+        [1, 0.62, 1, -3],
+        [1.0005, 0.62, 1, 3],
+        [2.003, 0.5, 0.58, 2],
+        [3.006, 0.2, 0.36, -4],
+        [4.012, 0.09, 0.24, 5],
+        [5.02, 0.05, 0.17, -6],
+        [7.03, 0.025, 0.12, 4],
+    ];
+    for (const [ratio, amp, decayMul, cents] of partials) {
+        const decay = Math.min(naturalDecay * decayMul, dur + 0.35);
+        const g = ctx.createGain();
+        const peak = vel * 0.24 * amp;
+        g.gain.setValueAtTime(0.0001, when);
+        g.gain.linearRampToValueAtTime(peak, when + 0.004);
+        g.gain.exponentialRampToValueAtTime(0.0001, when + Math.max(0.14, decay));
+        const o = ctx.createOscillator();
+        o.type = ratio < 1.01 ? "triangle" : "sine";
+        o.frequency.value = freq * ratio;
+        o.detune.value = cents;
+        o.connect(g).connect(body);
+        o.start(when);
+        o.stop(when + Math.max(0.14, decay) + 0.1);
+    }
+}
+function noiseHit(ctx, when, vel, out, hp, len, curve) {
+    const n = Math.floor(ctx.sampleRate * len);
+    const buf = ctx.createBuffer(1, n, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < n; i += 1)
+        data[i] = (Math.random() * 2 - 1) * (1 - i / n) ** curve;
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const f = ctx.createBiquadFilter();
+    f.type = "highpass";
+    f.frequency.value = hp;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.22, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + len);
+    src.connect(f).connect(g).connect(out);
+    src.start(when);
+}
+function drum(ctx, when, freq, vel, out, decay, punch) {
+    const o = ctx.createOscillator();
+    o.type = "sine";
+    o.frequency.setValueAtTime(freq * punch, when);
+    o.frequency.exponentialRampToValueAtTime(freq, when + 0.06);
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.5, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + decay);
+    o.connect(g).connect(out);
+    o.start(when);
+    o.stop(when + decay + 0.05);
+    noiseHit(ctx, when, vel * 0.4, out, 200, Math.min(decay, 0.12), 2);
+}
+function woodBlock(ctx, when, vel, out) {
+    const o = ctx.createOscillator();
+    o.type = "square";
+    o.frequency.value = 1100;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.2, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + 0.05);
+    const bp = ctx.createBiquadFilter();
+    bp.type = "bandpass";
+    bp.frequency.value = 1100;
+    o.connect(bp).connect(g).connect(out);
+    o.start(when);
+    o.stop(when + 0.07);
+}
+function cymSwell(ctx, when, dur, vel, out) {
+    const n = Math.floor(ctx.sampleRate * (dur + 0.3));
+    const buf = ctx.createBuffer(1, n, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < n; i += 1)
+        data[i] = Math.random() * 2 - 1;
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const hp = ctx.createBiquadFilter();
+    hp.type = "highpass";
+    hp.frequency.value = 6000;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(vel * 0.1, when + dur);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + dur + 0.3);
+    src.connect(hp).connect(g).connect(out);
+    src.start(when);
+}
+/**
+ * Play one theme note through its instrument voice into `out` (a per-layer gain
+ * node the director wires to master + reverb). `spb` is seconds-per-beat and
+ * `transpose` shifts the note in semitones for per-zone key changes. This is the
+ * engine's reusable instrument library; unknown instruments fall back to a sine.
+ */
+export function playMusicNote(ctx, event, when, spb, out, transpose = 0) {
+    const freq = mtof(event.midi + transpose);
+    const dur = Math.max(0.1, event.dur * spb);
+    const vel = event.vel;
+    const inst = event.inst;
+    switch (inst) {
+        case "strings": return strings(ctx, when, freq, dur, vel, out);
+        case "stacc": return strings(ctx, when, freq, Math.min(dur, 0.22), vel, out, 0.02);
+        case "pad": return pad(ctx, when, freq, dur, vel, out);
+        case "reed": return reed(ctx, when, freq, dur, vel, out);
+        case "horn": return horn(ctx, when, freq, dur, vel, out);
+        case "brassStab": return brassStab(ctx, when, freq, dur, vel, out);
+        case "flute": return flute(ctx, when, freq, dur, vel, out);
+        case "pipe": return pipe(ctx, when, freq, dur, vel, out);
+        case "squareLead": return squareLead(ctx, when, freq, dur, vel, out);
+        case "choir": return choir(ctx, when, freq, dur, vel, out);
+        case "oboe": return oboe(ctx, when, freq, dur, vel, out);
+        case "harp": return pluck(ctx, when, freq, vel, out, 1.4);
+        case "lute": return pluck(ctx, when, freq, vel, out, 0.7);
+        case "dulcimer": return pluck(ctx, when, freq, vel, out, 1.0);
+        case "bass": return pluck(ctx, when, freq, vel, out, 0.9, true);
+        case "bell": return bell(ctx, when, freq, vel, out);
+        case "tinyBell": return bell(ctx, when, freq, vel, out, 0.7);
+        case "piano": return piano(ctx, when, freq, dur, vel, out);
+        case "timpani": return drum(ctx, when, freq, vel, out, 0.6, 1.5);
+        case "warDrum": return drum(ctx, when, Math.max(50, freq * 0.5), vel, out, 0.35, 1.8);
+        case "frameDrum": return drum(ctx, when, Math.max(70, freq * 0.6), vel, out, 0.25, 1.6);
+        case "shaker": return noiseHit(ctx, when, vel, out, 6800, 0.055, 1.8);
+        case "woodBlock": return woodBlock(ctx, when, vel, out);
+        case "cymSwell": return cymSwell(ctx, when, dur, vel, out);
+        default: {
+            const o = ctx.createOscillator();
+            o.frequency.value = freq;
+            const g = adsr(ctx, when, dur, vel * 0.12, 0.02, 0.2);
+            o.connect(g).connect(out);
+            o.start(when);
+            o.stop(when + dur + 0.3);
+        }
+    }
+}

package/dist/audio/synthEngine.d.ts

@@ -0,0 +1,9 @@
+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;
+/**
+ * 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;

package/dist/audio/synthEngine.js

@@ -0,0 +1,57 @@
+/** Build the shared 1-second mono white-noise buffer every noise voice samples from. */
+export function createNoiseBuffer(ctx) {
+    const len = Math.floor(ctx.sampleRate);
+    const buf = ctx.createBuffer(1, len, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < len; i += 1)
+        data[i] = Math.random() * 2 - 1;
+    return buf;
+}
+function realizeTone(ctx, out, voice, cueGain, at) {
+    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 g = ctx.createGain();
+    g.gain.setValueAtTime(0, t);
+    g.gain.linearRampToValueAtTime(peak, t + attack);
+    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration);
+    osc.connect(g).connect(out);
+    osc.start(t);
+    osc.stop(t + voice.duration + 0.05);
+}
+function realizeNoise(ctx, out, noiseBuf, voice, cueGain, at) {
+    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;
+    const filter = ctx.createBiquadFilter();
+    filter.type = voice.filterType ?? "lowpass";
+    filter.frequency.value = voice.filterFreq;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(peak, t);
+    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration * decay);
+    src.connect(filter).connect(g).connect(out);
+    src.start(t, Math.random() * 0.5, voice.duration);
+}
+/**
+ * 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 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);
+    }
+}

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(() => {
@@ -27,7 +27,7 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
         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,9 +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

@@ -2,14 +2,27 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 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_EYE_HEIGHT = 1.6;
 const DEFAULT_SENSITIVITY = 0.0025;
 const DEFAULT_MAX_PITCH = 1.45;
-export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, }) {
+const VIEWMODEL_ORIGIN = new THREE.Vector3(0.34, -0.26, -0.72);
+const MUZZLE_TIP_LOCAL = new THREE.Vector3(0, 0.03, -0.61);
+const MUZZLE_OFFSET = VIEWMODEL_ORIGIN.clone().add(MUZZLE_TIP_LOCAL);
+const muzzleWorld = new THREE.Vector3();
+let muzzleTracked = false;
+/** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
+export function readFirstPersonMuzzle(target) {
+    if (!muzzleTracked)
+        return false;
+    target.copy(muzzleWorld);
+    return true;
+}
+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;
@@ -20,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)
@@ -61,19 +75,27 @@ 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;
+    }, []);
     useFrame(() => {
         const group = groupRef.current;
         if (group === null)
             return;
         group.position.copy(camera.position);
         group.quaternion.copy(camera.quaternion);
-        group.translateX(0.34);
-        group.translateY(-0.26);
-        group.translateZ(-0.72);
+        group.translateX(VIEWMODEL_ORIGIN.x);
+        group.translateY(VIEWMODEL_ORIGIN.y);
+        group.translateZ(VIEWMODEL_ORIGIN.z);
+        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;