Gamepad

The Gamepad object allows you to detect input from a connected console controller, PC gamepad or joystick. While a range of devices ought to work with the Gamepad object, it is designed for and works best with the XBox 360 controller, or similarly designed controllers (with the same button/stick layout).

Unfortunately whether or not a specific device is supported depends on a lot of factors, including the operating system, available drivers, and the browser's support. This makes it difficult to know in advance if a specific device will work. The XBox 360 controller works out of the box on Windows systems with the Google Chrome browser. The Playstation 3 controller does not typically work without installing third party drivers since it is not officially supported. For this reason it is recommended to test with Google Chrome on Windows with an XBox 360 controller, and always support an alternative input method such as Keyboard input.

Most mobile devices do not have a physical socket to connect a controller to. Therefore Gamepad input can usually only be used with desktop computers. For mobile devices with touchscreen input, focus on designing touch controls.

To prevent allowing websites to track you by your available controllers, most browsers supporting Gamepad input will report that there are no controllers connected until a button is pressed on one of the devices.

Key mapping

Different controllers have different button layouts, or the buttons have different names. For example, the Playstation 3 controller uses square, circle, triangle and X buttons, whereas the XBox 360 controller uses A, B, X and Y (note that X appears in a different position in each controller too). For consistency, the Gamepad object refers to the XBox 360 layout only.

The Gamepad object will also attempt to map other controller's keys to the XBox 360 layout internally, to ensure the same button always triggers the same event. However it is impractical to set this up for every device in existence, so some device buttons may trigger different key events in the Gamepad object. This is partly why it is recommended to focus on XBox 360 controllers. If you are interested in using Gamepad input extensively, be sure to test on as wide a range of devices as you can obtain.

Raw input can be obtained, circumventing the Gamepad object's built in key mapping, using the Raw expressions.

Controlling behaviors with Gamepad

To control behaviors with Gamepad input, use the Simulate control action. An example is shown below for controlling a Platform behavior with the left analog stick and A to jump.

Simulating behavior controls with Gamepad
For more information, see the section on Custom controls in the Behavior reference.

Multiple gamepads

Multiple gamepad devices can be connected to a single computer. To differentiate between them, most actions, conditions and expressions in the Gamepad object also take a Gamepad parameter. This is a zero-based index of the controller. For example, 0 identifies the first controller, 1 identifies the second, and so on. This allows you to make multiplayer gamepad-controlled games.

Gamepad properties

Analog deadzone
Devices with analog joysticks are extremely sensitive to input. This allows fine control in games, but also means a joystick in rest position can still register a fairly large amount of movement. If this wasn't ignored, a joystick-controlled player could start moving around erratically even when the player is not touching the control. To solve this all values close to rest position are ignored. Joystick movement is in the range -100 to 100 on each axis, and if the distance from the center is below the Analog deadzone value, it will return 0. For example, the default is 25, so values inside a circle with the radius 25 will still count as zero. This is the recommended value to ensure even ageing controllers with highly erratic input do not cause unintended player movement.

Gamepad conditions

Gamepads are supported
True if the current platform supports gamepad input. If this is false, then no gamepads or gamepad axis/button inputs will be detected at all.

Has gamepads
True if any gamepad is connected and activated. To prevent websites tracking you based on the available gamepads, most browsers supporting Gamepad input will report that no controllers are connected until a button is pressed on one of the devices.

On gamepad connected
Triggered when a gamepad device is connected to the computer. To prevent websites tracking you based on the available gamepads, most browsers supporting Gamepad input will report that no controllers are connected until a button is pressed on one of the devices, when On gamepad connected will also run.

On gamepad disconnected
Triggered when a gamepad device is disconnected from the computer, such as by pulling out its cable.

Compare axis
Compare the position of an analog joystick on a specific gamepad. Values within the Analog deadzone are returned as 0. Axes values range from -100 to 100.

Is button down
True if a given button is currently down on a specific gamepad. The buttons are always referred to according to the XBox 360 controller layout, and buttons are subject to mapping as described under Key mapping.

Is button index down
True if a given button by its numerical index is currently down on a specific gamepad. The index is still subject to mapping as described under Key mapping.

On any button pressed
Triggered when any button is pressed on a specific gamepad. The LastButton expression is set with the index of the button.

On any button released
Triggered when any button is released on a specific gamepad. The LastButton expression is set with the index of the button.

On button index pressed
Triggered when a given button by its numerical index is pressed on a specific gamepad. The index is still subject to mapping as described under Key mapping.

On button index released
Triggered when a given button by its numerical index is released on a specific gamepad. The index is still subject to mapping as described under Key mapping.

On button pressed
Triggered when a given button is pressed on a specific gamepad. The buttons are always referred to according to the XBox 360 controller layout, and buttons are subject to mapping as described under Key mapping.

On button released
Triggered when a given button is released on a specific gamepad. The buttons are always referred to according to the XBox 360 controller layout, and buttons are subject to mapping as described under Key mapping.

Gamepad actions

The Gamepad object has no actions.

Gamepad expressions

Axis(Gamepad, Index)
Retrieve the current position of an analog joystick on a specific gamepad. Index specifies left analog X and Y or right analog X and Y axes, subject to Key mapping. Axes range from -100 to 100. Axis values within the Analog deadzone are returned as 0.

Button(Gamepad, Index)
Retrieve the current button press value of a button on a specific gamepad. Index specifies the zero-based index of a button from the dropdown list in the Is button down condition (e.g. 0 returns the value for the A button). The returned value depends on the features of the button: if the button is pressure sensitive, it can return any value from 0 to 100 depending on the pressure; otherwise it returns 0 for not pressed and 100 for pressed. Buttons which are not pressure sensitive are easier to detect using the Is button down condition.

GamepadCount
Return the number of currently connected and active gamepad devices. To prevent websites tracking you based on the available gamepads, most browsers supporting Gamepad input will report that no controllers are connected until a button is pressed on one of the devices.

GamepadID(Gamepad)
A string intended to represent the device manufacturer and model for a specific gamepad, e.g. "XBox 360 controller". However in practice this varies depending on the system and browser in use.

LastButton
Return the numerical index of the last button pressed on a specific gamepad. This is useful with the On any button pressed and On any button released triggers to set up custom controls.

RawAxis(Gamepad, Index)
Retrieve raw axis input for a specific gamepad and axis index. This returns the value without keymapping, applying the analog deadzone, or multiplying the returned value by 100. Axis values range from -1 to 1.

RawAxisCount(Gamepad)
Return the number of axes available in the raw input for a specific gamepad. This returns the value without keymapping.

RawButton(Gamepad, Index)
Retrieve raw button input for a specific gamepad and button index. This returns the value without keymapping. Button values range from 0 to 1 (pressure sensitive buttons can return values in between).

RawButtonCount(Gamepad)
Return the number of buttons available in the raw input for a specific gamepad. This returns the value without keymapping.

Tags: