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

Last updated