@umicat/three-sdk 0.9.0 → 0.9.1

package/dist/GameAudio.d.ts

@@ -25,6 +25,12 @@
  * **4. iOS suspends the context when the app goes away** and does not bring it
  * back, so sound works until the first phone call and then never again.
  *
+ * Music is the one exception to rule 1, and for the same reason rule 1 exists.
+ * A three-minute track decodes to something like seventy megabytes of PCM;
+ * forty short effects as elements was fatal, but ONE element playing one long
+ * thing is exactly what elements are for. So effects are buffers and music
+ * streams, routed through the same graph so ducking still works.
+ *
  * The game brings its own clips; nothing here knows what a game sounds like.
  */
 export interface AudioClipSpec {
@@ -42,8 +48,9 @@ export interface GameAudioOptions {
     base?: string;
     /** File extension, including the dot. */
     extension?: string;
-    /** A clip to loop as music. Loaded first, so the theme is not queued behind
-     *  every sound effect. */
+    /** A track to loop as music. Streamed, not decoded — see the note above.
+     *  A name containing a dot is used as-is, so `'theme.mp3'` works alongside
+     *  `.ogg` effects. */
     music?: string;
     musicVolume?: number;
 }
@@ -51,13 +58,13 @@ export declare class GameAudio {
     private ctx;
     private master;
     private musicGain;
-    private musicSource;
+    private musicEl;
+    private musicName;
     private readonly buffers;
     private readonly lastPlayed;
     private readonly clips;
     private readonly base;
     private readonly ext;
-    private readonly music?;
     private readonly musicVolume;
     private muted;
     private readonly cleanups;
@@ -66,8 +73,17 @@ export declare class GameAudio {
      *  a cached flag is exactly the bug described above. */
     get ready(): boolean;
     private start;
+    /** `'theme.mp3'` stays as it is; `'coin'` becomes `coin.ogg`. */
+    private urlFor;
     private loadAll;
     private startMusic;
+    /**
+     * Change the track. Pass `null` for silence.
+     *
+     * Each scene gets its own: a lobby that sounds like the fight is a lobby you
+     * do not linger in.
+     */
+    setMusic(name: string | null): void;
     play(name: string): void;
     /** Duck the music for a moment — for an ending that should be heard over it. */
     duck(seconds?: number): void;

package/dist/GameAudio.js

@@ -25,6 +25,12 @@
  * **4. iOS suspends the context when the app goes away** and does not bring it
  * back, so sound works until the first phone call and then never again.
  *
+ * Music is the one exception to rule 1, and for the same reason rule 1 exists.
+ * A three-minute track decodes to something like seventy megabytes of PCM;
+ * forty short effects as elements was fatal, but ONE element playing one long
+ * thing is exactly what elements are for. So effects are buffers and music
+ * streams, routed through the same graph so ducking still works.
+ *
  * The game brings its own clips; nothing here knows what a game sounds like.
  */
 export class GameAudio {
@@ -32,7 +38,8 @@ export class GameAudio {
         this.ctx = null;
         this.master = null;
         this.musicGain = null;
-        this.musicSource = null;
+        this.musicEl = null;
+        this.musicName = null;
         this.buffers = new Map();
         this.lastPlayed = new Map();
         this.muted = false;
@@ -40,7 +47,7 @@ export class GameAudio {
         this.clips = opts.clips;
         this.base = opts.base ?? 'audio/';
         this.ext = opts.extension ?? '.ogg';
-        this.music = opts.music;
+        this.musicName = opts.music ?? null;
         this.musicVolume = opts.musicVolume ?? 0.28;
         const unlock = () => {
             void this.start().then(() => {
@@ -92,42 +99,68 @@ export class GameAudio {
         if (this.ready)
             this.startMusic();
     }
+    /** `'theme.mp3'` stays as it is; `'coin'` becomes `coin.ogg`. */
+    urlFor(name) {
+        return `${this.base}${name}${name.includes('.') ? '' : this.ext}`;
+    }
     async loadAll() {
         const load = async (name) => {
             try {
-                const res = await fetch(`${this.base}${name}${this.ext}`);
+                const res = await fetch(this.urlFor(name));
                 const bytes = await res.arrayBuffer();
                 const buf = await this.ctx.decodeAudioData(bytes);
                 // Tagged so a test can see WHICH clip played — a buffer has no name,
                 // and "some audio happened" is not a check.
                 buf.__name = name;
                 this.buffers.set(name, buf);
-                if (name === this.music && this.ready && !this.musicSource)
-                    this.startMusic();
             }
             catch {
                 /* a clip that will not decode is not worth taking the game down for */
             }
         };
-        // Music first, then everything else at once. One at a time queued the theme
-        // behind every effect and left the first actions silent — caution about
+        // All at once. One at a time left the first actions silent — caution about
         // decode cost, for work that is not on the main thread.
-        if (this.music)
-            await load(this.music);
         await Promise.all(Object.keys(this.clips).map(load));
     }
     startMusic() {
-        if (!this.ctx || !this.musicGain || this.musicSource || this.muted || !this.music)
+        if (!this.ctx || !this.musicGain || this.muted || !this.musicName)
             return;
-        const buf = this.buffers.get(this.music);
-        if (!buf)
-            return; // still decoding; loadAll calls back
-        const src = this.ctx.createBufferSource();
-        src.buffer = buf;
-        src.loop = true;
-        src.connect(this.musicGain);
-        src.start();
-        this.musicSource = src;
+        if (!this.musicEl) {
+            const el = new Audio(this.urlFor(this.musicName));
+            el.loop = true;
+            el.preload = 'auto';
+            el.crossOrigin = 'anonymous';
+            // Routed through the graph, not played on its own, so `duck()` and the
+            // master gain reach it like everything else.
+            try {
+                this.ctx.createMediaElementSource(el).connect(this.musicGain);
+            }
+            catch {
+                // Some engines refuse to route an element they consider tainted. Fall
+                // back to playing it directly rather than losing the music entirely.
+                el.volume = this.musicVolume;
+            }
+            this.musicEl = el;
+        }
+        void this.musicEl.play().catch(() => { });
+    }
+    /**
+     * Change the track. Pass `null` for silence.
+     *
+     * Each scene gets its own: a lobby that sounds like the fight is a lobby you
+     * do not linger in.
+     */
+    setMusic(name) {
+        if (name === this.musicName)
+            return;
+        this.musicName = name;
+        if (this.musicEl) {
+            this.musicEl.pause();
+            this.musicEl.src = '';
+            this.musicEl = null; // a new element: the old one's graph node is spent
+        }
+        if (name && this.ready && !this.muted)
+            this.startMusic();
     }
     play(name) {
         const ctx = this.ctx;
@@ -168,7 +201,11 @@ export class GameAudio {
         if (this.master && this.ctx) {
             this.master.gain.setTargetAtTime(on ? 0 : 1, this.ctx.currentTime, 0.02);
         }
-        if (!on && this.ready)
+        // Pause the stream as well as silencing it: a muted track still costs a
+        // decoder and a download for something nobody can hear.
+        if (on)
+            this.musicEl?.pause();
+        else if (this.ready)
             this.startMusic();
     }
     get isMuted() { return this.muted; }
@@ -176,7 +213,7 @@ export class GameAudio {
         for (const c of this.cleanups)
             c();
         this.cleanups.length = 0;
-        this.musicSource?.stop();
+        this.musicEl?.pause();
         void this.ctx?.close();
         this.ctx = null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
   "type": "module",
   "main": "dist/index.js",