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 state InputObject InputObject: An object containing detailed input information.
bool bCreateTouchButton	Specifies whether to display an action button on the screen.
Tuple InputType	The key for executing the action can be specified using Enum.KeyCode, and also multiple keys can be assigned if needed.

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

Value

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

Value

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

Value

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

Tool 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

Tool 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 Handling