@woosh/meep-engine 2.169.1 → 2.169.2

package/src/engine/input/devices/gamepad/GamepadHandle.js

@@ -1,6 +1,8 @@
 import Signal from "../../../../core/events/signal/Signal.js";
 import { InputDeviceSwitch } from "../InputDeviceSwitch.js";
 import { GamepadAxes } from "./GamepadAxes.js";
+import { gamepad_layout_for_device } from "./gamepad_layout_database.js";
+import { GAMEPAD_STANDARD_LAYOUT } from "./GamepadLayout.js";
 import { GamepadStick } from "./GamepadStick.js";
 import { GAMEPAD_STANDARD_AXIS_COUNT, GAMEPAD_STANDARD_BUTTON_COUNT } from "./GamepadStandardMapping.js";
 
@@ -9,6 +11,10 @@ import { GAMEPAD_STANDARD_AXIS_COUNT, GAMEPAD_STANDARD_BUTTON_COUNT } from "./Ga
  * Native {@link Gamepad} objects are immutable snapshots in most browsers, this class provides a stable, observable
  * representation that is refreshed from those snapshots via {@link GamepadHandle#update}.
  *
+ * State is always presented in the standard mapping, so {@link GamepadButtons} and {@link GamepadAxes} are
+ * valid indices whatever the hardware is. A pad the browser declined to map reports its inputs in its own
+ * order, and {@link layout} is the translation back to the standard one - see {@link GamepadLayout}.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -33,6 +39,19 @@ export class GamepadHandle {
      */
     mapping = "";
 
+    /**
+     * How this handle reaches the device's inputs.
+     *
+     * Resolved from the hardware whenever {@link id} changes, and only ever anything other than a passthrough
+     * for a device the browser declined to map that is also known to {@link gamepad_layout_for_device}. Read
+     * it to find out how a pad is being interpreted, for a settings screen or when a pad misbehaves.
+     *
+     * Do not modify directly
+     *
+     * @type {GamepadLayout}
+     */
+    layout = GAMEPAD_STANDARD_LAYOUT;
+
     /**
      * Whether the gamepad is currently connected
      * Do not modify directly
@@ -94,8 +113,11 @@ export class GamepadHandle {
     buttonValues = [];
 
     /**
-     * Axis values in the range [-1,1], exactly as reported by the hardware.
-     * For the standard mapping, see {@link GamepadAxes} for valid indices.
+     * Axis values in the range [-1,1], indexed as {@link GamepadAxes}.
+     *
+     * Values are exactly as the hardware reported them, placed in the slot the standard mapping puts them in.
+     * On a pad the browser mapped itself those are the same thing; on one it did not, {@link layout} says
+     * which device axis each slot came from, and slots the device has no axis for read 0.
      *
      * Uncorrected: a resting stick rarely reads 0 here. Read {@link stickLeft}/{@link stickRight} for values
      * with the learned rest position removed.
@@ -156,22 +178,29 @@ export class GamepadHandle {
      */
     update(source) {
 
+        /*
+        Which device an id names cannot change without the id changing, so the layout is resolved on that edge
+        rather than on every poll
+         */
+        if (source.id !== this.id) {
+            this.layout = gamepad_layout_for_device(source);
+        }
+
         this.index = source.index;
         this.id = source.id;
         this.mapping = source.mapping;
 
+        const layout = this.layout;
+
         // buttons
-        const sourceButtons = source.buttons;
-        const buttonCount = sourceButtons.length;
+        const buttonCount = layout.presentedButtonCount(source);
 
         for (let i = 0; i < buttonCount; i++) {
-            const sourceButton = sourceButtons[i];
-
             const button = this.getButton(i);
 
-            this.buttonValues[i] = sourceButton.value;
+            this.buttonValues[i] = layout.readButtonValue(i, source);
 
-            if (sourceButton.pressed) {
+            if (layout.isButtonPressed(i, source)) {
 
                 if (button.is_up) {
                     button.press();
@@ -187,11 +216,10 @@ export class GamepadHandle {
         }
 
         // axes
-        const sourceAxes = source.axes;
-        const axisCount = sourceAxes.length;
+        const axisCount = layout.presentedAxisCount(source);
 
         for (let i = 0; i < axisCount; i++) {
-            const value = sourceAxes[i];
+            const value = layout.readAxis(i, source);
 
             // hardware beyond the standard mapping has not been seen before and reads as neutral
             const oldValue = this.axes[i] !== undefined ? this.axes[i] : 0;

package/src/engine/input/devices/gamepad/GamepadLayout.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Where each input of the standard mapping is found on a specific piece of hardware.
+ *
+ * The Gamepad API only promises the standard layout when {@link Gamepad#mapping} is `"standard"`. When it is
+ * anything else the browser is telling us it did not recognise the device, and the indices in `axes` and
+ * `buttons` mean whatever the device's HID report happens to say - a stick where the standard mapping expects a
+ * trigger, a trigger resting at -1 where it expects a released button. Reading such a device as though it were
+ * standard is not a small inaccuracy: a trigger axis read as an axis of the right stick pins that stick to full
+ * deflection forever.
+ *
+ * A layout is the translation, and it sits in the device layer for the same reason
+ * {@link GamepadStickCalibration} does - it describes what the hardware is, not what the game wants. It is the
+ * work the browser would have done had it recognised the pad.
+ *
+ * This class is that translation for a pad the browser already put in the standard layout: identity, a
+ * bit-exact passthrough. Opting out of translation is therefore not a mode, it is this layout - the same shape
+ * as an identity calibration. {@link GamepadDeviceLayout} is the translating one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GamepadLayout {
+    /**
+     * Human-readable name, for a settings screen that wants to say how a pad is being read
+     * @readonly
+     * @type {string}
+     */
+    readonly name: string;
+    /**
+     * How many standard buttons this layout presents for the given device.
+     *
+     * Passthrough presents every button the device reports, including any beyond the standard mapping - a pad
+     * the browser mapped to standard is free to report more, and dropping them would lose hardware that works.
+     *
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    presentedButtonCount(source: Gamepad): number;
+    /**
+     *
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    presentedAxisCount(source: Gamepad): number;
+    /**
+     * Analog travel of a standard button, in [0,1]
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    readButtonValue(index: number, source: Gamepad): number;
+    /**
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {boolean}
+     */
+    isButtonPressed(index: number, source: Gamepad): boolean;
+    /**
+     * Value of a standard axis, in [-1,1]
+     *
+     * @param {number} index standard axis index, see {@link GamepadAxes}
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    readAxis(index: number, source: Gamepad): number;
+    /**
+     * Index of the device axis read as a standard axis, or {@link GAMEPAD_LAYOUT_ABSENT}.
+     * For diagnostics and layout UI - reading values goes through {@link readAxis}.
+     *
+     * @param {number} index standard axis index, see {@link GamepadAxes}
+     * @returns {number}
+     */
+    axisSource(index: number): number;
+    /**
+     * Index of the device button read as a standard button, or {@link GAMEPAD_LAYOUT_ABSENT}
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @returns {number}
+     */
+    buttonSource(index: number): number;
+    /**
+     * Index of the device axis whose travel drives a standard button, or {@link GAMEPAD_LAYOUT_ABSENT}.
+     * This is how a non-standard pad reports its triggers.
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @returns {number}
+     */
+    buttonAxisSource(index: number): number;
+    /**
+     * Index of the device axis carrying a D-pad hat, or {@link GAMEPAD_LAYOUT_ABSENT}
+     * @returns {number}
+     */
+    get hatAxis(): number;
+    /**
+     * Whether this layout can be applied to the given device.
+     *
+     * Checked once when a pad connects rather than on every read. The same vendor and product can ship report
+     * descriptors that differ between firmware revisions - the browsers carry several layouts for the Xbox
+     * wireless pad alone for exactly this reason - and a layout that reaches past the end of what a device
+     * reports would otherwise write undefined into an axis and poison a stick with NaN.
+     *
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {boolean}
+     */
+    describes(source: Gamepad): boolean;
+}
+/**
+ * No device input drives this standard input, so it reads as neutral and never fires.
+ *
+ * That is the same answer the standard mapping already gives for hardware that lacks a button, see
+ * {@link GamepadHandle#buttons} - absence is uniform rather than expressive.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const GAMEPAD_LAYOUT_ABSENT: number;
+/**
+ * The layout of a pad the browser has already put in the standard mapping: a bit-exact passthrough.
+ *
+ * Shared by every handle reading such a pad, and carries no state, so it must not be modified.
+ *
+ * @readonly
+ * @type {GamepadLayout}
+ */
+export const GAMEPAD_STANDARD_LAYOUT: GamepadLayout;
+//# sourceMappingURL=GamepadLayout.d.ts.map

package/src/engine/input/devices/gamepad/GamepadLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadLayout.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;;OAIG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;;;OAQG;IACH,6BAHW,OAAO,GACL,MAAM,CAIlB;IAED;;;;OAIG;IACH,2BAHW,OAAO,GACL,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,UACN,OAAO,GACL,MAAM,CAIlB;IAED;;;;;OAKG;IACH,uBAJW,MAAM,UACN,OAAO,GACL,OAAO,CAInB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,UACN,OAAO,GACL,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,sBAEC;IAED;;;;;;;;;;OAUG;IACH,kBAHW,OAAO,GACL,OAAO,CAInB;CACJ;AAED;;;;;;;;GAQG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;;;GAOG;AACH,sCAFU,aAAa,CAEoC"}

package/src/engine/input/devices/gamepad/GamepadLayout.js

@@ -0,0 +1,160 @@
+/**
+ * Where each input of the standard mapping is found on a specific piece of hardware.
+ *
+ * The Gamepad API only promises the standard layout when {@link Gamepad#mapping} is `"standard"`. When it is
+ * anything else the browser is telling us it did not recognise the device, and the indices in `axes` and
+ * `buttons` mean whatever the device's HID report happens to say - a stick where the standard mapping expects a
+ * trigger, a trigger resting at -1 where it expects a released button. Reading such a device as though it were
+ * standard is not a small inaccuracy: a trigger axis read as an axis of the right stick pins that stick to full
+ * deflection forever.
+ *
+ * A layout is the translation, and it sits in the device layer for the same reason
+ * {@link GamepadStickCalibration} does - it describes what the hardware is, not what the game wants. It is the
+ * work the browser would have done had it recognised the pad.
+ *
+ * This class is that translation for a pad the browser already put in the standard layout: identity, a
+ * bit-exact passthrough. Opting out of translation is therefore not a mode, it is this layout - the same shape
+ * as an identity calibration. {@link GamepadDeviceLayout} is the translating one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GamepadLayout {
+
+    /**
+     * Human-readable name, for a settings screen that wants to say how a pad is being read
+     * @readonly
+     * @type {string}
+     */
+    name = "standard";
+
+    /**
+     * How many standard buttons this layout presents for the given device.
+     *
+     * Passthrough presents every button the device reports, including any beyond the standard mapping - a pad
+     * the browser mapped to standard is free to report more, and dropping them would lose hardware that works.
+     *
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    presentedButtonCount(source) {
+        return source.buttons.length;
+    }
+
+    /**
+     *
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    presentedAxisCount(source) {
+        return source.axes.length;
+    }
+
+    /**
+     * Analog travel of a standard button, in [0,1]
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    readButtonValue(index, source) {
+        return source.buttons[index].value;
+    }
+
+    /**
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {boolean}
+     */
+    isButtonPressed(index, source) {
+        return source.buttons[index].pressed;
+    }
+
+    /**
+     * Value of a standard axis, in [-1,1]
+     *
+     * @param {number} index standard axis index, see {@link GamepadAxes}
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {number}
+     */
+    readAxis(index, source) {
+        return source.axes[index];
+    }
+
+    /**
+     * Index of the device axis read as a standard axis, or {@link GAMEPAD_LAYOUT_ABSENT}.
+     * For diagnostics and layout UI - reading values goes through {@link readAxis}.
+     *
+     * @param {number} index standard axis index, see {@link GamepadAxes}
+     * @returns {number}
+     */
+    axisSource(index) {
+        return index;
+    }
+
+    /**
+     * Index of the device button read as a standard button, or {@link GAMEPAD_LAYOUT_ABSENT}
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @returns {number}
+     */
+    buttonSource(index) {
+        return index;
+    }
+
+    /**
+     * Index of the device axis whose travel drives a standard button, or {@link GAMEPAD_LAYOUT_ABSENT}.
+     * This is how a non-standard pad reports its triggers.
+     *
+     * @param {number} index standard button index, see {@link GamepadButtons}
+     * @returns {number}
+     */
+    buttonAxisSource(index) {
+        return GAMEPAD_LAYOUT_ABSENT;
+    }
+
+    /**
+     * Index of the device axis carrying a D-pad hat, or {@link GAMEPAD_LAYOUT_ABSENT}
+     * @returns {number}
+     */
+    get hatAxis() {
+        return GAMEPAD_LAYOUT_ABSENT;
+    }
+
+    /**
+     * Whether this layout can be applied to the given device.
+     *
+     * Checked once when a pad connects rather than on every read. The same vendor and product can ship report
+     * descriptors that differ between firmware revisions - the browsers carry several layouts for the Xbox
+     * wireless pad alone for exactly this reason - and a layout that reaches past the end of what a device
+     * reports would otherwise write undefined into an axis and poison a stick with NaN.
+     *
+     * @param {Gamepad} source native gamepad snapshot
+     * @returns {boolean}
+     */
+    describes(source) {
+        return true;
+    }
+}
+
+/**
+ * No device input drives this standard input, so it reads as neutral and never fires.
+ *
+ * That is the same answer the standard mapping already gives for hardware that lacks a button, see
+ * {@link GamepadHandle#buttons} - absence is uniform rather than expressive.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const GAMEPAD_LAYOUT_ABSENT = -1;
+
+/**
+ * The layout of a pad the browser has already put in the standard mapping: a bit-exact passthrough.
+ *
+ * Shared by every handle reading such a pad, and carries no state, so it must not be modified.
+ *
+ * @readonly
+ * @type {GamepadLayout}
+ */
+export const GAMEPAD_STANDARD_LAYOUT = new GamepadLayout();

package/src/engine/input/devices/gamepad/GamepadStandardMapping.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Value of {@link Gamepad#mapping} when the browser has already put the device in the standard layout.
+ *
+ * Any other value means it did not recognise the device and the indices mean whatever the device's HID report
+ * says, see {@link GamepadLayout}.
+ *
+ * @readonly
+ * @type {string}
+ */
+export const GAMEPAD_MAPPING_STANDARD: string;
 /**
  * Number of buttons defined by the "standard" gamepad mapping
  * see https://w3c.github.io/gamepad/#remapping

package/src/engine/input/devices/gamepad/GamepadStandardMapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GamepadStandardMapping.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadStandardMapping.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,0CAFU,MAAM,CAE6B"}
+{"version":3,"file":"GamepadStandardMapping.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadStandardMapping.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,uCAFU,MAAM,CAEmC;AAEnD;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,0CAFU,MAAM,CAE6B"}

package/src/engine/input/devices/gamepad/GamepadStandardMapping.js

@@ -1,3 +1,14 @@
+/**
+ * Value of {@link Gamepad#mapping} when the browser has already put the device in the standard layout.
+ *
+ * Any other value means it did not recognise the device and the indices mean whatever the device's HID report
+ * says, see {@link GamepadLayout}.
+ *
+ * @readonly
+ * @type {string}
+ */
+export const GAMEPAD_MAPPING_STANDARD = "standard";
+
 /**
  * Number of buttons defined by the "standard" gamepad mapping
  * see https://w3c.github.io/gamepad/#remapping

package/src/engine/input/devices/gamepad/GamepadStick.d.ts

@@ -26,9 +26,13 @@ export class GamepadStick {
      */
     axisY: number;
     /**
-     * Hardware value, exactly as reported.
+     * The hardware's own value for this stick, uncorrected.
      * A resting stick rarely reads (0,0) here, that is what {@link calibration} is for.
      *
+     * Uncorrected means the calibration has not been applied. Finding the stick is a separate question, and on
+     * a pad the browser did not recognise it is {@link GamepadHandle#layout} that answers it - the value here
+     * is still the hardware's, taken from whichever axes are actually this stick's.
+     *
      * @readonly
      * @type {Vector2}
      */

package/src/engine/input/devices/gamepad/GamepadStick.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GamepadStick.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadStick.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH;IAyDI;;;;OAIG;IACH,mBAHW,MAAM,SACN,MAAM,EAKhB;IA/DD;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,cAFU,OAAO,CAEG;IAEpB;;;;;;;;;OASG;IACH,gBAFU,OAAO,CAEK;IAEtB;;;OAGG;IACH,sBAFU,uBAAuB,CAEW;IAE5C;;OAEG;IACH;QACI;;;WAGG;;MAEL;IAiBF;;;;;OAKG;IACH,aAHW,MAAM,EAAE,GACN,IAAI,CA0BhB;IAED;;;;;OAKG;IACH,SAFa,IAAI,CAMhB;IAED;;;;;;;;;;;OAWG;IACH,qBAFa,IAAI,CAUhB;;CAkBJ;oBAnKmB,kCAAkC;wCACd,8BAA8B"}
+{"version":3,"file":"GamepadStick.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadStick.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH;IA6DI;;;;OAIG;IACH,mBAHW,MAAM,SACN,MAAM,EAKhB;IAnED;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;OAUG;IACH,cAFU,OAAO,CAEG;IAEpB;;;;;;;;;OASG;IACH,gBAFU,OAAO,CAEK;IAEtB;;;OAGG;IACH,sBAFU,uBAAuB,CAEW;IAE5C;;OAEG;IACH;QACI;;;WAGG;;MAEL;IAiBF;;;;;OAKG;IACH,aAHW,MAAM,EAAE,GACN,IAAI,CA0BhB;IAED;;;;;OAKG;IACH,SAFa,IAAI,CAMhB;IAED;;;;;;;;;;;OAWG;IACH,qBAFa,IAAI,CAUhB;;CAkBJ;oBAvKmB,kCAAkC;wCACd,8BAA8B"}

package/src/engine/input/devices/gamepad/GamepadStick.js

@@ -28,9 +28,13 @@ export class GamepadStick {
     axisY = 1;
 
     /**
-     * Hardware value, exactly as reported.
+     * The hardware's own value for this stick, uncorrected.
      * A resting stick rarely reads (0,0) here, that is what {@link calibration} is for.
      *
+     * Uncorrected means the calibration has not been applied. Finding the stick is a separate question, and on
+     * a pad the browser did not recognise it is {@link GamepadHandle#layout} that answers it - the value here
+     * is still the hardware's, taken from whichever axes are actually this stick's.
+     *
      * @readonly
      * @type {Vector2}
      */

package/src/engine/input/devices/gamepad/gamepad_layout_database.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Vendor and product of a device, as `vendor:product` in lower case, or an empty string when the id does not
+ * carry them.
+ *
+ * {@link Gamepad#id} is the only identity the Gamepad API exposes and its contents are explicitly
+ * browser-specific, so this reads the two formats that carry USB identifiers. Matching on hardware
+ * identifiers rather than on the whole string is what keeps an entry working when a browser changes the
+ * prose around them, and it is how the rest of the field does it - SDL's controller database is keyed on the
+ * same numbers.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function gamepad_device_key(id: string): string;
+/**
+ * The layout to read a device through.
+ *
+ * A pad the browser already mapped is passed through untouched, whatever the table says - it is the same
+ * hardware over a connection that was recognised, and translating it twice would break it. An unknown pad is
+ * also passed through: it is the only guess available, it is what this code has always done, and for the
+ * majority of pads that report a nearly standard order it is right.
+ *
+ * @param {Gamepad} source native gamepad snapshot
+ * @returns {GamepadLayout}
+ */
+export function gamepad_layout_for_device(source: Gamepad): GamepadLayout;
+//# sourceMappingURL=gamepad_layout_database.d.ts.map

package/src/engine/input/devices/gamepad/gamepad_layout_database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamepad_layout_database.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/gamepad_layout_database.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;GAYG;AACH,uCAHW,MAAM,GACJ,MAAM,CAgBlB;AAkED;;;;;;;;;;GAUG;AACH,kDAHW,OAAO,iBAwBjB"}

package/src/engine/input/devices/gamepad/gamepad_layout_database.js

@@ -0,0 +1,144 @@
+import { GamepadAxes } from "./GamepadAxes.js";
+import { GamepadButtons } from "./GamepadButtons.js";
+import { GamepadDeviceLayout } from "./GamepadDeviceLayout.js";
+import { GAMEPAD_STANDARD_LAYOUT } from "./GamepadLayout.js";
+import { GAMEPAD_MAPPING_STANDARD } from "./GamepadStandardMapping.js";
+
+/**
+ * Chrome names an unrecognised pad "Unknown Gamepad (Vendor: 045e Product: 0b13)"
+ * @type {RegExp}
+ */
+const CHROME_IDENTITY = /vendor:\s*([0-9a-f]{4})\s+product:\s*([0-9a-f]{4})/i;
+
+/**
+ * Firefox puts the same numbers first, as in "045e-0b13-Xbox Wireless Controller"
+ * @type {RegExp}
+ */
+const FIREFOX_IDENTITY = /^([0-9a-f]{4})-([0-9a-f]{4})-/i;
+
+/**
+ * Vendor and product of a device, as `vendor:product` in lower case, or an empty string when the id does not
+ * carry them.
+ *
+ * {@link Gamepad#id} is the only identity the Gamepad API exposes and its contents are explicitly
+ * browser-specific, so this reads the two formats that carry USB identifiers. Matching on hardware
+ * identifiers rather than on the whole string is what keeps an entry working when a browser changes the
+ * prose around them, and it is how the rest of the field does it - SDL's controller database is keyed on the
+ * same numbers.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function gamepad_device_key(id) {
+    const chrome = CHROME_IDENTITY.exec(id);
+
+    if (chrome !== null) {
+        return `${chrome[1]}:${chrome[2]}`.toLowerCase();
+    }
+
+    const firefox = FIREFOX_IDENTITY.exec(id);
+
+    if (firefox !== null) {
+        return `${firefox[1]}:${firefox[2]}`.toLowerCase();
+    }
+
+    return "";
+}
+
+/**
+ * Xbox Wireless Controller, model 1914, connected over Bluetooth.
+ *
+ * The same pad over USB or the Xbox wireless adapter arrives already in the standard mapping and never reaches
+ * this layout. Over Bluetooth the browser reports the HID report's own order instead:
+ *
+ *      axes    0 left stick x, 1 left stick y, 2 right stick x, 3 left trigger, 4 right trigger,
+ *              5 right stick y, 9 D-pad hat
+ *      buttons 0 A, 1 B, 3 X, 4 Y, 6 LB, 7 RB, 10 view, 11 menu, 13 left stick, 14 right stick
+ *
+ * The triggers are the damaging part: they rest at -1, and axes 3 and 4 are where the standard mapping expects
+ * the right stick, so a game reading the right stick sees permanent full deflection until this layout is
+ * applied.
+ *
+ * Provenance, because these tables are only as good as the evidence behind them. The axis assignments and both
+ * trigger axes were established on the reporting device - the four stick axes are the only ones that carry
+ * sensor noise at rest, and the trigger axes are the only ones resting at exactly -1. The face and shoulder
+ * button indices were observed firing on that device, with 2 and 5 never firing, which is the blank-button
+ * pattern this report descriptor is known for. The remaining button indices and the hat follow the layout the
+ * browsers themselves carry for this family of pad.
+ *
+ * Buttons 2, 5, 8, 9 and 12 are reported by the device and are deliberately left unsourced: nothing here
+ * established what they are, and an unsourced button reads as released rather than as a guess.
+ *
+ * @returns {GamepadDeviceLayout}
+ */
+function make_xbox_wireless_bluetooth_layout() {
+    return new GamepadDeviceLayout("Xbox Wireless Controller (Bluetooth)")
+        .readsAxisFrom(GamepadAxes.left_stick_x, 0)
+        .readsAxisFrom(GamepadAxes.left_stick_y, 1)
+        .readsAxisFrom(GamepadAxes.right_stick_x, 2)
+        .readsAxisFrom(GamepadAxes.right_stick_y, 5)
+
+        .readsButtonFrom(GamepadButtons.a, 0)
+        .readsButtonFrom(GamepadButtons.b, 1)
+        .readsButtonFrom(GamepadButtons.x, 3)
+        .readsButtonFrom(GamepadButtons.y, 4)
+        .readsButtonFrom(GamepadButtons.left_bumper, 6)
+        .readsButtonFrom(GamepadButtons.right_bumper, 7)
+        .readsButtonFrom(GamepadButtons.back, 10)
+        .readsButtonFrom(GamepadButtons.start, 11)
+        .readsButtonFrom(GamepadButtons.left_stick, 13)
+        .readsButtonFrom(GamepadButtons.right_stick, 14)
+
+        .readsButtonFromAxis(GamepadButtons.left_trigger, 3)
+        .readsButtonFromAxis(GamepadButtons.right_trigger, 4)
+
+        .readsDpadFromHatAxis(9);
+}
+
+/**
+ * Layouts for devices the browsers do not put in the standard mapping, keyed by {@link gamepad_device_key}.
+ *
+ * Small on purpose. Every stack that talks to gamepads ends up carrying a table like this - the browsers carry
+ * one per platform, SDL ships thousands of lines of it - because there is no way to derive a device's layout
+ * from what the Gamepad API exposes. Entries are added when a device has been observed, not in anticipation.
+ *
+ * @readonly
+ * @type {Map<string, GamepadDeviceLayout>}
+ */
+const LAYOUTS = new Map([
+    ["045e:0b13", make_xbox_wireless_bluetooth_layout()]
+]);
+
+/**
+ * The layout to read a device through.
+ *
+ * A pad the browser already mapped is passed through untouched, whatever the table says - it is the same
+ * hardware over a connection that was recognised, and translating it twice would break it. An unknown pad is
+ * also passed through: it is the only guess available, it is what this code has always done, and for the
+ * majority of pads that report a nearly standard order it is right.
+ *
+ * @param {Gamepad} source native gamepad snapshot
+ * @returns {GamepadLayout}
+ */
+export function gamepad_layout_for_device(source) {
+    if (source.mapping === GAMEPAD_MAPPING_STANDARD) {
+        return GAMEPAD_STANDARD_LAYOUT;
+    }
+
+    const layout = LAYOUTS.get(gamepad_device_key(source.id));
+
+    if (layout === undefined) {
+        return GAMEPAD_STANDARD_LAYOUT;
+    }
+
+    /*
+    Vendor and product do not pin down a report descriptor - firmware revisions of this very pad differ, which
+    is why the browsers carry several layouts for it - so an entry that reaches past what the device reports
+    is the wrong entry rather than a usable one
+     */
+    if (!layout.describes(source)) {
+        return GAMEPAD_STANDARD_LAYOUT;
+    }
+
+    return layout;
+}

package/src/engine/input/devices/gamepad/gamepad_read_hat_axis.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decode a D-pad reported as a HID hat switch on an axis.
+ *
+ * A hat is a single control with eight positions and a null state, so a browser that has not recognised the
+ * pad normalizes those eight positions evenly over [-1,1] - `-1` is up and the value increases clockwise to
+ * `+1` at up-and-left. The null state sits outside the switch's logical range, so a centred hat normalizes
+ * outside [-1,1] entirely; devices have been seen reporting values in the billions for it. Some report exactly
+ * `0` before their first real report, which is unambiguous because no hat position lands on zero.
+ *
+ * @param {number} value raw axis value
+ * @returns {number} bit field of {@link GamepadHatDirection}
+ */
+export function gamepad_read_hat_axis(value: number): number;
+/**
+ * D-pad directions, as a bit field so one value can carry the diagonals
+ */
+export type GamepadHatDirection = number;
+export namespace GamepadHatDirection {
+    let none: number;
+    let up: number;
+    let right: number;
+    let down: number;
+    let left: number;
+}
+//# sourceMappingURL=gamepad_read_hat_axis.d.ts.map

package/src/engine/input/devices/gamepad/gamepad_read_hat_axis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamepad_read_hat_axis.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/gamepad_read_hat_axis.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;GAWG;AACH,6CAHW,MAAM,GACJ,MAAM,CAUlB;;;;kCAzDS,MAAM"}