@umicat/three-sdk 0.11.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,6 +55,10 @@ 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;
@@ -82,7 +86,43 @@ export declare 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(): 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;

package/dist/GameAudio.js

@@ -35,6 +35,8 @@
  */
 export class GameAudio {
     constructor(opts) {
+        this.loading = null;
+        this.pending = null;
         this.ctx = null;
         this.master = null;
         this.musicGain = null;
@@ -81,34 +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);
-            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
         // 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) {
@@ -175,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;
@@ -266,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.11.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",