@jgengine/shell 0.9.0 → 0.11.0

package/dist/GameUiPreview.js

@@ -37,7 +37,6 @@ export const defaultUiScenario = (ctx, playable) => {
 export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
     const [ctx, setCtx] = useState(null);
     useEffect(() => {
-        playable.game.scene.clear();
         const context = createGameContext({
             definition: playable.game,
             content: playable.content,
@@ -53,7 +52,6 @@ export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
         }
         setCtx(context);
         return () => {
-            playable.game.scene.clear();
             setCtx(null);
         };
     }, [playable, scenario]);

package/dist/audio/audioEngine.d.ts

@@ -1,4 +1,6 @@
 import { type AudioBusDef, type SoundDef } from "@jgengine/core/audio/audioFalloff";
+import type { MusicTheme } from "@jgengine/core/audio/music";
+import { type CrossfadeOptions } from "./musicDirector.js";
 export interface Vec3 {
     x: number;
     y: number;
@@ -7,6 +9,10 @@ export interface Vec3 {
 export interface AudioSceneConfig {
     sounds?: Record<string, SoundDef>;
     buses?: Record<string, AudioBusDef>;
+    /** Procedural music themes, crossfaded by {@link AudioEngine.playMusic}. Mixed through the `musicBus` (default "music") so the settings volume applies. */
+    music?: Record<string, MusicTheme>;
+    /** Bus id the procedural music director mixes through. Default "music". */
+    musicBus?: string;
 }
 export interface AudioEmitterHandle {
     setPosition(position: Vec3): void;
@@ -16,6 +22,8 @@ export interface AudioEngine {
     setListenerPose(position: Vec3): void;
     playOneShot(soundId: string, position?: Vec3): void;
     playLoop(soundId: string, position?: Vec3): AudioEmitterHandle | null;
+    /** Crossfade the procedural soundtrack to `themeId` (null fades out). No-op when no `music` catalog is configured. */
+    playMusic(themeId: string | null, options?: CrossfadeOptions): void;
     setBusGain(busId: string, gain: number): void;
     setMasterGain(gain: number): void;
     resume(): void;

package/dist/audio/audioEngine.js

@@ -1,9 +1,13 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { createDisposer } from "@jgengine/core/game/defineGame";
+import { MusicDirector } from "./musicDirector.js";
+import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
         playOneShot: () => undefined,
         playLoop: () => null,
+        playMusic: () => undefined,
         setBusGain: () => undefined,
         setMasterGain: () => undefined,
         resume: () => undefined,
@@ -43,6 +47,21 @@ export function createAudioEngine(config = {}) {
         }
         return node;
     }
+    let noiseBuffer = null;
+    function sharedNoiseBuffer() {
+        if (noiseBuffer === null)
+            noiseBuffer = createNoiseBuffer(context);
+        return noiseBuffer;
+    }
+    let director = null;
+    function musicDirector() {
+        if (config.music === undefined)
+            return null;
+        if (director === null) {
+            director = new MusicDirector(context, busGainNode(config.musicBus ?? "music"), config.music);
+        }
+        return director;
+    }
     const bufferCache = new Map();
     function loadBuffer(url) {
         let pending = bufferCache.get(url);
@@ -56,48 +75,82 @@ export function createAudioEngine(config = {}) {
         return pending;
     }
     let listenerPosition = { x: 0, y: 0, z: 0 };
+    const activeSpatialUpdaters = new Set();
     function playInternal(soundId, position, loop) {
         const sound = sounds[soundId];
         if (sound === undefined)
             return null;
         const bus = busGainNode(sound.bus);
         let currentPosition = position ?? listenerPosition;
-        let gainNode = null;
-        let stopped = false;
+        if (sound.synth !== undefined) {
+            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 };
+        }
+        if (sound.url === undefined)
+            return null;
+        const disposer = createDisposer();
+        let liveGain = null;
+        function updateGain() {
+            if (liveGain !== null) {
+                liveGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            }
+        }
         void loadBuffer(sound.url).then((buffer) => {
-            if (stopped || buffer === null)
+            if (buffer === null)
                 return;
             const sourceNode = context.createBufferSource();
             sourceNode.buffer = buffer;
             sourceNode.loop = loop || (sound.loop ?? false);
-            gainNode = context.createGain();
+            const gainNode = context.createGain();
             gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             sourceNode.connect(gainNode);
             gainNode.connect(bus);
             sourceNode.start();
+            liveGain = gainNode;
+            disposer.onDispose(() => {
+                try {
+                    sourceNode.stop();
+                }
+                catch {
+                }
+                sourceNode.disconnect();
+                gainNode.disconnect();
+                liveGain = null;
+            });
         });
+        if (loop)
+            activeSpatialUpdaters.add(updateGain);
         return {
             setPosition(next) {
                 currentPosition = next;
-                if (gainNode !== null) {
-                    gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-                }
+                updateGain();
             },
             stop() {
-                stopped = true;
+                activeSpatialUpdaters.delete(updateGain);
+                disposer.dispose();
             },
         };
     }
     return {
         setListenerPose(position) {
             listenerPosition = position;
+            for (const updateGain of activeSpatialUpdaters)
+                updateGain();
         },
         playOneShot(soundId, position) {
+            void context.resume().catch(() => undefined);
             playInternal(soundId, position, false);
         },
         playLoop(soundId, position) {
             return playInternal(soundId, position, true);
         },
+        playMusic(themeId, options) {
+            void context.resume().catch(() => undefined);
+            musicDirector()?.crossfadeTo(themeId, options);
+        },
         setBusGain(busId, gain) {
             busGainNode(busId).gain.value = gain;
         },
@@ -108,6 +161,8 @@ export function createAudioEngine(config = {}) {
             void context.resume().catch(() => undefined);
         },
         dispose() {
+            activeSpatialUpdaters.clear();
+            director?.dispose();
             void context.close().catch(() => undefined);
         },
     };

package/dist/audio/audioWire.d.ts

@@ -0,0 +1,22 @@
+import type { AudioEngine } from "./audioEngine.js";
+type AudioPlayPayload = {
+    sound: string;
+    at?: readonly [number, number, number];
+};
+type AudioMusicPayload = {
+    theme: string | null;
+    transpose?: number;
+};
+/** Minimal event bus the shell wires to the audio engine. @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;
+};
+/**
+ * Subscribe game audio events to the shell audio engine.
+ * Returns a single unsubscribe that tears all three listeners down.
+ * @internal
+ */
+export declare function attachAudioEventWire(events: AudioEventBus, audioEngine: Pick<AudioEngine, "playOneShot" | "playMusic" | "resume">): () => void;
+export {};

package/dist/audio/audioWire.js

@@ -0,0 +1,19 @@
+/**
+ * Subscribe game audio events to the shell audio engine.
+ * Returns a single unsubscribe that tears all three listeners down.
+ * @internal
+ */
+export function attachAudioEventWire(events, audioEngine) {
+    const offPlay = events.on("audio.play", ({ sound, at }) => {
+        audioEngine.playOneShot(sound, at === undefined ? undefined : { x: at[0], y: at[1], z: at[2] });
+    });
+    const offMusic = events.on("audio.music", ({ theme, transpose }) => {
+        audioEngine.playMusic(theme, transpose === undefined ? undefined : { transpose });
+    });
+    const offResume = events.on("audio.resume", () => audioEngine.resume());
+    return () => {
+        offPlay();
+        offMusic();
+        offResume();
+    };
+}

package/dist/audio/musicDirector.d.ts

@@ -0,0 +1,31 @@
+import { type MusicTheme } from "@jgengine/core/audio/music";
+/** Options for a music crossfade. */
+export interface CrossfadeOptions {
+    /** Semitone shift applied to every note of the incoming theme (per-zone key). Default 0. */
+    transpose?: number;
+}
+/**
+ * Runs a set of looping {@link MusicTheme}s as crossfadeable layers on one shared
+ * Web Audio graph: master → compressor → destination, with a fixed convolution
+ * reverb send. `crossfadeTo` swaps the audible theme; a 110ms lookahead scheduler
+ * keeps each active layer's notes queued ahead of the clock so loops are seamless.
+ */
+export declare class MusicDirector {
+    private readonly ctx;
+    private readonly master;
+    private readonly reverbSend;
+    private readonly layers;
+    private timer;
+    private volume;
+    private current;
+    constructor(ctx: BaseAudioContext, destination: AudioNode, themes: Record<string, MusicTheme>);
+    /** The currently faded-in theme id, or null when music is stopped. */
+    currentTheme(): string | null;
+    /** Fade to `themeId` (or fade all out when null). No-op if it is already current. */
+    crossfadeTo(themeId: string | null, options?: CrossfadeOptions): void;
+    /** Music volume 0..1, scaling the master gain. */
+    setVolume(volume: number): void;
+    /** Stop the scheduler and release the graph. */
+    dispose(): void;
+    private tick;
+}

package/dist/audio/musicDirector.js

@@ -0,0 +1,125 @@
+import { notesInWindow, themeLoopSeconds } from "@jgengine/core/audio/music";
+import { playMusicNote } from "./musicVoices.js";
+const LOOKAHEAD = 0.6;
+const TICK_MS = 110;
+const FADE_IN = 0.75;
+const FADE_OUT = 0.35;
+const MASTER_BASE = 0.2;
+/**
+ * Runs a set of looping {@link MusicTheme}s as crossfadeable layers on one shared
+ * Web Audio graph: master → compressor → destination, with a fixed convolution
+ * reverb send. `crossfadeTo` swaps the audible theme; a 110ms lookahead scheduler
+ * keeps each active layer's notes queued ahead of the clock so loops are seamless.
+ */
+export class MusicDirector {
+    ctx;
+    master;
+    reverbSend;
+    layers = new Map();
+    timer;
+    volume = 1;
+    current = null;
+    constructor(ctx, destination, themes) {
+        this.ctx = ctx;
+        this.master = ctx.createGain();
+        this.master.gain.value = MASTER_BASE;
+        const compressor = ctx.createDynamicsCompressor();
+        compressor.threshold.value = -18;
+        compressor.knee.value = 18;
+        compressor.ratio.value = 2.2;
+        compressor.attack.value = 0.015;
+        compressor.release.value = 0.25;
+        this.master.connect(compressor);
+        compressor.connect(destination);
+        const irSeconds = 2.6;
+        const len = Math.floor(ctx.sampleRate * irSeconds);
+        const ir = ctx.createBuffer(2, len, ctx.sampleRate);
+        for (let ch = 0; ch < 2; ch += 1) {
+            const data = ir.getChannelData(ch);
+            for (let i = 0; i < len; i += 1)
+                data[i] = (Math.random() * 2 - 1) * (1 - i / len) ** 2.4;
+        }
+        const reverb = ctx.createConvolver();
+        reverb.buffer = ir;
+        this.reverbSend = ctx.createGain();
+        this.reverbSend.gain.value = 0.55;
+        this.reverbSend.connect(reverb);
+        reverb.connect(this.master);
+        for (const [id, theme] of Object.entries(themes)) {
+            const gain = ctx.createGain();
+            gain.gain.value = 0;
+            gain.connect(this.master);
+            gain.connect(this.reverbSend);
+            this.layers.set(id, {
+                theme,
+                gain,
+                trim: theme.trim ?? 1,
+                active: false,
+                target: 0,
+                anchor: 0,
+                nextFrom: 0,
+                transpose: 0,
+            });
+        }
+        if (typeof setInterval === "function") {
+            this.timer = setInterval(() => this.tick(), TICK_MS);
+        }
+    }
+    /** The currently faded-in theme id, or null when music is stopped. */
+    currentTheme() {
+        return this.current;
+    }
+    /** Fade to `themeId` (or fade all out when null). No-op if it is already current. */
+    crossfadeTo(themeId, options = {}) {
+        if (themeId === this.current)
+            return;
+        this.current = themeId;
+        const now = this.ctx.currentTime;
+        for (const [id, layer] of this.layers) {
+            const target = id === themeId ? layer.trim : 0;
+            if (layer.target === target)
+                continue;
+            const rising = target > layer.target;
+            layer.target = target;
+            layer.gain.gain.setTargetAtTime(target, now, rising ? FADE_IN : FADE_OUT);
+            if (rising) {
+                layer.active = true;
+                layer.anchor = now + 0.15;
+                layer.nextFrom = layer.anchor - 1e-6;
+                layer.transpose = options.transpose ?? 0;
+            }
+            else {
+                layer.active = false;
+            }
+        }
+    }
+    /** Music volume 0..1, scaling the master gain. */
+    setVolume(volume) {
+        this.volume = Math.max(0, volume);
+        this.master.gain.value = MASTER_BASE * this.volume;
+    }
+    /** Stop the scheduler and release the graph. */
+    dispose() {
+        if (this.timer !== undefined)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.master.disconnect();
+        this.reverbSend.disconnect();
+    }
+    tick() {
+        const horizon = this.ctx.currentTime + LOOKAHEAD;
+        const spbAvailable = 60;
+        for (const layer of this.layers.values()) {
+            if (!layer.active)
+                continue;
+            if (themeLoopSeconds(layer.theme) <= 0)
+                continue;
+            const spb = spbAvailable / layer.theme.bpm;
+            const notes = notesInWindow(layer.theme, layer.anchor, layer.nextFrom, horizon);
+            for (const { event, when } of notes) {
+                playMusicNote(this.ctx, event, when, spb, layer.gain, layer.transpose);
+            }
+            layer.nextFrom = horizon;
+        }
+    }
+}

package/dist/audio/musicVoices.d.ts

@@ -0,0 +1,10 @@
+import { type NoteEvent } from "@jgengine/core/audio/music";
+type Ctx = BaseAudioContext;
+/**
+ * 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 declare function playMusicNote(ctx: Ctx, event: NoteEvent, when: number, spb: number, out: GainNode, transpose?: number): void;
+export {};