@jgengine/shell 0.8.0 → 0.10.0

package/dist/GameUiPreview.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { createGameContext } from "@jgengine/core/runtime/gameContext";
 import { GameProvider } from "@jgengine/react/provider";
+import { HudViewportProvider } from "@jgengine/react/hudViewport";
 const PREVIEW_USER_ID = "ui-preview";
 const TICK_STEP = 1 / 60;
 function runTicks(ctx, playable, seconds) {
@@ -59,5 +60,5 @@ export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
     if (ctx === null)
         return _jsx("div", { className: "h-full w-full bg-neutral-900" });
     const GameUI = playable.GameUI;
-    return (_jsx("div", { "data-ui-preview-ready": true, className: "relative h-full w-full overflow-hidden", style: { background: "linear-gradient(180deg, #2a3d33 0%, #1a2320 55%, #141b18 100%)" }, children: _jsx(GameProvider, { context: ctx, children: _jsx(GameUI, {}) }) }));
+    return (_jsx("div", { "data-ui-preview-ready": true, className: "relative h-full w-full overflow-hidden", style: { background: "linear-gradient(180deg, #2a3d33 0%, #1a2320 55%, #141b18 100%)" }, children: _jsx(GameProvider, { context: ctx, children: _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, children: _jsx(GameUI, {}) }) }) }));
 }

package/dist/audio/AudioComponents.js

@@ -1,6 +1,6 @@
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
-import { useSceneEntities, useSceneObjects } from "@jgengine/react/hooks";
+import { useGameContext } from "@jgengine/react/provider";
 export function AudioListener({ engine }) {
     const camera = useThree((state) => state.camera);
     useFrame(() => {
@@ -8,18 +8,20 @@ export function AudioListener({ engine }) {
     });
     return null;
 }
-function useTrackedEmitters(engine, soundByKey, entries) {
+function useTrackedEmitters(engine, soundByKey, readEntries) {
     const handles = useRef(new Map());
+    const lastPose = useRef(new Map());
     useEffect(() => () => {
         for (const handle of handles.current.values())
             handle.stop();
         handles.current.clear();
+        lastPose.current.clear();
     }, [engine]);
     useFrame(() => {
         if (soundByKey === undefined)
             return;
         const live = new Set();
-        for (const entry of entries) {
+        for (const entry of readEntries()) {
             const soundId = soundByKey[entry.key];
             if (soundId === undefined)
                 continue;
@@ -27,27 +29,42 @@ function useTrackedEmitters(engine, soundByKey, entries) {
             let handle = handles.current.get(entry.id);
             if (handle === undefined) {
                 handle = engine.playLoop(soundId, { x: entry.position[0], y: entry.position[1], z: entry.position[2] }) ?? undefined;
-                if (handle !== undefined)
+                if (handle !== undefined) {
                     handles.current.set(entry.id, handle);
+                    lastPose.current.set(entry.id, entry.position);
+                }
+                continue;
+            }
+            const prev = lastPose.current.get(entry.id);
+            if (prev !== undefined &&
+                prev[0] === entry.position[0] &&
+                prev[1] === entry.position[1] &&
+                prev[2] === entry.position[2]) {
                 continue;
             }
             handle.setPosition({ x: entry.position[0], y: entry.position[1], z: entry.position[2] });
+            lastPose.current.set(entry.id, entry.position);
         }
         for (const [id, handle] of handles.current) {
             if (!live.has(id)) {
                 handle.stop();
                 handles.current.delete(id);
+                lastPose.current.delete(id);
             }
         }
     });
 }
 export function EntityAudioEmitters({ engine, entitySounds, }) {
-    const entities = useSceneEntities();
-    useTrackedEmitters(engine, entitySounds, entities.map((entity) => ({ id: entity.id, key: entity.name, position: entity.position })));
+    const ctx = useGameContext();
+    useTrackedEmitters(engine, entitySounds, () => ctx.scene.entity.list().map((entity) => ({ id: entity.id, key: entity.name, position: entity.position })));
     return null;
 }
 export function ObjectAudioEmitters({ engine, objectSounds, }) {
-    const objects = useSceneObjects();
-    useTrackedEmitters(engine, objectSounds, objects.map((object) => ({ id: object.instanceId, key: object.catalogId, position: object.position })));
+    const ctx = useGameContext();
+    useTrackedEmitters(engine, objectSounds, () => ctx.scene.object.list().map((object) => ({
+        id: object.instanceId,
+        key: object.catalogId,
+        position: object.position,
+    })));
     return null;
 }

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,7 +22,10 @@ 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;
     dispose(): void;
 }

package/dist/audio/audioEngine.js

@@ -1,10 +1,14 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+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,
         dispose: () => undefined,
     };
@@ -42,6 +46,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);
@@ -61,6 +80,15 @@ export function createAudioEngine(config = {}) {
             return null;
         const bus = busGainNode(sound.bus);
         let currentPosition = position ?? listenerPosition;
+        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;
         let gainNode = null;
         let stopped = false;
         void loadBuffer(sound.url).then((buffer) => {
@@ -92,18 +120,27 @@ export function createAudioEngine(config = {}) {
             listenerPosition = position;
         },
         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;
         },
+        setMasterGain(gain) {
+            masterGain.gain.value = gain;
+        },
         resume() {
             void context.resume().catch(() => undefined);
         },
         dispose() {
+            director?.dispose();
             void context.close().catch(() => undefined);
         },
     };

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 {};