Open Source Cross-Platform Game Programming

Gamepad

Library for interacting with USB Gamepads meant to be used in conjunction with the Game library. The Gamepad library is currently supported for the following project types: C#/OpenTK, JavaScript, Python/PyGame. Projects that use the Gamepad library can still be safely exported to other project types. However, the number of gamepads detected will always be 0. Note that JavaScript projects may or may not support the Gamepad library depending on browser.

enum ButtonId[link]

Convenience enum for use as button binding ID's. Auto configure will use these values. Note that the other button ID enums will have identical integer values as this enum.

NameDescription
BUTTON_LEFT

BUTTON_RIGHT

BUTTON_UP

BUTTON_DOWN

DPAD

AXIS1

AXIS2

LEFT_TRIGGER

RIGHT_TRIGGER

LEFT_BUMPER

RIGHT_BUMPER

START

BACK

AXIS1_BUTTON

AXIS2_BUTTON

enum PsButtonId[link]

Convenience enum for use as button binding ID's. These map the integer ID's of the auto-configure to the recognizeable PlayStation gamepad. Corresponds to equivalent buttons in the ButtonId enum.

NameDescription
SQUARE

CIRCLE

TRIANGLE

X

DPAD

AXIS1

AXIS2

LEFT_BUMPER2

RIGHT_BUMPER2

LEFT_BUMPER1

RIGHT_BUMPER1

START

SELECT

enum XBoxButtonId[link]

Convenience enum for use as button binding ID's. These map the integer ID's of the auto-configure to the recognizeable XBox gamepad. Corresponds to equivalent buttons in the ButtonId enum.

NameDescription
X

B

Y

A

DPAD

AXIS1

AXIS2

AXIS1_BUTTON

AXIS2_BUTTON

LEFT_TRIGGER

RIGHT_TRIGGER

LEFT_BUMPER

RIGHT_BUMPER

START

BACK

class GamepadDevice[link]

Represents a physical gamepad device.

function bindAnalogAxis(buttonId, isPositive)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as a direction of an analog axis. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned. An analog axis returns a float from -1.0 to 1.0 when queried. This function only binds one direction of the axis. For example, if you bind with isPositive set to false, the button pressed will cause querying it to be less than 0.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

isPositive boolean

Direction of the axis to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function bindAnalogAxis2dX(buttonId, isPositive)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as the X component of an analog axis in a specific direction. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned. A 2D analog axis returns a pair of floats when queried (each being from -1.0 to 1.0). This function only binds one side of the axis for the x direction. For example, if you bind with isPositive set to false, pressing this button will cause queries to the first part of the 2D vector returned to be less than 0.0.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

isPositive boolean

Direction of the axis to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function bindAnalogAxis2dY(buttonId, isPositive)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as the Y component of an analog axis in a specific direction. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned. A 2D analog axis returns a pair of floats when queried (each being from -1.0 to 1.0). This function only binds one side of the axis for the y direction. For example, if you bind with isPositive set to false, pressing this button will cause queries to the second part of the 2D vector returned to be less than 0.0.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

isPositive boolean

Direction of the axis to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function bindAnalogButton(buttonId)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as an analog button. An analog button returns a float between 0.0 and 1.0 when queried. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function bindDigitalAxis(buttonId, isPositive)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as a direction of a digital axis. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned. A digital axis returns -1, 0, or 1 when queried. This function only binds one direction of the axis. For example, if you bind with isPositive set to false, the button pressed will cause querying it to return -1.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

isPositive boolean

Direction of the axis to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function bindDigitalAxis2dX(buttonId, isPositive)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as the X component of a digital axis in a specific direction. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned. A 2D digital axis returns a pair of integers when queried (each being from -1 to 1). This function only binds one side of the axis for the x direction. For example, if you bind with isPositive set to false, pressing this button will cause queries to possibly have -1 in the first part of the 2D vector returned.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

isPositive boolean

Direction of the axis to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function bindDigitalAxis2dY(buttonId, isPositive)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as the Y component of a digital axis in a specific direction. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned. A 2D digital axis returns a pair of integers when queried (each being from -1 to 1). This function only binds one side of the axis for the y direction. For example, if you bind with isPositive set to false, pressing this button will cause queries to possibly have -1 in the second part of the 2D vector returned.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

isPositive boolean

Direction of the axis to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function bindDigitalButton(buttonId)[link]

Binds any actively pressed button or axis that is not already bound in the active configuration to the button ID as a digital button. If binding is successful, true is returned. If a button or axis is pressed, but is already associated with another button ID, nothing will be bound and false is returned. If no buttons or axes are pressed, false is returned. A digital button returns a boolean when queried.

Arguments

NameTypeDescription
buttonId string or integer

Button ID to bind.

Return Value

TypeDescription
boolean

True if a button was bound.

function clearBinding(buttonId)[link]

Removes the binding for the given button ID in the active configuration. If the button ID does not exist in the current configuration, nothing will happen and no error is generated.

Arguments

NameTypeDescription
buttonId string or integer

A button ID previously assigned.

function clearBindings()[link]

Removes all bindings in the active configuration.

function clearId()[link]

Clears the ID for this device.

function flattenConfigs()[link]

Removes all items in the GamepadDevice's configuration stack other than the active one.

function getAxisCount()[link]

Returns the number of axes on this device. This is the number of hardware axes on this device. Note that a single "joystick" axis on a device is generally counted as 2 separate axes. This is because an axis is single-directional that has a positive and negative direction, whereas a joystick axis is 2-dimensional and is treated as two separate axes by the hardware.

Return Value

TypeDescription
integer

Number of axes on this device.

function getAxisState(index)[link]

Returns the state of an axis.

Arguments

NameTypeDescription
index integer

The index of the axis. This must be between 0 and n - 1 where n is the value returned by getAxisCount()

Return Value

TypeDescription
float

The current state of the axis from -1.0 to 1.0.

function getButtonCount()[link]

Returns the number of buttons on this device. This is the number of push-buttons on this device. Axes and directional pads do not count towards this value.

Return Value

TypeDescription
integer

Number of buttons on this device

function getButtonState(index)[link]

Returns the state of a button.

Arguments

NameTypeDescription
index integer

The index of the button. This must be between 0 and n - 1 where n is the value returned by getButtonCount()

Return Value

TypeDescription
boolean

True if the button is currently being held.

function getCurrentState(buttonId)[link]

Returns the state of the given configured button. The actual type that is returned depends on how the button or series of buttons/axes are configured.

  • If the button or axis direction is configured as a digital button, a boolean will be returned.
  • If the button or axis direction is configured as an analog button, a float from 0.0 to 1.0 will be returned, even if the button or axis is hardware digital button.
  • If the axes are configured as a digital 1D axis, an integer from -1 to 1 will be returned.
  • If the axes are configured as an analog 1D axis, a float from -1.0 to 1.0 will be returned.
  • If the axes are configured as a digital 2D axis, a list of two integers will be returned, each between -1 and 1.
  • If the axes are configured as an analog 2D axis, a list of two integers will be returned, each between -1.0 and 1.0.

Arguments

NameTypeDescription
buttonId string or integer

The button ID of a button or 1D or 2D axis that has been configured.

Return Value

TypeDescription
boolean or integer or float or List of floats or List of integers

The current state of the configured button.

function getId()[link]

Returns the user-assigned ID to this device.

Return Value

TypeDescription
string or integer or null

ID value

function getName()[link]

Returns the name of this device as reported by the hardware. This is a product string such as "Lodgy-Tek Stick-o-Joy 5000". This value should be shown to the user in any configuration UI to help identify specific devices. Note: some platforms are unable to identify the product name and will instead return a description of the device including the number of buttons and axes instead.

Return Value

TypeDescription
string

The name of the gamepad

function popConfig()[link]

Pops the active configuration off of the GamepadDevice's configuration stack.

function pushAutoConfigure()[link]

Pushes a configuration to the GamepadDevice's configuration stack that makes its best guess as to how the buttons ought to be configured.

function pushEmptyConfig()[link]

Pushes an empty configuration to the GamepadDevice's configuration stack.

function setId(id)[link]

Sets an ID for this device.

Arguments

NameTypeDescription
id string or integer

A value that can be used to identify this device. More consistently reliable than simply its device index.

class GamepadManager[link]

The GamepadManager is a static class with various utility methods for interacting with Gamepads.

function clearAllIds()[link]

Clears all the ID's that are currently configured to GamepadDevices.

function getDeviceById(id)[link]

A static method that returns a GamepadDevice instance by providing the ID value previously assigned to it. ID's can either be a string or integer and are assigned to devices in a few possible ways.

  • The ID was assigned by loading the previous config file.
  • The ID was assigned to the GamepadDevice via auto-configuring.
  • The ID was manually assigned to a GamepadDevice instance.

Arguments

NameTypeDescription
id string or integer

The ID that has been assigned to this device.

Return Value

TypeDescription
Gamepad.GamepadDevice

a gamepad device with that ID

function getDeviceByIndex(index)[link]

A static method that returns a GamepadDevice instance by providing its index value.

Arguments

NameTypeDescription
index integer

The index of the gamepad device as an index value from 0 to n - 1 where n is the number of gamepads as reported by getDeviceCount().

Return Value

TypeDescription
Gamepad.GamepadDevice

a gamepad device

function getDeviceCount()[link]

A static method that returns the number of devices that are currently available.

Return Value

TypeDescription
integer

Number of devices currently available.

function isGamepadSupported()[link]

A static method that returns true if Gamepads are supported.

Return Value

TypeDescription
boolean

true if the gamepad is supported.

function platformRequiresRefresh()[link]

A static method that returns true if the current platform does not detect gamepads on startup and must be periodically checked. Notably this returns true in JavaScript projects, because the browser does not report the existence of a gamepad unless you first push a button after the page has loaded. Technically this method is not funcetionally necessary as it is safe to call refreshDevices multiple times on any platform. But it does allow for better UX i.e. displaying a message in your gamepad config UI that explicitly tells the user "Please push a button for the gamepad to show up".

Return Value

TypeDescription
boolean

True if new gamepads can appear at any time

function refreshDevices()[link]

A static method that checks to see if any new devices are available. This must be called before accessing any Gamepad methods that interact with devices.

function restoreSettingsFromUserData(deviceIdOrIdList)[link]

Checks to see if there is a previously saved gamepad configuration in UserData. If so, configure as many gamepad devices as possible and assign ID's accordingly. Return the number of gamepads successfully configured.

Arguments

NameTypeDescription
deviceIdOrIdList string or integer or List of integers or List of strings

ID's to assign to devices.

Return Value

TypeDescription
integer

number of gamepads successfully configured.

function saveSettingsToUserData()[link]

Saves the current gamepad configuration to UserData so that it can be re-used the next time this program runs. This will overwrite configurations for previous gamepads that have the same hardware fingerprint as those currently configured. But if no gamepads are currently configured, this function will not delete previous configurations.