Gamepad Support

A Gamepad is narrowly defined as a device with two thumbsticks, a dpad, and four face buttons. Additionally, they will usually have two shoulder and two trigger buttons. Most gamepads also have two buttons in the middle section of the gamepad.

A gamepad may have additional controls (such as a gyro) which are exposed from the device but each gamepad is guaranteed to at least have the above-mentioned minimum set of controls.

The goal of gamepad support is to guarantee correct location and functioning of controls across platforms and hardware. A PS4 DualShock controller, for example, is meant to look identical regardless of which platform it is supported on. And a gamepad's south face button, for example, is meant to be expected to always indeed be the bottom-most face button.

Controls

The following controls are present on every gamepad:

Control Type Description
leftStick StickControl Thumbstick on the left side of the gamepad. Deadzoned. Provides a normalized 2D motion vector. X is [-1..1] from left to right, Y is [-1..1] from bottom to top. Has up/down/left/right buttons for use in dpad-like fashion.
rightStick StickControl Thumbstick on the right side of the gamepad. Deadzoned. Provides a normalized 2D motion vector. X is [-1..1] from left to right, Y is [-1..1] from bottom to top. Has up/down/left/right buttons for use in dpad-like fashion.
dpad Dpad
buttonNorth ButtonControl The upper one of the four actions buttons (usually located on the right side of the gamepad). Labelled "Y" on Xbox controllers and "Triangle" on PlayStation controllers.
buttonSouth ButtonControl The lower one of the four actions buttons (usually located on the right side of the gamepad). Labelled "A" on Xbox controllers and "Cross" on PlayStation controllers.
buttonWest ButtonControl The left one of the four actions buttons (usually located on the right side of the gamepad). Labelled "X" on Xbox controllers and "Square" on PlayStation controllers.
buttonEast ButtonControl The right one of the four actions buttons (usually located on the right side of the gamepad). Labelled "B" on Xbox controllers and "Circle" on PlayStation controllers.
leftShoulder ButtonControl The left shoulder button.
rightShoulder ButtonControl The right shoulder button.
leftTrigger ButtonControl The left trigger button.
rightTrigger ButtonControl The right trigger button.
startButton ButtonControl The start button.
selectButton ButtonControl The select button.
leftStickButton ButtonControl The button pressed by pressing down the left stick.
rightStickButton ButtonControl The button pressed by pressing down the right stick.

NOTE: Be aware that buttons are also full floating-point axes. This means that, for example, the left and right triggers can function both as buttons as well as full floating-point axes.

Gamepad buttons can also be accessed using the indexer property on Gamepad and the GamepadButton enumeration:

Gamepad.current[GamepadButton.LeftShoulder];

Gamepads have both both Xbox-style and PS4-style aliases on buttons. The following four accessors all retrieve the same "north" face button, for example:

Gamepad.current[GamepadButton.Y]
Gamepad.current["Y"]
Gamepad.current[GamepadButton.Triangle]
Gamepad.current["Triangle"]

Polling

On Windows (XInput controllers only), UWP and Switch, gamepads are polled explicitly by Unity, rather than delivered as events.

The frequency of the polling can be controlled manually. The default polling frequency is 60 Hz. Use InputSystem.pollingFrequency to get or set the frequency.

// Poll gamepads at 120 Hz.
InputSystem.pollingFrequency = 120;

Increased frequency should lead to an increased number of events on the respective devices. The timestamps provided on the events should roughly following the spacing dicated by the polling frequency. Note, however, that the asynchronous background polling depends on OS thread scheduling and is thus susceptible to variance.

Rumble

The Gamepad class implements the IDualMotorRumble interface to allow you to control the left and right motor speeds. In most common gamepads, the left motor emits a low-frequency rumble, and the right motor emits a high frequency rumble.

// Rumble the  low-frequency (left) motor at 1/4 speed and the high-frequency
// (right) motor at 3/4 speed.
Gamepad.current.SetMotorSpeeds(0.25f, 0.75f);

NOTE: Only the following combinations of devices/OSes currently support rumble:

  • PS4, Xbox and Switch controllers when connected to their respective consoles (requires console-specific packages to be installed in your project).
  • PS4 controllers when connected to Mac or Windows/UWP computers.
  • Xbox controllers on windows.

Pausing, Resuming, and Stopping Haptics

IDualMotorRumble is based on IHaptics, which is the base interface for any haptics support on any device, and allows you to pause, resume and reset haptic feedback, using the PauseHaptics, ResumeHaptics and ResetHaptics methods respectively.

In can be desirable to globally pause or stop haptics for all devices in certain situation. For example, if the player enters the in-game menu, it can make sense to pauses haptics while the player is in the menu and then resume haptics effects once the player resumes the game. You can use the corresponding methods on InputSystem for that (which work the same way as the per-device methods, but affect all devices):

// Pause haptics globally.
InputSystem.PauseHaptics();

// Resume haptics globally.
InputSystem.ResumeHaptics();

// Stop haptics globally.
InputSystem.ResetHaptics();

The difference between PauseHaptics and ResetHaptics is that the latter will reset haptics playback state on each device to its initial state whereas PauseHaptics will preserve playback state in memory and only stop playback on the hardware.

PlayStation controllers

PlayStation controllers are well supported on different devices. They are implemented as different derived types of the DualShockGamepad base class (which itself derives from Gamepad):

  • DualShock3GamepadHID: A DualShock 3 controller connected to a desktop computer using the HID interface. Currently only supported on macOS, and does not support rumble.

  • DualShock4GamepadHID: A DualShock 4 controller connected to a desktop computer using the HID interface (supported on macOS, Windows, UWP, and Linux).

DualShock4GamepadHID implements additional, DualShock-specific functionality on top the general support in the Gamepad class:

NOTES:

  • We support PlayStation controllers on WebGL in some browser/OS configs, but they will always be represented as basic Gamepad or Joystick devices, and we do not support Rumble or any other DualShock specific functionality.
  • We do not support the "DualShock 4 USB Wireless Adaptor" to connect a PlayStation controller to a desktop machine. Use USB or Bluetooth to connect it.

Xbox

Xbox controllers are well supported on different devices. They are implemented using the XInputController class, (which derives from Gamepad). On Windows/UWP, any type of supported XInput controller (which includes all Xbox One or Xbox 360 compatible controllers) will be connected to using the XInput API and is represented directly as an XInputController instance. You can query the XInputController.subType property to get information about the type of controller (wheel, gamepad, etc).

On other platforms we use specific derived classes to represent Xbox controllers:

NOTES:

  • XInput controllers on Mac currently require the installation of the Xbox Controller Driver for macOS. Only USB connections are supported, no wireless dongles. However, the latest generation of Xbox One controllers natively supported Bluetooth, and are natively supported on Macs as HID devices without any additional driver when connected via Bluetooth.
  • We support Xbox controllers on WebGL in some browser/OS configs, but they will always be represented as basic Gamepad or Joystick devices, and we do not support Rumble or any other Xbox specific functionality.

Switch

We support Switch Pro controllers on desktop computers via the SwitchProControllerHID class, which implements the basic gamepad functionality.