@umicat/three-sdk 0.9.1 → 0.10.0

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.1",
+  "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",