Gamepad
The Gamepad class is part of the Input package.
local Gamepad = require(packages.Input).Gamepad
local gamepad = Gamepad.new()
Types
GamepadState
Properties
ButtonDown
This item is read only and cannot be modified. Read OnlyThe ButtonDown signal fires when a gamepad button is pressed down. The pressed KeyCode is passed to the signal, along with whether or not the event was processed.
gamepad.ButtonDown:Connect(function(button: Enum.KeyCode, processed: boolean)
print("Button down", button, processed)
end)
ButtonUp
This item is read only and cannot be modified. Read OnlyThe ButtonUp signal fires when a gamepad button is released. The released KeyCode is passed to the signal, along with whether or not the event was processed.
gamepad.ButtonUp:Connect(function(button: Enum.KeyCode, processed: boolean)
print("Button up", button, processed)
end)
Connected
This item is read only and cannot be modified. Read OnlyGamepad.Connected:
Signal
Fires when the gamepad is connected. This will not fire if the
active gamepad is switched. To detect switching to different
active gamepads, use the GamepadChanged
signal.
There is also a gamepad:IsConnected()
method.
gamepad.Connected:Connect(function()
print("Connected")
end)
Disconnected
This item is read only and cannot be modified. Read OnlyGamepad.Disconnected:
Signal
Fires when the gamepad is disconnected. This will not fire if the
active gamepad is switched. To detect switching to different
active gamepads, use the GamepadChanged
signal.
There is also a gamepad:IsConnected()
method.
gamepad.Disconnected:Connect(function()
print("Disconnected")
end)
GamepadChanged
This item is read only and cannot be modified. Read OnlyFires when the active gamepad switches. Internally, the gamepad object will always wrap around the active gamepad, so nothing needs to be changed.
gamepad.GamepadChanged:Connect(function(newGamepad: Enum.UserInputType)
print("Active gamepad changed to:", newGamepad)
end)
DefaultDeadzone
Gamepad.DefaultDeadzone:
number
Default
Defaults to 0.05
The default deadzone used for trigger and thumbstick analog readings. It is usually best to set this to a small value, or allow players to set this option themselves in an in-game settings menu.
The GetThumbstick
and GetTrigger
methods also allow
a deadzone value to be passed in, which overrides this
value.
SupportsVibration
This item is read only and cannot be modified. Read OnlyGamepad.SupportsVibration:
boolean
Flag to indicate if the currently-active gamepad supports haptic motor vibration.
It is safe to use the motor methods on the gamepad without checking this value, but nothing will happen if the motors are not supported.
State
This item is read only and cannot be modified. Read OnlyGamepad.State:
GamepadState
Maps KeyCodes to the matching InputObjects within the gamepad.
These can be used to directly read the current input state of
a given part of the gamepad. For most cases, the given methods
and properties of Gamepad
should make use of this table quite
rare, but it is provided for special use-cases that might occur.
Do Not Cache
These state objects will change if the active gamepad changes.
Because a player might switch up gamepads during playtime, it cannot
be assumed that these state objects will always be the same. Thus
they should be accessed directly from this State
table anytime they
need to be used.
local leftThumbstick = gamepad.State[Enum.KeyCode.Thumbstick1]
print(leftThumbstick.Position)
-- It would be better to use gamepad:GetThumbstick(Enum.KeyCode.Thumbstick1),
-- but this is just an example of direct state access.
Functions
new
Constructs a gamepad object.
If no gamepad UserInputType is provided, this object will always wrap
around the currently-active gamepad, even if it changes. In most cases
where input is needed from just the primary gamepad used by the player,
leaving the gamepad
argument blank is preferred.
Only include the gamepad
argument when it is necessary to hard-lock
the object to a specific gamepad input type.
-- In most cases, construct the gamepad as such:
local gamepad = Gamepad.new()
-- If the exact UserInputType gamepad is needed, pass it as such:
local gamepad = Gamepad.new(Enum.UserInputType.Gamepad1)
GetThumbstick
Gets the position of the given thumbstick. The two thumbstick
KeyCodes are Enum.KeyCode.Thumbstick1
and Enum.KeyCode.Thumbstick2
.
If deadzoneThreshold
is not included, the DefaultDeadzone
value is
used instead.
local leftThumbstick = gamepad:GetThumbstick(Enum.KeyCode.Thumbstick1)
print("Left thumbstick position", leftThumbstick)
GetTrigger
Gets the position of the given trigger. The triggers are usually going
to be Enum.KeyCode.ButtonL2
and Enum.KeyCode.ButtonR2
. These trigger
buttons are analog, and will output a value between the range of [0, 1].
If deadzoneThreshold
is not included, the DefaultDeadzone
value is
used instead.
local triggerAmount = gamepad:GetTrigger(Enum.KeyCode.ButtonR2)
print(triggerAmount)
IsButtonDown
Returns true
if the given button is down. This includes
any button on the gamepad, such as Enum.KeyCode.ButtonA
,
Enum.KeyCode.ButtonL3
, Enum.KeyCode.DPadUp
, etc.
-- Check if the 'A' button is down:
if gamepad:IsButtonDown(Enum.KeyCode.ButtonA) then
print("ButtonA is down")
end
IsMotorSupported
Gamepad:
IsMotorSupported
(
motor:
Enum.VibrationMotor
) →
boolean
Returns true
if the given motor is supported.
-- Pulse the trigger (e.g. shooting a weapon), but fall back to
-- the large motor if not supported:
local motor = Enum.VibrationMotor.Large
if gamepad:IsMotorSupported(Enum.VibrationMotor.RightTrigger) then
motor = Enum.VibrationMotor.RightTrigger
end
gamepad:PulseMotor(motor, 1, 0.1)
SetMotor
Gamepad:
SetMotor
(
motor:
Enum.VibrationMotor
,
intensity:
number
) →
number
Sets the gamepad's haptic motor to a certain intensity. The intensity value is a number in the range of [0, 1].
gamepad:SetMotor(Enum.VibrationMotor.Large, 0.5)
PulseMotor
Gamepad:
PulseMotor
(
motor:
Enum.VibrationMotor
,
intensity:
number
,
duration:
number
) →
(
)
Sets the gamepad's haptic motor to a certain intensity for a given
period of time. The motor will stop vibrating after the given
duration
has elapsed.
Calling any motor setter methods (e.g. SetMotor
, PulseMotor
,
StopMotor
) after calling this method will override the pulse.
For instance, if PulseMotor
is called, and then SetMotor
is
called right afterwards, SetMotor
will take precedent.
-- Pulse the large motor for 0.2 seconds with an intensity of 90%:
gamepad:PulseMotor(Enum.VibrationMotor.Large, 0.9, 0.2)
-- Example of PulseMotor being overridden:
gamepad:PulseMotor(Enum.VibrationMotor.Large, 1, 3)
task.wait(0.1)
gamepad:SetMotor(Enum.VibrationMotor.Large, 0.5)
-- Now the pulse won't shut off the motor after 3 seconds,
-- because SetMotor was called, which cancels the pulse.
StopMotor
Gamepad:
StopMotor
(
motor:
Enum.VibrationMotor
) →
(
)
Stops the given motor. This is equivalent to calling
gamepad:SetMotor(motor, 0)
.
gamepad:SetMotor(Enum.VibrationMotor.Large, 1)
task.wait(0.1)
gamepad:StopMotor(Enum.VibrationMotor.Large)
StopMotors
Gamepad:
StopMotors
(
) →
(
)
Stops all motors on the gamepad.
gamepad:SetMotor(Enum.VibrationMotor.Large, 1)
gamepad:SetMotor(Enum.VibrationMotor.Small, 1)
task.wait(0.1)
gamepad:StopMotors()
IsConnected
Gamepad:
IsConnected
(
) →
boolean
Returns true
if the gamepad is currently connected.
GetUserInputType
Gamepad:
GetUserInputType
(
) →
Enum.UserInputType?
Gets the current gamepad UserInputType that the gamepad object
is using. This will be nil
if there is no connected gamepad.
SetAutoSelectGui
Gamepad:
SetAutoSelectGui
(
enabled:
boolean
) →
(
)
Sets the GuiService.AutoSelectGuiEnabled
property.
This sets whether or not the Select button on a gamepad will try to auto-select a GUI object on screen. This does not turn on/off GUI gamepad navigation, but just the initial selection using the Select button.
For UX purposes, it usually is preferred to set this to false
and then
manually set the GuiService.SelectedObject
property within code to set the selected object for gamepads.
gamepad:SetAutoSelectGui(false)
game:GetService("GuiService").SelectedObject = someGuiObject
IsAutoSelectGuiEnabled
Gamepad:
IsAutoSelectGuiEnabled
(
) →
boolean
Returns the GuiService.AutoSelectGuiEnabled
property.
Destroy
Gamepad:
Destroy
(
) →
(
)
Destroys the gamepad object.