@umicat/three-sdk 0.11.0 → 0.13.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/dist/Input3D.d.ts

@@ -27,9 +27,10 @@ export interface Input3DOptions {
     /** Where key events are read from. */
     target?: Window;
     /**
-     * On-screen thumbstick + jump button. `'auto'` (the default) adds them when
+     * On-screen thumbstick and buttons. `'auto'` (the default) adds them when
      * the device reports coarse pointers and no fine one — i.e. a phone, not a
-     * laptop with a touchscreen.
+     * laptop with a touchscreen. What the cluster CONTAINS is a separate
+     * question — see `jump` and `actions`.
      */
     touch?: boolean | 'auto';
     /**
@@ -52,6 +53,21 @@ export interface Input3DOptions {
     /** A shape for the JUMP button, in place of its `▲`. Same reasoning as
      *  `Input3DAction.icon`, for the one button the platform owns outright. */
     jumpIcon?: string;
+    /**
+     * Whether this game HAS a jump. Default `true`.
+     *
+     * Jumping is not universal — a game played by walking around a board does
+     * not want a jump button, and it was getting one anyway because the button
+     * came bundled with the thumbstick under `touch`. Turning `touch` off to be
+     * rid of it takes the stick with it, which is not a trade anyone would make.
+     *
+     * `false` removes the on-screen button AND makes `jump` permanently false,
+     * which also hands **`Space` back to the game**. Those two belong together:
+     * Space is read here as jump, so a game with no jump that binds Space to
+     * something of its own would otherwise have the hero hop every time the
+     * player used it.
+     */
+    jump?: boolean;
     /**
      * How the thumbstick behaves on touch.
      *
@@ -111,6 +127,8 @@ export declare class Input3D {
     private touchJump;
     private actions;
     private jumpIcon?;
+    /** Whether this game has a jump at all — see `Input3DOptions.jump`. */
+    private readonly hasJump;
     /** The glyph inside each on-screen button, by action id (`'jump'` for the
      *  platform's own). Kept so an icon can be CHANGED while the game runs —
      *  which is the point of it for anything the player switches: an attack

package/dist/Input3D.js

@@ -71,7 +71,7 @@ export class Input3D {
         this.onDown = (e) => {
             this.keysDown.add(e.code);
             if (!e.repeat) {
-                if (e.code === 'Space')
+                if (e.code === 'Space' && this.hasJump)
                     this.beginPress('jump');
                 for (const a of this.actions)
                     if (a.keys?.includes(e.code))
@@ -120,6 +120,7 @@ export class Input3D {
         this.target.addEventListener('blur', this.onBlur);
         this.actions = opts.actions ?? [];
         this.jumpIcon = opts.jumpIcon;
+        this.hasJump = opts.jump ?? true;
         this.stickMode = opts.stick ?? 'floating';
         this.wantLook = opts.look ?? true;
         this.topInset = opts.controlsTopInset ?? 'max(64px, 12%)';
@@ -206,6 +207,8 @@ export class Input3D {
     /** Whether the jump control is held right now. Pass it to the controller —
      *  coyote time and buffering live there, not here. */
     get jump() {
+        if (!this.hasJump)
+            return false;
         return this.enabled && this.held_('jump', this.touchJump || this.isDown('Space'));
     }
     /**
@@ -278,7 +281,7 @@ export class Input3D {
         if (this.keysDown.has(code))
             return; // held, not re-pressed
         this.keysDown.add(code);
-        if (code === 'Space')
+        if (code === 'Space' && this.hasJump)
             this.beginPress('jump');
         for (const a of this.actions)
             if (a.keys?.includes(code))
@@ -465,16 +468,29 @@ export class Input3D {
             return el;
         };
         this.glyphs.clear();
-        const btn = makeButton('▲', this.jumpIcon);
-        if (glyph)
-            this.glyphs.set('jump', glyph);
-        cluster.append(btn);
-        for (const a of this.actions) {
-            const el = makeButton(a.label ?? a.id.slice(0, 1).toUpperCase(), a.icon);
+        // ONE LIST, and the game decides what is in it.
+        //
+        // Jump used to be built here on its own, before the loop, which is what
+        // made it the one button a game could not decline — it arrived with the
+        // thumbstick whether the game had a jump or not. It is an entry in the
+        // list now, present unless `jump: false`, and everything after it is
+        // whatever the game declared. What this class owns is PLACING them.
+        const buttons = [
+            ...(this.hasJump ? [{ id: 'jump', label: '▲', icon: this.jumpIcon }] : []),
+            ...this.actions.map((a) => ({ id: a.id, label: a.label ?? a.id.slice(0, 1).toUpperCase(), icon: a.icon })),
+        ];
+        let jumpBtn = null;
+        for (const b of buttons) {
+            const el = makeButton(b.label, b.icon);
             if (glyph)
-                this.glyphs.set(a.id, glyph);
+                this.glyphs.set(b.id, glyph);
             cluster.append(el);
-            this.wireButton(el, a.id);
+            // Jump is the platform's own: its press is read through `get jump()`
+            // rather than through the action latch, so it is wired below instead.
+            if (b.id === 'jump')
+                jumpBtn = el;
+            else
+                this.wireButton(el, b.id);
         }
         root.append(zone, lookZone, pad, cluster);
         container.appendChild(root);
@@ -613,13 +629,16 @@ export class Input3D {
             on(grip, ev, (e) => { if (e.pointerId === stickId)
                 reset(); });
         }
-        on(btn, 'pointerdown', (e) => {
-            btn.setPointerCapture(e.pointerId);
-            this.touchJump = true;
-            this.beginPress('jump');
-        });
-        for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {
-            on(btn, ev, () => { this.touchJump = false; });
+        if (jumpBtn) {
+            const jb = jumpBtn;
+            on(jb, 'pointerdown', (e) => {
+                jb.setPointerCapture(e.pointerId);
+                this.touchJump = true;
+                this.beginPress('jump');
+            });
+            for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {
+                on(jb, ev, () => { this.touchJump = false; });
+            }
         }
     }
     wireButton(el, id) {

package/package.json

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