gamepad-helper

Lightweight, zero-dependency wrapper class for the HTML5 Gamepad API.

$ npm i gamepad-helper

$ yarn add gamepad-helper

Simply install the package via npm or yarn. You will need to use a module bundler like webpack to access it in your client-side code.

The GamepadHelper class can be imported and used by calling the GamepadHelper.update() static method within your game loop.

import { GamepadHelper } from "gamepad-helper";

// ...within game loop
GamepadHelper.update();

When a button on a connected gamepad is pressed or released, a CustomEvent will be dispatched to the document containing a detail property identifying the gamepad/button that was pressed/released.

There are two CustomEvent types:

• gamepadbuttondown - dispatched when the value property of any button changes from 0 to 1
• gamepadbuttonup - dispatched when the value property of any button changes from 1 to 0

Here is an example that simply logs the gamepad/button that was pressed down:

// JavaScript
document.addEventListener("gamepadbuttondown", (event) => {
	const { button, gamepad } = event.detail;
	console.log(`button ${button} on gamepad ${gamepad} was pressed down`);
});

// TypeScript
import type { IGamepadButtonEventDetail } from "gamepad-helper";
document.addEventListener("gamepadbuttondown", (event: CustomEvent<IGamepadButtonEventDetail>) => {
	const { button, gamepad } = event.detail;
	console.log(`button ${button} on gamepad ${gamepad} was pressed down`);
});

Here is an example which causes player 1 to jump if button 0 on gamepad 0 is released:

// JavaScript
document.addEventListener("gamepadbuttonup", (event) => {
	const { button, gamepad } = event.detail;
	if (gamepad === 0 && button === 0) {
		player1.jump();
	}
});

// TypeScript
import type { IGamepadButtonEventDetail } from "gamepad-helper";
document.addEventListener("gamepadbuttonup", (event: CustomEvent<IGamepadButtonEventDetail>) => {
	const { button, gamepad } = event.detail;
	if (gamepad === 0 && button === 0) {
		player1.jump();
	}
});

The instantaneous state of any button or axis on a connected gamepad can also be queried via the GamepadHelper.getButtonValue() and GamepadHelper.getAxisValue() static methods.

To log informational output to the console, set GamepadHelper.logOutput to true (false by default):

GamepadHelper.logOutput = true;

gamepad 0 connected
gamepad 0: button 0 is down
gamepad 0: button 0 is up

Check it out on npm:

• https://www.npmjs.com/package/gamepad-helper

More info on the Gamepad API:

• https://www.w3.org/TR/gamepad/
• https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API