Class Gamepad
An Xbox-style gamepad with two sticks, a D-Pad, four face buttons, two triggers, two shoulder buttons, and two menu buttons that usually sit in the midsection of the gamepad.
Inherited Members
Namespace: UnityEngine .InputSystem
Assembly: Unity.InputSystem.dll
Syntax
public class Gamepad : InputDevice, IDualMotorRumble, IHapticsRemarks
The Gamepad layout provides a standardized layouts for gamepads. Generally, if a specific device is represented as a Gamepad, the controls, such as the face buttons, are guaranteed to be mapped correctly and consistently. If, based on the set of supported devices available to the input system, this cannot be guaranteed, a given device is usually represented as a generic Joystick or as just a plain HID instead.
Examples
using UnityEngine;
using UnityEngine.InputSystem;
namespace DocCodeSamples.Tests
{
internal class GamepadExample : MonoBehaviour
{
void Start()
{
// Print all connected gamepads
Debug.Log(string.Join("\n", Gamepad.all));
}
void Update()
{
var gamepad = Gamepad.current;
// No gamepad connected.
if (gamepad == null)
{
return;
}
// Check if "Button North" was pressed this frame
if (gamepad.buttonNorth.wasPressedThisFrame)
{
Debug.Log("Button North was pressed");
}
// Check if the button control is being continuously actuated and read its value
if (gamepad.rightTrigger.IsActuated())
{
Debug.Log("Right trigger value: " + gamepad.rightTrigger.ReadValue());
}
// Read left stick value and perform some code based on the value
Vector2 move = gamepad.leftStick.ReadValue();
{
// Use the Vector2 move for the game logic here
}
// Creating haptic feedback while "Button South" is pressed and stopping it when released.
if (gamepad.buttonSouth.wasPressedThisFrame)
{
gamepad.SetMotorSpeeds(0.2f, 1.0f);
}
else if (gamepad.buttonSouth.wasReleasedThisFrame)
{
gamepad.ResetHaptics();
}
}
}
}Properties
this[GamepadButton]
Retrieve a gamepad button by its Gamepad
Declaration
public ButtonControl this[GamepadButton button] { get; }Parameters
| Type | Name | Description |
|---|---|---|
| Gamepad |
button | Button to retrieve. |
Property Value
| Type | Description |
|---|---|
| Button |
Exceptions
| Type | Condition |
|---|---|
| Argument |
|
See Also
aButton
Same as button
Declaration
public ButtonControl aButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
all
A list of gamepads currently connected to the system.
Declaration
public static ReadOnlyArray<Gamepad> all { get; }Property Value
| Type | Description |
|---|---|
| Read |
Remarks
Returns all currently connected gamepads.
Does not cause GC allocation.
Do not hold on to the value returned by this getter but rather query it whenever you need it. Whenever the gamepad setup changes, the value returned by this getter is invalidated.
Alternately, for querying a single gamepad, you can use current for example.
See Also
bButton
Same as button
Declaration
public ButtonControl bButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
buttonEast
The right face button of the gamepad.
Declaration
public ButtonControl buttonEast { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the B/Circle face button.
On an Xbox controller, this is the b
See Also
buttonNorth
The top face button of the gamepad.
Declaration
public ButtonControl buttonNorth { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the Y/Triangle face button.
On an Xbox controller, this is the y
See Also
buttonSouth
The bottom face button of the gamepad.
Declaration
public ButtonControl buttonSouth { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the A/Cross face button.
On an Xbox controller, this is the a
See Also
buttonWest
The left face button of the gamepad.
Declaration
public ButtonControl buttonWest { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the X/Square face button.
On an Xbox controller, this is the x
See Also
circleButton
Same as button
Declaration
public ButtonControl circleButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
crossButton
Same as button
Declaration
public ButtonControl crossButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
current
The gamepad last used/connected by the player or null if there is no gamepad connected
to the system.
Declaration
public static Gamepad current { get; }Property Value
| Type | Description |
|---|---|
| Gamepad |
Remarks
When added, a device is automatically made current (see Make
For local multiplayer scenarios (or whenever there are multiple gamepads that need to be usable
in a concurrent fashion), it is not recommended to rely on this property. Instead, it is recommended
to use Player
See Also
dpad
The 4-way directional pad on the gamepad.
Declaration
public DpadControl dpad { get; protected set; }Property Value
| Type | Description |
|---|---|
| Dpad |
Remarks
Control representing the d-pad.
See Also
leftShoulder
The left shoulder/bumper button that sits on top of left
Declaration
public ButtonControl leftShoulder { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the left shoulder button. On Xbox controllers, this is usually called "left bumper" whereas on PS4 controllers, this button is referred to as "L1".
See Also
leftStick
The left thumbstick on the gamepad.
Declaration
public StickControl leftStick { get; protected set; }Property Value
| Type | Description |
|---|---|
| Stick |
Remarks
Control representing the left thumbstick.
See Also
leftStickButton
The button that gets triggered when left
Declaration
public ButtonControl leftStickButton { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing a click with the left stick.
See Also
leftTrigger
The left trigger button sitting below left
Declaration
public ButtonControl leftTrigger { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the left trigger button. On PS4 controllers, this button is referred to as "L2".
See Also
rightShoulder
The right shoulder/bumper button that sits on top of right
Declaration
public ButtonControl rightShoulder { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the right shoulder button. On Xbox controllers, this is usually called "right bumper" whereas on PS4 controllers, this button is referred to as "R1".
See Also
rightStick
The right thumbstick on the gamepad.
Declaration
public StickControl rightStick { get; protected set; }Property Value
| Type | Description |
|---|---|
| Stick |
Remarks
Control representing the right thumbstick.
See Also
rightStickButton
The button that gets triggered when right
Declaration
public ButtonControl rightStickButton { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing a click with the right stick.
See Also
rightTrigger
The right trigger button sitting below right
Declaration
public ButtonControl rightTrigger { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the right trigger button. On PS4 controllers, this button is referred to as "R2".
See Also
selectButton
The left button in the middle section of the gamepad (called "view" on Xbox controllers and "share" on PS4 controllers).
Declaration
public ButtonControl selectButton { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the left button in midsection.
See Also
squareButton
Same as button
Declaration
public ButtonControl squareButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
startButton
The right button in the middle section of the gamepad (called "menu" on Xbox controllers and "options" on PS4 controllers).
Declaration
public ButtonControl startButton { get; protected set; }Property Value
| Type | Description |
|---|---|
| Button |
Remarks
Control representing the right button in midsection.
See Also
triangleButton
Same as button
Declaration
public ButtonControl triangleButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
xButton
Same as button
Declaration
public ButtonControl xButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
yButton
Same as button
Declaration
public ButtonControl yButton { get; }Property Value
| Type | Description |
|---|---|
| Button |
See Also
Methods
FinishSetup()
Perform final initialization tasks after the control hierarchy has been put into place.
Declaration
protected override void FinishSetup()Overrides
Remarks
This method can be overridden to perform control- or device-specific setup work. The most common use case is for looking up child controls and storing them in local getters.
Examples
public class MyDevice : InputDevice
{
public ButtonControl button { get; private set; }
public AxisControl axis { get; private set; }
protected override void OnFinishSetup()
{
// Cache controls in getters.
button = GetChildControl("button");
axis = GetChildControl("axis");
}
}
See Also
MakeCurrent()
Make the gamepad the current gamepad.
Declaration
public override void MakeCurrent()Overrides
Remarks
This is called automatically by the system when there is input on a gamepad.
More remarks are available in Make
Examples
using System;
using UnityEngine;
using UnityEngine.InputSystem;
public class MakeCurrentGamepadExample : MonoBehaviour
{
void Update()
{
/// Make the first Gamepad always the current one
if (Gamepad.all.Count > 0)
{
Gamepad.all[0].MakeCurrent();
}
}
}See Also
OnAdded()
Called by the system when the device is added to devices.
Declaration
protected override void OnAdded()Overrides
Remarks
This is called after the device has already been added.
devicesAddedOn
Examples
using UnityEngine.InputSystem;
public class MyDevice : InputDevice
{
public static MyDevice current { get; private set; }
protected override void OnAdded()
{
// use this context to assign the current device for instance
base.OnAdded();
current = this;
}
}
See Also
OnRemoved()
Called by the system when the device is removed from devices.
Declaration
protected override void OnRemoved()Overrides
Remarks
Examples
using UnityEngine.InputSystem;
public class MyDevice : InputDevice
{
public static MyDevice current { get; private set; }
protected override void OnRemoved()
{
// use this context to unassign the current device for instance
base.OnRemoved();
if (current == this)
current = null;
}
}
See Also
PauseHaptics()
Pause rumble effects on the gamepad.
Declaration
public virtual void PauseHaptics()Remarks
It will pause rumble effects and save the current motor speeds.
Resume from those speeds with Resume
Examples
using UnityEngine;
using UnityEngine.InputSystem;
namespace DocCodeSamples.Tests
{
internal class GamepadHapticsExample : MonoBehaviour
{
bool hapticsArePaused = false;
void Update()
{
var gamepad = Gamepad.current;
// No gamepad connected, no need to continue.
if (gamepad == null)
return;
float leftTrigger = gamepad.leftTrigger.ReadValue();
float rightTrigger = gamepad.rightTrigger.ReadValue();
// Only set motor speeds if haptics were not paused and if trigger is actuated.
// Both triggers must be actuated past 0.2f to start haptics.
if (!hapticsArePaused &&
(gamepad.leftTrigger.IsActuated() || gamepad.rightTrigger.IsActuated()))
gamepad.SetMotorSpeeds(
leftTrigger < 0.2f ? 0.0f : leftTrigger,
rightTrigger < 0.2f ? 0.0f : rightTrigger);
// Toggle haptics "playback" when "Button South" is pressed.
// Notice that if you release the triggers after pausing,
// and press the button again, haptics will resume.
if (gamepad.buttonSouth.wasPressedThisFrame)
{
if (hapticsArePaused)
gamepad.ResumeHaptics();
else
gamepad.PauseHaptics();
hapticsArePaused = !hapticsArePaused;
}
// Notice that if you release the triggers after pausing,
// and press the Start button, haptics will be reset.
if (gamepad.startButton.wasPressedThisFrame)
gamepad.ResetHaptics();
}
}
}See Also
ResetHaptics()
Resets rumble effects on the gamepad by setting motor speeds to 0.
Declaration
public virtual void ResetHaptics()Remarks
Some devices such as Dual
Examples
using UnityEngine;
using UnityEngine.InputSystem;
namespace DocCodeSamples.Tests
{
internal class GamepadHapticsExample : MonoBehaviour
{
bool hapticsArePaused = false;
void Update()
{
var gamepad = Gamepad.current;
// No gamepad connected, no need to continue.
if (gamepad == null)
return;
float leftTrigger = gamepad.leftTrigger.ReadValue();
float rightTrigger = gamepad.rightTrigger.ReadValue();
// Only set motor speeds if haptics were not paused and if trigger is actuated.
// Both triggers must be actuated past 0.2f to start haptics.
if (!hapticsArePaused &&
(gamepad.leftTrigger.IsActuated() || gamepad.rightTrigger.IsActuated()))
gamepad.SetMotorSpeeds(
leftTrigger < 0.2f ? 0.0f : leftTrigger,
rightTrigger < 0.2f ? 0.0f : rightTrigger);
// Toggle haptics "playback" when "Button South" is pressed.
// Notice that if you release the triggers after pausing,
// and press the button again, haptics will resume.
if (gamepad.buttonSouth.wasPressedThisFrame)
{
if (hapticsArePaused)
gamepad.ResumeHaptics();
else
gamepad.PauseHaptics();
hapticsArePaused = !hapticsArePaused;
}
// Notice that if you release the triggers after pausing,
// and press the Start button, haptics will be reset.
if (gamepad.startButton.wasPressedThisFrame)
gamepad.ResetHaptics();
}
}
}See Also
ResumeHaptics()
Resume rumble effects on the gamepad.
Declaration
public virtual void ResumeHaptics()Remarks
It will resume rumble effects from the previously set motor speeds, such as motor speeds saved when
calling Pause
Examples
using UnityEngine;
using UnityEngine.InputSystem;
namespace DocCodeSamples.Tests
{
internal class GamepadHapticsExample : MonoBehaviour
{
bool hapticsArePaused = false;
void Update()
{
var gamepad = Gamepad.current;
// No gamepad connected, no need to continue.
if (gamepad == null)
return;
float leftTrigger = gamepad.leftTrigger.ReadValue();
float rightTrigger = gamepad.rightTrigger.ReadValue();
// Only set motor speeds if haptics were not paused and if trigger is actuated.
// Both triggers must be actuated past 0.2f to start haptics.
if (!hapticsArePaused &&
(gamepad.leftTrigger.IsActuated() || gamepad.rightTrigger.IsActuated()))
gamepad.SetMotorSpeeds(
leftTrigger < 0.2f ? 0.0f : leftTrigger,
rightTrigger < 0.2f ? 0.0f : rightTrigger);
// Toggle haptics "playback" when "Button South" is pressed.
// Notice that if you release the triggers after pausing,
// and press the button again, haptics will resume.
if (gamepad.buttonSouth.wasPressedThisFrame)
{
if (hapticsArePaused)
gamepad.ResumeHaptics();
else
gamepad.PauseHaptics();
hapticsArePaused = !hapticsArePaused;
}
// Notice that if you release the triggers after pausing,
// and press the Start button, haptics will be reset.
if (gamepad.startButton.wasPressedThisFrame)
gamepad.ResetHaptics();
}
}
}See Also
SetMotorSpeeds(float, float)
Set the motor speeds of the low-frequency (usually on the left) and high-frequency (usually on the right) motors.
Declaration
public virtual void SetMotorSpeeds(float lowFrequency, float highFrequency)Parameters
| Type | Name | Description |
|---|---|---|
| float | lowFrequency | Speed of the low-frequency (left) motor. Normalized [0..1] value with 1 indicating maximum speed and 0 indicating the motor is turned off. Will automatically be clamped into range. |
| float | highFrequency | Speed of the high-frequency (right) motor. Normalized [0..1] value with 1 indicating maximum speed and 0 indicating the motor is turned off. Will automatically be clamped into range. |
Remarks
Note that hardware will put limits on the level of control you have over the motors. Rumbling the motors at maximum speed for an extended period of time may cause them to turn off for some time to prevent overheating. Also, how quickly the motors react and how often the speed can be updated will depend on the hardware and drivers.
Examples
using UnityEngine;
using UnityEngine.InputSystem;
namespace DocCodeSamples.Tests
{
internal class GamepadHapticsExample : MonoBehaviour
{
bool hapticsArePaused = false;
void Update()
{
var gamepad = Gamepad.current;
// No gamepad connected, no need to continue.
if (gamepad == null)
return;
float leftTrigger = gamepad.leftTrigger.ReadValue();
float rightTrigger = gamepad.rightTrigger.ReadValue();
// Only set motor speeds if haptics were not paused and if trigger is actuated.
// Both triggers must be actuated past 0.2f to start haptics.
if (!hapticsArePaused &&
(gamepad.leftTrigger.IsActuated() || gamepad.rightTrigger.IsActuated()))
gamepad.SetMotorSpeeds(
leftTrigger < 0.2f ? 0.0f : leftTrigger,
rightTrigger < 0.2f ? 0.0f : rightTrigger);
// Toggle haptics "playback" when "Button South" is pressed.
// Notice that if you release the triggers after pausing,
// and press the button again, haptics will resume.
if (gamepad.buttonSouth.wasPressedThisFrame)
{
if (hapticsArePaused)
gamepad.ResumeHaptics();
else
gamepad.PauseHaptics();
hapticsArePaused = !hapticsArePaused;
}
// Notice that if you release the triggers after pausing,
// and press the Start button, haptics will be reset.
if (gamepad.startButton.wasPressedThisFrame)
gamepad.ResetHaptics();
}
}
}