@woosh/meep-engine 2.169.0 → 2.169.2

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"}

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

@@ -0,0 +1,61 @@
+/**
+ * D-pad directions, as a bit field so one value can carry the diagonals
+ * @readonly
+ * @enum {number}
+ */
+export const GamepadHatDirection = {
+    'none': 0,
+    'up': 1,
+    'right': 2,
+    'down': 4,
+    'left': 8
+};
+
+const UP = GamepadHatDirection.up;
+const RIGHT = GamepadHatDirection.right;
+const DOWN = GamepadHatDirection.down;
+const LEFT = GamepadHatDirection.left;
+
+/**
+ * The eight hat positions, clockwise from up
+ * @readonly
+ * @type {number[]}
+ */
+const HAT_POSITIONS = [
+    UP,
+    UP | RIGHT,
+    RIGHT,
+    RIGHT | DOWN,
+    DOWN,
+    DOWN | LEFT,
+    LEFT,
+    LEFT | UP
+];
+
+/**
+ * Distance between adjacent hat positions once the switch's eight positions are spread over [-1,1]
+ * @type {number}
+ */
+const POSITION_STEP = 2 / (HAT_POSITIONS.length - 1);
+
+/**
+ * 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) {
+    if (value < -1 || value > 1 || value === 0) {
+        return GamepadHatDirection.none;
+    }
+
+    const position = Math.round((value + 1) / POSITION_STEP);
+
+    return HAT_POSITIONS[position];
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prototypeGamepadTester.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prototypeGamepadTester.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/prototypeGamepadTester.js"],"names":[],"mappings":""}