gameController.js
A JavaScript library that lets you handle, configure, and use gamepad and controllers on a browser.
Getting started
GameController.js is a lightweight library (~6KB) that uses JavaScript and the standard Gamepad API, and does not have any plugin/library dependencies.
Installation
From npm:
npm i gamecontroller.js
From yarn:
yarn add gamecontroller.js
Directly into your webpage (check latest release on github):
<script src="./gamecontroller.min.js"></script>
Usage
After importing the library into your webpage/project, gameControl
will be available to use. This object comes with a series of properties and methods that will allow to handle the different gamepads connected to the computer.
The connected gamepads will be stored in a list of gamepad
objects in gameControl
. This gamepad
object is not the default one returned by the browser but a higher-level interface to interact with it and simplify its usability.
Once the file is imported into the project, the object gameControl
will be available and ready to be used.
gameControl;
Visit the Wiki for a full list of the properties, methods and events of these two objects.
Events for gameControl
For the object gameControl
, events are associated using the .on()
method:
gameControl;
Here is a list of the events that can be associated using .on()
:
Name | Description |
---|---|
connect |
Triggered every time that a gamepad is connected to the browser. It returns an instance of the `gamepad` object described below. |
disconnect |
Triggered when a gamepad is disconnected from the browser. |
beforeCycle |
Triggered before the gamepads are checked for pressed buttons/joysticks movement (before those events are triggered). |
afterCycle |
Triggered after the gamepads are checked for pressed buttons/joysticks movement (after those events have been triggered). |
Events for gamepad
The events for the gamepad
objects work a little bit different. The event name, is the name of the button/direction that was activated (e.g. button0
, up
, etc.) And there are three functions that can be used to associate event handlers for them in different situations:
.on()
: triggered every cycle, while the button/joystick is pressed/active..before()
: triggered the first cycle that a button/joystick is pressed..after()
: triggered the first cycle after a button/joystick stopped being pressed.
All three functions can be chained and allow two parameters: the first one is the button/direction that was activated, and the second parameter is the callback function. Example:
gamepad
To see the event flow and how the different events are lined-up and interact with each other, visit the Event Flow wikipage.
Thisus
These are the events that can be passed as first parameter to the event functions:
Name | Description |
---|---|
button0 |
Triggered when button 0 is pressed. |
button1 |
Triggered when button 1 is pressed. |
button2 |
Triggered when button 2 is pressed. |
button3 |
Triggered when button 3 is pressed. |
button4 |
Triggered when button 4 is pressed. |
button5 |
Triggered when button 5 is pressed. |
button6 |
Triggered when button 6 is pressed. |
button7 |
Triggered when button 7 is pressed. |
button8 |
Triggered when button 8 is pressed. |
button9 |
Triggered when button 9 is pressed. |
button10 |
Triggered when button 10 is pressed. |
button11 |
Triggered when button 11 is pressed. |
button12 |
Triggered when button 12 is pressed. |
button13 |
Triggered when button 13 is pressed. |
button14 |
Triggered when button 14 is pressed. |
button15 |
Triggered when button 15 is pressed. |
button16 |
Triggered when button 16 is pressed. |
up0 |
Triggered when the first axe/joystick is moved up. |
down0 |
Triggered when the first axe/joystick is moved down. |
right0 |
Triggered when the first axe/joystick is moved right. |
left0 |
Triggered when the first axe/joystick is moved left. |
up1 |
Triggered when the second axe/joystick is moved up. |
down1 |
Triggered when the second axe/joystick is moved down. |
right1 |
Triggered when the second axe/joystick is moved right. |
left1 |
Triggered when the second axe/joystick is moved left. |
start |
Triggered when Start button is pressed. This is an alias for event button9 . |
select |
Triggered when Select button is pressed. This is an alias for event button8 . |
power |
Triggered when Power button is pressed (e.g. the Xbox logo in an Xbox controller). This is an alias for event button16 . |
l1 |
Triggered when the left back button 1 is pressed. This is an alias for event button4 . |
l2 |
Triggered when left back button 2 is pressed. This is an alias for event button6 . |
r1 |
Triggered when right back button 1 is pressed. This is an alias for event button5 . |
r2 |
Triggered when right back button 2 is pressed. This is an alias for event button7 . |
up |
Triggered when the main/first axe/joystick is moved up. This is an alias for event up0 . |
down |
Triggered when the main/first axe/joystick is moved down. This is an alias for event down0 . |
right |
Triggered when the main/first axe/joystick is moved right. This is an alias for event right0 . |
left |
Triggered when the main/first axe/joystick is moved left. This is an alias for event left0 . |
These names are not arbitrary. They match the buttons and axes described in the W3C Gamepad API specicification:
Browser Support
Edge |
Firefox |
Chrome |
Safari |
Opera |
---|---|---|---|---|
12+ | 29+ | 25+ | 10.1+ | 24+ |
Examples
The examples
folder contains different examples to showcase how to use the library:
- Connectivity: shows how to detect if a gamepad was connected/disconnected.
- Buttons and Joysticks: see how the buttons from your gamepad map to the default gamepad.
- SNES Controller: replica of a SNES controller (based on a previous CodePen demo).
- Alvanoid: small Arkanoid-based game (based on a previous CodePen demo).
- Pong: multiplayer demo with the classic game Pong for 2 players on 2 gamepads.