Gamepad

The gamepad object allows for easier gamepad set up. It uses the Gamepad API to create helper functions to listen for button presses or joystick movement.

To start listening for connected gamepads, you first need to enable it. To do that you need to set the following:

gamepad.enabled = true;

to disable the gamepad, just change the enabled property to false.

Changing the polling interval #

In order to get the correct information from the Gamepad API, we need to poll the data at an interval. By default this interval is 200ms, but you can change it by doing

gamepad.pollingInterval = 400;

Which will change the interval to 400ms.

.on([gamepadAction]) #

The .on call allows you to set up listeners for your gamepad actions.

gamepadAction #

actions #

Type:

type actions = string[] | number[]

The actions array is an array of buttons or joystick actions that will trigger a callback.

You can use either the button number or an alias for the buttons. For the users convenience there are playstation and xbox specific aliases available.

For example:

gamepad.on({
    actions: ['pad-down', 'right-shoulder'],
    callback: () => {},
});

will trigger the callback when the down pad and the right shoulder button are pressed at the same time.

You can also use joystick aliases to trigger callbacks on specific joystick movements.

For example:

gamepad.on({
    actions: ['left.joystick'],
    callback: () => {},
});

will trigger the callback when the left joystick moves.

There are also aliases for specific directions available:

gamepad.on({
    actions: ['left.joystick.down'],
    callback: () => {},
});

will trigger the callback when the left joystick is moved down.

The available aliases are

[
    'right.joystick',
    'left.joystick',
    'left.joystick.down',
    'left.joystick.up',
    'left.joystick.left',
    'left.joystick.right',
    'right.joystick.down',
    'right.joystick.up',
    'right.joystick.left',
    'right.joystick.right',
]

type #

Type

type type = ('press' | 'hold')

The type of action to execute.

Choosing press will trigger the action once if you press and then release the button. Using hold on the other hand will trigger the action constantly until you release the button.

The default value for type is hold.

callback #

Type:

type callback = ([{pressed, touched, value}]) => {} | ([axisX, axisY]) => {} | string

The function that will execute when a gamepad action is triggered.

gamepad.on({
    actions: ['face-button-down'],
    callback: ([button]) => doSomething(button.pressed, button.touched, button.value),
});

gamepad.on({
    actions: ['left.joystick'],
    callback: ([axisX, axisY]) => doSomething(axisX, axisY),
});

If you are using an action for buttons, you can get the GamepadButton objects for each button that is pressed. If you are using a joystick action, you can get the x and y coordinates of the joystick.

If you already have a registered action you can use it instead of a function:

gamepad.on({
    actions: ['face-button-down'],
    callback: 'registered-action',
});

.off([actions]) #

Removes a registered gamepad action.

gamepad.off(['left.joystick']);

You will need to provide the exact actions you have registered in order to remove them.

For example if you have registered an action using a playstation alias, you will also need to remove it using the same alias.