@umicat/three-sdk 0.8.2 → 0.8.4

package/dist/Input3D.d.ts

@@ -55,6 +55,17 @@ export interface Input3DOptions {
     /** Radians of camera rotation per screen-width dragged. Same number governs
      *  touch drags and desktop right-drags, so there is one knob to turn. */
     lookSensitivity?: number;
+    /**
+     * How much of the top of the screen the move and look zones leave alone.
+     *
+     * A HUD lives at the top — score, hearts, a mute button — and the zones are
+     * full-screen and sit ABOVE the game's DOM, so without this every button up
+     * there is unreachable on a phone while looking perfectly fine. Nobody
+     * drives a thumbstick from the top edge, so the trade is free.
+     *
+     * A CSS length; the default is `max(64px, 12%)`.
+     */
+    controlsTopInset?: string;
 }
 /**
  * Movement and jump, from a keyboard or a thumb, behind one interface.
@@ -82,8 +93,10 @@ export declare class Input3D {
     private actions;
     private stickMode;
     private wantLook;
+    private topInset;
     private lookSens;
     private readonly lookDelta;
+    private enabled;
     private readonly touchHeld;
     private readonly pressedAt;
     private readonly unconsumed;
@@ -91,6 +104,21 @@ export declare class Input3D {
     private readonly cleanups;
     constructor(options?: Input3DOptions | Window);
     isDown(...codes: string[]): boolean;
+    /**
+     * Stop accepting input, and take the on-screen controls off the screen.
+     *
+     * For the moment a game puts a modal up — a game-over screen, a shop, a
+     * dialogue box. Two things go wrong otherwise, and the second is worse: the
+     * character keeps walking behind the dialog, and the controls' full-screen
+     * layer sits ABOVE the game's own DOM at z-index 10, so the button in that
+     * modal cannot be tapped at all. "Play Again" that does nothing is this bug.
+     *
+     * Disabling clears what was held, so a thumb that was pushing the stick when
+     * the modal opened does not resume walking when it closes.
+     */
+    setEnabled(on: boolean): void;
+    /** Whether input is currently being accepted. */
+    get isEnabled(): boolean;
     /**
      * Which way to walk. Keyboard and stick are merged, so both work on a device
      * with both.

package/dist/Input3D.js

@@ -69,8 +69,10 @@ export class Input3D {
         this.actions = [];
         this.stickMode = 'floating';
         this.wantLook = true;
+        this.topInset = 'max(64px, 12%)';
         this.lookSens = 4.6;
         this.lookDelta = { x: 0, y: 0 };
+        this.enabled = true;
         this.touchHeld = new Set();
         this.pressedAt = new Map();
         this.unconsumed = new Set();
@@ -87,6 +89,7 @@ export class Input3D {
         this.actions = opts.actions ?? [];
         this.stickMode = opts.stick ?? 'floating';
         this.wantLook = opts.look ?? true;
+        this.topInset = opts.controlsTopInset ?? 'max(64px, 12%)';
         this.lookSens = opts.lookSensitivity ?? 4.6;
         if (this.wantLook && typeof document !== 'undefined') {
             this.mountMouseLook(opts.container?.ownerDocument ?? document);
@@ -96,7 +99,43 @@ export class Input3D {
             this.mountTouch(opts.container ?? document.body);
         }
     }
-    isDown(...codes) { return codes.some((c) => this.keysDown.has(c)); }
+    isDown(...codes) {
+        return this.enabled && codes.some((c) => this.keysDown.has(c));
+    }
+    /**
+     * Stop accepting input, and take the on-screen controls off the screen.
+     *
+     * For the moment a game puts a modal up — a game-over screen, a shop, a
+     * dialogue box. Two things go wrong otherwise, and the second is worse: the
+     * character keeps walking behind the dialog, and the controls' full-screen
+     * layer sits ABOVE the game's own DOM at z-index 10, so the button in that
+     * modal cannot be tapped at all. "Play Again" that does nothing is this bug.
+     *
+     * Disabling clears what was held, so a thumb that was pushing the stick when
+     * the modal opened does not resume walking when it closes.
+     */
+    setEnabled(on) {
+        this.enabled = on;
+        if (!on) {
+            this.keysDown.clear();
+            this.touchHeld.clear();
+            this.pressedAt.clear();
+            this.unconsumed.clear();
+            this.stick.x = 0;
+            this.stick.z = 0;
+            this.touchJump = false;
+            this.lookDelta.x = 0;
+            this.lookDelta.y = 0;
+        }
+        if (this.root) {
+            this.root.style.display = on ? '' : 'none';
+            // display:none alone would be enough for hit-testing, but a game that
+            // fades its modal in wants the controls gone, not just inert.
+            this.root.style.pointerEvents = 'none';
+        }
+    }
+    /** Whether input is currently being accepted. */
+    get isEnabled() { return this.enabled; }
     /**
      * Which way to walk. Keyboard and stick are merged, so both work on a device
      * with both.
@@ -109,6 +148,8 @@ export class Input3D {
      * behaviour, which is correct for a camera that never moves.
      */
     direction(cameraYaw = 0) {
+        if (!this.enabled)
+            return { x: 0, z: 0 };
         let x = this.stick.x, z = this.stick.z;
         if (this.isDown('KeyW', 'ArrowUp'))
             z -= 1;
@@ -131,9 +172,13 @@ 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() { return this.held_('jump', this.touchJump || this.isDown('Space')); }
+    get jump() {
+        return this.enabled && this.held_('jump', this.touchJump || this.isDown('Space'));
+    }
     /** Whether an action is held right now — button or bound key, same answer. */
     held(id) {
+        if (!this.enabled)
+            return false;
         const a = this.actions.find((x) => x.id === id);
         return this.held_(id, this.touchHeld.has(id) || (a?.keys ? this.isDown(...a.keys) : false));
     }
@@ -146,6 +191,8 @@ export class Input3D {
      * it twice must not apply it twice. Pass straight to `LoadedScene3D.orbit`.
      */
     look() {
+        if (!this.enabled)
+            return { x: 0, y: 0 };
         const out = { x: this.lookDelta.x, y: this.lookDelta.y };
         this.lookDelta.x = 0;
         this.lookDelta.y = 0;
@@ -157,7 +204,7 @@ export class Input3D {
      *  to last frame's, which means a press that begins and ends between two
      *  frames never happened. This latches at the event, so it cannot be missed
      *  — and it clears on read, so holding the button does not chain. */
-    consume(id) { return this.unconsumed.delete(id); }
+    consume(id) { return this.enabled && this.unconsumed.delete(id); }
     held_(id, physical) {
         if (physical)
             return true;
@@ -269,7 +316,7 @@ export class Input3D {
         // anything. It deliberately stops short of the buttons on the right.
         const zone = document.createElement('div');
         Object.assign(zone.style, {
-            position: 'absolute', left: '0', top: '0', width: '50%', height: '100%',
+            position: 'absolute', left: '0', top: this.topInset, width: '50%', bottom: '0',
             pointerEvents: floating ? 'auto' : 'none',
         });
         Object.assign(zone.style, NO_SELECTION);
@@ -278,7 +325,7 @@ export class Input3D {
         // can be the whole right half rather than an awkward cut-out around them.
         const lookZone = document.createElement('div');
         Object.assign(lookZone.style, {
-            position: 'absolute', right: '0', top: '0', width: '50%', height: '100%',
+            position: 'absolute', right: '0', top: this.topInset, width: '50%', bottom: '0',
             pointerEvents: this.wantLook ? 'auto' : 'none',
         });
         Object.assign(lookZone.style, NO_SELECTION);

package/package.json

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