Using the Gamepad API

This article is in need of a technical review.

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for the proper prefixes to use in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the spec changes.

HTML5 introduced many of the necessary components for rich, interactive game development. Technologies like <canvas>, WebGL, <audio>, and <video>, along with JavaScript implementations, have matured to the point where they can now support many tasks previously requiring native code. The Gamepad API is a way for developers and designers to access and use gamepads and other game controllers.

Note: As of Firefox 24, the Gamepad API is available behind a preference. You can enable it by loading about:config and setting the dom.gamepad.enabled preference to true. Nightly and Aurora builds of Firefox have the API enabled by default. We expect to ship release builds with it similarly enabled in Firefox 28.

The Gamepad API introduces new events on the Window object for reading gamepad and controller (hereby referred to as gamepad) state. In addition to these events, the API also adds a Gamepad object, which you can use to query the state of connected gamepads.

Connecting to a gamepad

When a new gamepad is connected to the computer, the focused page first receives a Window.gamepadconnected event. If a gamepad is already connected when the page loaded, the Window.gamepadconnected event is dispatched to the focused page when the user presses a button or moves an axis.

You can use Window.gamepadconnected like this:

window.addEventListener("gamepadconnected", function(e) {
  console.log("Gamepad connected at index %d: %s. %d buttons, %d axes.",
  e.gamepad.index, e.gamepad.id,
  e.gamepad.buttons.length, e.gamepad.axes.length);
});

Each gamepad has a unique ID associated with it, which is available on the event's gamepad property.

Disconnecting a gamepad

When a gamepad is disconnected, and if a page has previously received data (e.g., Window.gamepadconnected), a second event is dispatched to the focused window, Window.gamepaddisconnected:

window.addEventListener("gamepaddisconnected", function(e) {
  console.log("Gamepad disconnected from index %d: %s",
  e.gamepad.index, e.gamepad.id);
});

The Gamepad's ID will be the same for Window.gamepadconnected and Window.gamepaddisconnected events, making it a suitable key for storing gamepad device information:

var gamepads = {};

function gamepadHandler(event, connecting) {
  var gamepad = event.gamepad;

  if (connecting) {
    gamepads[gamepad.id] = gamepad;
  } else {
    delete gamepads[gamepad.id];
  }
}

window.addEventListener("gamepadconnected", function(e) { gamepadHandler(e, true); }, false);
window.addEventListener("gamepaddisconnected", function(e) { gamepadHandler(e, false); }, false);

This previous example also demonstrates how the gamepad property can be held after the event has completed — a technique we will use for device state querying later.

Querying the Gamepad object

As you can see, the gamepad events discussed above include a gamepad property on the event object, which returns a Gamepad object. We can use this in order to determine which gamepad (i.e., its ID) had caused the event, since multiple gamepads might be connected at once. We can do much more with the Gamepad object, including holding a reference to it and querying it to find out which buttons and axes are being pressed at any one time. Doing so is often desirable for games or other interactive web pages that need to know the state of a gamepad now vs. the next time an event fires.

Performing such checks tends to involve using the Gamepad object in conjunction with an animation loop (e.g., requestAnimationFrame), where developers want to make decisions for the current frame based on the state of the gamepad or gamepads.

Note: The Gamepad API also provides a function -- Navigator.getGamepads-- that returns a list of all devices currently visible to the webpage, an array of Gamepad objects. This can then be used to get pretty much the same information. For example, the first code example above you be rewritten as shown below:

window.addEventListener("gamepadconnected", function(e) {
  var gp = navigator.getGamepads()[0];
  console.log("Gamepad connected at index %d: %s. %d buttons, %d axes.",
  gp.index, gp.id,
  gp.buttons.length, gp.axes.length);
});

The Gamepad object's properties are as follows:

  • id: A string containing some information about the controller. This is not strictly specified, but in Firefox it will contain three pieces of information separated by dashes (-): two 4-digit hexadecimal strings containing the USB vendor and product id of the controller, and the name of the controller as provided by the driver. This information is intended to allow you to find a mapping for the controls on the device as well as display useful feedback to the user..
  • index: An integer that is auto-incremented to be unique for each device currently connected to the system. This can be used to distinguish multiple controllers; a gamepad that is disconnected and reconnected will retain the same index.
  • mapping: A string indicating whether the browser has remapped the controls on the device to a known layout. Currently there is only one supported known layout–the standard gamepad. If the browser is able to map controls on the device to that layout the mapping property will be set to the string standard.
  • connected: A boolean indicating whether the gamepad is still connected to the system. If this is so the value is True; if not, it is False.
  • buttons: An array of GamepadButton objects representing the buttons present on the device. Each entry in the array is 0 if the button is not pressed, and non-zero (typically 1.0) if the button is pressed. Each GamepadButton has a pressed and a value property:
    • The pressed property is a boolean indicating whether the button is currently pressed (true) or unpressed (false).
    • The value property is a floating point value used to enable representing analog buttons, such as the triggers on many modern gamepads. The values are normalized to the range 0.0..1.0, with 0.0 representing a button that is not pressed, and 1.0 representing a button that is fully pressed.
  • axes: An array representing the controls with axes present on the device (e.g. analog thumb sticks). Each entry in the array is a floating point value in the range -1.0 - 1.0, representing the axis position from the lowest value (-1.0) to the highest value (1.0).
  • timestamp: This returns a DOMHighResTimeStamp representing the last time the data for this gamepad was updated, allowing developers to determine if the axes and button data have been updated from the hardware. The value must be relative to the navigationStart attribute of the PerformanceTiming interface. Values are monotonically increasing, meaning that they can be compared to determine the ordering of updates, as newer values will always be greater than or equal to older values. Note that this property is not currently supported anywhere.

Note: The Gamepad object is available on the Window.gamepadconnected event rather than the Window object itself, for security reasons. Once we have a reference to it, we can query its properties for information about the current state of the gamepad. Behind the scenes, this object will be updated every time the gamepad's state changes.

Using button information

Let's look at a simple example that displays connection information for one gamepad (it ignores subsequent gamepad connections) and allows you to move a ball around the screen using the four gamepad buttons on the right hand side of the gamepad. You can view the demo live, and find the source code on Github.

To start with, we declare some variables: The gamepadInfo paragraph that the connection info is written into, the ball that we want to move, the start variable that acts as the ID for requestAnimation Frame, the a and b variables that act as position modifiers for moving the ball, and the shorthand variables that will be used for the requestAnimationFrame and cancelRequestAnimationFrame cross browser forks.

var gamepadInfo = document.getElementById("gamepad-info");
var ball = document.getElementById("ball");
var start;
var a = 0;
var b = 0;

var rAF = window.mozRequestAnimationFrame ||
  window.webkitRequestAnimationFrame ||
  window.requestAnimationFrame;

var rAFStop = window.mozCancelRequestAnimationFrame ||
  window.webkitCancelRequestAnimationFrame ||
  window.cancelRequestAnimationFrame;

Next we use the Window.gamepadconnected event to check for a gamepad being connected. When one is connected, we grab the gamepad using Navigator.getGamepads[0], print information about the gamepad into our gamepad info div, and fire the gameLoop() function that starts the whole ball movement process up.

window.addEventListener("gamepadconnected", function(e) {
  var gp = navigator.getGamepads()[0];
  gamepadInfo.innerHTML = "Gamepad connected at index " + gp.index + ": " + gp.id + ". It has " + gp.buttons.length + " buttons and " + gp.axes.length + " axes.";

  gameLoop();
});

Now we use the Window.gamepaddisconnected event to check if the gamepad is disconnected again. If so, we stop the requestAnimationFrame loop (see below) and revert the gamepad information back to what it was originally.

window.addEventListener("gamepaddisconnected", function(e) {
  gamepadInfo.innerHTML = "Waiting for gamepad.";

  rAFStop(start);
});

Chrome does things differently here. Instead of constantly storing the gamepad's latest state in a variable it only stores a snapshot, so to do the same thing in Chrome you have to keep polling it and then only use the Gamepad object in code when it is available. We have done this below using Window.setInterval; once the object is available the gamepad info is outputted, the game loop is started, and the interval is cleared using Window.clearInterval.

if(navigator.webkitGetGamepads) {
  // Webkit browser that uses prefixes
  var interval = setInterval(webkitGP, 500);
}

function webkitGP() {
  var gp = navigator.webkitGetGamepads()[0];
  if(gp) {
    gamepadInfo.innerHTML = "Gamepad connected at index " + gp.index + ": " + gp.id + ". It has " + gp.buttons.length + " buttons and " + gp.axes.length + " axes.";
    gameLoop();
    clearInterval(interval);
  }
}

Now on to the main game loop. In each execution of the loop we check if one of four buttons is being pressed; if so, we update the values of the a and b movement variables appropriately, then update the left and top properties, changing their values to the current values of a and b respectively. This has the effect of moving the ball around the screen. I've had to fork the code here too, as in Chrome Navigator.getGamepads needs a webkit prefix and the button values are stores as an array of double values, whereas in Firefox Navigator.getGamepads doesn't need a prefix, and the button values are stored as an array of GamepadButton objects; it is the GamepadButton.value or GamepadButton.pressed property of these we need to access, depending on what type of button it is in each case. In this simple example I've just allowed either.

After all this is done, we use our rAF variable to request the next animation frame, running gameLoop() again.

function gameLoop() {
  if(navigator.webkitGetGamepads) {
    var gp = navigator.webkitGetGamepads()[0];

    if(gp.buttons[0] == 1) {
      b--;
    } else if(gp.buttons[1] == 1) {
      a++;
    } else if(gp.buttons[2] == 1) {
      b++;
    } else if(gp.buttons[3] == 1) {
      a--;
    }
  } else {
    var gp = navigator.getGamepads()[0];

    if(gp.buttons[0].value > 0 || gp.buttons[0].pressed == true) {
      b--;
    } else if(gp.buttons[1].value > 0 || gp.buttons[1].pressed == true) {
      a++;
    } else if(gp.buttons[2].value > 0 || gp.buttons[2].pressed == true) {
      b++;
    } else if(gp.buttons[3].value > 0 || gp.buttons[3].pressed == true) {
      a--;
    }
  }

  ball.style.left = a*2 + "px";
  ball.style.top = b*2 + "px";

  var start = rAF(gameLoop);
};

Using axes information

TBD (basically the same, except using axes[i] rather than button[i].value for both Firefox and Chrome.)

Complete example: Displaying gamepad state

This example shows how to use the Gamepad object, as well as the Window.gamepadconnected and Window.gamepaddisconnected events in order to display the state of all gamepads connected to the system. You can find a working demo and look at the full source code on Github.

var controllers = {};
var rAF = window.mozRequestAnimationFrame ||
  window.webkitRequestAnimationFrame ||
  window.requestAnimationFrame;

function connecthandler(e) {
  addgamepad(e.gamepad);
}
function addgamepad(gamepad) {
  controllers[gamepad.index] = gamepad; var d = document.createElement("div");
  d.setAttribute("id", "controller" + gamepad.index);
  var t = document.createElement("h1");
  t.appendChild(document.createTextNode("gamepad: " + gamepad.id));
  d.appendChild(t);
  var b = document.createElement("div");
  b.className = "buttons";
  for (var i=0; i<gamepad.buttons.length; i++) {
    var e = document.createElement("span");
    e.className = "button";
    //e.id = "b" + i;
    e.innerHTML = i;
    b.appendChild(e);
  }
  d.appendChild(b);
  var a = document.createElement("div");
  a.className = "axes";
  for (var i=0; i<gamepad.axes.length; i++) {
    var e = document.createElement("progress");
    e.className = "axis";
    //e.id = "a" + i;
    e.setAttribute("max", "2");
    e.setAttribute("value", "1");
    e.innerHTML = i;
    a.appendChild(e);
  }
  d.appendChild(a);
  document.getElementById("start").style.display = "none";
  document.body.appendChild(d);
  rAF(updateStatus);
}

function disconnecthandler(e) {
  removegamepad(e.gamepad);
}

function removegamepad(gamepad) {
  var d = document.getElementById("controller" + gamepad.index);
  document.body.removeChild(d);
  delete controllers[gamepad.index];
}

function updateStatus() {
  if (navigator.webkitGetGamepads) {
    scangamepads();
  }
  for (j in controllers) {
    var controller = controllers[j];
    var d = document.getElementById("controller" + j);
    var buttons = d.getElementsByClassName("button");
    for (var i=0; i<controller.buttons.length; i++) {
      var b = buttons[i];
      var val = controller.buttons[i];
      var pressed = val == 1.0;
      if (typeof(val) == "object") {
        pressed = val.pressed;
        val = val.value;
      }
      var pct = Math.round(val * 100) + "%"
      b.style.backgroundSize = pct + " " + pct;
      if (pressed) {
        b.className = "button pressed";
      } else {
        b.className = "button";
      }
    }

    var axes = d.getElementsByClassName("axis");
    for (var i=0; i<controller.axes.length; i++) {
      var a = axes[i];
      a.innerHTML = i + ": " + controller.axes[i].toFixed(4);
      a.setAttribute("value", controller.axes[i] + 1);
    }
  }
  rAF(updateStatus);
}

function scangamepads() {
  var gamepads = navigator.webkitGetGamepads();
  for (var i = 0; i < gamepads.length; i++) {
    if (gamepads[i]) {
      if (!(gamepads[i].index in controllers)) {
        addgamepad(gamepads[i]);
      } else {
        controllers[gamepads[i].index] = gamepads[i];
      }
    }
  }
}

window.addEventListener("gamepadconnected", connecthandler);
window.addEventListener("gamepaddisconnected", disconnecthandler);
if (navigator.webkitGetGamepads) {
  setInterval(scangamepads, 500);
}

Specifications

Specification Status Comment
Gamepad Working Draft  

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
General support 21.0 webkit 24.0 (24.0) moz
28.0 (28.0)
Not supported Not supported Not supported
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
General support Not supported Not supported Not supported Not supported Not supported

 

 

 

Document Tags and Contributors

Contributors to this page: Jeremie, grendel, Raffzahn, lillithompson, chrisdavidmills
Last updated by: Jeremie,