pixijs-input-devices 0.2.5 → 0.2.7

package/README.md

@@ -2,223 +2,223 @@
 
 🚧 WIP - This API is a work in progress, and is subject to change.
 
-- Adds support for ⌨️ **Keyboard**, 🎮 **Gamepads**, and other human-interface devices
-- A simple `Navigation` API which hooks devices into existing pointer/mouse events
-- A powerful event-based API for event-driven interactions
-- and of course, a high-performance API for real-time applications
+- Adds comprehensive support for ⌨️ **Keyboard**, 🎮 **Gamepads**, and other human-interface devices
+- High-performance, easy-to-use, sensible defaults
+- Supports either real-time or event driven APIs
+- Built-in `Navigation` API to navigate pointer/mouse based menus _(optional)_
 
 <hr/>
 
-### 💿 Install
+## 💿 Install
 
 ```sh
 npm i pixijs-input-devices
 ```
 
-#### Setup
+### Setup
 
 ```ts
-import { InputDevice, Navigation } from "pixijs-input-devices"
+import { InputDevice } from "pixijs-input-devices"
 
-// register mixin
-registerPixiJSInputDeviceMixin( Container )
-
-// add update loop
 Ticker.shared.add( () => InputDevice.update() )
+```
 
-// enable navigation
+_(Optional)_ Enable the Navigation API:
+
+```ts
+import { Navigation } from "pixijs-input-devices"
+
+// set root node
 Navigation.stage = app.stage
+
+// register mixin
+registerPixiJSInputDeviceMixin( Container )
 ```
 
-### ✨ Binding Groups
+## Overview
 
-Use named "groups" to create referenceable groups of inputs.
+There are a few very simple themes:
 
-```ts
-InputDevice.keyboard.options.namedGroups = {
-    jump: [ "ArrowUp", "Space", "KeyW" ],
-    crouch: [ "ArrowDown", "KeyS" ],
-    slower: [ "ShiftLeft", "ShiftRight" ],
-    left: [ "ArrowLeft", "KeyA" ],
-    right: [ "ArrowRight", "KeyD" ],
+- All devices are accessed through the `InputDevice` manager
+- There are three supported device types: ⌨️ `"keyboard"`, 🎮 `"gamepad"` and 👻 `"custom"`
+- Inputs can be accessed directly, or configured by [Named Groups](#named-input-groups)
 
-    toggleGraphics: [ "KeyB" ],
-    // other...
-};
+### InputDevice Manager
 
-GamepadDevice.defaultOptions.namedGroups = {
-    jump: [ "A" ],
-    crouch: [ "B", "X", "RightTrigger" ],
+The `InputDevice` singleton controls all device discovery.
 
-    toggleGraphics: [ "RightStick" ],
-    // other...
-};
+```ts
+InputDevice.keyboard  // KeyboardDevice
+InputDevice.gamepads  // Array<GamepadDevice>
+InputDevice.custom    // Array<CustomDevice>
 ```
 
-These can then be used with the real-time and event-based APIs.
+You can access all **active/connected** devices using `.devices`:
 
 ```ts
-// real-time:
-if ( gamepad.groupPressed("jump") ) doJump();
+for ( const device of InputDevice.devices ) {  // ...
+```
 
-// events:
-InputDevice.gamepads[0].onGroup( "jump", ( event ) => doJump() );
+#### InputDevice - properties
 
-// ...or listen to ANY device:
-InputDevice.onGroup( "toggleGraphics", ( event ) => toggleGraphics() );
-```
+| Property | Type | Description |
+|---|---|---|
+| `InputDevice.isMobile` | `boolean` | Whether the context is mobile (including tablets). |
+| `InputDevice.isTouchCapable` | `boolean` | Whether the context has touchscreen capability. |
+| `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 - on() Events
 
-You definitely do not have to use named inputs:
+Access global events directly through the manager:
 
 ```ts
-// real-time:
-if ( keyboard.key.Space || keyboard.key.KeyW ) jump = true;
-if ( gamepad.button.A || gamepad.button.LeftTrigger ) jump = true;
+InputDevice.on( "deviceconnected", ({ device }) => {
+    // a device was connected
+    // do additional setup here, show a dialog, etc.
+})
 
-// events:
-InputDevice.gamepads[0].on( "A", ( event ) => doJump() );
+InputDevice.off( "deviceconnected" ) // stop listening
 ```
 
-### Realtime API
+| Event | Description | Payload |
+|---|---|---|
+| `"deviceconnected"` | `{device}` | A device has become available. |
+| `"devicedisconnected"` | `{device}` | A device has been removed. |
 
-Iterate through `InputDevice.devices`, or access devices directly:
 
-```ts
-let jump = false, crouch = false, moveX = 0
+### KeyboardDevice
 
-const keyboard = InputDevice.keyboard
-if ( keyboard.groupPressed( "jump" ) ) jump = true
-if ( keyboard.groupPressed( "crouch" ) ) crouch = true
-if ( keyboard.groupPressed( "left" ) ) moveX -= 1
-if ( keyboard.groupPressed( "right" ) ) moveX += 1
-if ( keyboard.groupPressed( "slower" ) ) moveX *= 0.5
+Unlike gamepads & custom devices, there is a single global keyboard device.
 
-for ( const gamepad of InputDevice.gamepads ) {
-    if ( gamepad.groupPressed( "jump" ) ) jump = true
-    if ( gamepad.groupPressed( "crouch" ) ) crouch = true
+```ts
+let keyboard = InputDevice.keyboard
 
-    // 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 ( keyboard.key.ControlLeft ) {  // ...
 ```
 
-### Event API
+> [!NOTE]
+> **Detection:** On mobiles/tablets the keyboard will not appear in `InputDevice.devices` until
+> a keyboard is detected. See `keyboard.detected`.
 
-Use `on( ... )` to subscribe to built-in events. Use `onGroup( ... )` to subscribe to custom named input group events.
+#### Keyboard Layout - detection
 
 ```ts
-// global events
-InputDevice.on( "deviceconnected", ({ device }) =>
-    console.debug( "A new " + device.type + " device connected!" )
-)
+keyboard.layout  // "AZERTY" | "JCUKEN" | "QWERTY" | "QWERTZ"
 
-// device events
-InputDevice.keyboard.on( "layoutdetected", ({ layout }) =>
-    console.debug( "layout detected as " + layout );
-)
+keyboard.getKeyLabel( "KeyZ" )  // Я
+```
 
-// bind keys/buttons
-InputDevice.keyboard.on( "Escape", () => showMenu() )
-InputDevice.gamepads[0].on( "Back", () => showMenu() )
+> [!NOTE]
+> **Layout support:** Detects the **"big four"** (AZERTY, JCUKEN, QWERTY and QWERTZ).
+> 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)
+> when available, before falling back to default AZERTY, JCUKEN, QWERTY or QWERTZ key values.
 
-// use "onGroup()" to add custom events too:
-InputDevice.onGroup( "pause_menu", ( event ) => {
-    // menu was triggered!
-})
-```
+The keyboard layout is automatically detected from (in order):
 
-#### Global Events
+1. Browser API <sup>[(browser support)](https://caniuse.com/mdn-api_keyboardlayoutmap)</sup>
+2. Keypresses
+3. Browser Language
 
-| Event | Description | Payload |
-|---|---|---|
-| `"deviceconnected"` | `{device}` | A device has become available. |
-| `"devicedisconnected"` | `{device}` | A device has been removed. |
+You can also manually force the layout:
 
-#### Keyboard Device Events
+```ts
+// force layout
+InputDevice.keyboard.layout = "JCUKEN"
 
-| 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. |
-| `"group"` | `{groupName,event,keyCode,keyLabel,device}` | A named input group key was pressed. |
-| **Key presses:** | | |
-| `"KeyA"` \| `"KeyB"` \| ... 103 more ... | `{event,keyCode,keyLabel,device}` | `"KeyA"` was pressed. |
+InputDevice.keyboard.getKeyLabel( "KeyW" )  // "Ц"
+InputDevice.keyboard.layoutSource  // "manual"
+```
 
-#### Gamepad Device Events
+#### KeyboardDevice Events
 
 | Event | Description | Payload |
 |---|---|---|
-| `"group"` | `{groupName,button,buttonCode,device}` | A named input group button was pressed. |
-| **Button presses:** | | |
-| `"A"` \| `"B"` \| `"X"` \| ... 13 more ... | `{button,buttonCode,device}` | Button `"A"` was pressed. Equivalent to `0`. |
-| ... | ... | ... |
-| **Button presses (no label):** | | |
-| `0` \| `1` \| `2` \| ... 13 more ... | `{button,buttonCode,device}` | Button `0` was pressed. Equivalent to `"A"`. |
+| `"layoutdetected"` | `{layout,layoutSource,device}` | The keyboard layout (`"QWERTY"`, `"QWERTZ"`, `"AZERTY"`, or `"JCUKEN"`) has been detected, either from the native API or from keypresses. |
+| `"group"` | `{groupName,event,keyCode,keyLabel,device}` | A **named input group** key was pressed. |
+| **Key presses:** | | |
+| `"KeyA"` | `{event,keyCode,keyLabel,device}` | The `"KeyA"` was pressed. |
+| `"KeyB"` | `{event,keyCode,keyLabel,device}` | The `"KeyB"` was pressed. |
+| `"KeyC"` | `{event,keyCode,keyLabel,device}` | The `"KeyC"` was pressed. |
 | ... | ... | ... |
 
-> [!TIP]
-> **Multiplayer:** For multiple players, consider assigning devices
-> using `device.meta` (e.g. `device.meta.player = 1`) and use
-> `InputDevice.devices` to iterate through devices.
 
-### Navigation API
+### GamepadDevice
 
-By default, any element with `"mousedown"` or `"pointerdown"` handlers is navigatable.
+Gamepads are automatically detected via the browser API when first interacted with <sup>[(read more)](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API)</sup>.
 
-Container properties | type | default | description
----------------------|------|---------|--------------
-`isNavigatable`      | `boolean` | `false` | returns `true` if `navigationMode` is set to `"target"`, or is `"auto"` and a `"pointerdown"` or `"mousedown"` event handler is registered.
-`navigationMode`     | `"auto"` \| `"disabled"` \| `"target"` | `"auto"` | When set to `"auto"`, a `Container` can be navigated to if it has a `"pointerdown"` or `"mousedown"` event handler registered.
-`navigationPriority` | `number` | `0` | The priority relative to other navigation items in this group.
+Gamepad accessors are modelled around the "Standard Controller Layout":
 
-Navigation intent | Keyboard               | Gamepads
-------------------|------------------------|-----------------------------------
-`"navigateLeft"`  | `ArrowLeft`, `KeyA`    | Left Joystick (Left), `DPadLeft`
-`"navigateRight"` | `ArrowRight`, `KeyD`   | Left Joystick (Right), `DPadRight`
-`"navigateUp"`    | `ArrowUp`, `KeyW`      | Left Joystick (Up), `DPadDown`
-`"navigateDown"`  | `ArrowDown`, `KeyS`    | Left Joystick (Down), `DPadUp`
-`"navigateBack"`  | `Escape`, `Backspace`  | `B`, `Back`
-`"trigger"`       | `Enter,` `Space`       | `A`
+```ts
+let gamepad = InputDevice.gamepads[0]
 
-Container events  | description
-------------------|--------------------------------------------------------
-`focus`           | Target became focused.
-`blur`            | Target lost focus.
+if ( gamepad.button.Start ) {  // ...
+if ( gamepad.leftTrigger > 0.25 ) {  // ...
+if ( gamepad.leftJoystick.x > 0.5 ) {  // ...
+```
 
 > [!TIP]
-> Modify `device.options.navigation.binds` to override which keys/buttons are used for navigation.
->
-> Or set `device.options.navigation.enabled = false` to disable navigation.
+> **Special requirements?** You can always access `gamepad.source` and reference the
+> underlying API directly as needed.
 
+#### Vibration & Haptics
 
-### Devices
+Use the `playVibration()` method to play a haptic vibration, in supported browsers.
 
-#### Gamepads
+```ts
+gamepad.playVibration()
 
-##### Gamepad Layouts
+gamepad.playVibration({
+  duration: 150,
+  weakMagnitude: 0.25,
+  strongMagnitude: 0.65,
+})
+```
 
-> [!NOTE]
-> **Gamepad Labels:** The gamepad buttons are aliased with generic standard controller buttons in a Logitech/Xbox/Steam controller layout.
-
-| Button | ButtonCode | Name | Generic | Nintendo<br/>(*physical) | Playstation | Xbox |
-|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| `0` | `"A"` | **A** | A | B | Cross | A |
-| `1` | `"B"` | **B** | B | A | Circle | B |
-| `2` | `"X"` | **X** | X | Y | Square | X |
-| `3` | `"Y"` | **Y** | Y | X | Triangle | Y |
-| `4` | `"LeftShoulder"` | **Left Shoulder** | LeftShoulder | L | L1 | LB |
-| `5` | `"RightShoulder"` | **Right Shoulder** | RightShoulder | R | R1 | RB |
-| `6` | `"LeftTrigger"` | **Left Trigger** | LeftTrigger | L2 | ZL | LT |
-| `7` | `"RightTrigger"` | **Right Trigger** | RightTrigger | R2 | ZR | RT |
-| `8` | `"Back"` | **Back** | Back | Minus | Options | Back |
-| `9` | `"Start"` | **Start** | Start | Plus | Select | Start |
-| `10` | `"LeftStick"` | **Left Stick** | LeftStick | L3 | LeftStick | LSB |
-| `11` | `"RightStick"` | **Right Stick** | RightStick | R3 | RightStick | RSB |
-| `12` | `"DPadUp"` | **D-Pad Up** | DPadUp | DPadUp | DPadUp | DPadUp |
-| `13` | `"DPadDown"` | **D-Pad Down** | DPadDown | DPadDown | DPadDown | DPadDown |
-| `14` | `"DPadLeft"` | **D-Pad Left** | DPadLeft | DPadLeft | DPadLeft | DPadLeft |
-| `15` | `"DPadRight"` | **D-Pad Right** | DPadRight | DPadRight | DPadRight | DPadRight |
+#### Gamepad Button Codes
+
+The gamepad buttons reference **Standard Controller Layout**:
+
+| Button # | ButtonCode | Standard | Nintendo* | Playstation | Xbox |
+|:---:|:---:|:---:|:---:|:---:|:---:|
+| `0` | `"A"` | **A** | A | Cross | A |
+| `1` | `"B"` | **B** | X | Circle | B |
+| `2` | `"X"` | **X** | B | Square | X |
+| `3` | `"Y"` | **Y** | Y | Triangle | Y |
+| `4` | `"LeftShoulder"` | **Left Shoulder** | L | L1 | LB |
+| `5` | `"RightShoulder"` | **Right Shoulder** | R | R1 | RB |
+| `6` | `"LeftTrigger"` | **Left Trigger** | L2 | ZL | LT |
+| `7` | `"RightTrigger"` | **Right Trigger** | R2 | ZR | RT |
+| `8` | `"Back"` | **Back** | Minus | Options | Back |
+| `9` | `"Start"` | **Start** | Plus | Select | Start |
+| `10` | `"LeftStick"` | **Left Stick (click)** | L3 | L3 | LSB |
+| `11` | `"RightStick"` | **Right Stick (click)** | R3 | R3 | RSB |
+| `12` | `"DPadUp"` | **D-Pad Up** | ⬆️ | ⬆️ | ⬆️ |
+| `13` | `"DPadDown"` | **D-Pad Down** | ⬇️ | ⬇️ | ⬇️ |
+| `14` | `"DPadLeft"` | **D-Pad Left** |  ⬅️ | ⬅️ | ⬅️ |
+| `15` | `"DPadRight"` | **D-Pad Right** | ➡️ | ➡️ | ➡️ |
+
+*See [Nintendo Layout Remapping](#gamepad---nintendo-layout-remapping) for more context
+
+#### Gamepad Layouts
+
+```ts
+gamepad.layout  // "nintendo" | "xbox" | "playstation" | "logitech" | "steam" | "generic"
+```
+
+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
@@ -226,9 +226,9 @@ Container events  | description
 >
 > Set `GamepadDevice.defaultOptions.remapNintendoMode` to apply the remapping as required.
 >
-> - `"physical"` _(default)_ &ndash; A,B,X,Y refer the physical layout of a standard controller (Left=X,Top=Y,Bottom=A,Right=B).
-> - `"accurate"` &ndash; A,B,X,Y refer to the exact Nintendo labels (Left=Y,Top=X,Bottom=B,Right=A).
-> - `"none"` &ndash; A,B,X,Y refer to the button indices 0,1,2,3 (Left=Y,Top=B,Bottom=X,Right=A).
+> - `"physical"` _**(default)**_ &ndash; The A,B,X,Y button codes will refer the physical layout of a standard controller (Left=X, Top=Y, Bottom=A, Right=B).
+> - `"accurate"` &ndash; The A,B,X,Y button codes will correspond 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
@@ -244,9 +244,222 @@ Container events  | description
 >     0             0              1               2
 > ```
 
-#### Device assignment
+You can manually override this per-gamepad, or for all gamepads:
+
+```ts
+gamepad.options.remapNintendoMode = "none"
+GamepadDevice.defaultOptions.remapNintendoMode = "none"
+```
+
+#### GamepadDevice Events
+
+| Event | Description | Payload |
+|---|---|---|
+| `"group"` | `{groupName,button,buttonCode,device}` | A **named input group** 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`. |
+| ... | ... | ... |
+| **Button presses (no label):** | | |
+| `0` or `Button.A` | `{button,buttonCode,device}` | Button at offset `0` was pressed. |
+| `1` or `Button.B` | `{button,buttonCode,device}` | Button at offset `1` was pressed. |
+| `2` or `Button.X` | `{button,buttonCode,device}` | Button at offset `2` was pressed. |
+| ... | ... | ... |
+
+### Custom Devices
 
-You can assign IDs and other meta data using the `device.meta` dictionary.
+You can add custom devices to the device manager so it will be polled togehter and included in `InputDevice.devices`.
+
+```ts
+import { type CustomDevice, InputDevice } from "pixijs-input-devices"
+
+export const myDevice: CustomDevice = {
+    id: "on-screen-buttons",
+    type: "custom",
+    meta: {},
+    
+    update: ( now: number ) => {
+        // polling update
+    }
+}
+
+InputDevice.add( myDevice )
+```
+
+## Named Input Groups
+
+Use named "groups" to create named inputs that can be referenced.
+
+This allows you to change the keys/buttons later (e.g. allow users to override inputs).
+
+```ts
+// keyboard:
+InputDevice.keyboard.options.namedGroups = {
+    jump: [ "ArrowUp", "Space", "KeyW" ],
+    crouch: [ "ArrowDown", "KeyS" ],
+    toggleGraphics: [ "KeyB" ],
+}
+
+// all gamepads:
+GamepadDevice.defaultOptions.namedGroups = {
+    jump: [ "A" ],
+    crouch: [ "B", "X", "RightTrigger" ],
+    toggleGraphics: [ "RightStick" ],
+}
+```
+
+These can then be used with either the real-time and event-based APIs.
+
+#### Event-based:
+
+```ts
+// listen to all devices:
+InputDevice.onGroup( "toggleGraphics", ( e ) => toggleGraphics() )
+
+// listen to specific devices:
+InputDevice.keyboard.onGroup( "jump", ( e ) => doJump() )
+InputDevice.gamepads[0].onGroup( "jump", ( e ) => doJump() )
+```
+
+#### Real-time:
+
+```ts
+let jump = false, crouch = false, moveX = 0
+
+const keyboard = InputDevice.keyboard
+if ( keyboard.groupPressed( "jump" ) ) jump = true
+if ( keyboard.groupPressed( "crouch" ) ) crouch = true
+if ( keyboard.key.ArrowLeft ) moveX = -1
+else if ( keyboard.key.ArrowRight ) moveX = 1
+
+for ( const gamepad of InputDevice.gamepads ) {
+    if ( gamepad.groupPressed( "jump" ) ) jump = true
+    if ( gamepad.groupPressed( "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 )
+}
+```
+
+## Navigation API
+
+Automatically traverse existing pointer/mouse based menus using the `Navigation` API.
+
+```ts
+Navigation.stage = app.stage
+
+const button = new ButtonSprite()
+button.on( "mousedown", () => button.run( clickAnimation ) )
+button.on( "mouseout", () => button.run( resetAnimation ) )
+button.on( "mouseover", () => button.run( hoverAnimation ) )
+
+app.stage.addChild( button )
+
+button.isNavigatable  // true
+```
+
+> [!NOTE]
+> **isNavigatable:** By default, any element with `"mousedown"` or `"pointerdown"` handlers is navigatable.
+
+> [!WARNING]
+> **Fallback Hover Effect:** If there is no `"pointerover"` or `"mouseover"` handler detected on a container, `Navigation`
+>  will apply abasic alpha effect to the selected item to indicate which container is currently the navigation target. This
+> can be disabled by setting `Navigation.options.useFallbackHoverEffect` to `false`.
+
+### Disable Navigation
+
+You can **disable** the navigation API - either permanently or temporarily - like so:
+
+```ts
+Navigation.options.enabled = false
+```
+
+### Navigation Hierarchy
+
+UIs can be complex! The Navigation API allows you to take over some - or all - of the navigation elements.
+
+```ts
+class MyVerticalMenu implements NavigationResponder
+{
+    becameFirstResponder() {
+        console.log( "I'm in charge now!" )
+    }
+
+    resignedAsFirstResponder() {
+        console.log( "Nooo! My power is gone!" )
+    }
+
+    handledNavigationIntent( intent, device ): boolean {
+        if ( intent === "navigateUp" ) this.moveCursorUp()
+        else if ( intent === "navigateDown" ) this.moveCursorDown()
+        else if ( intent === "navigateBack" ) this.loseFocus()
+        else if ( intent === "trigger" ) this.clickCursorItem()
+
+        // we are going to return false here, which will propagates unhandled
+        // intents ("navigateLeft", "navigateRight") up to the next responder
+        // in the stack - which could be a parent view, etc.
+        return false
+    }
+}
+
+const myMenu = new MyVerticalMenu()
+Navigation.pushResponder( myMenu )
+```
+
+In a game, you might use this to disable navigation outside of menus:
+
+```ts
+class GameScene implements NavigationResponder
+{
+    handledNavigationIntent( intent, device ) {
+        // ignore navigation intents, but allow other navigatable
+        // views to be pushed on top of me - e.g. a dialog window:
+        return true
+    }
+}
+```
+
+### Default Navigation Binds
+
+Keyboard and gamepad devices are configured with a few default binds for navigation.
+
+The default binds are below:
+
+Navigation Intent | Keyboard               | Gamepad
+------------------|------------------------|-----------------------------------
+`"navigateLeft"`  | `ArrowLeft`, `KeyA`    | Left Joystick (Left), `DPadLeft`
+`"navigateRight"` | `ArrowRight`, `KeyD`   | Left Joystick (Right), `DPadRight`
+`"navigateUp"`    | `ArrowUp`, `KeyW`      | Left Joystick (Up), `DPadDown`
+`"navigateDown"`  | `ArrowDown`, `KeyS`    | Left Joystick (Down), `DPadUp`
+`"navigateBack"`  | `Escape`, `Backspace`  | `B`, `Back`
+`"trigger"`       | `Enter,` `Space`       | `A`
+
+These can be manually configured in `<device>.options.navigation.binds`.
+
+#### Container Mixin
+
+Container properties | type | default | description
+---------------------|------|---------|--------------
+`isNavigatable`      | `boolean` | `false` | returns `true` if `navigationMode` is set to `"target"`, or is `"auto"` and a `"pointerdown"` or `"mousedown"` event handler is registered.
+`navigationMode`     | `"auto"` \| `"disabled"` \| `"target"` | `"auto"` | When set to `"auto"`, a `Container` can be navigated to if it has a `"pointerdown"` or `"mousedown"` event handler registered.
+`navigationPriority` | `number` | `0` | The priority relative to other navigation items in this group.
+
+Container events  | description
+------------------|--------------------------------------------------------
+`focus`           | Target became focused.
+`blur`            | Target lost focus.
+
+
+## Advanced usage
+
+### Local Player Assignment
+
+Use the `<device>.meta` property to set assorted meta data on devices as needed.
+
+You lose TypeScript's nice strong types, but its very handy for things like user assignment in multiplayer games.
 
 ```ts
 InputDevice.on("deviceconnected", ({ device }) =>
@@ -263,20 +476,79 @@ for ( const device of InputDevice.devices )
 }
 ```
 
-#### Custom devices
+### On-Screen Inputs
 
-You can add custom devices to the device manager:
+You can easily map an on-screen input device using the `CustomDevice` interface.
 
 ```ts
-// 1. subclass CustomDevice
-class MySpecialDevice extends CustomDevice
-{
-    constructor() {
-        super( "special-device" )
+export class OnScreenInputContainer extends Container implements CustomDevice {
+    id = "onscreen";
+    type = "custom" as const;
+    meta: Record<string, any> = {};
+
+    inputs = {
+        moveX: 0.0
+        jump: false,
+    }
+
+    update( now )
+    {
+        this.moveX = this._virtualJoystick.x
+        this.jump = this._jumpButton.isTouching()
     }
 }
 
-// 2. add the device
-const device = new MySpecialDevice();
-InputDevice.add( device )
+const onscreen = new OnScreenInputContainer();
+
+InputDevice.add( onscreen )
+InputDevice.remove( onscreen )
+```
+
+### Two Users; One Keyboard
+
+You could set up multiple named inputs:
+
+```ts
+InputDevice.keyboard.options.namedGroups = {
+    jump: [ "ArrowUp", "KeyW" ],
+    defend: [ "ArrowDown", "KeyS" ],
+    left: [ "ArrowLeft", "KeyA" ],
+    right: [ "ArrowRight", "KeyD" ],
+
+    p1_jump: [ "KeyW" ],
+    p1_defend: [ "KeyS" ],
+    p1_left: [ "KeyA" ],
+    p1_right: [ "KeyD" ],
+
+    p2_jump: [ "ArrowUp" ],
+    p2_defend: [ "ArrowDown" ],
+    p2_left: [ "ArrowLeft" ],
+    p2_right: [ "ArrowRight" ],
+}
+```
+
+and then switch groups depending on the mode:
+
+```ts
+if ( gameMode === "2p" )
+{
+    // multiplayer
+    player1.jump = device.pressedGroup( "p1_jump" )
+    player1.defend = device.pressedGroup( "p1_defend" )
+    player1.moveX += device.pressedGroup( "p1_left" ) ? -1 : 0
+    player1.moveX += device.pressedGroup( "p1_right" ) ? 1 : 0
+    player2.jump = device.pressedGroup( "p2_jump" )
+    player2.defend = device.pressedGroup( "p2_defend" )
+    player2.moveX += device.pressedGroup( "p2_left" ) ? -1 : 0
+    player2.moveX += device.pressedGroup( "p2_right" ) ? 1 : 0
+}
+else
+{
+    // single player
+    player1.jump = device.pressedGroup( "jump" )
+    player1.defend = device.pressedGroup( "defend" )
+    player1.moveX += device.pressedGroup( "left" ) ? -1 : 0
+    player1.moveX += device.pressedGroup( "right" ) ? 1 : 0
+    player2.updateComputerPlayer()
+}
 ```