For thread safety, this property is not safe to read in an unsynchronized thread.
BindAction will bind an action to user input given an action handling function. Upon a matching input being performed, the action handler function will be called with the arguments listed below. Valid input enum items include those within the following:
enum/PlayerAction . Call this function when a player enters the context in which an action can be performed. When the player leaves the context, call
ContextActionService/UnbindAction|UnbindAction with the same
actionName. You can manually call the action handling function of an action by using
The code sample below shows how a
Sound can be
Sound/Play|played while a key (H), game pad button, or touch screen button is pressed.
local ContextActionService = game:GetService("ContextActionService") -- A car horn sound local honkSound = Instance.new("Sound", workspace) honkSound.Looped = true honkSound.SoundId = "rbxassetid://3017580236" local function handleAction(actionName, inputState, inputObject) if actionName == "HonkHorn" then if inputState == Enum.UserInputState.Begin then honkSound:Play() else honkSound:Pause() end end end -- When the player sits in the vehicle: ContextActionService:BindAction("HonkHorn", handleAction, true, Enum.KeyCode.H, Enum.KeyCode.ButtonY) -- When the player gets out: ContextActionService:UnbindAction("HonkHorn")
Action Handler Parameters
The action handler functions are called with the following parameters:
|1||The same string that was originally passed to BindAction†|
|2||The state of the input (Begin, Change, End or Cancel)*|
|3||An object that contains information about the input (varies based on UserInputType)|
†This allows one function to handle multiple actions at once, if necessary.
*Cancel is sent if some input was in-progress and another action bound over the in-progress input, or if the in-progress bound action was
Action Bindings Stack
Action bindings behave like a stack: if two actions are bound to the same user input, the most recently bound action handler will be used. If an action handler returns
Enum.ContextActionResult.Pass, the next most recently bound action handler will be called, and so on until a handler sinks the input (by returning
ContextActionService/UnbindAction|UnbindAction is called, the action handler is removed from the stack. This stack behavior can be overridden using
ContextActionService/BindActionAtPriority|BindActionAtPriority, where an additional priority parameter after
createTouchButton may override the order in which actions are bound (higher before lower).
In addition to input types, this function’s third parameter controls whether a button is created for
UserInputService/TouchEnabled|TouchEnabled devices. Upon the first touch button’s creation, a
ScreenGui named “ContextActionGui” is added to the
PlayerGui. Inside the ScreenGui is a
Frame called “ContextButtonFrame” is added. It is in this frame in which
ImageButton|ImageButtons for bound actions are parented; you can use
ContextActionService/GetButton|GetButton to retrieve such buttons for customization.
A string representing the action being performed (e.g. “HonkHorn” or “OpenDoor”)
The action-handling function, called with the following parameters when the bound inputs are triggered: string (actionName), Enum.UserInputState and an InputObject
Whether a GUI button should be created for the action on touch input devices
Any number of Enum.KeyCode or Enum.UserInputType representing the inputs to bind to the action
Stacked Action Handlers
This code sample demonstrates how BindAction acts like a stack. It binds two actions, FirstAction (
C keys) and SecondAction (
X keys) to two action handling functions. The second one will pass on a certain input (the
Both actions use the
X keys, however the second handler will pass input only if
X is pressed. So, when
X is pressed, the second handler is called and then the first. The first action is also bound to the
C key, and can be triggered even though the other two inputs are “covered” by the second action.
Test this code out by pasting it into a LocalScript within StarterPlayerScripts, then pressing
C. Observe which action handlers are called with what actions.
ContextActionService Tool Reload
This example properly shows how to use ContextActionService in binding user input to a contextual action. The context is the tool being equipped; the action is reloading some weapon. Test this code sample by placing it in a LocalScript parented to a Tool. When the Tool is equipped, a “Reload” action is bound, and when the Tool is unequipped the “Reload” action is unbound. When the player presses R with the Tool equipped, the message “Reloading!” will appear.
General Action Handler
This code sample uses ContextActionService to bind an action named “BoundAction” to a general action handler function on the
F key. Place this in a LocalScript inside StarterPlayerScripts and press
F to see the message “Handling action: BoundAction”.