A quick reference for implementing gamepad (controller) input on Roblox. This cheatsheet is written for intermediate scripters.
Used for binding to inputs gracefully. If an input is bound to one action and another action is to use the same
button, the BindAction
functions will handle the collision properly. Example: (A)
could make the player jump OR open a door but only when close enough.
Each input type bound to a function using BindAction works like a stack
: whichever function was the most recent
to be bound will be called when that input type is activated by the player.
:BindAction(name, func, touchButton, inputTypes...)
name, InputState, and InputObject when
inputTypes are used.
Unbinds a function from action
Input types for
As soon as a player can use an input (like A/B, triggers, or thumbstick), use
:BindAction(...). This will override the given input types current actions with the new one. When the player can no longer use the input for the action, use
When the given input type is activated/changed, the function passed to :BindAction(...) is called with the action name, the input state
) and the InputObject
. It's good practice to have just one action-handling function per script.
Gamepad KeyCodes and UserInputTypes
Buttons use the UserInputStates Began/End. Triggers and thumbsticks use Change.
Returns true if at least one gamepad is connected.
Fired when a gamepad is available.
Fired when a gamepad is no longer available.
UserInputService.InputBegan for actions involving button presses! Use
ContextActionService:BindAction(...) because this "overrides" existing actions using the given input types, and properly returns control to existing actions when yours are unbound.
Tips and Good Practices
A Button - Enum.KeyCode.ButtonA
Bound to jump by default. Should be used as accept button for prompts.
B Button - Enum.KeyCode.ButtonB
Should be used as back or cancel button for menus/prompts.
Right Trigger - Enum.KeyCode.ButtonR2
Use for primary character actions.
Left Trigger - Enum.KeyCode.ButtonL2
Use for secondary character actions.
Right Thumbstick - Enum.KeyCode.Thumbstick1
Use for camera movement.
Left Thumbstick - Enum.KeyCode.Thumbstick2
Use for character movement.
Right/Left Bumpers - Enum.KeyCode.ButtonR1/ButtonL1
Bound to switch tools by default.
A good way to know what kinds of control schemes work is by playing other gamepad/controller enabled games.