UnityGame/Library/PackageCache/com.unity.inputsystem/Documentation~/Gamepad.md

uid
input-system-gamepad

Gamepad Support

• Controls
  • Deadzones
• Polling
• Rumble
  • Pausing, resuming, and stopping haptics
• PlayStation controllers
• Xbox controllers
• Switch controllers
• Cursor Control
• Discover all connected devices

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: Generic HID gamepads will not be surfaced as Gamepad devices but rather be created as generic joysticks. This is because the Input System cannot guarantee correct mapping of buttons and axes on the controller (the information is simply not available at the HID level). Only HID gamepads that are explicitly supported by the Input System (like the PS4 controller) will come out as gamepads. Note that you can set up the same kind of support for specific HID gamepads yourself (see "Overriding the HID Fallback").

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"]

Deadzones

Deadzones prevent accidental input due to slight variations in where gamepad sticks come to rest at their centre point. They allow a certain small inner area where the input is considered to be zero even if it is slightly off from the zero position.

To add a deadzone to gamepad stick, put a stick deadzone Processor on the sticks, like this:

     {
        "name" : "MyGamepad",
        "extend" : "Gamepad",
        "controls" : [
            {
                "name" : "leftStick",
                "processors" : "stickDeadzone(min=0.125,max=0.925)"
            },
            {
                "name" : "rightStick",
                "processors" : "stickDeadzone(min=0.125,max=0.925)"
            }
        ]
    }

You can do the same in your C# state structs.

    public struct MyDeviceState
    {
        [InputControl(processors = "stickDeadzone(min=0.125,max=0.925)"]
        public StickControl leftStick;
        [InputControl(processors = "stickDeadzone(min=0.125,max=0.925)"]
        public StickControl rightStick;
    }

The gamepad layout already adds stick deadzone processors which take their min and max values from InputSettings.defaultDeadzoneMin and InputSettings.defaultDeadzoneMax.

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.

• DualSenseGamepadHID: A DualSense controller connected to a desktop computer using the HID interface. Supported on macOS, Windows.

• DualShock4GampadiOS: A DualShock 4 controller connected to an iOS Device via Bluetooth. Requires iOS 13 or higher.

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

Note that, due to limitations in the USB driver and/or the hardware, only one IOCTL (input/output control) command can be serviced at a time. SetLightBarColor(Color) and SetMotorSpeeds(Single, Single) functionality on Dualshock 4 is implemented using IOCTL commands, and so if either method is called in quick succession, it is likely that only the first command will successfully complete. The other commands will be dropped. If there is a need to set both lightbar color and rumble motor speeds at the same time, use the SetMotorSpeedsAndLightBarColor(Single, Single, Color) method.

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 controllers

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 controllers

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

Note

: This support does not currently work for Switch Pro controllers connected via wired USB. Instead, the Switch Pro controller must be connected via Bluetooth. This is due to the controller using a prioprietary communication protocol on top of HID which does not allow treating the controller like any other HID.

Note

: Switch Joy-Cons are not currently supported on desktop.

Cursor Control

To give gamepads and joysticks control over a hardware or software cursor, you can use the VirtualMouseInput component. See VirtualMouseInput component in the UI section of the manual.

Discover all connected devices

There are various ways to discover the currently connected devices, as shown in the code samples below.

To query a list of all connected devices (does not allocate; read-only access):

InputSystem.devices

To get notified when a device is added or removed:

InputSystem.onDeviceChange +=
    (device, change) =>
    {
        if (change == InputDeviceChange.Added || change == InputDeviceChange.Removed)
        {
            Debug.Log($"Device '{device}' was {change}");
        }
    }

To find all gamepads and joysticks:

var devices = InputSystem.devices;
for (var i = 0; i < devices.Count; ++i)
{
    var device = devices[i];
    if (device is Joystick || device is Gamepad)
    {
        Debug.Log("Found " + device);
    }
}