@umicat/three-sdk 0.8.5 → 0.9.1

package/dist/GameAudio.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Sound for a web game, through Web Audio.
+ *
+ * This is a platform capability rather than something each game writes,
+ * because getting it wrong is invisible in every place a creator would look.
+ * Four traps, all of them found the expensive way:
+ *
+ * **1. Never use `HTMLAudioElement` for game sound.** iOS gives each element a
+ * real audio pipeline, caps how many may exist, and charges for every
+ * `play()`. A game pooling about forty of them ran at 11fps on an iPhone and
+ * a locked 60 with the sound muted — while a desktop A/B showed no difference
+ * at all. Web Audio decodes each clip once into a buffer; playing one
+ * allocates a source node the browser throws away, and overlap is free.
+ *
+ * **2. The context starts suspended.** Browsers block audio until a gesture and
+ * iOS is strictest. A SYNTHETIC click does not count, which is how a
+ * measurement run can end up testing the muted case and reporting silence as
+ * success.
+ *
+ * **3. `resume()` is asynchronous.** Reading `ctx.state` on the next line finds
+ * 'suspended' and a cached "unlocked" flag stays false forever — the game is
+ * silent no matter how many times it is tapped. Readiness is derived here, not
+ * stored.
+ *
+ * **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 {
+    /** 0-1, balanced by ear against the music. */
+    volume?: number;
+    /** Minimum gap between retriggers, in ms. Four towers reloading together
+     *  turn one thwip into a buzz; a few tens of milliseconds fixes it and
+     *  nobody notices a dropped shot. */
+    throttle?: number;
+}
+export interface GameAudioOptions {
+    /** Clip name → how to play it. Names map to `${base}${name}${extension}`. */
+    clips: Record<string, AudioClipSpec>;
+    /** Where the files live, relative to the game. */
+    base?: string;
+    /** File extension, including the dot. */
+    extension?: string;
+    /** 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;
+}
+export declare class GameAudio {
+    private ctx;
+    private master;
+    private musicGain;
+    private musicEl;
+    private musicName;
+    private readonly buffers;
+    private readonly lastPlayed;
+    private readonly clips;
+    private readonly base;
+    private readonly ext;
+    private readonly musicVolume;
+    private muted;
+    private readonly cleanups;
+    constructor(opts: GameAudioOptions);
+    /** Whether sound can be heard right now. Asked of the context every time —
+     *  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;
+    setMuted(on: boolean): void;
+    get isMuted(): boolean;
+    dispose(): void;
+}

package/dist/GameAudio.js

@@ -0,0 +1,220 @@
+/**
+ * Sound for a web game, through Web Audio.
+ *
+ * This is a platform capability rather than something each game writes,
+ * because getting it wrong is invisible in every place a creator would look.
+ * Four traps, all of them found the expensive way:
+ *
+ * **1. Never use `HTMLAudioElement` for game sound.** iOS gives each element a
+ * real audio pipeline, caps how many may exist, and charges for every
+ * `play()`. A game pooling about forty of them ran at 11fps on an iPhone and
+ * a locked 60 with the sound muted — while a desktop A/B showed no difference
+ * at all. Web Audio decodes each clip once into a buffer; playing one
+ * allocates a source node the browser throws away, and overlap is free.
+ *
+ * **2. The context starts suspended.** Browsers block audio until a gesture and
+ * iOS is strictest. A SYNTHETIC click does not count, which is how a
+ * measurement run can end up testing the muted case and reporting silence as
+ * success.
+ *
+ * **3. `resume()` is asynchronous.** Reading `ctx.state` on the next line finds
+ * 'suspended' and a cached "unlocked" flag stays false forever — the game is
+ * silent no matter how many times it is tapped. Readiness is derived here, not
+ * stored.
+ *
+ * **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 {
+    constructor(opts) {
+        this.ctx = null;
+        this.master = null;
+        this.musicGain = null;
+        this.musicEl = null;
+        this.musicName = null;
+        this.buffers = new Map();
+        this.lastPlayed = new Map();
+        this.muted = false;
+        this.cleanups = [];
+        this.clips = opts.clips;
+        this.base = opts.base ?? 'audio/';
+        this.ext = opts.extension ?? '.ogg';
+        this.musicName = opts.music ?? null;
+        this.musicVolume = opts.musicVolume ?? 0.28;
+        const unlock = () => {
+            void this.start().then(() => {
+                if (!this.ready)
+                    return;
+                for (const ev of ['pointerdown', 'keydown', 'touchstart'])
+                    window.removeEventListener(ev, unlock);
+            });
+        };
+        for (const ev of ['pointerdown', 'keydown', 'touchstart'])
+            window.addEventListener(ev, unlock);
+        this.cleanups.push(() => {
+            for (const ev of ['pointerdown', 'keydown', 'touchstart'])
+                window.removeEventListener(ev, unlock);
+        });
+        const onVisible = () => {
+            if (!document.hidden && this.ctx?.state === 'suspended')
+                void this.ctx.resume();
+        };
+        document.addEventListener('visibilitychange', onVisible);
+        this.cleanups.push(() => document.removeEventListener('visibilitychange', onVisible));
+    }
+    /** Whether sound can be heard right now. Asked of the context every time —
+     *  a cached flag is exactly the bug described above. */
+    get ready() { return this.ctx?.state === 'running'; }
+    async start() {
+        if (this.ready)
+            return;
+        const AC = window.AudioContext
+            ?? window.webkitAudioContext;
+        if (!AC)
+            return;
+        if (!this.ctx) {
+            this.ctx = new AC();
+            this.master = this.ctx.createGain();
+            this.master.gain.value = this.muted ? 0 : 1;
+            this.master.connect(this.ctx.destination);
+            this.musicGain = this.ctx.createGain();
+            this.musicGain.gain.value = this.musicVolume;
+            this.musicGain.connect(this.master);
+            void this.loadAll();
+        }
+        // Called inside the gesture's call stack, and awaited before anything asks
+        // whether it worked.
+        try {
+            await this.ctx.resume();
+        }
+        catch { /* a blocked context is not fatal */ }
+        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.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);
+            }
+            catch {
+                /* a clip that will not decode is not worth taking the game down for */
+            }
+        };
+        // 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.
+        await Promise.all(Object.keys(this.clips).map(load));
+    }
+    startMusic() {
+        if (!this.ctx || !this.musicGain || this.muted || !this.musicName)
+            return;
+        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;
+        if (this.muted || !this.ready || !ctx || !this.master)
+            return;
+        const buf = this.buffers.get(name);
+        if (!buf)
+            return;
+        const spec = this.clips[name];
+        const now = performance.now();
+        const gap = spec?.throttle ?? 0;
+        if (gap && now - (this.lastPlayed.get(name) ?? -1e9) < gap)
+            return;
+        this.lastPlayed.set(name, now);
+        const src = ctx.createBufferSource();
+        src.buffer = buf;
+        const g = ctx.createGain();
+        g.gain.value = spec?.volume ?? 0.5;
+        src.connect(g);
+        g.connect(this.master);
+        src.start();
+        // Nodes disconnect themselves when they end; without this they pile up as
+        // garbage the collector has to chase during play.
+        src.onended = () => { src.disconnect(); g.disconnect(); };
+    }
+    /** Duck the music for a moment — for an ending that should be heard over it. */
+    duck(seconds = 3) {
+        if (!this.ctx || !this.musicGain)
+            return;
+        const t = this.ctx.currentTime;
+        this.musicGain.gain.cancelScheduledValues(t);
+        this.musicGain.gain.setValueAtTime(this.musicGain.gain.value, t);
+        this.musicGain.gain.linearRampToValueAtTime(this.musicVolume * 0.25, t + 0.2);
+        this.musicGain.gain.linearRampToValueAtTime(this.musicVolume, t + seconds);
+    }
+    setMuted(on) {
+        this.muted = on;
+        if (this.master && this.ctx) {
+            this.master.gain.setTargetAtTime(on ? 0 : 1, this.ctx.currentTime, 0.02);
+        }
+        // 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; }
+    dispose() {
+        for (const c of this.cleanups)
+            c();
+        this.cleanups.length = 0;
+        this.musicEl?.pause();
+        void this.ctx?.close();
+        this.ctx = null;
+    }
+}

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { Input3D } from './Input3D.js';
 export type { Input3DOptions, Input3DAction } from './Input3D.js';
 export { attachToSocket, findBone, boneNames } from './Sockets.js';
 export { flashTint, updateTints, isTinted } from './Tint.js';
+export { GameAudio } from './GameAudio.js';
+export type { GameAudioOptions, AudioClipSpec } from './GameAudio.js';
 export type { Attachment } from './Sockets.js';
 export type { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';
 export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { CharacterAnimator } from './CharacterAnimator.js';
 export { Input3D } from './Input3D.js';
 export { attachToSocket, findBone, boneNames } from './Sockets.js';
 export { flashTint, updateTints, isTinted } from './Tint.js';
+export { GameAudio } from './GameAudio.js';
 // Re-exported so a game imports one package for the common case. A game should
 // not have to know that identity and saves come from a different package than
 // the renderer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.8.5",
+  "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",