gamepad.js

A simple HTML5 Gamepad handler that provides keyboard-like events for Gamepad axes and button.

Try it right now in your browser: http://tom32i.github.io/gamepad.js/

Installation:

npm install gamepad.js

Import

HTML:

<script src="gamepad.js"></script>
<script>const { GamepadListener } = gamepad;</script>

ES modules:

import { GamepadListener } from 'gamepad.js';

CommonJs modules:

const { GamepadListener } = require('gamepad.js');

Usage:

const listener = new GamepadListener(/* options*/);

listener.on('gamepad:button', onButtonChange);

listener.start();

Configuration:

Property	Type	Default	Description
analog	boolean	true	Set to false to get fixed value: e.g for a axis [-1, 0, 1]. Used to reduce the number of change event triggered if you dont need analog values.
precision	integer	0	When in analog mode, set the number of decimals. Used to reduce the muber of event triggered but keep analog values.
deadZone	float	0	Percent of noise to ignore around 0. Ex: deadZone set to 0.3 will cause axis position of from -0.3 to 0.3 to be considered 0. Axes moves below 30% from default positon won't trigger a change.

Theses options can be set for the whole gamepad:

const listener = new GamepadListener({
  analog: false,
  deadZone: 0.3
});

Or distinctly for axes and buttons:

const listener = new GamepadListener({
  button: {
    analog: false
  },
  axis: {
    precision: 2,
    deadZone: 0.5
  }
});

Events:

To listen for events use the listener.addEventListener(eventName, callback); method (also available under alias listener.on(...)).

To stop listening for events use the listener.removeEventListener(eventName, callback); method (also available under alias listener.off(...)).

gamepad:connected

A new gamepad is connected.

listener.on('gamepad:connected', event => {
    const {
        index, // Gamepad index: Number [0-3].
        gamepad, // Native Gamepad object.
    } = event.detail;
});

gamepad:disconnected

A gamepad was disconnected.

listener.on('gamepad:disconnected', event => {
    const {
        index, // Gamepad index: Number [0-3].
        // Native Gamepad object is no longer available.
    } = event.detail;
});

gamepad:axis

A gamepad axis value has changed.

listener.on('gamepad:axis', event => {
    const {
        index,// Gamepad index: Number [0-3].
        axis, // Axis index: Number [0-N].
        value, // Current value: Number between -1 and 1. Float in analog mode, integer otherwise.
        gamepad, // Native Gamepad object
    } = event.detail;
});

Optional: Can be listened for a specific Gamepad index: gamepad:{gamepad}:axis.

Optional: Can be listened for a specific Gamepad index and a specific axis: gamepad:{gamepad}:axis:{axis}.

gamepad:button

A gamepad button value has changed.

listener.on('gamepad:button', event => {
    const {
        index,// Gamepad index: Number [0-3].
        button, // Button index: Number [0-N].
        value, // Current value: Number between 0 and 1. Float in analog mode, integer otherwise.
        pressed, // Native GamepadButton pressed value: Boolean.
        gamepad, // Native Gamepad object
    } = event.detail;
});

Optional: Can be listened for a specific Gamepad index: gamepad:{gamepad}:button.

Optional: Can be listened for a specific Gamepad index and a specific axis: gamepad:{gamepad}:button:{button}.

Stop listening

When you don't need to listen for events anymore:

listener.stop();

Contributing

Clone the repository:

git clone git@github.com:Tom32i/gamepad.js.git

Install dev dependencies:

npm install

Launch the dev server

make start

Go to http://localhost:8080

Code quality

Linting:

make lint

Run tests:

make test