ContextActionService

ContextActionService : Instance

Overview

The ContextActionService class is a service that allows developers to bind user inputs to specific actions under certain conditions or contexts. It provides a way to map various input types to in-game actions, making it easier to create responsive and intuitive controls for players across multiple devices. This service is particularly useful for managing contextual input, such as enabling specific actions only when a tool is equipped or a player is near an object

Description

The ContextActionService simplifies input handling by allowing developers to define actions and associate them with user inputs. These actions can be dynamically enabled or disabled based on the player's current context, such as proximity to an object or interaction with a specific tool.

Properties

Methods

BindAction

Defines an action and binds the function to handle the action.

Parameters

string ActionName
Value FunctionToBind
bool bCreateTouchButton
Tuple InputType

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

Remove and unbind action.

Parameters

string ActionName

Return

void

Code Samples

local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

ContextActionService:UnbindAction(ActionName)

GetAllBoundActionInfo

Gets all action information bound to the ContextActionService.

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

The GetBoundActionInfo method retrieves action information based on the provided action name and returns it.

Parameters

string ActionName

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

Given the name of a bound action with a touch button, sets the description of the action.

Parameters

string ActionName
string InDescription

Return

void

Code Samples

SetImage

If actionName key contains a bound action, then image is set as the image of the touch button.

Parameters

string ActionName
string ImageId

Return

void

Code Samples

ContextActionService:SetImage(ActionName, "ovdrassetid://1234")

SetPosition

Given the name of a bound action with a touch button, sets the position of the button within the ContextButtonFrame.

Parameters

string ActionName
UDim2 InPosition

Return

void

Code Samples

local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

ContextActionService:SetPosition(ActionName, UDim2.new(0.5, 0, 0.8, 0))

SetTitle

Given the name of a bound action with a touch button, sets the text shown on the button.

Parameters

string ActionName
string InTitle

Return

void

Code Samples

local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

ContextActionService:SetTitle(ActionName, "Action")

GetButton

Retrieves a ImageButton of a bound action that had a touch input button created.

Parameters

string ActionName

Return

Value

Code Samples

local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

local ActionButton = ContextActionService:GetButton(ActionName)
print(ActionButton)

Events

LocalToolEquipped

This event fires when a tool is equipped locally. Typically used to handle or initialize any functionality or UI specific to the equipped tool. Can be leveraged to manage tool-specific actions or properties.

Parameters

Code Samples

LocalToolUnequipped

This event fires when a tool is unequipped locally. It is typically used to clean up or reset functionality or UI that was specific to the equipped tool. Useful for managing resources or reverting actions tied to the tool.

Parameters

Code Samples