Setup

Getting Controller.js running is simple.

Basic Configuration

To start listening for gamepads, include the library and run the search() function:

// index.html
<script src="js/Controller.min.js"></script>

// main.js
Controller.search();

Finding Controllers

Any gamepads connected will fire a gc.controller.found event and become accessible through the detail.controller attribute of the Event object.

Controller.search();

window.addEventListener('gc.controller.found', function(event) {
    var controller = event.detail.controller;
    console.log("Controller found at index " + controller.index + ".");
    console.log("'" + controller.name + "' is ready!");
}, false);

>> "Controller found at index 0."
>> "'Wireless Controller' is ready!"

You can also get a controller by it's index using Controller.getController() or by finding it in Controller.controllers.

var controllerA = Controller.getController(0);
var controllerB = Controller.controllers[0];

// controllerA and controllerB are the same controller

Compatibility

The Controller object provides a supported attribute used to check for gamepad support in the current browser.

if (Controller.supported) {
    Controller.search();
} else {
    // Fallback...
}

It isn't strictly necessary to check compatibility before running Controller.search() because it does that itself internally, but the supported attribute is good for assinging a fallback option.

search() Options

The search() method can accept a list of options.

unsupportedCallback

A function passed to unsupportedCallback will fire as soon as Controller.js determines that it is incompatible with the current browser.

Controller.search({
    unsupportedCallback: fallback
});

function fallback() {
    window.alert("This browser does not support the Gamepad API");
}

settings

If a list of settings is passed to search(), any controllers found will have their local settings initialized with the specified values.

Controller.search({
    settings: {
        useAnalogAsDpad: "both"
    }
});

var controller = Controller.getController(0);
console.log(controller.settings.useAnalogAsDpad);
>> "both"

→ Learn about settings.

Disconnected Controllers

When a gamepad is no longer visible to the browser it will fire a gc.controller.lost event.

window.addEventListener('gc.controller.lost', function(event) {
    console.log("The controller at index " + event.detail.index + " has been disconnected.");
    console.log(Controller.getController(0));
}, false);

>> "The controller at index 0 has been disconnected."
>> undefined

A controller's index will remain the same for as long as that controller is connected. If two controllers are connected, and the controller at index 0 is disconnected, Controller.getController(0) will be undefined while Controller.getController(1) will continue to be the second controller.

// Two controllers are connected
var controllerA = Controller.getController(0);
var controllerB = Controller.getController(1);

console.log(Controller.controllers);
>> Object {
>>     0: Controller,
>>     1: Controller
>> }

// The controller at index 0 (controllerA), is disconnected
console.log(controllerA);
>> undefined

console.log(controllerB);
>> Controller {…}

console.log(Controller.controllers);
>> Object {
>>     1: Controller
>> }