https://github.com/cdleveille/gamepad-helper
Lightweight, zero-dependency wrapper class for the HTML5 Gamepad API.
https://github.com/cdleveille/gamepad-helper
gamepad gamepad-api html5 javascript javascript-game js npm npm-package typescript
Last synced: about 1 year ago
JSON representation
Lightweight, zero-dependency wrapper class for the HTML5 Gamepad API.
- Host: GitHub
- URL: https://github.com/cdleveille/gamepad-helper
- Owner: cdleveille
- License: mit
- Created: 2021-07-25T17:00:57.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2023-09-27T02:06:44.000Z (over 2 years ago)
- Last Synced: 2025-03-24T19:39:36.332Z (about 1 year ago)
- Topics: gamepad, gamepad-api, html5, javascript, javascript-game, js, npm, npm-package, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/gamepad-helper
- Size: 86.9 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gamepad-helper
Lightweight, zero-dependency wrapper class for the HTML5 Gamepad API.
```bash
$ 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](https://webpack.js.org/) 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.
```javascript
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
// 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) => {
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
// 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) => {
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):
```javascript
GamepadHelper.logOutput = true;
```
```text
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