pixijs-input-devices 0.5.8 → 0.7.0

package/README.md

@@ -1,53 +1,76 @@
 # 🎮 PixiJS Input Devices  [![License](https://badgen.net/npm/license/pixijs-input-devices)](https://github.com/reececomo/pixijs-input-devices/blob/main/LICENSE) [![Tests](https://github.com/reececomo/pixijs-input-devices/actions/workflows/tests.yml/badge.svg)](https://github.com/reececomo/pixijs-input-devices/actions/workflows/tests.yml) [![Downloads per month](https://img.shields.io/npm/dm/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices) [![NPM version](https://img.shields.io/npm/v/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices)
 
-⚡ Simple keyboard & gamepad management for PixiJS
+⚡ Simple & powerful input device support for a variety of devices in PixiJS
 
 | | |
 | ------ | ------ |
-| 🎮 Interface [keyboards](#keyboarddevice), [gamepads](#gamepaddevice), and [more](#custom-devices)! | 🚀 Flexible [update](#real-time) and [event-driven](#keyboarddevice-events) APIs |
-| ⚡ Optimized for [INP performance](https://web.dev/articles/inp) | 🪄 Built-in [named binds](#named-binds) |
-| 🔮 Highly configurable | 🌐 Built-in [international keyboard](#keyboard-layout---detection) support |
-| ✅ Cross-platform &amp; mobile-friendly <sup>[[1]](https://caniuse.com/mdn-api_keyboardlayoutmap) [[2]](https://caniuse.com/mdn-api_gamepad_vibrationactuator) [[3]](https://chromestatus.com/feature/5989275208253440)</sup>  | 🧭 Built-in [UI navigation](#uinavigation-api) _(optional)_ |
+| 🎮 Instant [keyboard](#keyboarddevice), [gamepads](#gamepaddevice), and [custom device](#custom-devices) support | 🚀 [Real-time](#real-time) &amp; [event-driven](#keyboarddevice-events) APIs |
+| ⚡ Optimized for [performance](https://web.dev/articles/inp) | 🧭 Built-in [UI navigation](#uinavigation-api) |
+| 🔮 Highly configurable (with sensible defaults) | 🪄 Supports [input binding](#named-binds) |
+| ✅ Cross-platform &amp; mobile-friendly <sup>[[1]](https://caniuse.com/mdn-api_keyboardlayoutmap) [[2]](https://caniuse.com/mdn-api_gamepad_vibrationactuator) [[3]](https://chromestatus.com/feature/5989275208253440)</sup>  | 🌐 Automatic [Intl layouts](#keyboard-layout---detection) detection |
 | 🍃 Zero dependencies & tree-shakeable | ✨ Supports PixiJS v8, v7, v6.3+ |
 
 
-## Sample Usage
-
-*Handle device inputs with ease.*
+## Basic Usage
 
 ```ts
-import { InputDevice, GamepadDevice } from "pixijs-input-devices";
+import { InputDevice } from "pixijs-input-devices";
+
+let moveX = 0.0,
+    jump = false;
+
+for (const device of InputDevice.devices)
+{
+    if (device.bindDown("left"))    moveX = -1;
+    if (device.bindDown("right"))   moveX =  1;
+    if (device.bindDown("jump"))    jump = true;
+
+    if (device.type === "gamepad" && device.leftJoystick.x != 0.0)
+    {
+        moveX = device.leftJoystick.x;
+    }
+}
+```
 
+#### Configure binds
 
-// Set named binds
+```ts
+import { GamepadDevice, KeyboardDevice } from "pixijs-input-devices";
+
+// ⌨️ keyboard
 KeyboardDevice.global.configureBinds({
-    jump: [ "Space" ]
-})
+    jump:   ["Space"],
+    left:   ["KeyA", "ArrowLeft"],
+    right:  ["KeyD", "ArrowRight"],
+});
 
+// 🎮 gamepads
 GamepadDevice.configureDefaultBinds({
-    jump: [ "A", "LeftStickUp" ]
-})
+    left:   ["DpadLeft"],
+    right:  ["DpadRight"],
+    jump:   ["Face1"],
+});
+```
 
-// Use binds
-for ( const device of InputDevice.devices ) {
-    if ( device.pressedBind("jump") ) // ...
-}
+> [!TIP]
+> See [**Named binds**](#named-binds) for more information on configuring devices.
 
-// Event-driven
-InputDevice.onBind( "jump", ({ device }) => {
-    if ( device.type === "gamepad" ) {
-        device.playVibration({ duration: 50 })
-    }
-});
+#### Events
+
+```ts
+// targeted
+device.onBindDown("menu", ({ device }) => { });
+
+// global
+InputDevice.onBindDown("menu", ({ device }) => { });
 ```
 
-## Getting Started with PixiJS Input Devices
+## 💿 Install
 
 *Everything you need to quickly integrate device management.*
 
-**PixiJS Input Devices** adds first-class support for input devices, and
-provides a simple, but powerful navigation manager that can enable devices to
-navigate existing pointer-based UIs.
+**PixiJS Input Devices** provides an input manager, and a navigation manager that enables
+non-pointer devices to navigate pointer-based user interfaces (UIs).
 
 The key concepts are:
 
@@ -76,10 +99,11 @@ yarn add pixijs-input-devices --dev
 **2.** Register the update loop:
 
 ```ts
-import { Ticker } from 'pixi.js';
-import { InputDevice } from 'pixijs-input-devices';
+import { Ticker } from 'pixi.js'
+import { InputDevice } from 'pixijs-input-devices'
 
-Ticker.shared.add(ticker => InputDevice.update());
+
+Ticker.shared.add(() => InputDevice.update())
 ```
 
 > [!TIP]
@@ -88,14 +112,15 @@ Ticker.shared.add(ticker => InputDevice.update());
 **3.** (Optional) enable the UINavigation API
 
 ```ts
-import * as PIXI from 'pixi.js';
-import { UINavigation, registerPixiJSNavigationMixin } from 'pixijs-input-devices';
+import * as PIXI from 'pixi.js'
+import { UINavigation, registerPixiJSNavigationMixin } from 'pixijs-input-devices'
+
 
 const app = new PIXI.Application(/*…*/)
 
 // enable the navigation API
-UINavigation.configureWithRoot( app.stage )
-registerPixiJSNavigationMixin( PIXI.Container )
+UINavigation.configureWithRoot(app.stage)
+registerPixiJSNavigationMixin(PIXI.Container)
 ```
 
 ✨ You are now ready to use inputs!
@@ -108,46 +133,65 @@ The `InputDevice` singleton controls all device discovery.
 
 ```ts
 InputDevice.keyboard  // KeyboardDevice
-InputDevice.gamepads  // Array<GamepadDevice>
-InputDevice.custom    // Array<CustomDevice>
+InputDevice.gamepads  // GamepadDevice[]
+InputDevice.custom    // Device[]
 ```
 
 You can access all **active/connected** devices using `.devices`:
 
 ```ts
-for ( const device of InputDevice.devices ) {  // …
+for (const device of InputDevice.devices) {  // …
 ```
 
 #### InputDevice - properties
 
+The `InputDevice` manager provides the following **context capability** properties:
+
 | Property | Type | Description |
 |---|---|---|
-| `InputDevice.isMobile` | `boolean` | Whether the context is mobile (including tablets). |
-| `InputDevice.isTouchCapable` | `boolean` | Whether the context has touchscreen capability. |
+| `InputDevice.hasMouseLikePointer` | `boolean` | Whether the context has a mouse/trackpad. |
+| `InputDevice.isMobile` | `boolean` | Whether the context is mobile capable. |
+| `InputDevice.isTouchCapable` | `boolean` | Whether the context is touchscreen capable. |
+
+As well as shortcuts to **connected devices**:
+
+| Accessor | Type | Description |
+|---|---|---|
 | `InputDevice.lastInteractedDevice` | `Device?` | The most recently interacted device (or first if multiple). |
 | `InputDevice.devices` | `Device[]` | All active, connected devices. |
 | `InputDevice.keyboard` | `KeyboardDevice` | The global keyboard. |
 | `InputDevice.gamepads` | `GamepadDevice[]` | Connected gamepads. |
-| `InputDevice.custom` | `CustomDevice[]` | Custom devices. |
+| `InputDevice.custom` | `CustomDevice[]` | Any custom devices. |
 
 #### InputDevice - on() Events
 
 Access global events directly through the manager:
 
 ```ts
-InputDevice.on( "deviceadded", ({ device }) => {
-    // a device was connected
+InputDevice.on("deviceadded", ({ device }) => {
+    // new device was connected or became available
     // do additional setup here, show a dialog, etc.
 })
 
-InputDevice.off( "deviceadded" ) // stop listening
+InputDevice.off("deviceadded") // stop listening
 ```
 
 | Event | Description | Payload |
 |---|---|---|
 | `"deviceadded"` | `{device}` | A device has been added. |
 | `"deviceremoved"` | `{device}` | A device has been removed. |
+| `"lastdevicechanged"` | `{device}` | The _last interacted device_ has changed. |
+
 
+#### InputDevice - onBindDown() Events
+
+You may also subscribe globally to **named bind** events:
+
+```ts
+InputDevice.onBindDown("my_custom_bind", (event) => {
+    // a bound input waas triggered
+})
+```
 
 ### KeyboardDevice
 
@@ -156,7 +200,7 @@ Unlike gamepads & custom devices, there is a single global keyboard device.
 ```ts
 let keyboard = InputDevice.keyboard
 
-if ( keyboard.key.ControlLeft ) {  // …
+if (keyboard.key.ControlLeft) {  // …
 ```
 
 > [!NOTE]
@@ -168,7 +212,7 @@ if ( keyboard.key.ControlLeft ) {  // …
 ```ts
 keyboard.layout  // "AZERTY" | "JCUKEN" | "QWERTY" | "QWERTZ"
 
-keyboard.getKeyLabel( "KeyZ" )  // Я
+keyboard.getKeyLabel("KeyZ")  // Я
 ```
 
 > [!NOTE]
@@ -176,7 +220,7 @@ keyboard.getKeyLabel( "KeyZ" )  // Я
 > Almost every keyboard is one of these four (or a regional derivative &ndash; e.g. Hangeul,
 > Kana). There is no built-in detection for specialist or esoteric layouts (e.g. Dvorak, Colemak, BÉPO).
 >
-> The `keyboard.getKeyLabel( key )` uses the [KeyboardLayoutMap API](https://caniuse.com/mdn-api_keyboardlayoutmap)
+> The `keyboard.getKeyLabel(key)` uses the [KeyboardLayoutMap API](https://caniuse.com/mdn-api_keyboardlayoutmap)
 > when available, before falling back to default AZERTY, JCUKEN, QWERTY or QWERTZ key values.
 
 The keyboard layout is automatically detected from (in order):
@@ -191,7 +235,7 @@ You can also manually force the layout:
 // force layout
 InputDevice.keyboard.layout = "JCUKEN"
 
-InputDevice.keyboard.getKeyLabel( "KeyW" )  // "Ц"
+InputDevice.keyboard.getKeyLabel("KeyW")  // "Ц"
 InputDevice.keyboard.layoutSource  // "manual"
 ```
 
@@ -200,7 +244,7 @@ InputDevice.keyboard.layoutSource  // "manual"
 | Event | Description | Payload |
 |---|---|---|
 | `"layoutdetected"` | `{layout,layoutSource,device}` | The keyboard layout (`"QWERTY"`, `"QWERTZ"`, `"AZERTY"`, or `"JCUKEN"`) has been detected, either from the native API or from keypresses. |
-| `"bind"` | `{name,event,keyCode,keyLabel,device}` | A **named bind** key was pressed. |
+| `"binddown"` | `{name,event,keyCode,keyLabel,device}` | A **named bind** key was pressed. |
 | **Key presses:** | | |
 | `"KeyA"` | `{event,keyCode,keyLabel,device}` | The `"KeyA"` was pressed. |
 | `"KeyB"` | `{event,keyCode,keyLabel,device}` | The `"KeyB"` was pressed. |
@@ -215,11 +259,22 @@ Gamepads are automatically detected via the browser API when first interacted wi
 Gamepad accessors are modelled around the "Standard Controller Layout":
 
 ```ts
-let gamepad = InputDevice.gamepads[0]
+const gamepad = InputDevice.gamepads[0];
 
-if ( gamepad.button.Start ) {  // …
-if ( gamepad.leftTrigger > 0.25 ) {  // …
-if ( gamepad.leftJoystick.x > 0.5 ) {  // …
+if (gamepad.button.DpadDown)
+{
+    // button pressed
+}
+
+if (gamepad.leftTrigger > 0.25)
+{
+    // trigger pulled
+}
+
+if (gamepad.leftJoystick.x < -0.33)
+{
+    // joystick moved
+}
 ```
 
 > [!TIP]
@@ -228,39 +283,69 @@ if ( gamepad.leftJoystick.x > 0.5 ) {  // …
 
 #### Vibration & Haptics
 
-Use the `playVibration()` method to play a haptic vibration, in supported browsers.
+Use the `playHaptic()` method to play a haptic vibration effect on supported devices.
 
 ```ts
-gamepad.playVibration({
+device.playHaptic({
     duration: 150,
-    weakMagnitude: 0.75,
-    strongMagnitude: 0.25,
+    rumble: 0.75,
+    buzz: 0.25,
+    rightTrigger: 0.1, // limited support
     // …
-})
+});
 ```
 
+and to cancel all haptics:
+
+```ts
+device.stopHaptics();
+```
+
+##### Multiple simultaneous haptics on Gamepads
+
+Haptics automatically manage their queue under-the-hood, so you can combine or queue
+them very easily.
+
+```ts
+device.playHaptic({ duration: 150, buzz: 0.75 });
+device.playHaptic({ duration: 500, rumble: 0.5 });
+device.playHaptic({ duration: 250, rumble: 1.0 });
+device.playHaptic({
+    startDelay: 450,
+    duration: 300
+    leftTrigger: 0.25,
+    rightTrigger: 0.25,
+    buzz: 1.0,
+    rumble: device.supportsTriggerRumble ? 0.5 : 1.0,
+});
+```
+
+> [!TIP]
+> **Configure gamepad vibration:** On gamepads you can use `device.options.vibration.enabled`
+> and `device.options.vibration.intensity` to control vibration.
+
 #### Gamepad Button Codes
 
 The gamepad buttons reference **Standard Controller Layout**:
 
-| Button Index | GamepadCode | Description | Xbox | Playstation | Nintendo<sup>[[?]](#gamepad---nintendo-layout-remapping)</sup> |
+| Button # | GamepadCode | Description | Xbox Series X | Playstation 5 DualSense® | Nintendo Switch™ Pro |
 |:---:|:---|:---|:---:|:---:|:---:|
-| `0` | `"A"` | **Face Button 0** | A | Cross | A |
-| `1` | `"B"` | **Face Button 1** | B | Circle | X* |
-| `2` | `"X"` | **Face Button 2** | X | Square | B* |
-| `3` | `"Y"` | **Face Button 3** | Y | Triangle | Y |
+| `0` | `"Face1"` | **Face Button 1** | A | Cross | B |
+| `1` | `"Face2"` | **Face Button 2** | B | Circle | A |
+| `2` | `"Face3"` | **Face Button 3** | X | Square | Y |
+| `3` | `"Face4"` | **Face Button 4** | Y | Triangle | X |
 | `4` | `"LeftShoulder"` | **Left Shoulder** | LB | L1 | L |
 | `5` | `"RightShoulder"` | **Right Shoulder** | RB | R1 | R |
 | `6` | `"LeftTrigger"` | **Left Trigger** | LT | L2 | ZL |
 | `7` | `"RightTrigger"` | **Right Trigger** | RT | R2 | ZR |
-| `8` | `"Back"` | **Back** | Back | Options | Minus |
-| `9` | `"Start"` | **Start** | Start | Select | Plus |
-| `10` | `"LeftStickClick"` | **Left Stick Click** | LSB | L3 | L3 |
-| `11` | `"RightStickClick"` | **Right Stick Click** | RSB | R3 | R3 |
-| `12` | `"DPadUp"` | **D-Pad Up** | ⬆️ | ⬆️ | ⬆️ |
-| `13` | `"DPadDown"` | **D-Pad Down** | ⬇️ | ⬇️ | ⬇️ |
-| `14` | `"DPadLeft"` | **D-Pad Left** |  ⬅️ | ⬅️ | ⬅️ |
-| `15` | `"DPadRight"` | **D-Pad Right** | ➡️ | ➡️ | ➡️ |
+| `8` | `"Back"` | **Back** | View | Options | Minus |
+| `9` | `"Start"` | **Start** | Menu | Select | Plus |
+| `10` | `"LeftStickClick"` | **Left Stick (Click)** | LSB | L3 | L3 |
+| `11` | `"RightStickClick"` | **Right Stick (Click)** | RSB | R3 | R3 |
+| `12` | `"DpadUp"` | **D-Pad Up** | ⬆️ | ⬆️ | ⬆️ |
+| `13` | `"DpadDown"` | **D-Pad Down** | ⬇️ | ⬇️ | ⬇️ |
+| `14` | `"DpadLeft"` | **D-Pad Left** |  ⬅️ | ⬅️ | ⬅️ |
+| `15` | `"DpadRight"` | **D-Pad Right** | ➡️ | ➡️ | ➡️ |
 
 #### Gamepad Axis Codes
 
@@ -268,71 +353,32 @@ Bindable helpers are available for the joysticks too:
 
 | Axis # | GamepadCode | Standard | Layout
 |:---:|:---:|:---:|:---:|
-| `0` | `"LeftStickLeft"`<br/>`"LeftStickRight"` | **Left Stick (Left/Right)** | ⬅️➡️ |
-| `1` | `"LeftStickUp"`<br/>`"LeftStickDown"` | **Left Stick (Up/Down)** | ⬆️⬇️ |
-| `2` | `"RightStickLeft"`<br/>`"RightStickRight"` | **Right Stick (Left/Right)** | ⬅️➡️ |
-| `3` | `"RightStickUp"`<br/>`"RightStickDown"` | **Right Stick (Up/Down)** | ⬆️⬇️ |
+| `0` | `"LeftStickLeft"`<br/>`"LeftStickRight"` | **Left Stick (X-Axis)** | ⬅️➡️ |
+| `1` | `"LeftStickUp"`<br/>`"LeftStickDown"` | **Left Stick (Y-Axis)** | ⬆️⬇️ |
+| `2` | `"RightStickLeft"`<br/>`"RightStickRight"` | **Right Stick (X-Axis)** | ⬅️➡️ |
+| `3` | `"RightStickUp"`<br/>`"RightStickDown"` | **Right Stick (Y-Axis)** | ⬆️⬇️ |
 
 > [!TIP]
-> Set the `joystick.threshold` option in `GamepadDevice.defaultOptions` to control when this is triggered.
+> Set the `joystick.pressThreshold` option in `GamepadDevice.defaultOptions` to adjust event sensitivity.
 
 #### Gamepad Layouts
 
 ```ts
-gamepad.layout  // "nintendo" | "xbox" | "playstation" | "logitech" | "steam" | "standard"
+gamepad.layout // "xbox_one"
 ```
 
-Layout detection is **highly non-standard** across major browsers, it should generally be used for aesthetic
-improvements (e.g. showing [device-specific icons](https://thoseawesomeguys.com/prompts/)).
-
-There is some limited layout remapping support built-in for Nintendo controllers, which appear to be the
-only major brand controller that deviates from the standard.
-
-##### Gamepad - Nintendo Layout Remapping
-
-> [!CAUTION]
-> ***Nintendo:** Both the labels and physical positions of the A,B,X,Y buttons are different
-> on Nintendo controllers.
->
-> Set `GamepadDevice.defaultOptions.nintendoRemapMode` to apply the remapping as required.
->
-> - `"physical"` _**(default)**_ &ndash; The A,B,X,Y button codes will refer the standard face button positions (Left=X, Top=Y, Bottom=A, Right=B).
-> - `"accurate"` &ndash; The A,B,X,Y button codes will refer to the exact Nintendo labels (Left=Y, Top=X, Bottom=B, Right=A).
-> - `"none"` &ndash; The A,B,X,Y button codes mapping stay at the default indices (Left=Y, Top=B, Bottom=X, Right=A).
->
-> ```
-> standard       nintendo        nintendo       nintendo
->  layout       "physical"      "accurate"       "none"
-> reference      (default)
-> 
->     Y             Y              X               B
->   X   B         X   B          Y   A           Y   A
->     A             A              B               X
->
->     3             3              2               1
->   2   1         2   1          3   0           3   0
->     0             0              1               2
-> ```
-
-You can manually override this per-gamepad, or for all gamepads:
-
-```ts
-// set default
-GamepadDevice.defaultOptions.nintendoRemapMode = "none"
-
-// set for a single gamepad
-gamepad.options.nintendoRemapMode = "accurate"
-```
+Gamepad device layout reporting is a non-standard API, and should only be used for aesthetic
+enhancements improvements (i.e. [display layout-specific icons](https://thoseawesomeguys.com/prompts/)).
 
 #### GamepadDevice Events
 
 | Event | Description | Payload |
 |---|---|---|
-| `"bind"` | `{name,button,buttonCode,device}` | A **named bind** button was pressed. |
+| `"binddown"` | `{name,button,buttonCode,device}` | A **named bind** button was pressed. |
 | **Button presses:** | | |
-| `"A"` | `{button,buttonCode,device}` | Standard layout button `"A"` was pressed. Equivalent to `0`. |
-| `"B"` | `{button,buttonCode,device}` | Standard layout button `"B"` was pressed. Equivalent to `1`. |
-| `"X"` | `{button,buttonCode,device}` | Standard layout button `"X"` was pressed. Equivalent to `2`. |
+| `"Face1"` | `{button,buttonCode,device}` | Standard layout button `"Face1"` was pressed. Equivalent to `0`. |
+| `"Face2"` | `{button,buttonCode,device}` | Standard layout button `"Face2"` was pressed. Equivalent to `1`. |
+| `"Face3"` | `{button,buttonCode,device}` | Standard layout button `"Face3"` was pressed. Equivalent to `2`. |
 | … | … | … |
 | **Button presses (no label):** | | |
 | `0` or `Button.A` | `{button,buttonCode,device}` | Button at offset `0` was pressed. |
@@ -347,17 +393,16 @@ You can add custom devices to the device manager so it will be polled togehter a
 ```ts
 import { type CustomDevice, InputDevice } from "pixijs-input-devices"
 
-export const myDevice: CustomDevice = {
-    id: "on-screen-buttons",
+export const onScreenButtonsDevice: CustomDevice = {
     type: "custom",
+    id: "OnScreen",
     meta: {},
-    
-    update: ( now: number ) => {
+    update: (now: number) => {
         // polling update
     }
-}
+};
 
-InputDevice.add( myDevice )
+InputDevice.add(onScreenButtonsDevice);
 ```
 
 ## Named Binds
@@ -376,8 +421,8 @@ InputDevice.keyboard.configureBinds({
 
 // all gamepads:
 GamepadDevice.configureDefaultBinds({
-    jump: [ "A", "LeftStickUp" ],
-    crouch: [ "B", "X", "RightTrigger" ],
+    jump: [ "Face1", "LeftStickUp" ],
+    crouch: [ "Face2", "Face3", "RightTrigger" ],
     toggleGraphics: [ "RightStickUp", "RightStickDown" ],
 })
 ```
@@ -388,11 +433,11 @@ These can then be used with either the real-time and event-based APIs.
 
 ```ts
 // listen to all devices:
-InputDevice.onBind( "toggleGraphics", ( e ) => toggleGraphics() )
+InputDevice.onBindDown("toggleGraphics", (e) => toggleGraphics())
 
 // listen to specific devices:
-InputDevice.keyboard.onBind( "jump", ( e ) => doJump() )
-InputDevice.gamepads[0].onBind( "jump", ( e ) => doJump() )
+InputDevice.keyboard.onBindDown("jump", (e) => doJump())
+InputDevice.gamepads[0].onBindDown("jump", (e) => doJump())
 ```
 
 #### Real-time:
@@ -401,19 +446,19 @@ InputDevice.gamepads[0].onBind( "jump", ( e ) => doJump() )
 let jump = false, crouch = false, moveX = 0
 
 const keyboard = InputDevice.keyboard
-if ( keyboard.pressedBind( "jump" ) ) jump = true
-if ( keyboard.pressedBind( "crouch" ) ) crouch = true
-if ( keyboard.key.ArrowLeft ) moveX = -1
-else if ( keyboard.key.ArrowRight ) moveX = 1
+if (keyboard.bindDown("jump")) jump = true
+if (keyboard.bindDown("crouch")) crouch = true
+if (keyboard.key.ArrowLeft) moveX = -1
+else if (keyboard.key.ArrowRight) moveX = 1
 
-for ( const gamepad of InputDevice.gamepads ) {
-    if ( gamepad.pressedBind( "jump" ) ) jump = true
-    if ( gamepad.pressedBind( "crouch" ) ) crouch = true
+for (const gamepad of InputDevice.gamepads) {
+    if (gamepad.bindDown("jump")) jump = true
+    if (gamepad.bindDown("crouch")) crouch = true
 
     // gamepads have additional analog inputs
     // we're going to apply these only if touched
-    if ( gamepad.leftJoystick.x != 0 ) moveX = gamepad.leftJoystick.x
-    if ( gamepad.leftTrigger > 0 ) moveX *= ( 1 - gamepad.leftTrigger )
+    if (gamepad.leftJoystick.x != 0) moveX = gamepad.leftJoystick.x
+    if (gamepad.leftTrigger > 0) moveX *= (1 - gamepad.leftTrigger)
 }
 ```
 
@@ -426,8 +471,8 @@ _Traverse a UI using input devices._
 Set up navigation once using:
 
 ```ts
-UINavigation.configureWithRoot( app.stage )  // any root container
-registerPixiJSNavigationMixin( PIXI.Container )
+UINavigation.configureWithRoot(app.stage)  // any root container
+registerPixiJSNavigationMixin(PIXI.Container)
 ```
 
 Navigation should now work automatically if your buttons handle these events:
@@ -494,7 +539,7 @@ Containers are extended with a few properties/accessors:
 > [!WARNING]
 > **Fallback Hover Effect:** If there is no `"pointerover"` or `"mouseover"` handler detected on a container, `UINavigation`
 >  will apply abasic alpha effect to the selected item to indicate which container is currently the navigation target. This
-> can be disabled by setting `UINavigation.options.useFallbackHoverEffect` to `false`.
+> can be disabled by setting `UINavigation.options.enableFallbackOverEffect` to `false`.
 
 ### Default Binds
 
@@ -502,12 +547,12 @@ The keyboard and gamepad devices are preconfigured with the following binds, fee
 
 Navigation Intent Bind | Keyboard | Gamepad
 ---|---|---
-`"navigate.left"` | "ArrowLeft", "KeyA" | "DPadLeft", "LeftStickLeft"
-`"navigate.right"` | "ArrowRight", "KeyD" | "DPadRight", "LeftStickRight"
-`"navigate.up"` | "ArrowUp", "KeyW" | "DPadUp", "LeftStickUp"
-`"navigate.down"` | "ArrowDown", "KeyS" | "DPadDown", "LeftStickDown"
-`"navigate.trigger"` | "Enter", "Space" | "A"
-`"navigate.back"` | "Escape", "Backspace" | "B", "Back"
+`"navigate.left"` | "ArrowLeft", "KeyA" | "DpadLeft", "LeftStickLeft"
+`"navigate.right"` | "ArrowRight", "KeyD" | "DpadRight", "LeftStickRight"
+`"navigate.up"` | "ArrowUp", "KeyW" | "DpadUp", "LeftStickUp"
+`"navigate.down"` | "ArrowDown", "KeyS" | "DpadDown", "LeftStickDown"
+`"navigate.trigger"` | "Enter", "Space" | "Face1"
+`"navigate.back"` | "Escape", "Backspace" | "Face2", "Back"
 
 ### Manual control for submenus & modal views
 
@@ -515,7 +560,7 @@ You can manually take control of navigation using:
 
 ```ts
 // take control
-UINavigation.pushResponder( myModalView )
+UINavigation.pushResponder(myModalView)
 
 // relinquish control
 UINavigation.popResponder()
@@ -535,9 +580,9 @@ InputDevice.on("deviceconnected", ({ device }) =>
     device.meta.localPlayerId = 123
 )
 
-for ( const device of InputDevice.devices )
+for (const device of InputDevice.devices)
 {
-    if ( device.meta.localPlayerId === 123 )
+    if (device.meta.localPlayerId === 123)
     {
         // use assigned input device!
     }
@@ -550,26 +595,29 @@ You can easily map an on-screen input device using the `CustomDevice` interface.
 
 ```ts
 export class OnScreenInputContainer extends Container implements CustomDevice {
-    id = "onscreen";
-    type = "custom" as const;
-    meta: Record<string, any> = {};
+    id = "onscreen"
+    type = "custom" as const
+    meta: Record<string, any> = {}
 
     inputs = {
         moveX: 0.0
         jump: false,
     }
 
-    update( now )
+    update(now)
     {
-        this.moveX = this._virtualJoystick.x
-        this.jump = this._jumpButton.isTouching()
+        this.inputs.moveX = this._virtualJoystick.x
+        this.inputs.jump = this._jumpButton.isTouching()
     }
+
+    // e.g. disable named binds for onscreen joysticks:
+    bindDown(name){ return false } 
 }
 
-const onscreen = new OnScreenInputContainer();
+const onscreen = new OnScreenInputContainer()
 
-InputDevice.add( onscreen )
-InputDevice.remove( onscreen )
+InputDevice.add(onscreen)
+InputDevice.remove(onscreen)
 ```
 
 ### Two Users; One Keyboard
@@ -591,32 +639,32 @@ InputDevice.keyboard.configureBinds({
     p2_jump: [ "ArrowUp" ],
     p2_defend: [ "ArrowDown" ],
     p2_left: [ "ArrowLeft" ],
-    p2_right: [ "ArrowRight" ],
+    p2_right: [ "ArrowRight" ]
 })
 ```
 
 and then switch groups depending on the mode:
 
 ```ts
-if ( gameMode === "multiplayer" )
+if (gameMode === "multiplayer")
 {
-    player1.jump   = device.pressedBind( "p1_jump" )
-    player1.defend = device.pressedBind( "p1_defend" )
-    player1.moveX += device.pressedBind( "p1_left" ) ? -1 : 0
-    player1.moveX += device.pressedBind( "p1_right" ) ? 1 : 0
-
-    player2.jump   = device.pressedBind( "p2_jump" )
-    player2.defend = device.pressedBind( "p2_defend" )
-    player2.moveX += device.pressedBind( "p2_left" ) ? -1 : 0
-    player2.moveX += device.pressedBind( "p2_right" ) ? 1 : 0
+    player1.jump   = device.bindDown("p1_jump")
+    player1.defend = device.bindDown("p1_defend")
+    player1.moveX += device.bindDown("p1_left") ? -1 : 0
+    player1.moveX += device.bindDown("p1_right") ? 1 : 0
+
+    player2.jump   = device.bindDown("p2_jump")
+    player2.defend = device.bindDown("p2_defend")
+    player2.moveX += device.bindDown("p2_left") ? -1 : 0
+    player2.moveX += device.bindDown("p2_right") ? 1 : 0
 }
 else
 {
-    player1.jump   = device.pressedBind( "jump" )
-    player1.defend = device.pressedBind( "defend" )
-    player1.moveX += device.pressedBind( "left" ) ? -1 : 0
-    player1.moveX += device.pressedBind( "right" ) ? 1 : 0
+    player1.jump   = device.bindDown("jump")
+    player1.defend = device.bindDown("defend")
+    player1.moveX += device.bindDown("left") ? -1 : 0
+    player1.moveX += device.bindDown("right") ? 1 : 0
 
-    updateComputerPlayerInput( player2 )
+    updateComputerPlayerInput(player2)
 }
 ```