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();

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, and the buttonName 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, buttonName) {
  // pause the game
});
onGamepad(['south', 'rightstick'], function(gamepad, button, buttonName) {
  // 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, buttonName) {
  // pause the game
});
onGamepad(['south', 'rightstick'], function(gamepad, button, buttonName) {
  // 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, buttonName) {
  // pause the game
});
onGamepad(['south', 'rightstick'], function(gamepad, button, buttonName) {
  // 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
  }
}