IsGamepadButtonDown
This functions allows a developer to quickly check if a particular button is pressed on a particular gamepad. It returns true if the Enum/UserInputType|gamepad has the specified Enum/KeyCode|button pressed down, otherwise it returns false.
Valid UserInputTypes
The specified gamepad should be one of the following UserInputType enum values:
| Name | |
|---|---|
| Enum.UserInputType.Gamepad1-8< |
Valid KeyCodes
The specified button should be one of the following KeyCodes enum values:
| Name | |
|---|---|
| Enum.KeyCode.ButtonX< | |
| Enum.KeyCode.ButtonY< | |
| Enum.KeyCode.ButtonA< | |
| Enum.KeyCode.ButtonB< | |
| Enum.KeyCode.ButtonR1< | |
| Enum.KeyCode.ButtonL1< | |
| Enum.KeyCode.ButtonR3< | |
| Enum.KeyCode.ButtonL3< | |
| Enum.KeyCode.ButtonStart< | |
| Enum.KeyCode.ButtonSelect< | |
| Enum.KeyCode.DPadLeft< | |
| Enum.KeyCode.DPadRight< | |
| Enum.KeyCode.DPadUp< | |
| Enum.KeyCode.DPadDown< |
This can be used to check whether a specific button, such as A, is being held down. For example:
local UserInputService = game:GetService("UserInputService")
local button = Enum.KeyCode.ButtonA
local gamepad = Enum.UserInputType.Gamepad1
local isButtonHeld = UserInputService:IsGamepadButtonDown(gamepad, button)
Since UserInputService is client-side only, this function can only be used in a LocalScript.
See this page for articles on cross-platform development.
See also
UserInputService/GamepadConnectedUserInputService/GamepadDisconnectedUserInputService/GetConnectedGamepadsUserInputService/GetNavigationGamepadsUserInputService/SetNavigationGamepadUserInputService/IsNavigationGamepadUserInputService/GetSupportedGamepadKeyCodesUserInputService/GetGamepadStateUserInputService/GetGamepadConnectedUserInputService/GamepadSupportsUserInputService/GamepadEnabledUserInputType/IsKeyDown- A similar event with a different use: To check if a givenEnum/KeyCode|keyon aEnum/UserInputType|keyboardis pressed.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
|
|
The |
||
|
|
The |
Returns
| Return Type | Summary |
|---|---|
|
Whether the specified gamepad button on the given gamepad is pressed is pressed |
Code Samples
Special Action on Gamepad Button Combo
This example uses the UserInputService/IsGamepadButtonDown function to create different behaviors when the Enum/KeyCode|X gamepad button is pressed than when a X button is not pressed when user input UserInputBegan|begins.
The local function IsGamepadXDown() returns whether the X gamepad button is down. This function checks if the X button is down for the activeGamepad, which is set by GetActiveGamepad. The GetActiveGamepad() fnction finds the lowest numbered UserInputService/GetNavigationGamepads|navigation gamepad, UserInputService/GetConnectedGamepads|connected gamepad, or Enum/KeyCode|gamepad1 if there are no navigation or connected gamepads.
local UserInputService = game:GetService("UserInputService")
local activeGamepad = nil
local buttonX = Enum.KeyCode.ButtonX
local function IsGamepadXDown()
if activeGamepad then
return UserInputService:IsGamepadButtonDown(activeGamepad, buttonX)
end
return false
end
local function Input(input, gameProcessedEvent)
if not IsGamepadXDown() then
-- Normal event
else
-- X Button down event
end
end
function GetActiveGamepad()
local activateGamepad = nil
local navigationGamepads = {}
navigationGamepads = UserInputService:GetNavigationGamepads()
if #navigationGamepads > 1 then
for i = 1, #navigationGamepads do
if activateGamepad == nil then
activateGamepad = navigationGamepads[i]
elseif navigationGamepads[i].Value < activateGamepad.Value then
activateGamepad = navigationGamepads[i]
end
end
else
local connectedGamepads = {}
connectedGamepads = UserInputService:GetConnectedGamepads()
if #connectedGamepads > 0 then
for i = 1, #connectedGamepads do
if activateGamepad == nil then
activateGamepad = connectedGamepads[i]
elseif connectedGamepads[i].Value < activateGamepad.Value then
activateGamepad = connectedGamepads[i]
end
end
end
if activateGamepad == nil then -- nothing is connected, at least set up for gamepad1
activateGamepad = Enum.UserInputType.Gamepad1
end
end
return activateGamepad
end
if UserInputService.GamepadEnabled then
activeGamepad = GetActiveGamepad()
UserInputService.InputBegan:Connect(Input)
end