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.
- namespace Gamepad
- enum ButtonId
- enum PsButtonId
- enum XBoxButtonId
- class GamepadDevice
- function bindAnalogAxis(buttonId, isPositive)
- function bindAnalogAxis2dX(buttonId, isPositive)
- function bindAnalogAxis2dY(buttonId, isPositive)
- function bindAnalogButton(buttonId)
- function bindDigitalAxis(buttonId, isPositive)
- function bindDigitalAxis2dX(buttonId, isPositive)
- function bindDigitalAxis2dY(buttonId, isPositive)
- function bindDigitalButton(buttonId)
- function clearBinding(buttonId)
- function clearBindings()
- function clearId()
- function flattenConfigs()
- function getAxisCount()
- function getAxisState(index)
- function getButtonCount()
- function getButtonState(index)
- function getCurrentState(buttonId)
- function getId()
- function getName()
- function popConfig()
- function pushAutoConfigure()
- function pushEmptyConfig()
- function setId(id)
- class GamepadManager
- static function clearAllIds()
- static function getDeviceById(id)
- static function getDeviceByIndex(index)
- static function getDeviceCount()
- static function isGamepadSupported()
- static function platformRequiresRefresh()
- static function refreshDevices()
- static function restoreSettingsFromUserData(deviceIdOrIdList)
- static function saveSettingsToUserData()
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.
| Name | Description |
|---|---|
| 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.
| Name | Description |
|---|---|
| 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.
| Name | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
| isPositive | boolean | Direction of the axis to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
| isPositive | boolean | Direction of the axis to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
| isPositive | boolean | Direction of the axis to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
| isPositive | boolean | Direction of the axis to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
| isPositive | boolean | Direction of the axis to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
| isPositive | boolean | Direction of the axis to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | Button ID to bind. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| 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
| Type | Description |
|---|---|
| integer | Number of axes on this device. |
function getAxisState(index)[link]
Returns the state of an axis.
Arguments
| Name | Type | Description |
|---|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Type | Description |
|---|---|
| integer | Number of buttons on this device |
function getButtonState(index)[link]
Returns the state of a button.
Arguments
| Name | Type | Description |
|---|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| buttonId | string or integer | The button ID of a button or 1D or 2D axis that has been configured. |
Return Value
| Type | Description |
|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| id | string or integer | The ID that has been assigned to this device. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| 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
| Type | Description |
|---|---|
| Gamepad.GamepadDevice | a gamepad device |
function getDeviceCount()[link]
A static method that returns the number of devices that are currently available.
Return Value
| Type | Description |
|---|---|
| integer | Number of devices currently available. |
function isGamepadSupported()[link]
A static method that returns true if Gamepads are supported.
Return Value
| Type | Description |
|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| deviceIdOrIdList | string or integer or List of integers or List of strings | ID's to assign to devices. |
Return Value
| Type | Description |
|---|---|
| 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.