Both gamepads and buttons start with an index of 1. That is, the first detected gamepad had an ID of 1, and the first button on that gamepad has a button ID of 1.

Up to 16 gamepads are supported. Up to 32 buttons and 6 axis per gamepad are supported. Any gamepads you wish to read input from should be plugged in before starting a script in which you intend to use it for.

To make working with the POV hat (aka D-pad) a bit easier, a few variables have been added to global scope:

Every gamepa model will have it's own unique button & axis map. In modern times, Xbox and PlayStation controllers have become a bit of a standard for PC gaming, however there are thousands of USB gamepads that do not conform to any standard.

Unfortunately, this means that you will likely need to discover how buttons & axis are mapped for your gamepad if they are not a common and well-recognized controller. You may do this by conecting the gamepad and running the included 'keytest.lua' script. Once the script has been run, it will continue to dump information on any keys, mouse buttons, or gamepad inputs that it can detect.

For your convenience, details on a few gamepads will be detailed below.

XBox 360

XBox 360 controllers have a few quirks to them. First and foremost, it needs to be noted that the "Guide" button (that big round button in the center that usually as an XBox logo on it) does not actually trigger a gamepad button press, but rather a normal virtual key as if from a keyboard. Pressing the Guide button sends a vk up/down event for VK 0x07; according to Microsoft's documentation this VK code is "undefined."

The controller only has one POV-hat and responds with a number value that is consistent with gamepad.getPOV()'s documentation. The POV-hat will only give data at 45° resolution meaning it is only 8-directional.

The two analog sticks each have 2 axis while the left and right triggers share an axis. The left analog stick uses Axis 1 in the horizontal direction (0.0 = left, 100.0 = right) and Axis 2 in the vertical direction (0.0 = up, 100.0 = down) while the right analog stick uses Axis 5 for the horizontal direction and Axis 4 in the vertical direction. LT (left trigger) and RT (right trigger) share an axis (Axis 3) such that the right trigger only provides data in the 50.0 (unpressed state) to 0.0 (fully pressed state) range and the left trigger only provides data in the 50.0 (unpressed state) to 100.0 (fully pressed state) range.

Generic USB PS2-like

While a PS2-style gamepad may be more straight-forward than XBox 360 controllers, there is one slightly unusual thing: the analog toggle button. When this toggle is off, both analog sticks instead behave more like digital inputs and will instead result in values 0.0, ~50.0 (centered) or 100.0 rather than a linear progression from 0.0 to 100.0. They will act more like a POV-hat than analog input, however, it is important to note that they still output analog, dual-axis values. The analog button itself will not expose any output or be readable, therefor you will not receive any events for this button.

The controller only has one POV-hat and responds with a number value that is consistent with gamepad.getPOV()'s documentation. The POV-hat will only give data at 45° resolution meaning it is only 8-directional.

Nintendo Switch JoyCons

Known Quirks

• When paired via Bluetooth to a PC, the joycon lights still flash rather than represent controller order.
• Joysticks act more like 8-directional POV-hats rather than dual-axis controls.
• Left and Right joycons will not combine to a singular device but instead behave as two separate controllers.
• No accelerometer/gyro data is provided.

Each JoyCon has a joystick, however, please note that it acts like an 8-directional POV-hat. The orientation for each JoyCon depends on whether it is a Left (L) or Right (R) JoyCon. Both follow a 0° to 315° range in the clockwise direction and both begin (0°) pointing towards the "inside" (where the Switch would be if they were directly connected) and are therefore opposite to each other. See the diagram for clarity.

Button Layout