pixijs-input-devices 0.1.2 → 0.2.0

package/README.md

@@ -1,578 +1,218 @@
-# 🕹️ 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 &nbsp[![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)
 
 WIP
 
-- Adds support for ⌨️ keyboards, 🎮 gamepads, and other human interface devices
-- Built-in event API for navigating user-focusable elements
-- Built-in polling API for real-time inputs
+- 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
 
 <hr/>
 
-```ts
-// set up ticker (or put in your main update loop):
-Ticker.shared.add( () => InputDeviceManager.shared.update() );
-```
-
-### Realtime API (polling)
-
-Simple example
-
-```ts
-let jump = false;
-let hide = false;
-let moveX = 0.0;
-
-for ( const device of InputDeviceManager.shared.devices )
-{
-  if ( device.type === "keyboard" )
-  {
-    if ( device.key["ArrowUp"] ) jump = true
-    if ( device.key["ArrowDown"] ) hide = true
-    if ( device.key["ArrowLeft"] ) moveX = -1.0
-    if ( device.key["ArrowRight"] ) moveX = 1.0
-  }
-  else if ( device.type === "gamepad" )
-  {
-    if ( device.button[Button.A] ) jump = true
-    if ( device.rightTrigger >= 0.25 ) hide = true
-    if ( device.leftJoystick.x !== 0.0 ) moveX = device.leftJoystick.x
-  }
-}
-```
-
-> [!NOTE]
-> You can use `device.button[Button.RightTrigger]` to detect triggers too.
-
-> [!NOTE]
-> You can use `device.pressingAll([...])` and `device.pressingAny([...])` to check groups of keys/buttons.
-
-> [!NOTE]
-> You can use `device.assignee` to store any device assignment-related data (such as a user ID).
-
-
-### Event-driven API
-
-```
-InputDeviceManager.shared.keyboard.bindGlobal({
-  { key: "KeyA", action}
-})
-```
-
-By default, any element with "mousedown" or "pointerdown" will
-
-Container events  | description
-------------------|--------------------------------------------------------
-`focus`           | Target became focused. args: direction: { x, y }
-`blur`            | Target lost focus. args: direction: { x, y }
-`focusHinted`     | Target may be about to become focused. args: direction: { x, y }
-`blurHinted`      | Target may be about to lose focus. args: direction: { x, y }
-
-Container properties | description
----------------------|-----------------------------------------------------
-`focusable`          | boolean?, default: `undefined`
-`isFocusGroup`       | boolean?, default: `false`
-`focusPriority`      | number?, default: `0`
-`focusGroup`         | PIXI.Container?, default: `app.stage ?? undefined`
-`focusTransform`     | `{ x, y }`, default: `{ x: 5, y: 5 }`
-`isFocusable`        | get () => boolean, returns true if "focusable" = true, or InputDevice.defaultOptions.autoFocusable and has "mousedown", "pointerdown"
-
-Device gesture   | Keyboard (primary) | Keyboard (alt)  | Gamepad
------------------|--------------------|-----------------|------------------
-`"moveFocusLeft"`  | Left Arrow Key     | A Key           | Left Stick Left
-`"moveFocusRight"` | Right Arrow Key    | D Key           | Left Stick Right
-`"moveFocusUp"`    | Up Arrow Key       | W Key           | Left Stick Up
-`"moveFocusDown"`  | Down Arrow Key     | S Key           | Left Stick Down
-`"focusover"`      | Return Key         | Space           | A Button
-`"moveUpOneLevel"` | Escape Key         | Backspace       | B Button
-
-
-### Global defaults:
-
-```ts
-InputDevice.defaultOptions = {
-  /** Globally enable/disable the navigation API. (i.e. if the browser loses focus). */
-  focusEnabled: true,
-  /**
-   * (default: true) When enabled, any element with "mousedown" or "pointerdown"
-   * is considered focusable. The "focusableTransform" will also apply.
-   */
-  autoFocusable: true,
-  focusableTransform: { x: 5, y: 5 },
-  keyboard: {
-    enabled: true,
-    layouts: [ "qwerty", "azerty", "jcuken", "qwertz" ],
-    autoLanguageLayout: true, // fr*/nl-BE* -> azerty, uk*/ru* -> jcuken
-    internationalization: {
-      /** when true, labels are mapped to their layout */
-      mapLabels: true,
-    }
-  },
-  gamepad: {
-    enabled: true,
-    layouts: [ "standard", "nintendo" ],
-    firstIntentCooldownMs: 400,
-    intentCooldownMs: 100,
-  },
-}
-```
-
-```ts
-class InputDevice {
-  
-}
-
-```
-
-
-<hr/>
-
-<hr/>
-
-
-⚡ Powerful, high-performance animations for PixiJS
-
-| | |
-| ------ | ------ |
-| 🔮 Simple, declarative API | 🎬 Based on [Cocos2d](https://docs.cocos2d-x.org/cocos2d-x/v3/en/actions/getting_started.html)/[SKActions](https://developer.apple.com/documentation/spritekit/getting_started_with_actions) |
-| 🚀 35+ [built-in actions](#action-initializers), 30+ [timing modes](#timing-modes) | 🔀 Reuseable, chainable & reversible |
-| 🍃 No dependencies & tree-shakeable | ⌚ Full speed/pausing control |
-| 🤏 `~4.3kb` minzipped | ✨ Supports PixiJS 8+, 7+, 6.3+ |
-
-
-## Sample Usage
-
-*Create, configure, and run animations & actions.*
-
-```ts
-// Define an action
-const spinAndRemove = Action.sequence([
-  Action.rotateByDegrees(360, 0.2).easeInOut(),
-  Action.fadeOut(0.2).easeIn(),
-  Action.removeFromParent(),
-  Action.run(() => console.info('✨ done!'))
-]);
-
-// Run an action
-mySprite.run(spinAndRemove);
-```
-
-## Getting Started with PixiJS Actions
-
-*Everything you need to quickly build beautiful animations.*
-
-**PixiJS Actions** is based off the idiomatic and expressive [**SKActions API**](https://developer.apple.com/documentation/spritekit/getting_started_with_actions), extending `Container` to add first-class support for running and managing actions.
-
-The core concepts are:
-
-1. **Nodes:** _Any container (e.g. `Container`, `Sprite`, `Graphics`)_
-2. **Actions:** _Stateless, reusable recipes_ (e.g. animations, triggers, and more)
-3. **TimingMode & speed:** _Controls for the speed & smoothness of actions and animations_
-
-> [!NOTE]
-> _See [Timing Modes](#timing-modes) and [Manipulating Action Speed](#manipulating-action-speed) for more information._
-
-
-## Installation
-
-*Quick start guide.*
-
-**1.** Install the latest `pixijs-input-devices` package:
+### 💿 Install
 
 ```sh
-# npm
-npm install pixijs-input-devices -D
-
-# yarn
-yarn add pixijs-input-devices --dev
+npm i pixijs-input-devices
 ```
 
-**2.** Register the mixin & ticker:
+#### Setup
 
 ```ts
-import * as PIXI from 'pixi.js';
-import { Action, registerPixiJSActionsMixin } from 'pixijs-input-devices';
-
-// register container mixin
-registerPixiJSActionsMixin(PIXI.Container);
+import { InputDevice, Navigation } from "pixijs-input-devices"
 
-// register `Action.tick(...)` with shared ticker
-Ticker.shared.add(ticker => Action.tick(ticker.elapsedMS));
-```
-
-> [!TIP]
-> **PixiJS 7 / 6.3+:**
-> 
-> ```ts
-> Ticker.shared.add(() => Action.tick(Ticker.shared.elapsedMS));
-> // or
-> Ticker.shared.add((dt) => Action.tick(dt));
-> ```
-
-> [!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.** Done!
-
-✨ You are now ready to run your first action!
+// register mixin
+registerPixiJSInputDeviceMixin( Container )
 
-## Running Actions
+// add update loop
+Ticker.shared.add( () => InputDevice.update() )
 
-*Running actions in your canvas.*
-
-```ts
-// Hide me instantly!
-mySprite.run(Action.hide(), () => {
-  console.log('where did I go?');
-});
+// enable nav
+Navigation.stage = app.stage
 ```
 
-Nodes are extended with a few new methods and properties to make it easy to interact with actions.
-
-| Property | Description |
-| :----- | :------ |
-| `speed` | A speed modifier applied to all actions executed by the node and its descendants. Defaults to `1.0`. |
-| `isPaused` | A boolean value that determines whether actions on the node and its descendants are processed. Defaults to `false`. |
-
-| Method | Description |
-| :----- | :------ |
-| `run(action)` | Run an action. |
-| `run(action, completion)` | Run an action with a completion handler. |
-| `runWithKey(action, withKey)` | Run an action, and store it so it can be retrieved later. |
-| `runAsPromise(action): Promise<void>` | Run an action as a promise. |
-| `action(forKey): Action \| undefined` | Return an action associated with a specified key. |
-| `hasActions(): boolean` | Return a boolean indicating whether the node is executing actions. |
-| `removeAllActions(): void` | End and removes all actions from the node. |
-| `removeAction(forKey): void` | Remove an action associated with a specified key. |
+### Realtime API
 
-### Running Identifiable Actions
+Simple example:
 
 ```ts
-// Repeat an action forever!
-const spin = Action.repeatForever(Action.rotateBy(5, 1.0));
-mySprite.runWithKey(spin, 'spinForever');
+let jump = false,
+    hide = false,
+    moveX = 0.0;
 
-// Or remove it later.
-mySprite.removeAction('spinForever');
-```
-
-### Pausing All Actions
+// keyboard:
+const kb = InputDevice.keyboard;
+if ( kb.key.ArrowUp ) jump = true
+if ( kb.key.ArrowDown ) hide = true
+if ( kb.key.ArrowLeft ) moveX = -1.0
+else if ( kb.key.ArrowRight ) moveX = 1.0
 
-```ts
-mySprite.isPaused = true;
-// All actions will stop running.
-```
-
-### Manipulating Action Speed
-
-Speed can be manipulated on both actions and nodes.
-
-```ts
-const moveAction = Action.moveByX(10, 4.0);
-moveAction.speed = 2.0;
-// moveAction will now take only 2 seconds instead of 4.
-
-const repeatAction = Action.repeat(moveAction, 5);
-repeatAction.speed = 2.0;
-// Each moveAction will only take 1 second, for a total of 5 seconds.
-
-mySprite.run(moveAction);
-mySprite.speed = 2.0;
-// mySprite is running at 2x speed!
-// The entire action should now take ~2.5 seconds.
-
-mySprite.parent!.speed = 1 / 4;
-// Now we've slowed down mySprite's parent.
-// The entire action will now take ~10 seconds.
+// gamepads:
+for ( const gamepad of InputDevice.gamepads )
+{
+  if ( gamepad.button.A ) jump = true
+  if ( gamepad.rightTrigger > 0.25 ) hide = true
+  if ( gamepad.leftJoystick.x !== 0.0 ) moveX = gamepad.leftJoystick.x
+}
 ```
 
-> [!NOTE]
-> Changes to nodes' `speed` will take effect immediately, however changes to an `Action` initializer's `speed` or `timingMode` will not affect any actions that have already begun running.
-
-## Action Initializers
-
-*Combine these initializers to create expressive animations and behaviors.*
-
-Most actions implement specific predefined animations that are ready to use. If your animation needs fall outside of the suite provided here, then you should implement a custom action (see [Creating Custom Actions](#creating-custom-actions)).
-
-| Action | Description | Reversible? |
-| :----- | :---------- | :---------- |
-|***Chaining Actions***|||
-| `Action.group(actions)` | Run multiple actions in parallel. | Yes |
-| `Action.sequence(actions)` | Run multiple actions sequentially. | Yes |
-| `Action.repeat(action, count)` | Repeat an action a specified number of times. | Yes |
-| `Action.repeatForever(action)` | Repeat an action indefinitely. | Yes |
-|***Animating a Node's Position in a Linear Path***|||
-| `Action.moveBy(vector, duration)` | Move a node by a relative vector `{ x, y }` (e.g. `PIXI.Point`). | Yes |
-| `Action.moveBy(dx, dy, duration)` | Move a node by relative values. | Yes |
-| `Action.moveByX(dx, duration)` | Move a node horizontally by a relative value. | Yes |
-| `Action.moveByY(dy, duration)` | Move a node vertically by a relative value. | Yes |
-| `Action.moveTo(position, duration)` | Move a node to a specified position `{ x, y }` (e.g. `PIXI.Point`, `PIXI.Container`). |  _*No_ |
-| `Action.moveTo(x, y, duration)` | Move a node to a specified position. |  _*No_ |
-| `Action.moveToX(x, duration)` | Move a node to a specified horizontal position. |  _*No_ |
-| `Action.moveToY(y, duration)` | Move a node to a specified vertical position. |  _*No_ |
-|***Animating a Node's Position Along a Custom Path***|||
-| `Action.follow(path, duration)` | Move a node along a path, optionally orienting the node to the path. |  Yes | Yes |
-| `Action.followAtSpeed(path, speed)` | Move a node along a path at a specified speed, optionally orienting the node to the path. |  Yes |
-|***Animating the Rotation of a Node***|||
-| `Action.rotateBy(delta, duration)` | Rotate a node by a relative value (in radians). | Yes |
-| `Action.rotateByDegrees(delta, duration)` | Rotate a node by a relative value (in degrees). | Yes |
-| `Action.rotateTo(radians, duration)` | Rotate a node to a specified value (in radians). |  _*No_ |
-| `Action.rotateToDegrees(degrees, duration)` | Rotate a node to a specified value (in degrees). | _*No_ |
-|***Animating the Scaling of a Node***|||
-| `Action.scaleBy(vector, duration)` | Scale a node by a relative vector `{ x, y }` (e.g. `PIXI.Point`). | Yes |
-| `Action.scaleBy(scale, duration)` | Scale a node by a relative value. | Yes |
-| `Action.scaleBy(dx, dy, duration)` | Scale a node in each axis by relative values. | Yes |
-| `Action.scaleByX(dx, duration)` | Scale a node horizontally by a relative value. | Yes |
-| `Action.scaleByY(dy, duration)` | Scale a node vertically by a relative value. | Yes |
-| `Action.scaleTo(size, duration)` | Scale a node to achieve a specified size `{ width, height }` (e.g. `PIXI.ISize`, `PIXI.Container`). |  _*No_ |
-| `Action.scaleTo(scale, duration)` | Scale a node to a specified value. |  _*No_ |
-| `Action.scaleTo(x, y, duration)` | Scale a node in each axis to specified values. |  _*No_ |
-| `Action.scaleToX(x, duration)` | Scale a node horizontally to a specified value. |  _*No_ |
-| `Action.scaleToY(y, duration)` | Scale a node vertically to a specified value. |  _*No_ |
-|***Animating the Transparency of a Node***|||
-| `Action.fadeIn(duration)` | Fade the alpha to `1.0`. | Yes |
-| `Action.fadeOut(duration)` | Fade the alpha to `0.0`. | Yes |
-| `Action.fadeAlphaBy(delta, duration)` | Fade the alpha by a relative value. | Yes |
-| `Action.fadeAlphaTo(alpha, duration)` | Fade the alpha to a specified value. |  _*No_ |
-|***Controlling a Node's Visibility***|||
-| `Action.unhide()` | Set a node's `visible` property to `true`. | Yes |
-| `Action.hide()` | Set a node's `visible` property to `false`. | Yes |
-|***Removing a Node from the Canvas***|||
-| `Action.removeFromParent()` | Remove a node from its parent. | _†Identical_ |
-|***Running Actions on Children***|||
-| `Action.runOnChild(nameOrLabel, action)` | Add an action to a child node. | Yes |
-|***Delaying Actions***|||
-| `Action.waitForDuration(duration)` | Idle for a specified period of time. | _†Identical_ |
-| `Action.waitForDurationWithRange(duration, range)` | Idle for a randomized period of time. | _†Identical_ |
-|***Triggers and Custom Actions***|||
-| `Action.run(callback)` | Execute a block (i.e. trigger another action). | _†Identical_ |
-| `Action.customAction(duration, stepHandler)` | Execute a custom stepping function over the action duration. | _†Identical_ |
-|***Manipulating the Action Speed of a Node***|||
-| `Action.speedBy(delta, duration)` | Change how fast a node executes its actions by a relative value. | Yes |
-| `Action.speedTo(speed, duration)` | Set how fast a node executes actions to a specified value. |  _*No_ |
-
-> [!IMPORTANT]
-> #### Reversing Actions
-> Every action initializer has a `.reversed()` method which will return a new action. Some actions are **not reversible**, and these cases are noted in the table above:
-> - _**†Identical**_ &mdash; The reversed action is identical to the original action.
-> - _**\*No**_ &mdash; The reversed action will idle for the equivalent duration.
-
-### Action Chaining
-
-Many actions can be joined together using `Action.sequence()`, `Action.group()`, `Action.repeat()` and `Action.repeatForever()` to quickly create complex animations:
+### Event API
 
 ```ts
-import { Action } from 'pixijs-input-devices';
-
-// Expand and contract smoothly over 2 seconds
-const pulsate = Action.sequence([
-  Action.scaleTo(1.5, 1.0).easeOut(),
-  Action.scaleTo(1, 1.0).easeIn()
-]);
-
-// Follow a complex path (e.g. a bezier curve)
-const path = [
-  { x: 0, y: 0 },
-  { x: 100, y: 0 },
-  { x: 100, y: 100 },
-  { x: 200, y: 200 }
-];
-const followPath = Action.follow(path, 5.0);
-
-// Create a 10 second loop that goes back and forth
-const moveBackAndForthWhilePulsating = Action.group([
-  Action.repeat(pulsate, 5),
-  Action.sequence([followPath, followPath.reversed()]),
-]);
-
-// ✨ Animate continuously
-mySprite.run(Action.repeatForever(moveBackAndForthWhilePulsating));
-```
-
-## Timing Modes
-
-Every action has a `timingMode` which controls the timing curve of its execution.
+// listen to device events
+InputDevice.on( "deviceconnected", ({ device }) => {
+  console.debug( "A new " + device.type + " device connected!" ) // "keyboard" | "gamepad" | "custom"
+})
 
-The default timingMode for all actions is `TimingMode.linear`, which causes an animation to occur evenly over its duration.
+// keyboard events
+InputDevice.keyboard.on( "layoutdetected", ({ layout }) => {
+  console.debug( "layout detected as " + layout ); // "JCUKEN" | "AZERTY" | "QWERTZ" | "QWERTY"
+})
+InputDevice.keyboard.on( "Escape", () => showMenu() )
 
-You can customize the speed curve of actions in many ways:
+// gamepad events
+InputDevice.gamepads[0].on( Button.Back, () => showMenu() )
+InputDevice.gamepads[0].on( "Back", () => showMenu() )
 
-```ts
-// Default easings:
-Action.fadeIn(0.3).easeIn();
-Action.fadeIn(0.3).easeOut();
-Action.fadeIn(0.3).easeInOut();
+```
 
-// Set a specific TimingMode:
-Action.fadeIn(0.3).setTimingMode(TimingMode.easeInOutCubic);
+#### InputAction Events
 
-// Set a custom timing function:
-Action.fadeIn(0.3).setTimingMode(x => x * x);
-```
+| Event | Description | Payload |
+|---|---|---|
+| `"deviceconnected"` | `{device}` | A device has become available. |
+| `"devicedisconnected"` | `{device}` | A device has been removed. |
 
-> [!IMPORTANT]
-> **Timing Mutators:** The `.easeIn()`, `.easeOut()`, `.easeInOut()`, `setTimingMode(…)`, `setSpeed(…)` methods mutate the underlying action.
+#### Keyboard Events
 
-### Built-in TimingMode Options
+| 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. |
+| **Key presses:** | | |
+| `"KeyA"` \| `"KeyB"` \| ... 103 more ... | `{event,keyCode,keyLabel,device}` | `"KeyA"` was pressed. |
 
-See the following table for default `TimingMode` options.
+#### Gamepad Events
 
-| Pattern | Ease In, Ease Out | Ease In | Ease Out | Description |
-| --------------- | ----- | -- | --- | ----------- |
-| **Linear** | `linear` | - | - | Constant motion with no acceleration or deceleration. |
-| **Sine** | `easeInOutSine` | `easeInSine` | `easeOutSine` | Gentle start and end, with accelerated motion in the middle. |
-| **Circular** | `easeInOutCirc` | `easeInCirc` | `easeOutCirc` | Smooth start and end, faster acceleration in the middle, circular motion. |
-| **Cubic** | `easeInOutCubic` | `easeInCubic` | `easeOutCubic` | Gradual acceleration and deceleration, smooth motion throughout. |
-| **Quadratic** | `easeInOutQuad` | `easeInQuad` | `easeOutQuad` | Smooth acceleration and deceleration, starts and ends slowly, faster in the middle. |
-| **Quartic** | `easeInOutQuart` | `easeInQuart` | `easeOutQuart` | Slower start and end, increased acceleration in the middle. |
-| **Quintic** | `easeInOutQuint` | `easeInQuint` | `easeOutQuint` | Very gradual start and end, smoother acceleration in the middle. |
-| **Exponential** | `easeInOutExpo` | `easeInExpo` | `easeOutExpo` | Very slow start, exponential acceleration, slow end. |
-| **Back** | `easeInOutBack` | `easeInBack` | `easeOutBack` | Starts slowly, overshoots slightly, settles into final position. |
-| **Bounce** | `easeInOutBounce` | `easeInBounce` | `easeOutBounce` | Bouncy effect at the start or end, with multiple rebounds. |
-| **Elastic** | `easeInOutElastic` | `easeInElastic` | `easeOutElastic` | Stretchy motion with overshoot and multiple oscillations. |
+| Event | Description | Payload |
+|---|---|---|
+| **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"`. |
+| ... | ... | ... |
 
-### Default Timing Modes
+> [!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 instead.
 
-The `.easeIn()`, `.easeOut()`, `.easeInOut()`, and `.linear()` mutator methods on `Action` instances will set the timing mode of that action to the global default timing mode for that curve type.
+##### Gamepad Layouts
 
-| TimingMode mutator | Global setting | Default value |
-| :--- | :--- | :--- |
-| `action.easeIn()` | `Action.DefaultTimingModeEaseIn` | `TimingMode.easeInSine` |
-| `action.easeOut()` | `Action.DefaultTimingModeEaseOut` | `TimingMode.easeOutSine` |
-| `action.easeInOut()` | `Action.DefaultTimingModeEaseInOut` | `TimingMode.easeInOutSine` |
-| `action.linear()` | _(n/a)_ | `TimingMode.linear` |
+> [!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 |
+
+> [!CAUTION]
+> ***Nintendo:** Both the labels and physical positions of the A,B,X,Y buttons are different
+> on Nintendo controllers.
+>
+> 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).
+>
+> ```
+> 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
+> ```
 
-Global default timing modes can be set like so:
+#### Assigning devices
 
 ```ts
-// set default
-Action.DefaultTimingModeEaseIn = TimingMode.easeInQuad;
-
-// apply
-myNode.run(myAction.easeIn());
+InputDevice.on("deviceconnected", ({ device }) => {
+  device.meta.localPlayerId = 123
+})
 
-myAction.timingMode
-// TimingMode.easeInQuad
+for ( const device of InputDevice.devices )
+{
+  if ( device.meta.localPlayerId === 123 )
+  {
+    // do something
+  }
+}
 ```
 
-## Creating Custom Actions
-
-Beyond combining chaining actions like `sequence()`, `group()`, `repeat()` and `repeatForever()`, you can provide code that implements your own action.
+#### Custom devices
 
-### Composite Actions
-
-Actions are stateless and reusable, so you can create complex animations once, and then run them on many nodes.
+You can add custom devices to the device manager:
 
 ```ts
-/** A nice gentle rock back and forth. */
-const rockBackAndForth = Action.repeatForever(
-  Action.group([
-    Action.sequence([
-      Action.moveByX(5, 0.33).easeOut(),
-      Action.moveByX(-10, 0.34).easeInOut(),
-      Action.moveByX(5, 0.33).easeIn(),
-    ]),
-    Action.sequence([
-      Action.rotateByDegrees(-2, 0.33).easeOut(),
-      Action.rotateByDegrees(4, 0.34).easeInOut(),
-      Action.rotateByDegrees(-2, 0.33).easeIn(),
-    ]),
-  ])
-);
-
-// Run it over here
-someSprite.run(rockBackAndForth);
-
-// Run it somewhere else
-someOtherContainer.run(rockBackAndForth);
-```
-
-You can combine these with dynamic actions for more variety:
+// 1. subclass CustomDevice
+class MySpecialDevice extends CustomDevice
+{
+  constructor() {
+    super( "special-device" )
+  }
+}
 
-```ts
-const MyActions = {
-  squash: (amount: number, duration: number = 0.3) => Action.sequence([
-    Action.scaleTo(amount, 1 / amount, duration / 2).easeOut(),
-    Action.scaleTo(1, duration / 2).easeIn()
-  ]),
-  stretch: (amount: number, duration: number = 0.3) => Action.sequence([
-    Action.scaleTo(1 / amount, amount, duration / 2).easeOut(),
-    Action.scaleTo(1, duration / 2).easeIn()
-  ]),
-  squashAndStretch: (amount: number, duration: number = 0.3) => Action.sequence([
-    MyActions.squash(amount, duration / 2),
-    MyActions.stretch(amount, duration / 2),
-  ]),
-};
-
-// Small squish!
-mySprite.run(MyActions.squashAndStretch(1.25));
-
-// Big squish!
-mySprite.run(MyActions.squashAndStretch(2.0));
+// 2. add the device
+InputDevice.add( new MySpecialDevice() )
 ```
 
-### Custom Action (Basic)
+### Navigation API
 
-You can use the built-in `Action.customAction(duration, stepHandler)` to provide custom actions:
+By default, any element with `"mousedown"` or `"pointerdown"` handlers will be navigatable.
 
-```ts
-const rainbowColors = Action.customAction(5.0, (target, t, dt) => {
-  // Calculate color based on time "t".
-  const colorR = Math.sin(0.3 * t + 0) * 127 + 128;
-  const colorG = Math.sin(0.3 * t + 2) * 127 + 128;
-  const colorB = Math.sin(0.3 * t + 4) * 127 + 128;
+Container properties | type | default | description
+---------------------|------|---------|--------------
+`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.
+`isNavigatable`      | `get () => boolean` | `false` | returns `true` if `navigationMode` is `"target"`, or `"auto"` and a `"pointerdown"` or `"mousedown"` event handler is registered.
+`navigationPriority` | `number` | `0` | The priority relative to other navigation items in this group.
 
-  // Apply random color with time-based variation.
-  target.tint = (colorR << 16) + (colorG << 8) + colorB;
-});
+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`
 
-// Start rainbow effect
-mySprite.runWithKey(Action.repeatForever(rainbowColors), 'rainbow');
+Container events  | description
+------------------|--------------------------------------------------------
+`focus`           | Target became focused.
+`blur`            | Target lost focus.
 
-// Stop rainbow effect
-mySprite.removeAction('rainbow');
-```
 
-> **Step functions:**
-> - `target` = The node the aciton is runnning against.
-> - `t` = Progress of time from 0 to 1, which has been passed through the `timingMode` function.
-> - `dt` = delta/change in `t` since last step. Use for relative actions.
+> [!TIP]
+> Modify `device.options.navigation.binds` to override which keys/buttons are used for navigation.
 >
-> _Note: `t` can be outside of 0 and 1 in timing mode functions which overshoot, such as `TimingMode.easeInOutBack`._
-
-This function will be called as many times as the renderer asks over the course of its duration.
-
-### Custom Action (with State)
-
-Here is a practical example:
-
-```ts
-// Create a custom action that relies on
-// state (radius, inital target position).
-const makeOrbitAction = (
-  radius: number,
-  duration: number
-): Action => {
-  let startPos: PIXI.IPointData;
-
-  return Action.customAction(duration, (target, t, td) => {
-    if (!startPos) {
-      // Capture on first run
-      startPos = { x: target.x, y: target.y };
-    }
-
-    const angle = Math.PI * 2 * t;
-
-    target.position.set(
-      startPos.x + radius * Math.cos(angle),
-      startPos.y + radius * Math.sin(angle)
-    );
-  });
-};
-
-// Run the custom action
-mySprite.run(
-  Action.repeatForever(makeOrbitAction(10, 15.0))
-);
-```
+> Or set `device.options.navigation.enabled = false` to disable navigation.