Game Component: Input Manager

A component for handling input events and managing input device state.

Installation

npm install @basementuniverse/input-manager

For direct browser usage, include the UMD build with a script tag:

<script src="build/index.js"></script>

The build exposes the package's main class as the BasementUniverseInputManager browser global. It does not add each export directly to window.

How to use

Initialise the input manager before use:

import InputManager from '@basementuniverse/input-manager';

InputManager.initialise();

When using the library directly from a browser script, use the BasementUniverseInputManager global:

<script src="build/index.js"></script>
<script>
  BasementUniverseInputManager.initialise();

  // Every frame:
  BasementUniverseInputManager.update();

  if (BasementUniverseInputManager.keyPressed('Space')) {
    // ...
  }
</script>

Update the input manager state:

class Game {
  // ...

  public update(context: CanvasRenderingContext2D) {
    InputManager.update();
  }
}

Tear the input manager down when it is no longer needed (this removes all event listeners and resets the singleton so that initialise can safely be called again, e.g. when a component is unmounted and remounted):

InputManager.dispose();

// Check whether the input manager is currently initialised
InputManager.isInitialised();

Check the state of input devices:

// Check if any key is currently down
InputManager.keyDown();

// Check if a specific key is currently down
InputManager.keyDown(code?);

// Check if a key was pressed
InputManager.keyPressed(code?);

// Check if a key was released
InputManager.keyReleased(code?);

// Check if the main mouse button is currently down
InputManager.mouseDown(button?);

// Check if the main mouse button was pressed
InputManager.mousePressed(button?);

// Check if the main mouse button was released
InputManager.mouseReleased(button?);

// Check if the mouse wheel was scrolled up
InputManager.mouseWheelUp();

// Check if the mouse wheel was scrolled down
InputManager.mouseWheelDown();

// Get the current mouse position (relative to the element, or the viewport
// if the element is the window)
const position = InputManager.mousePosition;

// Get the currently hovered HTML element (or null if there isn't one)
const hoveredElement = InputManager.hoveredElement;

See here for a reference of key codes.

Mouse wheel "up" means scrolling away from the user (a negative deltaY). Note that OS-level settings such as macOS "natural scrolling" reverse this.

Options

const options = { ... };
InputManager.initialise(options);

| Option | Type | Default | Description | | --- | --- | --- | --- | | element | Window \| HTMLElement | window | The element to listen for mouse, touch and wheel events on (mouse position will be relative to this element) | | mouse | boolean | true | Enable mouse input | | mouseWheel | boolean | true | Enable mouse wheel input | | keyboard | boolean | true | Enable keyboard input | | preventContextMenu | boolean | false | Try to prevent the context menu from appearing on right-click | | ignoreEditableTargets | boolean | true | Ignore key presses inside form fields (<input>, <textarea>, <select> and contenteditable elements) |

Keyboard events are always tracked on window, regardless of element. This is because keyboard events are only dispatched to the focused element, and most elements (including <canvas>) can't receive focus by default.

By default, key presses inside form fields are ignored, so typing into (for example) a chat box won't trigger game input. Key releases are always tracked, so a key that was held down before focus moved into a form field still gets released. Set ignoreEditableTargets: false to track all key presses.

Mouse button releases are also tracked on window, so a button that is pressed inside element and released outside of it won't get stuck down.