@umicat/three-sdk 0.10.0 → 0.12.0

package/README.md

@@ -3,15 +3,27 @@
 The three.js runtime for Umicat games, per ADR-033. Platform services come from
 `@umicat/platform-sdk` untouched; what lives here is the engine layer we own.
 
-**Status: seed, not a product.** It loads a scene, runs physics, and proves the
-platform seam. It has no editor, no input system, no character controller, no
-audio, and no published package. Nothing in production uses it.
+**Status: published and in use.** `@umicat/three-sdk` is on npm; Balaboo (a
+tower defence that ships from `woodland/`) is built on it, and `umicat-template-3d`
+is what new 3D projects start from.
+
+What it has: the scene3d format and loader, physics wiring, a character
+controller and animator, an input layer that mounts on-screen controls on touch
+devices and binds keys everywhere, bone sockets, hit tints, and audio. What it
+still does not have: an editor.
+
+> This paragraph said "seed, not a product — no input system, no character
+> controller, no audio, and no published package" for ten minor versions after
+> each of those arrived. A status line is the first thing anyone reads and the
+> last thing anyone updates.
 
 ```
 @umicat/platform-sdk        identity · saves · gameData · rooms · ai · voice · dialogue
         ▲                              (shared with @umicat/phaser-sdk)
         │
-@umicat/three-sdk       ThreeUmicat · scene3d format · loadScene3D · physics wiring
+@umicat/three-sdk       ThreeUmicat · scene3d · loadScene3D · physics · Input3D
+                        CharacterController3D · CharacterAnimator · GameAudio
+                        sockets · tints
         ▲
    your game            gameplay
 ```
@@ -31,6 +43,11 @@ mocked — every line of SDK is the shipped code.**
 | physics runs | a crate dropped from y=6 settles on the ground and does not fall through |
 | design mode is render-only | same entities, zero mixers, zero bodies |
 | authoring mistakes fail loudly | duplicate ids and missing clips throw at load, naming the clips that exist |
+| music and effects are two volumes | the clip's gain hangs off `sfxGain`, not the master — `audio-volume.test.mjs` |
+
+Eight suites, not one: the table above is the platform seam. The others cover
+the character controller, the animator, sockets, tints, input icons, the
+courtyard sample and the audio graph.
 
 `slice.png` is the scene those assertions describe, rendered.
 

package/dist/GameAudio.d.ts

@@ -55,9 +55,20 @@ export interface GameAudioOptions {
     musicVolume?: number;
 }
 export declare class GameAudio {
+    /** How long a sound asked for during the unlock may wait for the context. */
+    private static readonly PENDING_MS;
+    private loading;
+    private pending;
     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,14 +76,53 @@ 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);
     /** 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;
+    /**
+     * Build the graph and start fetching, WITHOUT asking to be heard.
+     *
+     * A context may be constructed and a buffer decoded while suspended; only
+     * `resume()` needs a gesture. Separating the two is what lets `preload()`
+     * do the slow half early.
+     */
+    private ensureContext;
+    /**
+     * Fetch and decode every clip now, before anything has been pressed.
+     *
+     * Without this the first gesture of a session does BOTH jobs — it creates
+     * the context and it starts the downloads — so a sound asked for on that
+     * gesture has no buffer to play and is silently dropped. The gesture in
+     * question is usually a title screen's only button, which is the one press
+     * every player makes.
+     *
+     * Safe to call at boot: nothing here needs permission, and on a browser that
+     * has not been touched yet the context simply stays suspended until it is.
+     * Awaiting it is optional — the point is to have started.
+     */
+    preload(): Promise<void>;
     private start;
+    /**
+     * A sound asked for DURING the unlocking gesture, played the moment the
+     * context comes up.
+     *
+     * `resume()` is asynchronous, so a `play()` made inside the gesture that
+     * unlocks audio always finds `ready` false — the press that turns the sound
+     * on is the one press that cannot make one. Holding the request for a beat
+     * and firing it on `ready` costs nothing and covers exactly that case.
+     *
+     * One request, not a queue, and only if it is still FRESH. A button's click
+     * arriving a second late is worse than no click at all, and replaying a
+     * backlog the moment audio comes up is how a game greets you with a chord.
+     */
+    private flushPending;
     /** `'theme.mp3'` stays as it is; `'coin'` becomes `coin.ogg`. */
     private urlFor;
     private loadAll;
@@ -87,6 +137,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

@@ -35,13 +35,23 @@
  */
 export class GameAudio {
     constructor(opts) {
+        this.loading = null;
+        this.pending = null;
         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;
@@ -73,31 +83,85 @@ export class GameAudio {
     /** 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;
+    /**
+     * Build the graph and start fetching, WITHOUT asking to be heard.
+     *
+     * A context may be constructed and a buffer decoded while suspended; only
+     * `resume()` needs a gesture. Separating the two is what lets `preload()`
+     * do the slow half early.
+     */
+    ensureContext() {
+        if (this.ctx)
+            return true;
         const AC = window.AudioContext
             ?? window.webkitAudioContext;
         if (!AC)
+            return false;
+        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);
+        this.sfxGain = this.ctx.createGain();
+        this.sfxGain.gain.value = this.sfxVolume;
+        this.sfxGain.connect(this.master);
+        this.loading ?? (this.loading = this.loadAll());
+        return true;
+    }
+    /**
+     * Fetch and decode every clip now, before anything has been pressed.
+     *
+     * Without this the first gesture of a session does BOTH jobs — it creates
+     * the context and it starts the downloads — so a sound asked for on that
+     * gesture has no buffer to play and is silently dropped. The gesture in
+     * question is usually a title screen's only button, which is the one press
+     * every player makes.
+     *
+     * Safe to call at boot: nothing here needs permission, and on a browser that
+     * has not been touched yet the context simply stays suspended until it is.
+     * Awaiting it is optional — the point is to have started.
+     */
+    async preload() {
+        if (!this.ensureContext())
+            return;
+        await (this.loading ?? (this.loading = this.loadAll()));
+    }
+    async start() {
+        if (this.ready)
+            return;
+        if (!this.ensureContext())
             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)
+        if (this.ready) {
             this.startMusic();
+            this.flushPending();
+        }
+    }
+    /**
+     * A sound asked for DURING the unlocking gesture, played the moment the
+     * context comes up.
+     *
+     * `resume()` is asynchronous, so a `play()` made inside the gesture that
+     * unlocks audio always finds `ready` false — the press that turns the sound
+     * on is the one press that cannot make one. Holding the request for a beat
+     * and firing it on `ready` costs nothing and covers exactly that case.
+     *
+     * One request, not a queue, and only if it is still FRESH. A button's click
+     * arriving a second late is worse than no click at all, and replaying a
+     * backlog the moment audio comes up is how a game greets you with a chord.
+     */
+    flushPending() {
+        const p = this.pending;
+        this.pending = null;
+        if (p && performance.now() - p.at < GameAudio.PENDING_MS)
+            this.play(p.name);
     }
     /** `'theme.mp3'` stays as it is; `'coin'` becomes `coin.ogg`. */
     urlFor(name) {
@@ -164,8 +228,14 @@ export class GameAudio {
     }
     play(name) {
         const ctx = this.ctx;
-        if (this.muted || !this.ready || !ctx || !this.master)
+        if (this.muted)
+            return;
+        if (!this.ready || !ctx || !this.master) {
+            // Not "drop it": this is the unlocking gesture, and the sound it asked
+            // for is the one the player is waiting to hear. `start()` plays it.
+            this.pending = { name, at: performance.now() };
             return;
+        }
         const buf = this.buffers.get(name);
         if (!buf)
             return;
@@ -180,7 +250,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 +269,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) {
@@ -218,3 +325,5 @@ export class GameAudio {
         this.ctx = null;
     }
 }
+/** How long a sound asked for during the unlock may wait for the context. */
+GameAudio.PENDING_MS = 400;

package/package.json

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