Gamepad Support

A Gamepad is narrowly defined as a Device with two thumbsticks, a D-pad, and four face buttons. Additionally, gamepads usually have two shoulder and two trigger buttons. Most gamepads also have two buttons in the middle.

A gamepad can have additional Controls, such as a gyro, which the Device can expose. However, all gamepads are guaranteed to have at least the minimum set of Controls described above.

Gamepad support guarantees the correct location and functioning of Controls across platforms and hardware. For example, a PS4 DualShock controller layout should look identical regardless of which platform it is supported on. A gamepad's south face button should always be the lowermost face button.

NOTE: In case you want to use the gamepad for driving mouse input, there is a sample called Gamepad Mouse Cursor you can install from the package manager UI when selecting the Input System package. The sample demonstrates how to set up gamepad input to drive a virtual mouse cursor.

Controls

Every gamepad has the following Controls:

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 like a D-pad.
`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 like a D-pad.
`dpad`	`DpadControl`	The D-pad on the gamepad.
`buttonNorth`	`ButtonControl`	The upper button of the four action buttons, which are usually located on the right side of the gamepad. Labelled "Y" on Xbox controllers and "Triangle" on PlayStation controllers.
`buttonSouth`	`ButtonControl`	The lower button of the four action buttons, which are usually located on the right side of the gamepad. Labelled "A" on Xbox controllers and "Cross" on PlayStation controllers.
`buttonWest`	`ButtonControl`	The left button of the four action buttons, which are usually located on the right side of the gamepad. Labelled "X" on Xbox controllers and "Square" on PlayStation controllers.
`buttonEast`	`ButtonControl`	The right button of the four action buttons, which are 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 when the user presses down the left stick.
`rightStickButton`	`ButtonControl`	The button pressed when the user presses down the right stick.

Note: Buttons are also full floating-point axes. For example, the left and right triggers can function as buttons as well as full floating-point axes.

You can also access gamepad buttons 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. For example, the following four accessors all retrieve the same "north" face button:

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

Polling

On Windows (XInput controllers only), Universal Windows Platform (UWP), and Switch, Unity polls gamepads explicitly rather than deliver updates as events.

You can control polling frequency 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 follow the spacing dictated by the polling frequency. Note, however, that the asynchronous background polling depends on OS thread scheduling and can vary.

Rumble

The Gamepad class implements the IDualMotorRumble interface that allows 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. Only supported if you install console-specific input packages 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. You can pause, resume, and reset haptic feedback using the PauseHaptics, ResumeHaptics, and ResetHaptics methods respectively.

In certain situations, you might want to globally pause or stop haptics for all Devices. For example, if the player enters an in-game menu, you can pause haptics while the player is in the menu, and then resume haptics once the player resumes the game. You can use the corresponding methods on InputSystem to achieve this result. These methods work the same way as Device-specific 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 resets haptics playback state on each Device to its initial state, whereas PauseHaptics preserves playback state in memory and only stops playback on the hardware.

PlayStation controllers

PlayStation controllers are well supported on different Devices. The Input System implements these as different derived types of the DualShockGamepad base class, which derives from Gamepad):

DualShock3GamepadHID: A DualShock 3 controller connected to a desktop computer using the HID interface. Currently only supported on macOS. Doesn't support rumble.
DualShock4GamepadHID: A DualShock 4 controller connected to a desktop computer using the HID interface. Supported on macOS, Windows, UWP, and Linux.
DualShock4GampadiOS: A DualShock 4 controller connected to an iOS Device via Bluetooth. Requires iOS 13 or higher.

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

SetLightBarColor(Color): Used to set the color of the light bar on the controller.

Note:

Unity supports PlayStation controllers on WebGL in some browser and OS configurations, but treats them as basic Gamepad or Joystick Devices, and doesn't support rumble or any other DualShock-specific functionality.

Unity doesn't support connecting a PlayStation controller to a desktop machine using the DualShock 4 USB Wireless Adaptor. Use USB or Bluetooth to connect it.

Xbox

Xbox controllers are well supported on different Devices. The Input System implements these using the XInputController class, which derives from Gamepad. On Windows and UWP, Unity uses the XInput API to connect to any type of supported XInput controller, including all Xbox One or Xbox 360-compatible controllers. These controllers are represented as an XInputController instance. You can query the XInputController.subType property to get information about the type of controller (for example, a wheel or a gamepad).

On other platforms Unity, uses derived classes to represent Xbox controllers:

XboxGamepadMacOS: Any Xbox or compatible gamepad connected to a Mac via USB using the Xbox Controller Driver for macOS.
XboxOneGampadMacOSWireless: An Xbox One controller connected to a Mac via Bluetooth. Only the latest generation of Xbox One controllers supports Bluetooth. These controllers don't require any additional drivers in this scenario.
XboxOneGampadiOS: An Xbox One controller connected to an iOS Device via Bluetooth. Requires iOS 13 or higher.

Note:

XInput controllers on Mac currently require the installation of the Xbox Controller Driver for macOS. This driver only supports USB connections, and doesn't support wireless dongles. However, the latest generation of Xbox One controllers natively support Bluetooth. Macs natively support these controllers as HIDs without any additional drivers when connected via Bluetooth.

Unity supports Xbox controllers on WebGL in some browser and OS configurations, but treats them as basic Gamepad or Joystick Devices, and doesn't support rumble or any other Xbox-specific functionality.

Switch

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

Gamepad.md 14 KB Permalink History Raw