@umicat/three-sdk 0.9.0 → 0.10.0

package/dist/GameAudio.d.ts

@@ -25,6 +25,12 @@
  * **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.
  *
+ * Music is the one exception to rule 1, and for the same reason rule 1 exists.
+ * A three-minute track decodes to something like seventy megabytes of PCM;
+ * forty short effects as elements was fatal, but ONE element playing one long
+ * thing is exactly what elements are for. So effects are buffers and music
+ * streams, routed through the same graph so ducking still works.
+ *
  * The game brings its own clips; nothing here knows what a game sounds like.
  */
 export interface AudioClipSpec {
@@ -42,8 +48,9 @@ export interface GameAudioOptions {
     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. */
+    /** A track to loop as music. Streamed, not decoded — see the note above.
+     *  A name containing a dot is used as-is, so `'theme.mp3'` works alongside
+     *  `.ogg` effects. */
     music?: string;
     musicVolume?: number;
 }
@@ -51,13 +58,13 @@ export declare class GameAudio {
     private ctx;
     private master;
     private musicGain;
-    private musicSource;
+    private musicEl;
+    private musicName;
     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;
@@ -66,8 +73,17 @@ export declare class GameAudio {
      *  a cached flag is exactly the bug described above. */
     get ready(): boolean;
     private start;
+    /** `'theme.mp3'` stays as it is; `'coin'` becomes `coin.ogg`. */
+    private urlFor;
     private loadAll;
     private startMusic;
+    /**
+     * Change the track. Pass `null` for silence.
+     *
+     * Each scene gets its own: a lobby that sounds like the fight is a lobby you
+     * do not linger in.
+     */
+    setMusic(name: string | null): void;
     play(name: string): void;
     /** Duck the music for a moment — for an ending that should be heard over it. */
     duck(seconds?: number): void;

package/dist/GameAudio.js

@@ -25,6 +25,12 @@
  * **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.
  *
+ * Music is the one exception to rule 1, and for the same reason rule 1 exists.
+ * A three-minute track decodes to something like seventy megabytes of PCM;
+ * forty short effects as elements was fatal, but ONE element playing one long
+ * thing is exactly what elements are for. So effects are buffers and music
+ * streams, routed through the same graph so ducking still works.
+ *
  * The game brings its own clips; nothing here knows what a game sounds like.
  */
 export class GameAudio {
@@ -32,7 +38,8 @@ export class GameAudio {
         this.ctx = null;
         this.master = null;
         this.musicGain = null;
-        this.musicSource = null;
+        this.musicEl = null;
+        this.musicName = null;
         this.buffers = new Map();
         this.lastPlayed = new Map();
         this.muted = false;
@@ -40,7 +47,7 @@ export class GameAudio {
         this.clips = opts.clips;
         this.base = opts.base ?? 'audio/';
         this.ext = opts.extension ?? '.ogg';
-        this.music = opts.music;
+        this.musicName = opts.music ?? null;
         this.musicVolume = opts.musicVolume ?? 0.28;
         const unlock = () => {
             void this.start().then(() => {
@@ -92,42 +99,68 @@ export class GameAudio {
         if (this.ready)
             this.startMusic();
     }
+    /** `'theme.mp3'` stays as it is; `'coin'` becomes `coin.ogg`. */
+    urlFor(name) {
+        return `${this.base}${name}${name.includes('.') ? '' : this.ext}`;
+    }
     async loadAll() {
         const load = async (name) => {
             try {
-                const res = await fetch(`${this.base}${name}${this.ext}`);
+                const res = await fetch(this.urlFor(name));
                 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
+        // All at once. One at a time 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)
+        if (!this.ctx || !this.musicGain || this.muted || !this.musicName)
             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;
+        if (!this.musicEl) {
+            const el = new Audio(this.urlFor(this.musicName));
+            el.loop = true;
+            el.preload = 'auto';
+            el.crossOrigin = 'anonymous';
+            // Routed through the graph, not played on its own, so `duck()` and the
+            // master gain reach it like everything else.
+            try {
+                this.ctx.createMediaElementSource(el).connect(this.musicGain);
+            }
+            catch {
+                // Some engines refuse to route an element they consider tainted. Fall
+                // back to playing it directly rather than losing the music entirely.
+                el.volume = this.musicVolume;
+            }
+            this.musicEl = el;
+        }
+        void this.musicEl.play().catch(() => { });
+    }
+    /**
+     * Change the track. Pass `null` for silence.
+     *
+     * Each scene gets its own: a lobby that sounds like the fight is a lobby you
+     * do not linger in.
+     */
+    setMusic(name) {
+        if (name === this.musicName)
+            return;
+        this.musicName = name;
+        if (this.musicEl) {
+            this.musicEl.pause();
+            this.musicEl.src = '';
+            this.musicEl = null; // a new element: the old one's graph node is spent
+        }
+        if (name && this.ready && !this.muted)
+            this.startMusic();
     }
     play(name) {
         const ctx = this.ctx;
@@ -168,7 +201,11 @@ export class GameAudio {
         if (this.master && this.ctx) {
             this.master.gain.setTargetAtTime(on ? 0 : 1, this.ctx.currentTime, 0.02);
         }
-        if (!on && this.ready)
+        // Pause the stream as well as silencing it: a muted track still costs a
+        // decoder and a download for something nobody can hear.
+        if (on)
+            this.musicEl?.pause();
+        else if (this.ready)
             this.startMusic();
     }
     get isMuted() { return this.muted; }
@@ -176,7 +213,7 @@ export class GameAudio {
         for (const c of this.cleanups)
             c();
         this.cleanups.length = 0;
-        this.musicSource?.stop();
+        this.musicEl?.pause();
         void this.ctx?.close();
         this.ctx = null;
     }

package/dist/Input3D.d.ts

@@ -2,8 +2,24 @@
 export interface Input3DAction {
     /** What the game calls it: `input.held('attack')`, `input.consume('attack')`. */
     id: string;
-    /** What the button shows. Keep it one glyph. */
+    /** What the button shows, as text. Keep it one glyph. Ignored when `icon`
+     *  is given. */
     label?: string;
+    /**
+     * What the button shows, as a SHAPE: the URL of a single-colour SVG or PNG.
+     *
+     *  Preferred over `label`, and the reason is not decoration. A label is text,
+     *  and text on this layer has three problems that only show up on a device:
+     *  an emoji is a different picture in every platform's font, text can be
+     *  SELECTED (long-pressing a game's attack button is how the iOS Copy / Look
+     *  Up / Translate callout comes up mid-fight), and it cannot take the
+     *  button's colour, so a glyph can never match the controls drawn beside it.
+     *
+     *  Drawn as a CSS mask, so the file's own colour is discarded and the shape
+     *  is painted in the button's — which means one icon keeps matching if the
+     *  control layer is ever restyled.
+     */
+    icon?: string;
     /** Keyboard equivalents, e.g. `['KeyJ']`. */
     keys?: string[];
 }
@@ -33,6 +49,9 @@ export interface Input3DOptions {
      * platform places the controls, so the platform has to place ALL of them.
      */
     actions?: Input3DAction[];
+    /** 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;
     /**
      * How the thumbstick behaves on touch.
      *
@@ -91,6 +110,13 @@ export declare class Input3D {
     private readonly stick;
     private touchJump;
     private actions;
+    private jumpIcon?;
+    /** 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
+     *  button that still shows a sword while you are holding a bow is a button
+     *  that is lying about what it does. */
+    private glyphs;
     private stickMode;
     private wantLook;
     private topInset;
@@ -137,6 +163,18 @@ export declare 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(): boolean;
+    /**
+     * Change what a button SHOWS, without rebuilding the controls.
+     *
+     * `id` is an action's id, or `'jump'` for the platform's own button. Passing
+     * a url the button had no icon for at build time does nothing: the glyph is
+     * an element that only exists when one was given, and quietly growing one
+     * would move the label out from under a game that was relying on it.
+     *
+     * This is for buttons whose MEANING changes — an attack button under a bow
+     * and under a staff are two different actions wearing one control.
+     */
+    setActionIcon(id: string, icon: string): void;
     /** Whether an action is held right now — button or bound key, same answer. */
     held(id: string): boolean;
     /**

package/dist/Input3D.js

@@ -1,3 +1,29 @@
+/**
+ * The control layer's palette.
+ *
+ * A DARK translucent fill with a light rim, not a light fill. White-on-white
+ * is what the first version was, and over a bright board — snow, or this
+ * engine's default grass — the buttons washed out into the scene exactly when
+ * a thumb was looking for them. A dark disc reads against anything: bright
+ * scenes darken it into view, dark scenes leave the rim and the glyph doing
+ * the work.
+ *
+ * Deliberately neutral rather than themed. This layer belongs to the platform
+ * and sits over every game, so it cannot take a side about what colour a game
+ * is.
+ */
+const CONTROL = {
+    /** The disc under a thumb. */
+    fill: 'rgba(16,20,28,0.38)',
+    /** The rim, which is what actually makes it findable. */
+    rim: 'rgba(255,255,255,0.62)',
+    /** Glyphs and the stick's knob. */
+    ink: 'rgba(255,255,255,0.95)',
+    /** The stick's ring, a shade quieter than a button: it is a place to put a
+     *  thumb rather than a thing to press. */
+    padFill: 'rgba(16,20,28,0.30)',
+    padRim: 'rgba(255,255,255,0.45)',
+};
 /** How long a press stays readable, however briefly it was actually made.
  *
  *  A tap whose down and up both land between two frames is invisible to a
@@ -67,6 +93,12 @@ export class Input3D {
         this.stick = { x: 0, z: 0 };
         this.touchJump = false;
         this.actions = [];
+        /** 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
+         *  button that still shows a sword while you are holding a bow is a button
+         *  that is lying about what it does. */
+        this.glyphs = new Map();
         this.stickMode = 'floating';
         this.wantLook = true;
         this.topInset = 'max(64px, 12%)';
@@ -87,6 +119,7 @@ export class Input3D {
         // Losing focus mid-press would otherwise leave the character walking.
         this.target.addEventListener('blur', this.onBlur);
         this.actions = opts.actions ?? [];
+        this.jumpIcon = opts.jumpIcon;
         this.stickMode = opts.stick ?? 'floating';
         this.wantLook = opts.look ?? true;
         this.topInset = opts.controlsTopInset ?? 'max(64px, 12%)';
@@ -175,6 +208,25 @@ export class Input3D {
     get jump() {
         return this.enabled && this.held_('jump', this.touchJump || this.isDown('Space'));
     }
+    /**
+     * Change what a button SHOWS, without rebuilding the controls.
+     *
+     * `id` is an action's id, or `'jump'` for the platform's own button. Passing
+     * a url the button had no icon for at build time does nothing: the glyph is
+     * an element that only exists when one was given, and quietly growing one
+     * would move the label out from under a game that was relying on it.
+     *
+     * This is for buttons whose MEANING changes — an attack button under a bow
+     * and under a staff are two different actions wearing one control.
+     */
+    setActionIcon(id, icon) {
+        const g = this.glyphs.get(id);
+        if (!g)
+            return;
+        const u = `url("${icon}")`;
+        g.style.setProperty('mask-image', u);
+        g.style.setProperty('-webkit-mask-image', u);
+    }
     /** Whether an action is held right now — button or bound key, same answer. */
     held(id) {
         if (!this.enabled)
@@ -333,8 +385,8 @@ export class Input3D {
         Object.assign(pad.style, floating ? {
             position: 'absolute', width: '30vmin', height: '30vmin',
             maxWidth: '180px', maxHeight: '180px',
-            borderRadius: '50%', background: 'rgba(255,255,255,0.14)',
-            border: '2px solid rgba(255,255,255,0.35)',
+            borderRadius: '50%', background: CONTROL.padFill,
+            border: `2px solid ${CONTROL.padRim}`,
             // Never interactive when floating: the ZONE owns the pointer, and a pad
             // that also captured it would steal the very first move event as the
             // thumb crosses its edge.
@@ -344,13 +396,13 @@ export class Input3D {
         } : {
             position: 'absolute', left: '5vmin', bottom: '5vmin',
             width: '30vmin', height: '30vmin', maxWidth: '180px', maxHeight: '180px',
-            borderRadius: '50%', background: 'rgba(255,255,255,0.14)',
-            border: '2px solid rgba(255,255,255,0.35)', pointerEvents: 'auto',
+            borderRadius: '50%', background: CONTROL.padFill,
+            border: `2px solid ${CONTROL.padRim}`, pointerEvents: 'auto',
         });
         const knob = document.createElement('div');
         Object.assign(knob.style, {
             position: 'absolute', left: '50%', top: '50%', width: '40%', height: '40%',
-            borderRadius: '50%', background: 'rgba(255,255,255,0.55)',
+            borderRadius: '50%', background: CONTROL.ink,
             transform: 'translate(-50%, -50%)', pointerEvents: 'none',
         });
         pad.appendChild(knob);
@@ -365,28 +417,62 @@ export class Input3D {
             flexWrap: 'wrap-reverse', justifyContent: 'flex-start',
             gap: '3vmin', maxWidth: '52vmin', pointerEvents: 'none',
         });
-        const makeButton = (label) => {
+        /** Returns the button; its glyph, if it has one, is left in `glyph`. */
+        let glyph = null;
+        const makeButton = (label, icon) => {
+            glyph = null;
             const el = document.createElement('div');
             Object.assign(el.style, {
                 width: '20vmin', height: '20vmin', maxWidth: '120px', maxHeight: '120px',
                 flex: '0 0 auto',
-                borderRadius: '50%', background: 'rgba(255,255,255,0.2)',
-                border: '2px solid rgba(255,255,255,0.4)', pointerEvents: 'auto',
+                borderRadius: '50%', background: CONTROL.fill,
+                border: `2px solid ${CONTROL.rim}`, pointerEvents: 'auto',
                 display: 'flex', alignItems: 'center', justifyContent: 'center',
-                color: 'rgba(255,255,255,0.85)', font: '600 4vmin/1 system-ui, sans-serif',
+                color: CONTROL.ink, font: '600 4vmin/1 system-ui, sans-serif',
             });
-            el.textContent = label;
-            // Explicitly, not by inheritance. The label IS text -- a glyph in a div
-            // -- and long-pressing the attack button is how the iOS Copy / Look Up /
+            if (icon) {
+                // A MASK, not an <img>. The file's own colour is thrown away and the
+                // shape is painted in the button's `color`, so an icon keeps matching
+                // the controls beside it if those are ever restyled — and one file can
+                // serve a light layout and a dark one.
+                const g = document.createElement('span');
+                const u = `url("${icon}")`;
+                Object.assign(g.style, {
+                    width: '45%', height: '45%', display: 'block',
+                    backgroundColor: 'currentColor',
+                    webkitMask: `${u} center/contain no-repeat`,
+                    mask: `${u} center/contain no-repeat`,
+                });
+                // Safari still wants the prefixed longhands; the shorthand above is not
+                // enough there, and a mask that does not apply is a SOLID SQUARE rather
+                // than nothing — the most visible possible failure.
+                g.style.setProperty('-webkit-mask-image', u);
+                g.style.setProperty('-webkit-mask-size', 'contain');
+                g.style.setProperty('-webkit-mask-repeat', 'no-repeat');
+                g.style.setProperty('-webkit-mask-position', 'center');
+                el.append(g);
+                glyph = g;
+            }
+            else {
+                el.textContent = label;
+            }
+            // Explicitly, not by inheritance. A label IS text -- a glyph in a div --
+            // and long-pressing the attack button is how the iOS Copy / Look Up /
             // Translate callout came up mid-fight, with the selection handles
-            // clamped around the little crossed swords.
+            // clamped around the little crossed swords. Which is most of why `icon`
+            // exists.
             Object.assign(el.style, NO_SELECTION);
             return el;
         };
-        const btn = makeButton('▲');
+        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());
+            const el = makeButton(a.label ?? a.id.slice(0, 1).toUpperCase(), a.icon);
+            if (glyph)
+                this.glyphs.set(a.id, glyph);
             cluster.append(el);
             this.wireButton(el, a.id);
         }

package/package.json

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