@umicat/three-sdk 0.12.0 → 0.13.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))
@@ -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.12.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",