@umicat/three-sdk 0.12.0 → 0.14.0

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))
@@ -406,10 +409,9 @@ export class Input3D {
             transform: 'translate(-50%, -50%)', pointerEvents: 'none',
         });
         pad.appendChild(knob);
-        // ONE cluster holds every button, laid out by flexbox, because the bug this
-        // replaces was two buttons independently choosing "bottom right" and
-        // landing on top of each other. Jump sits at the corner where it always
-        // was; actions stack to its left and wrap upward.
+        // ONE cluster holds every button, because the bug this replaces was two of
+        // them independently choosing "bottom right" and landing on top of each
+        // other. What it does with them is `layOnArc` below.
         const cluster = document.createElement('div');
         Object.assign(cluster.style, {
             position: 'absolute', right: '6vmin', bottom: '7vmin',
@@ -417,6 +419,53 @@ export class Input3D {
             flexWrap: 'wrap-reverse', justifyContent: 'flex-start',
             gap: '3vmin', maxWidth: '52vmin', pointerEvents: 'none',
         });
+        /**
+         * Put the buttons on the arc a THUMB actually sweeps.
+         *
+         * They were a wrapping flex row, which is how they ended up in a straight
+         * line across the bottom of the screen the moment a game had exactly two —
+         * the third button had been the only thing forcing a wrap, so removing it
+         * silently changed the layout of the two that were left. A row is also the
+         * wrong shape regardless: a thumb is hinged at the bottom corner and moves
+         * on an arc around it, so buttons at the same HEIGHT are at different
+         * reaches, and the far one is the one that gets missed.
+         *
+         * So: a quarter circle centred on the corner. Index 0 sits low and to the
+         * left, and each one after it steps up and in toward the edge, every one of
+         * them the same distance from the thumb's hinge.
+         *
+         * The radius is DERIVED, not chosen: neighbours must be at least a button
+         * apart along the chord, so a wider sweep — which is what more buttons
+         * need — pushes the arc out. Past three the radius it asks for has the
+         * buttons halfway up the screen, so the old wrapping row is kept for that
+         * case rather than pretending an arc still fits.
+         */
+        const layOnArc = (els) => {
+            const S = 20; // vmin — the button size, below
+            const [A0, A1] = [16, 74]; // degrees, the comfortable sweep
+            if (els.length > 3)
+                return; // the flex row stays as it is
+            const step = els.length > 1 ? (A1 - A0) / (els.length - 1) : 0;
+            // Chord between neighbours = 2R·sin(step/2), and it may not be smaller
+            // than a button plus a little air.
+            const need = els.length > 1 ? (S * 1.12) / (2 * Math.sin((step * Math.PI) / 360)) : S * 1.3;
+            const R = Math.max(S * 1.3, need);
+            cluster.style.display = 'block';
+            cluster.style.width = '0';
+            cluster.style.height = '0';
+            els.forEach((el, i) => {
+                const t = ((A0 + step * i) * Math.PI) / 180;
+                // From the corner, in vmin, then back off by half a button so the
+                // ARC passes through each button's middle rather than its corner.
+                const dx = (R * Math.cos(t)).toFixed(2);
+                const dy = (R * Math.sin(t)).toFixed(2);
+                Object.assign(el.style, {
+                    position: 'absolute',
+                    right: `calc(${dx}vmin - min(${S / 2}vmin, 60px))`,
+                    bottom: `calc(${dy}vmin - min(${S / 2}vmin, 60px))`,
+                });
+            });
+        };
         /** Returns the button; its glyph, if it has one, is left in `glyph`. */
         let glyph = null;
         const makeButton = (label, icon) => {
@@ -465,17 +514,33 @@ 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;
+        const made = [];
+        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);
+            made.push(el);
+            // 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);
         }
+        layOnArc(made);
         root.append(zone, lookZone, pad, cluster);
         container.appendChild(root);
         this.root = root;
@@ -613,13 +678,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.12.0",
+  "version": "0.14.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",