ContextActionService
ContextActionService : Instance
Overview
This is a system that links actions to user inputs under specific conditions, such as enabling button inputs only when a player equips a certain tool or is in a particular location.
Each input action is defined as a string, allowing identification of the specific input function. When multiple actions are linked to the same name, the most recently bound action takes precedence, with previously linked actions reactivated upon unbinding.
This system operates exclusively in the client environment and manages inputs based on context, enabling appropriate actions to be applied without complex state checks.
It also allows keyboard and touch inputs, providing a consistent user experience across platforms.
Properties
Methods
BindAction
Input actions can be defined for specific strings, calling associated functions when the input occurs.
When a designated keyboard key or touch button is pressed, input details and state are passed as arguments to the linked function.
Parameters
string
ActionName
This name is used to identify the action.
Value
FunctionToBind
The function is executed upon input detection, and the following arguments are passed to the linked functions:
string
ActionName: The name of the action defined by BindAction()Enum.UserInputState
: The input stateInputObject
InputObject: An object containing detailed input information.
bool
bCreateTouchButton
Specifies whether to display the button to trigger the action on the screen.
Tuple
InputType
You can specify the key(s) to trigger the action using Enum.KeyCode, and it's also possible to assign multiple keys
Return
void
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
local IsCreateTouchButton = true
local KeyCode = Enum.KeyCode.F
local function OnAction(actionName, inputState, inputObject)
if inputState == Enum.UserInputState.Begin then
print(actionName .. " triggered!")
end
end
ContextActionService:BindAction(ActionName, OnAction, IsCreateTouchButton, KeyCode)
UnbindAction
Unbinds an input action defined for a specific string.
Parameters
string
ActionName
The name of the action defined by BindAction()
Return
void
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
ContextActionService:UnbindAction(ActionName)
GetAllBoundActionInfo
Returns all bound action information in a table format.
The returned table uses the name of each action as a key, with values containing detailed information that can be retrieved when the names are passed to GetBoundActionInfo().
This is useful for verifying correct priority application or identifying overridden actions when multiple actions are bound simultaneously.
Parameters
Return
Dictionary
A dictionary containing all bound action information.
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local AllActions = ContextActionService:GetAllBoundActionInfo()
for actionName, actionInfo in pairs(AllActions) do
print("Action Name : ", actionName)
print("Input Types : ", actionInfo.InputTypes)
end
GetBoundActionInfo
Returns input information and properties bound to a specific action name.
Parameters
string
ActionName
The name of the action defined by BindAction()
Return
Dictionary
A dictionary containing action information.
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
local ActionInfo = ContextActionService:GetBoundActionInfo(ActionName)
if ActionInfo then
print("Action Name : ", ActionName)
print("Input Types : ", ActionInfo.InputTypes)
else
print("Action not found.")
end
SetDescription
Sets descriptive text for an action defined via BindAction().
The set text is not displayed directly in the UI and is used solely for describing or distinguishing the action.
Parameters
string
ActionName
The name of the action defined by BindAction()
string
InDescription
The description to be set.
Return
void
Code Samples
local ContextActionService = game:GetService("ContextActionService")
ContextActionService:SetDescription(ActionName, "Press the button to jump.")
for actionName, actionInfo in pairs(AllActions) do
print("Action Name : ", actionName)
print("Description : ", actionInfo.Description)
end
SetImage
Sets an image for a touch button created via BindAction().
Parameters
string
ActionName
The name of the action defined by BindAction()
string
ImageId
The AssetId of the image to display on the touch button.
Return
void
Code Samples
ContextActionService:SetImage(ActionName, "ovdrassetid://1234")
SetPosition
Sets the on-screen position of a touch button created via BindAction().
Parameters
string
ActionName
The name of the action defined by BindAction()
UDim2
InPosition
The position to be set.
Return
void
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
ContextActionService:SetPosition(ActionName, UDim2.new(0.5, 0, 0.8, 0))
SetTitle
Sets the text displayed on a touch button created via BindAction().
Parameters
string
ActionName
The name of the action defined by BindAction()
string
InTitle
The content to be set.
Return
void
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
ContextActionService:SetTitle(ActionName, "Action")
GetButton
Returns the touch button created via BindAction() as an ImageButton object. Returns nil for actions not using a touch button.
Parameters
string
ActionName
The name of the action defined by BindAction()
Return
Instance
The created touch button.
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
local ActionButton = ContextActionService:GetButton(ActionName)
print(ActionButton)
Events
LocalToolEquipped
This event triggers when a player equips a tool.
Parameters
Instance
Tool
The equipped tool.
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local function OnToolEquipped(tool)
print("OnToolEquipped")
end
ContextActionService.LocalToolEquipped:Connect(OnToolEquipped)
LocalToolUnequipped
This event triggers when a player unequips a tool.
Parameters
Instance
Tool
The unequipped tool.
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local function OnToolUnequipped(tool)
print("OnToolUnequipped")
end
ContextActionService.LocalToolUnequipped:Connect(OnToolUnequipped)
See also
Mobile Input HandlingLast updated