@umicat/three-sdk 0.10.0 → 0.11.0

package/dist/GameAudio.d.ts

@@ -58,6 +58,13 @@ export declare class GameAudio {
     private ctx;
     private master;
     private musicGain;
+    /** Everything that is not music, on its own knob.
+     *
+     *  Effects used to connect straight to the master, which made "quieter
+     *  music" and "quieter sound" the same lever — and they are the two things
+     *  players most want to set separately. Someone who wants the track down
+     *  wants to keep hearing what is shooting at them. */
+    private sfxGain;
     private musicEl;
     private musicName;
     private readonly buffers;
@@ -65,7 +72,10 @@ export declare class GameAudio {
     private readonly clips;
     private readonly base;
     private readonly ext;
-    private readonly musicVolume;
+    /** Not readonly any more: it is the top of the music's range and the level
+     *  `duck()` returns to, and both move when the player moves the slider. */
+    private musicVolume;
+    private sfxVolume;
     private muted;
     private readonly cleanups;
     constructor(opts: GameAudioOptions);
@@ -87,6 +97,19 @@ export declare class GameAudio {
     play(name: string): void;
     /** Duck the music for a moment — for an ending that should be heard over it. */
     duck(seconds?: number): void;
+    /**
+     * How loud the music is, 0 to 1, as a fraction of the mix it was given.
+     *
+     * Separate from mute, and both are kept: mute is a switch you flip on the way
+     * into a room and back on the way out, and losing the level you had set to
+     * find it back at 1 is a small betrayal. Muted, this still records what the
+     * player chose — unmuting restores it.
+     */
+    setMusicVolume(v: number): void;
+    get musicLevel(): number;
+    /** How loud everything that is not music is, 0 to 1. */
+    setSfxVolume(v: number): void;
+    get sfxLevel(): number;
     setMuted(on: boolean): void;
     get isMuted(): boolean;
     dispose(): void;

package/dist/GameAudio.js

@@ -38,10 +38,18 @@ export class GameAudio {
         this.ctx = null;
         this.master = null;
         this.musicGain = null;
+        /** Everything that is not music, on its own knob.
+         *
+         *  Effects used to connect straight to the master, which made "quieter
+         *  music" and "quieter sound" the same lever — and they are the two things
+         *  players most want to set separately. Someone who wants the track down
+         *  wants to keep hearing what is shooting at them. */
+        this.sfxGain = null;
         this.musicEl = null;
         this.musicName = null;
         this.buffers = new Map();
         this.lastPlayed = new Map();
+        this.sfxVolume = 1;
         this.muted = false;
         this.cleanups = [];
         this.clips = opts.clips;
@@ -88,6 +96,9 @@ export class GameAudio {
             this.musicGain = this.ctx.createGain();
             this.musicGain.gain.value = this.musicVolume;
             this.musicGain.connect(this.master);
+            this.sfxGain = this.ctx.createGain();
+            this.sfxGain.gain.value = this.sfxVolume;
+            this.sfxGain.connect(this.master);
             void this.loadAll();
         }
         // Called inside the gesture's call stack, and awaited before anything asks
@@ -180,7 +191,10 @@ export class GameAudio {
         const g = ctx.createGain();
         g.gain.value = spec?.volume ?? 0.5;
         src.connect(g);
-        g.connect(this.master);
+        // Through the effects knob, not straight to the master. The clip's own
+        // `volume` is still its balance against the others; this is the player's
+        // opinion about all of them at once.
+        g.connect(this.sfxGain ?? this.master);
         src.start();
         // Nodes disconnect themselves when they end; without this they pile up as
         // garbage the collector has to chase during play.
@@ -196,6 +210,40 @@ export class GameAudio {
         this.musicGain.gain.linearRampToValueAtTime(this.musicVolume * 0.25, t + 0.2);
         this.musicGain.gain.linearRampToValueAtTime(this.musicVolume, t + seconds);
     }
+    /**
+     * How loud the music is, 0 to 1, as a fraction of the mix it was given.
+     *
+     * Separate from mute, and both are kept: mute is a switch you flip on the way
+     * into a room and back on the way out, and losing the level you had set to
+     * find it back at 1 is a small betrayal. Muted, this still records what the
+     * player chose — unmuting restores it.
+     */
+    setMusicVolume(v) {
+        this.musicVolume = Math.max(0, Math.min(1, v));
+        if (this.musicGain && this.ctx) {
+            // Ramped, not assigned. A gain that jumps clicks, audibly, and a slider
+            // is a stream of tiny jumps.
+            this.musicGain.gain.setTargetAtTime(this.musicVolume, this.ctx.currentTime, 0.02);
+        }
+        // The fallback path, where the element could not be routed through the
+        // graph. Without this, the slider does nothing at all on those engines —
+        // and they are the ones nobody tests on.
+        if (this.musicEl && this.musicEl.volume !== undefined) {
+            try {
+                this.musicEl.volume = this.musicVolume;
+            }
+            catch { /* not fatal */ }
+        }
+    }
+    get musicLevel() { return this.musicVolume; }
+    /** How loud everything that is not music is, 0 to 1. */
+    setSfxVolume(v) {
+        this.sfxVolume = Math.max(0, Math.min(1, v));
+        if (this.sfxGain && this.ctx) {
+            this.sfxGain.gain.setTargetAtTime(this.sfxVolume, this.ctx.currentTime, 0.02);
+        }
+    }
+    get sfxLevel() { return this.sfxVolume; }
     setMuted(on) {
         this.muted = on;
         if (this.master && this.ctx) {

package/package.json

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