van an nguyen

Dealing with gamepad events

Dealing with gamepad events

Introduction

Some games, mainly arcade/action games, are designed to be used with a gamepad:

a xbox 360 gamepad

The Gamepad API is currently (as at September 2017) supported by all major browsers (including Microsoft Edge), except Safari and Internet Explorer. Note that the API is still a draft and may change in the future (though it has changed very little since 2012). We recommend using a Wired Xbox 360 Controller or a PS2 controller, both of which should work out of the box on Windows XP, Windows Vista, Windows, and Linux desktop distributions. Wireless controllers are supposed to work too, but we haven’t tested the API with them. You may find someone who has managed but they’ve probably needed to install an operating system driver to make it work.

gamepad support table

See the up to date version of this table.

Detecting gamepads

Events triggered when the gamepad is plugged in or unplugged

Let’s start with a ‘discovery’ script to check that the GamePad is connected, and to see the range of facilities it can offer to JavaScript.

If the user interacts with a controller (presses a button, moves a stick) a gamepadconnected event will be sent to the page.  NB the page must be visible! The event object passed to the gamepadconnected listener has a gamepad property which describes the connected device.

Example on JSBin

  1. window.addEventListener(“gamepadconnected”, function(e) {
  2.    var gamepad = e.gamepad;
  3.    var index = gamepad.index;
  4.    var id = gamepad.id;
  5.    var nbButtons = gamepad.buttons.length;
  6.    var nbAxes = gamepad.axes.length;
  8.    console.log(“Gamepad No “ + index +
  9.                “, with id “ + id + ” is connected. It has “ +
  10.                nbButtons + ” buttons and “ +
  11.                nbAxes + ” axes”);
  12. });

Gamepad detected, message on the jsbin exmaple

If a gamepad is disconnected (you unplug it), a gamepaddisconnected event is fired. Any references to the gamepad object will have their connected property set to false.

  1. window.addEventListener(“gamepaddisconnected”, function(e) {
  2.    var gamepad = e.gamepad;
  3.    var index = gamepad.index;
  5.    console.log(“Gamepad No “ + index + ” has been disconnected”);
  6. });

gamepad disconnected, screenshot from jsbin console

Scanning for gamepads

If you reload the page, and if the gamepad has already been detected by the browser, it will not fire the gamepadconnected event again. This can be problematic if you use a global variable for managing the gamepad, or an array of gamepads in your code. As the event is not fired, these variables will stay undefined…

So, you need to regularly scan for gamepads available on the system. You should still use that event listener if you want to do something special when the system detects that a gamepad has been unplugged.

Here is the code to use to scan for a gamepad:

  1. var gamepad;
  3. function mainloop() {
  4.    …
  5.    scangamepads();
  7.    // test gamepad status: buttons, joysticks etc.
  8.    …
  9.    requestAnimationFrame(mainloop);
  10. }
  12. function scangamepads() {
  13.   // function called 60 times/s
  14.   // the gamepad is a “snapshot”, so we need to set it
  15.   // 60 times / second in order to have an updated status
  16.   var gamepads = navigator.getGamepads();
  18.   for (var i = 0; i < gamepads.length; i++) {
  19.     // current gamepad is not necessarily the first
  20.     if(gamepads[i] !== undefined)
  21.        gamepad = gamepads[i];
  22.     }
  23. }

In this code, we check every 1/60 second for newly or re-connected gamepads, and we update the gamepad global var with the first gamepad object returned by the browser. We need to do this so that we have an accurate “snapshot” of the gamepad state, with fixed values for the buttons, axes, etc. If we want to check the current button and joystick statuses, we must poll the browser at a high frequency  and call for an updated snapshot.

From the specification: “getGamepads retrieves a snapshot of the data for the currently connected and interacted-with gamepads.”

This code will be integrated (as well as the event listeners presented earlier) in the next JSBin examples.

To keep things simple, the above code works with a single gamepad – here’s a good example of managing multiple gamepads.

Detecting button status and axes values (joysticks)

Properties of the gamepad object

The gamepad object returned in the event listener has different properties:

    • id: a string indicating the id of the gamepad. Useful with the mapping property below.
    • index: an integer used to distinguish multiple controllers (gamepad 1, gamepad 2, etc.).
    • connected:  true if the controller is still connected, false if it has been disconnected.
    • mapping: not implemented yet by most browsers. It will allow the controllers of the gamepad to be remapped. A layout map is associated with the id of the gamepad. By default, and before they implement support for different mapping, all connected gamepads use a standard default layout.

standard gamepad layout
Click the above image to open a large view in another window/tab.

    • axes: an array of floating point values containing the state of each axis on the device. Usually these represent the analog sticks, with a pair of axes giving the position of the stick in its X and Y axes. Each axis is normalized to the range of -1.0…1.0, with -1.0 representing the up or left-most position of the axis, and 1.0 representing the down or right-most position of the axis.
    • buttons: an array of GamepadButton objects containing the state of each button on the device. Each GamepadButton has a pressed  and avalue property.
    • The pressed property is a Boolean property 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 depressed.

Detecting whether a button is pressed

Digital, on/off buttons evaluate to either one or zero (respectively). Whereas analog buttons will return a floating-point value between zero and one.

Example on JSBin. You might also give a look at at this demo that does the same thing but with multiple gamepads.

button status detected, example on jsbin

Code for checking if a button is pressed:

  1. function checkButtons(gamepad) {
  2.    for (var i = 0; i < gamepad.buttons.length; i++) {
  3.       // do nothing is the gamepad is not ok
  4.       if(gamepad === undefined) return;
  5.       if(!gamepad.connected) return;
  7.       var b = gamepad.buttons[i];
  9.       if(b.pressed) {
  10.          console.log(“Button “ + i + ” is pressed.”);
  11.          if(b.value !== undefined)
  12.              // analog trigger L2 or R2, value is a float in [0, 1]
  13.              console.log(“Its value:” + b.val);
  14.       }
  15.    }
  16. }

In line 11, notice how we detect whether the current button is an analog trigger (L2 or R2 on Xbox360 or PS2/PS3 gamepads). 

Next, we’ll integrate it into the mainloop code. Note that we also need to call the scangamepads function from the loop, to generate fresh “snapshots” of the gamepad with updated properties. Without this call, the gamepad.buttons will return the same  states every time.

  1. function mainloop() {
  2.    // clear, draw objects, etc…
  3.    …
  4.    scangamepads();
  5.    // Check gamepad button states
  6.    checkButtons(gamepad);
  8.    // animate at 60 frames/s
  9.    requestAnimationFrame(mainloop);
  10. }

Detecting axes (joystick) values

Example on JSBin

axes detection in JsBin

Code for detecting the axes’ values:

  1. // detect axis (joystick states)
  2. function checkAxes(gamepad) {
  3.    if(gamepad === undefined) return;
  4.    if(!gamepad.connected) return;
  6.    for (var i=0; i<gamepad.axes.length; i++) {
  7.      var axisValue = gamepad.axes[i];
  8.      // do something with the value
  9.      …
  10.    }
  11. }

Detecting the direction (left, right, up, down, diagonals) and angle of the left joystick

We could add an inputStates object similar to the one we used in the game framework, and check its values in the mainloop to decide whether to move the player up/down/left/right, including diagonals – or maybe we’d prefer to use the current angle of the joystick. Here is how we manage this:

JSBin example:

direction and angle detection for joystick

Source code extract:

  1. var inputStates = {};
  2. …
  3. function mainloop() {
  4.    // clear, draw objects, etc…
  5.    // update gamepad status
  6.    scangamepads();
  7.   // Check gamepad button states
  8.   checkButtons(gamepad);
  9.   // Check joysticks states
  10.   checkAxes(gamepad);
  12.   // Move the player, taking into account
  13.   // the gamepad left joystick state
  14.   updatePlayerPosition();
  16.   // We could use the same technique in
  17.   // order to react when buttons are pressed
  18.   //…
  20.   // animate at 60 frames/s
  21.   requestAnimationFrame(mainloop);
  22. }
  24. function updatePlayerPosition() {
  25.    directionDiv.innerHTML += “”;
  26.    if(inputStates.left) {
  27.       directionDiv.innerHTML = “Moving left”;
  28.    }
  29.    if(inputStates.right) {
  30.       directionDiv.innerHTML = “Moving right”;
  31.    }
  32.    if(inputStates.up) {
  33.       directionDiv.innerHTML = “Moving up”;
  34.    }
  35.    if(inputStates.down) {
  36.       directionDiv.innerHTML = “Moving down”;
  37.    }
  38.    // Display the angle in degrees, in the HTML page
  39.    angleDiv.innerHTML = Math.round((inputStates.angle*180/Math.PI));
  40. }
  42. // gamepad code below
  43. // ————————-
  44. // detect axis (joystick states)
  45. function checkAxes(gamepad) {
  46.   if(gamepad === undefined) return;
  47.   if(!gamepad.connected) return;
  49.   …
  51.   // Set inputStates.left, right, up, down
  52.   inputStates.left = inputStates.right = inputStates.up = inputStates.down = false;
  54.   // all values between [-1 and 1]
  55.   // Horizontal detection
  56.   if(gamepad.axes[0] > 0.5) {
  57.      inputStates.right=true;
  58.      inputStates.left=false;
  59.   } else if(gamepad.axes[0] < –0.5) {
  60.      inputStates.left=true;
  61.      inputStates.right=false;
  62.   }
  64.   // vertical detection
  65.   if(gamepad.axes[1] > 0.5) {
  66.     inputStates.down=true;
  67.     inputStates.up=false;
  68.   } else if(gamepad.axes[1] < –0.5) {
  69.     inputStates.up=true;
  70.     inputStates.down=false;
  71.   }
  73.   // compute the angle. gamepad.axes[1] is the
  74.   // sinus of the angle (values between [-1, 1]),
  75.   // gamepad.axes[0] is the cosinus of the angle.
  76.   // we display the value in degree as in a regular
  77.   // trigonometric circle, with the x axis to the right
  78.   // and the y axis that goes up.
  79.   // The angle = arcTan(sin/cos); We inverse the sign of
  80.   // the sinus in order to have the angle in standard
  81.   // x and y axis (y going up)
  82.   inputStates.angle = Math.atan2(-gamepad.axes[1], gamepad.axes[0]);
  83. }

Other gamepads and joysticks tested

Logitech Attack 3 Joystick on Linux

Hi (=dn reports): Have successfully installed a Logitech Attack 3 joy-stick on my Thinkpad running Linux Mint 17.1. It runs all of the code presented here correctly, reporting 11 buttons and 3 axes (the knurled rotating knob (closest to my pen) is described as a ‘throttle’ or ‘accelerator’)).

Traditionally Linux has been described as ‘for work only’ or ‘no games’, so it was a pleasant surprise to see how easy things were – no “driver” to install (it seems important to uninstall any existing connection between a device and the x-server), installed “joystick” testing and calibration tool, and the “jstest-gtk” configuration and testing tool; and that was ‘it’ – no actual configuration was necessary!

saitek joystick

Wireless Microsoft gamepad

Hi! (Michel Buffa reports) I managed to test a wireless Microsoft gamepad on a PC windows 8.1 and it worked with Chrome/FF. I did not try with a console version of the wireless gamepad, I tried with a version for PC, that comes with a wireless receiver (see pictures and video)

wireless padwureless pad

Video of this gamepad with Windows 8.1 + FireFox

External resources

Leave a comment