@umicat/three-sdk 0.8.5 → 0.9.0

package/dist/GameAudio.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ *
+ * 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 clip to loop as music. Loaded first, so the theme is not queued behind
+     *  every sound effect. */
+    music?: string;
+    musicVolume?: number;
+}
+export declare class GameAudio {
+    private ctx;
+    private master;
+    private musicGain;
+    private musicSource;
+    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;
+    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;
+    private loadAll;
+    private startMusic;
+    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,183 @@
+/**
+ * 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.
+ *
+ * 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.musicSource = 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.music = opts.music;
+        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();
+    }
+    async loadAll() {
+        const load = async (name) => {
+            try {
+                const res = await fetch(`${this.base}${name}${this.ext}`);
+                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
+        // 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)
+            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;
+    }
+    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);
+        }
+        if (!on && this.ready)
+            this.startMusic();
+    }
+    get isMuted() { return this.muted; }
+    dispose() {
+        for (const c of this.cleanups)
+            c();
+        this.cleanups.length = 0;
+        this.musicSource?.stop();
+        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.0",
   "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",