game-inputs

A simple library for abstracting key/mouse input for games.

Does stuff like:

• Virtual key bindings (i.e. map one or more physical keys to a single action)
• Emits down/up events for each binding (not each key)
• Handles annoying edge cases, like overlapping events from two keys bound to the same action, or the browser losing focus while a key is pressed, etc.
• Exposes objects with the current state of each binding, the number of press/release events since the last tick, etc.
• Also tracks mouse/pointer events and scroll/wheel inputs

Canonical names for physical keys are as specified by KeyboardEvent.code. To check key codes, try the live demo.

Sample usage:

import { GameInputs } from 'game-inputs'

// instantiate
var domElement = document.querySelector('...')
var inputs = new GameInputs(domElement, {
  preventDefaults: true, 
  allowContextMenu: false,
})

// bind an arbitrary event name to one or more physical key codes
inputs.bind( 'move-fwd',  'KeyW' )
inputs.bind( 'move-left', 'KeyA', 'ArrowLeft' )

// listen to that event name for press/release events
inputs.down.on( 'move-fwd', (ev) => { startMovingFwd() } )
inputs.up.on( 'move-fwd', (ev) => { stopMovingFwd() } )

// mouse/pointer buttons are bindable as `Mouse1`, `Mouse2`, ...
inputs.bind( 'shoot', 'Mouse1' )
inputs.bind( 'RMB', 'Mouse3' )

// you can also query various input states in the game loop
function myGameLoop() {
  // current boolean state of a key or mouse button
  var leftCurrentlyPressed = inputs.state['move-left']
  var shootButtonPressed = inputs.state['shoot']

  // pointer movement and scroll/wheel data
  var mouseMovedBy = [inputs.pointerState.dx, inputs.pointerState.dy]
  var scrolledBy = inputs.pointerState.scrolly

  // accumulated number of presses/releases since the last tick
  var fwdPresses = inputs.pressCount['move-fwd']
  var fwdReleases = inputs.releaseCount['move-fwd']

  // calling tick() zeroes out cumulative mouse/scroll/press/release values
  inputs.tick()
}

// you can optionally filter events before they occur - e.g. if you want
// keyboard events not to fire if control keys are pressed
inputs.filterEvents = (ev, bindingName) => {
    if (/^Key/.test(ev.code) && ev.ctrlKey) return false
    return true
}

Here's the interactive demo.

Installation

npm install game-inputs

API

The various methods and properties are documented via doc comments, so in a modern editor you should hopefully see them as tooltips.

Otherwise, please see the source ;)

Notes:

• When you specify a domElement, this module will only track pointer inputs (movement, clicks, and scrolls) inside that element. However keyboard inputs will be tracked globally at the document level.
• If you don't specify a DOM element, document will be used.
• For several reasons, this module doesn't call preventDefault or stopPropagation on mouse or scroll events, even if those properties are set. If you want to prevent parts of your page from scrolling or panning, it's more performant to do so via CSS.

Known issues:

• On Mac keyup events never fire while the Command key is pressed (see here), so if the user presses cmd+A it's impossible to detect whether the A key gets released. There's no great way to work around this - this library errs on the side of avoiding phantom key inputs by emulating an up for such key chords when the Command key is released.

---

History

• 0.8.0 Works around mac-only command key bug
• 0.7.0 Adds filterEvents()
• 0.6.0 Modernization pass - adopts real physical key codes, Pointer events (still fallback to mouse), etc. Also adds proper docs/types.
  Breaking changes:
  • now an ES module exporting a named class, not a factory function
  • Key binding names now use KeyboardEvent.code strings (e.g. KeyA, Space)
  • Bindings for mouse buttons are now Mouse1, Mouse2..
  • Mouse/scroll values (dx,dy,scrollx,scrolly) moved from inputs.state to inputs.pointerState
• 0.5.0 Minor features and dependency updates
• 0.3.0 Stable release

---

By

Made with 🍺 by Andy Hall.

License is ISC.

Originally modeled after game-shell, but probably doesn't resemble it much anymore.