pixijs-input-devices 0.3.0 → 0.4.0

package/README.md

@@ -1,47 +1,104 @@
-# 🕹️ pixijs-input-devices  [![NPM version](https://img.shields.io/npm/v/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices) [![Minzipped](https://badgen.net/bundlephobia/minzip/pixijs-input-devices@latest)](https://bundlephobia.com/package/pixijs-input-devices) [![Downloads per month](https://img.shields.io/npm/dm/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices) [![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) [![License](https://badgen.net/npm/license/pixijs-input-devices)](https://github.com/reececomo/pixijs-input-devices/blob/main/LICENSE)
+# 🕹️ 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)
 
-🚧 WIP - This API is a work in progress, and is subject to change.
+⚡ Powerful, high-performance input device management for PixiJS
 
-- 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)_
+| | |
+| ------ | ------ |
+| 🎮 Handles [keyboards](#keyboarddevice), [gamepads](#gamepaddevice), and [more](#custom-devices)! | 🚀 Flexible [low-level](#real-time) and [event-driven](#keyboarddevice-events) APIs |
+| 🔮 Resolves browser API inconsistencies <sup>[[1]](https://caniuse.com/mdn-api_keyboardlayoutmap) [[2]](https://caniuse.com/mdn-api_gamepad_vibrationactuator) [[3]](https://chromestatus.com/feature/5989275208253440)</sup> | 🧭 Seamless [navigation](#navigation-api) for pointer/mouse based UIs |
+| 📱 Powerful configuration options, sensible defaults | 🌐 Automatic i18n (built-in [internationalization](#keyboard-layout---detection)) |
+| ⚡ Optimized for speed (best-in-class [INP performance](https://web.dev/articles/inp)) | 🔀 Named binds (for [user-configurable inputs](#named-binds)) |
+| 🍃 Zero dependencies & tree-shakeable | ✨ Supports PixiJS v8, v7, v6.3+ |
 
-<hr/>
 
-## 💿 Install
+## Sample Usage
+
+*Handle device inputs with ease.*
+
+```ts
+import { InputDevice } from "pixijs-input-devices";
+
+// Iterative
+let jump = false
+
+for (const device of InputDevice.devices) {
+  if (device.type === "keyboard" && device.key.Space) jump = true
+  if (device.type === "gamepad" && device.button.A) jump = true
+}
+
+// Event-driven
+const gamepad = InputDevice.gamepads[0]
+
+gamepad?.on("LeftShoulder", (e) => {
+    e.device.playVibration({ duration: 100 })
+});
+```
+
+## Getting Started with PixiJS Input Devices
+
+*Everything you need to quickly integrate powerful device management.*
+
+**PixiJS Input Devices** adds first-class support for input device management and input handling. It also provides an optional navigation manager
+that can enable input devices to traverse pointer-based UIs.
+
+The core concepts are:
+
+1. **Devices:** _Any human interface device_
+2. **Binds:** _Custom, named input actions that can be triggered by assigned keys or buttons_
+3. **Navigation:** _A global controller that allows non-pointer devices to navigate UIs_
+
+> [!NOTE]
+> _See [Navigation API](#navigation-api) for more information._
+
+
+## Installation
+
+*Quick start guide.*
+
+**1.** Install the latest `pixijs-input-devices` package:
 
 ```sh
-npm i pixijs-input-devices
+# npm
+npm install pixijs-input-devices -D
+
+# yarn
+yarn add pixijs-input-devices --dev
 ```
 
-### Setup
+**2.** Register the update loop:
 
 ```ts
-import { InputDevice } from "pixijs-input-devices"
+import * as PIXI from 'pixi.js';
+import { InputDevice } from 'pixijs-input-devices';
 
-Ticker.shared.add( () => InputDevice.update() )
+// register `InputDevice.update()` with shared ticker
+Ticker.shared.add(ticker => InputDevice.update());
 ```
 
-_(Optional)_ Enable the Navigation API:
+> [!TIP]
+> **Input polling:** In the context of a video game, you may want to put the input update at the start of your game event loop insteaad
+
+> [!NOTE]
+> _If not using a PixiJS ticker, then just put `Action.tick(elapsedMs)` in the appropriate equivalent place (i.e. your `requestAnimationFrame()` render loop)._
+
+**3.** (Optional) enable the Navigation API
 
 ```ts
-import { Navigation } from "pixijs-input-devices"
+import * as PIXI from 'pixi.js';
+import { Navigation, registerPixiJSInputDevicesMixin } from 'pixijs-input-devices';
 
-// set root node
-Navigation.stage = app.stage
+// register container mixin
+registerPixiJSInputDevicesMixin(PIXI.Container);
 
-// register mixin
-registerPixiJSInputDeviceMixin( Container )
-```
+const app = new PIXI.Application(/*…*/)
 
-## Overview
+// set the root view for device navigation
+Navigation.stage = app.stage
+```
 
-There are a few very simple themes:
+✨ You are now ready to use inputs!
 
-- 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)
+## Features
 
 ### InputDevice Manager
 
@@ -56,7 +113,7 @@ InputDevice.custom    // Array<CustomDevice>
 You can access all **active/connected** devices using `.devices`:
 
 ```ts
-for ( const device of InputDevice.devices ) {  // ...
+for ( const device of InputDevice.devices ) {  // …
 ```
 
 #### InputDevice - properties
@@ -76,18 +133,18 @@ for ( const device of InputDevice.devices ) {  // ...
 Access global events directly through the manager:
 
 ```ts
-InputDevice.on( "deviceconnected", ({ device }) => {
+InputDevice.on( "deviceadded", ({ device }) => {
     // a device was connected
     // do additional setup here, show a dialog, etc.
 })
 
-InputDevice.off( "deviceconnected" ) // stop listening
+InputDevice.off( "deviceadded" ) // stop listening
 ```
 
 | Event | Description | Payload |
 |---|---|---|
-| `"deviceconnected"` | `{device}` | A device has become available. |
-| `"devicedisconnected"` | `{device}` | A device has been removed. |
+| `"deviceadded"` | `{device}` | A device has been added. |
+| `"deviceremoved"` | `{device}` | A device has been removed. |
 
 
 ### KeyboardDevice
@@ -97,7 +154,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]
@@ -141,12 +198,12 @@ 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. |
-| `"group"` | `{groupName,event,keyCode,keyLabel,device}` | A **named input group** key was pressed. |
+| `"bind"` | `{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. |
 | `"KeyC"` | `{event,keyCode,keyLabel,device}` | The `"KeyC"` was pressed. |
-| ... | ... | ... |
+| … | … | … |
 
 
 ### GamepadDevice
@@ -158,9 +215,9 @@ Gamepad accessors are modelled around the "Standard Controller Layout":
 ```ts
 let gamepad = InputDevice.gamepads[0]
 
-if ( gamepad.button.Start ) {  // ...
-if ( gamepad.leftTrigger > 0.25 ) {  // ...
-if ( gamepad.leftJoystick.x > 0.5 ) {  // ...
+if ( gamepad.button.Start ) {  // …
+if ( gamepad.leftTrigger > 0.25 ) {  // …
+if ( gamepad.leftJoystick.x > 0.5 ) {  // …
 ```
 
 > [!TIP]
@@ -172,12 +229,11 @@ if ( gamepad.leftJoystick.x > 0.5 ) {  // ...
 Use the `playVibration()` method to play a haptic vibration, in supported browsers.
 
 ```ts
-gamepad.playVibration()
-
 gamepad.playVibration({
-  duration: 150,
-  weakMagnitude: 0.25,
-  strongMagnitude: 0.65,
+    duration: 150,
+    weakMagnitude: 0.75,
+    strongMagnitude: 0.25,
+    // …
 })
 ```
 
@@ -255,17 +311,17 @@ GamepadDevice.defaultOptions.remapNintendoMode = "none"
 
 | Event | Description | Payload |
 |---|---|---|
-| `"group"` | `{groupName,button,buttonCode,device}` | A **named input group** button was pressed. |
+| `"bind"` | `{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`. |
-| ... | ... | ... |
+| … | … | … |
 | **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
 
@@ -287,22 +343,22 @@ export const myDevice: CustomDevice = {
 InputDevice.add( myDevice )
 ```
 
-## Named Input Groups
+## Named Binds
 
-Use named "groups" to create named inputs that can be referenced.
+Use _named binds_ to create mappings between abstract inputs and the keys/buttons that trigger those inputs.
 
 This allows you to change the keys/buttons later (e.g. allow users to override inputs).
 
 ```ts
 // keyboard:
-InputDevice.keyboard.options.namedGroups = {
+InputDevice.keyboard.options.binds = {
     jump: [ "ArrowUp", "Space", "KeyW" ],
     crouch: [ "ArrowDown", "KeyS" ],
     toggleGraphics: [ "KeyB" ],
 }
 
 // all gamepads:
-GamepadDevice.defaultOptions.namedGroups = {
+GamepadDevice.defaultOptions.binds = {
     jump: [ "A" ],
     crouch: [ "B", "X", "RightTrigger" ],
     toggleGraphics: [ "RightStick" ],
@@ -315,11 +371,11 @@ These can then be used with either the real-time and event-based APIs.
 
 ```ts
 // listen to all devices:
-InputDevice.onGroup( "toggleGraphics", ( e ) => toggleGraphics() )
+InputDevice.onBind( "toggleGraphics", ( e ) => toggleGraphics() )
 
 // listen to specific devices:
-InputDevice.keyboard.onGroup( "jump", ( e ) => doJump() )
-InputDevice.gamepads[0].onGroup( "jump", ( e ) => doJump() )
+InputDevice.keyboard.onBind( "jump", ( e ) => doJump() )
+InputDevice.gamepads[0].onBind( "jump", ( e ) => doJump() )
 ```
 
 #### Real-time:
@@ -328,14 +384,14 @@ InputDevice.gamepads[0].onGroup( "jump", ( e ) => doJump() )
 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.bindPressed( "jump" ) ) jump = true
+if ( keyboard.bindPressed( "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
+    if ( gamepad.bindPressed( "jump" ) ) jump = true
+    if ( gamepad.bindPressed( "crouch" ) ) crouch = true
 
     // gamepads have additional analog inputs
     // we're going to apply these only if touched
@@ -346,122 +402,64 @@ for ( const gamepad of InputDevice.gamepads ) {
 
 ## Navigation API
 
-Automatically traverse existing pointer/mouse based menus using the `Navigation` API.
+_Traverse a UI using input devices._
 
-```ts
-// set root container
-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 ) )
+The Navigation API is centered around a central **Navigation** controller, which listens to navigation intents from devices,
+then handles the intent.
 
-app.stage.addChild( button )
-
-button.isNavigatable  // true
-```
+The **Navigation** controller maintains a stack of `NavigationResponder` objects, which represent the **current navigation context**. For
+example, you might add a `NavigationResponder` for a drop-down UI. A normal `Container` can be used as a `NavigationResponder`, and any
+container on the stack will become the **current root container**.
 
 > [!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`.
+> The **current root container** is the top-most `Container` on the navigation responder stack, or otherwise `Navigation.stage`.
 
-### Disable Navigation
+When a device sends a navigation intent, the **Navigation** controller is responsible for asking each of the responders on the stack
+if it can handle the intent. If it can't, it is propagated up all the way to the **current root container**.
 
-You can **disable** the navigation API - either permanently or temporarily - like so:
+### Default UI Navigation Behavior
 
-```ts
-Navigation.options.enabled = false
-```
+When a navigation intent is **not** handled manually by a responder, it is handled in one of the following ways:
 
-### NavigationResponders
+| Intent | Behavior |
+|---|---|
+|`"navigateBack"`|<ul><li>No action.</li></ul>|
+|`"navigateLeft"`, `"navigateRight"`, `"navigateUp"`, `"navigateDown"`|<ul><li>Looks for the nearest `Container` where `container.isNavigatable` in the direction given, and if found, fires a `"focus"` event on it.</li><li>Additionally, if the newly focused container has registered an event handler for either `"pointerover"` or `"mouseover"` (in that order), it will fire that too.</li><li>If we were previously focused on a container, that previous container fires a `"blur"` event.</li><li>If the blurred container has register an event handler for either `"pointerout"` or `"mouseout"` (in that order), that event handler will be fired too.</li></ul>|
+|`"trigger"`|<ul><li>Checks if we are currently focused on a container, and then issue a `"trigger"` event.</li><li>If the focused container has registered an event handler for either `"pointerdown"` or `"mousedown"` (in that order), that event handler will be fired too.</li></ul>|
 
-UIs can be complex! The Navigation API allows you to take over some - or all - of the navigation elements.
+Container event  | Description | Equivalent
+-----------------|--------------------------------------------------------
+`trigger`        | Target was triggered. | `"pointerdown"`, `"mousedown"`
+`focus`          | Target became focused. | `"pointerover"`, `"mouseover"`
+`blur`           | Target lost focus. | `"pointerout"`, `"mouseout"`
 
-You can create **NavigationResponder** controllers, which can be a `Container` that becomes the
-"root" node for navigation. It can also just be any object (like a custom manager class).
+### Container Navigation
 
-It has a method called `handledNavigationIntent(): boolean` which can return a boolean saying whether
-the navigation event was handled. If you return false here, it is bubbled up to the next parent in the
-stack.
+Containers are extended with a few properties/accesors:
 
-To add a responder, just use `Navigation.pushResponder( responder )` - and then remove it with `Navigation.popResponder()`.
+Container properties | type | default | description
+---------------------|------|---------|--------------
+`isNavigatable`      | `get(): 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.
 
-```ts
-class MyVerticalMenu implements NavigationResponder
-{
-    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
-    }
+> [!NOTE]
+> **isNavigatable:** By default, any element with `"pointerdown"` or `"mousedown"` handlers is navigatable.
 
-    becameFirstResponder() {
-        console.log( "I'm in charge now!" )
-    }
+> [!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`.
 
-    resignedAsFirstResponder() {
-        console.log( "Nooo! My power is gone!" )
-    }
-}
 
-const myMenu = new MyVerticalMenu()
-Navigation.pushResponder( myMenu )
-```
+### Disable Navigation
 
-In a game, you might use this to disable navigation outside of menus:
+You can **disable** the navigation API entirely, either permanently or temporaril):
 
 ```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
-    }
-}
+Navigation.options.enabled = false
 ```
 
-### 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
 
@@ -519,7 +517,7 @@ InputDevice.remove( onscreen )
 You could set up multiple named inputs:
 
 ```ts
-InputDevice.keyboard.options.namedGroups = {
+InputDevice.keyboard.options.binds = {
     jump: [ "ArrowUp", "KeyW" ],
     defend: [ "ArrowDown", "KeyS" ],
     left: [ "ArrowLeft", "KeyA" ],
@@ -540,25 +538,25 @@ InputDevice.keyboard.options.namedGroups = {
 and then switch groups depending on the mode:
 
 ```ts
-if ( gameMode === "2p" )
+if ( gameMode === "multiplayer" )
 {
-    // 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
+    player1.jump   = device.bindPressed( "p1_jump" )
+    player1.defend = device.bindPressed( "p1_defend" )
+    player1.moveX += device.bindPressed( "p1_left" ) ? -1 : 0
+    player1.moveX += device.bindPressed( "p1_right" ) ? 1 : 0
+
+    player2.jump   = device.bindPressed( "p2_jump" )
+    player2.defend = device.bindPressed( "p2_defend" )
+    player2.moveX += device.bindPressed( "p2_left" ) ? -1 : 0
+    player2.moveX += device.bindPressed( "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()
+    player1.jump   = device.bindPressed( "jump" )
+    player1.defend = device.bindPressed( "defend" )
+    player1.moveX += device.bindPressed( "left" ) ? -1 : 0
+    player1.moveX += device.bindPressed( "right" ) ? 1 : 0
+
+    updateComputerPlayerInput( player2 )
 }
 ```