Gamepad

A simple gamepad API. You can use it move the main sprite or respond to gamepad events.

NOTE: Gamepad support requires using a secure context (HTTPS) and the GameLoop (since the gamepad state must be checked every frame as there are no global event listeners for gamepad button / axes events).

let { initGamepad, GameLoop, gamepadPressed } = kontra;

// this function must be called first before gamepad
// functions will work
initGamepad();

function update() {
  if (gamepadPressed('dpadleft')) {
    // move left
  }
}

// using the GameLoop is required
let loop = kontra.GameLoop({
  // ...
})
loop.start();
import { initGamepad, GameLoop, gamepadPressed } from 'path/to/kontra.mjs';

// this function must be called first before gamepad
// functions will work
initGamepad();

function update() {
  if (gamepadPressed('dpadleft')) {
    // move left
  }
}

// using the GameLoop is required
let loop = kontra.GameLoop({
  // ...
})
loop.start();
import { initGamepad, GameLoop, gamepadPressed } from 'kontra';

// this function must be called first before gamepad
// functions will work
initGamepad();

function update() {
  if (gamepadPressed('dpadleft')) {
    // move left
  }
}

// using the GameLoop is required
let loop = kontra.GameLoop({
  // ...
})
loop.start();

Table of Contents

Available Buttons

Below is a list of button names that are provided by default. If you need to extend or modify this list, you can use the gamepadMap property.

  • south (Xbox controller: A; PS4 controller: cross)
  • east (Xbox controller: B; PS4 controller: circle)
  • west (Xbox controller: X; PS4 controller: square)
  • north (Xbox controller: Y; PS4 controller: triangle)
  • leftshoulder (Xbox controller: LB; PS4 controller: L1)
  • rightshoulder (Xbox controller: RB; PS4 controller: R1)
  • lefttrigger (Xbox controller: LT; PS4 controller: L2)
  • righttrigger (Xbox controller: RT; PS4 controller: R2)
  • select (Xbox controller: back/view; PS4 controller: share)
  • start (Xbox controller: start/menu; PS4 controller: options)
  • leftstick
  • rightstick
  • dpadup
  • dpaddown
  • dpadleft
  • dpadright

gamepadAxis(​name, gamepad)

Get the value of a specific gamepad axis.

Available axes are:

  • leftstickx
  • leftsticky
  • rightstickx
  • rightsticky
let { Sprite, initGamepad, gamepadAxis } = kontra;

initGamepad();

let sprite = Sprite({
  update: function() {
    // check the axis of the gamepad connected to index 0
    let axisX = gamepadAxis('leftstickx', 0);
    let axisY = gamepadAxis('leftsticky', 0);

    if (axisX < -0.4) {
      // move left
    }
    else if (axisX > 0.4) {
      // move right
    }

    if (axisY < -0.4) {
      // move up
    }
    else if (axisY > 0.4) {
      // move down
    }
  }
});
import { Sprite, initGamepad, gamepadAxis } from 'path/to/kontra.mjs';

initGamepad();

let sprite = Sprite({
  update: function() {
    // check the axis of the gamepad connected to index 0
    let axisX = gamepadAxis('leftstickx', 0);
    let axisY = gamepadAxis('leftsticky', 0);

    if (axisX < -0.4) {
      // move left
    }
    else if (axisX > 0.4) {
      // move right
    }

    if (axisY < -0.4) {
      // move up
    }
    else if (axisY > 0.4) {
      // move down
    }
  }
});
import { Sprite, initGamepad, gamepadAxis } from 'kontra';

initGamepad();

let sprite = Sprite({
  update: function() {
    // check the axis of the gamepad connected to index 0
    let axisX = gamepadAxis('leftstickx', 0);
    let axisY = gamepadAxis('leftsticky', 0);

    if (axisX < -0.4) {
      // move left
    }
    else if (axisX > 0.4) {
      // move right
    }

    if (axisY < -0.4) {
      // move up
    }
    else if (axisY > 0.4) {
      // move down
    }
  }
});

gamepadAxis Parameters

name

String. Name of the axis.

gamepad

Number. Index of the gamepad to check.

gamepadAxis Return value

Number. The value of the axis between -1.0 and 1.0.

gamepadMap

Object. A map of Gamepad button indices to button names. Modify this object to expand the list of available buttons. By default, the map uses the Xbox and PS4 controller button indicies.

let { gamepadMap, gamepadPressed } = kontra;

gamepadMap[2] = 'buttonWest';

if (gamepadPressed('buttonWest')) {
  // handle west face button
}
import { gamepadMap, gamepadPressed } from 'path/to/kontra.mjs';

gamepadMap[2] = 'buttonWest';

if (gamepadPressed('buttonWest')) {
  // handle west face button
}
import { gamepadMap, gamepadPressed } from 'kontra';

gamepadMap[2] = 'buttonWest';

if (gamepadPressed('buttonWest')) {
  // handle west face button
}

gamepadPressed(​button[, options])

Check if a button is currently pressed. Use during an update() function to perform actions each frame.

You can check if the button is pressed on all gamepads or just a specific gamepad. To check a specific gamepad, pass the desired gamepad index as the gamepad option. If the gamepad option is ommited all gamepads will be checked and if at least one is pressing the button the function will return true.

let { Sprite, initGamepad, gamepadPressed } = kontra;

initGamepad();

let sprite = Sprite({
  update: function() {
    if (gamepadPressed('dpadleft')){
      // left dpad pressed
    }
    else if (gamepadPressed('dpadright')) {
      // right dpad pressed
    }

    if (gamepadPressed('dpadup')) {
      // up dpad pressed
    }
    else if (gamepadPressed('dpaddown')) {
      // down dpad pressed
    }
  }
});
import { Sprite, initGamepad, gamepadPressed } from 'path/to/kontra.mjs';

initGamepad();

let sprite = Sprite({
  update: function() {
    if (gamepadPressed('dpadleft')){
      // left dpad pressed
    }
    else if (gamepadPressed('dpadright')) {
      // right dpad pressed
    }

    if (gamepadPressed('dpadup')) {
      // up dpad pressed
    }
    else if (gamepadPressed('dpaddown')) {
      // down dpad pressed
    }
  }
});
import { Sprite, initGamepad, gamepadPressed } from 'kontra';

initGamepad();

let sprite = Sprite({
  update: function() {
    if (gamepadPressed('dpadleft')){
      // left dpad pressed
    }
    else if (gamepadPressed('dpadright')) {
      // right dpad pressed
    }

    if (gamepadPressed('dpadup')) {
      // up dpad pressed
    }
    else if (gamepadPressed('dpaddown')) {
      // down dpad pressed
    }
  }
});

gamepadPressed Parameters

button

String. Button name to check for pressed state.

options Optional

Object. Pressed options.

options.gamepad Optional

Number. Index of the gamepad to check for pressed state.

gamepadPressed Return value

Boolean. true if the button is pressed, false otherwise.

initGamepad(​)

Initialize gamepad event listeners. This function must be called before using other gamepad functions.

offGamepad(​buttons[, options])

Unregister the callback function for a button. Takes a single button or an array of buttons.

When unregistering a button, you have the choice to unregister from a specific gamepad or from all gamepads. To unregister from a specific gamepad, pass the desired gamepad index as the gamepad option. If the gamepad option is ommited the callback is unregistered from all gamepads instead of a specific one.

let { offGamepad } = kontra;

offGamepad('start');
offGamepad(['south', 'rightstick']);

offGamepad('south', {
  gamepad: 0  // unregister from just the gamepad at index 0
});
import { offGamepad } from 'path/to/kontra.mjs';

offGamepad('start');
offGamepad(['south', 'rightstick']);

offGamepad('south', {
  gamepad: 0  // unregister from just the gamepad at index 0
});
import { offGamepad } from 'kontra';

offGamepad('start');
offGamepad(['south', 'rightstick']);

offGamepad('south', {
  gamepad: 0  // unregister from just the gamepad at index 0
});

offGamepad Parameters

buttons

String or an Array of Strings. Button or buttons to unregister callback for.

options Optional

Object. Unregister options.

options.gamepad Optional

Number. Gamepad index. Defaults to unregistering from all gamepads.

options.handler Optional

'gamepaddown' or 'gamepadup'. Whether to unregister from gamepaddown or gamepadup event. Defaults to 'gamepaddown'.

onGamepad(​buttons, callback[, options])

Register a function to be called when a gamepad button is pressed. Takes a single button or an array of buttons. Is passed the Gamepad and the GamepadButton that was pressed as parameters.

When registering the function, you have the choice of registering to a specific gamepad or to all gamepads. To register to a specific gamepad, pass the desired gamepad index as the gamepad option. If the gamepad option is ommited the callback is bound to all gamepads instead of a specific one.

You can register a callback for both a specific gamepad and for all gamepads in two different calls. When this happens, the specific gamepad callback will be called first and then the global one.

let { initGamepad, onGamepad } = kontra;

initGamepad();

onGamepad('start', function(gamepad, button) {
  // pause the game
});
onGamepad(['south', 'rightstick'], function(gamepad, button) {
  // fire gun
});

onGamepad('south', function() {
  // handle south button
}, {
  gamepad: 0  // register just for the gamepad at index 0
});
import { initGamepad, onGamepad } from 'path/to/kontra.mjs';

initGamepad();

onGamepad('start', function(gamepad, button) {
  // pause the game
});
onGamepad(['south', 'rightstick'], function(gamepad, button) {
  // fire gun
});

onGamepad('south', function() {
  // handle south button
}, {
  gamepad: 0  // register just for the gamepad at index 0
});
import { initGamepad, onGamepad } from 'kontra';

initGamepad();

onGamepad('start', function(gamepad, button) {
  // pause the game
});
onGamepad(['south', 'rightstick'], function(gamepad, button) {
  // fire gun
});

onGamepad('south', function() {
  // handle south button
}, {
  gamepad: 0  // register just for the gamepad at index 0
});

onGamepad Parameters

buttons

String or an Array of Strings. Button or buttons to register callback for.

callback

Function. The function to be called when the button is pressed.

options Optional

Object. Register options.

options.gamepad Optional

Number. Gamepad index. Defaults to registerting for all gamepads.

options.handler Optional

'gamepaddown' or 'gamepadup'. Whether to register to the gamepaddown or gamepadup event. Defaults to 'gamepaddown'.

updateGamepad(​)

Update the gamepad state. Call this function every frame only if you are not using the GameLoop. Otherwise it is called automatically.

let { initGamepad, updateGamepad, gamepadPressed } = kontra;

initGamepad();

function update() {
  // not using GameLoop so need to manually call update state
  updateGamepad();

  if (gamepadPressed('dpadleft')) {
    // move left
  }
}
import { initGamepad, updateGamepad, gamepadPressed } from 'path/to/kontra.mjs';

initGamepad();

function update() {
  // not using GameLoop so need to manually call update state
  updateGamepad();

  if (gamepadPressed('dpadleft')) {
    // move left
  }
}
import { initGamepad, updateGamepad, gamepadPressed } from 'kontra';

initGamepad();

function update() {
  // not using GameLoop so need to manually call update state
  updateGamepad();

  if (gamepadPressed('dpadleft')) {
    // move left
  }
}