ContextActionService

Methods

BindAction(actionName : string,functionToBind : function,createTouchButton : bool,inputTypes : Tuple):void
Bind user input to an action given an action handling function.
BindActionAtPriority(actionName : string,functionToBind : function,createTouchButton : bool,priorityLevel : number,inputTypes : Tuple):void
Behaves like BindAction but also allows a priority to be assigned to the bound action for overlapping input types (higher before lower).
BindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodesForActivation : Tuple):void
Bind a Enum.KeyCode with a specific Enum.UserInputType to trigger Tool.Activation and ClickDetector events.
GetAllBoundActionInfo():Dictionary
Get a table of information about all bound actions (key is the name passed to BindAction, value is a table from GetBoundActionInfo when called with the key).
GetBoundActionInfo(actionName : string):Dictionary
Get a table of information about a bound action given its name originally passed to BindAction.
GetCurrentLocalToolIcon():string
Return the BackpackItem.TextureId of a Tool currently equipped by the Player.
SetDescription(actionName : string,description : string):void
Given the name of a bound action with a touch button, sets the description of the action.
SetImage(actionName : string,image : string):void
If actionName key contains a bound action, then image is set as the image of the touch button.
SetPosition(actionName : string,position : UDim2):void
Given the name of a bound action with a touch button, sets the position of the button within the ContextButtonFrame.
SetTitle(actionName : string,title : string):void
Given the name of a bound action with a touch button, sets the text shown on the button.
UnbindAction(actionName : string):void
Unbind an action from input given its name.
UnbindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodeForActivation : Enum.KeyCode):void
Unbind a Enum.KeyCode with a specific Enum.UserInputType from triggering Tool.Activation when bound with ContextActionService:BindActivate().
UnbindAllActions():void
Removes all functions bound. No actionNames will remain. All touch buttons will be removed.
GetButton(actionName : string):Instance
Yields
Retrieves a ImageButton of a bound action that had a touch input button created.

Events

LocalToolEquipped(toolEquipped : Instance):RBXScriptSignal
Fires when the current player equips a Tool.
LocalToolUnequipped(toolUnequipped : Instance):RBXScriptSignal
Fires when the current player unequips a Tool.

Properties

Methods

BindAction

void

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.KeyCode, Enum.UserInputType or Enum.PlayerActions . Call this function when a player enters the context in which an action can be performed. When the player leaves the context, call UnbindAction with the same actionName. You can manually call the action handling function of an action by using CallFunction.

The code sample below shows how a Sound can be 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://9120386436"

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:

#	Type	Description
1	string	The same string that was originally passed to BindAction†
2	Enum.UserInputState	The state of the input (Begin, Change, End or Cancel)*
3	InputObject	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 unbound.

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 nil or Enum.ContextActionResult.Sink). When UnbindAction is called, the action handler is removed from the stack. This stack behavior can be overridden using BindActionAtPriority, where an additional priority parameter after createTouchButton may override the order in which actions are bound (higher before lower).

Touch Buttons

In addition to input types, this function's third parameter controls whether a button is created for 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 ImageButtons for bound actions are parented; you can use GetButton to retrieve such buttons for customization.

Parameters

actionName: string

A string representing the action being performed (e.g. "HonkHorn" or "OpenDoor").

functionToBind: function

The action-handling function, called with the following parameters when the bound inputs are triggered: string (actionName), Enum.UserInputState and an InputObject.

createTouchButton: bool

Whether a GUI button should be created for the action on touch input devices.

inputTypes: Tuple

Any number of Enum.KeyCode or Enum.UserInputType representing the inputs to bind to the action.

Returns

void

Code Samples

ContextActionService Tool Reload

local ContextActionService = game:GetService("ContextActionService")

local ACTION_RELOAD = "Reload"

local tool = script.Parent

local function handleAction(actionName, inputState, _inputObject)
	if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
		print("Reloading!")
	end
end

tool.Equipped:Connect(function()
	ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)

tool.Unequipped:Connect(function()
	ContextActionService:UnbindAction(ACTION_RELOAD)
end)

General Action Handler

local ContextActionService = game:GetService("ContextActionService")

local function handleAction(actionName, inputState, inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Handling action: " .. actionName)
		print(inputObj.UserInputType)
	end

	-- Since this function does not return anything, this handler will
	-- "sink" the input and no other action handlers will be called after
	-- this one.
end

ContextActionService:BindAction("BoundAction", handleAction, false, Enum.KeyCode.F)

Stacked Action Handlers

local ContextActionService = game:GetService("ContextActionService")

-- Define an action handler for FirstAction
local function actionHandlerOne(actionName, inputState, _inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Action Handler One: " .. actionName)
	end
	-- This action handler returns nil, so it is assumed that
	-- it properly handles the action.
end

-- Binding the action FirstAction (it's on the bottom of the stack)
ContextActionService:BindAction("FirstAction", actionHandlerOne, false, Enum.KeyCode.Z, Enum.KeyCode.X, Enum.KeyCode.C)

-- Define an action handler for SecondAction
local function actionHandlerTwo(actionName, inputState, inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Action Handler Two: " .. actionName)
	end

	if inputObj.KeyCode == Enum.KeyCode.X then
		return Enum.ContextActionResult.Pass
	else
		-- Returning nil implicitly Sinks inputs
		return Enum.ContextActionResult.Sink
	end
end

-- Binding SecondAction over the first action (since it bound more recently, it is on the top of the stack)
-- Note that SecondAction uses the same keys as
ContextActionService:BindAction("SecondAction", actionHandlerTwo, false, Enum.KeyCode.Z, Enum.KeyCode.X)

BindActionAtPriority

void

BindActionAtPriority behaves like BindAction but also allows a priority to be assigned to the bound action. If multiple actions are bound to the same input, the higher priority function is called regardless of the order in which the actions were bound. In other words, this function overrides the normal "stack" behavior of BindAction.

Parameters

actionName: string

A string representing the action being performed (e.g. "HonkHorn" or "OpenDoor").

functionToBind: function

The action-handling function, called with the following parameters when the bound inputs are triggered: string (actionName), Enum.UserInputState and an InputObject.

createTouchButton: bool

Whether a GUI button should be created for the action on touch input devices.

priorityLevel: number

The priority level at which the action should be bound (higher considered before lower).

inputTypes: Tuple

Any number of Enum.KeyCode or Enum.UserInputType representing the inputs to bind to the action.

Returns

void

Code Samples

ContextActionService BindAction Priorities

local ContextActionService = game:GetService("ContextActionService")

local INPUT_KEY1 = Enum.KeyCode.Q
local INPUT_KEY2 = Enum.KeyCode.E

local function handleThrow(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
	if inputState ~= Enum.UserInputState.Begin then
		return Enum.ContextActionResult.Pass
	end
	print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)

	return Enum.ContextActionResult.Sink
end

local function handlePunch(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
	if inputState ~= Enum.UserInputState.Begin then
		return Enum.ContextActionResult.Pass
	end
	print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)

	return Enum.ContextActionResult.Sink
end

-- Without specifying priority, the most recently bound action is called first,
-- so pressing INPUT_KEY1 prints "Punch" and then sinks the input.
ContextActionService:BindAction("DefaultThrow", handleThrow, false, INPUT_KEY1)
ContextActionService:BindAction("DefaultPunch", handlePunch, false, INPUT_KEY1)

-- Here we bind both functions in the same order as above, but with explicitly swapped priorities.
-- That is, we give "Throw" a higher priority of 2 so it will be called first,
-- despite "Punch" still being bound more recently.
-- Pressing INPUT_KEY2 prints "Throw" and then sinks the input.
ContextActionService:BindActionAtPriority("PriorityThrow", handleThrow, false, 2, INPUT_KEY2)
ContextActionService:BindActionAtPriority("PriorityPunch", handlePunch, false, 1, INPUT_KEY2)

BindActivate

void

Bind a Enum.KeyCode that can be used with a Enum.UserInputType to activate ClickDetector events, Tools, and GuiButtons. When the given key/button is pressed, it fires the Mouse.Button1Down event on the mouse sent to Tool.Equipped. This in turn fires the Tool.Activated event if Tool.ManualActivationOnly is not set to true. For gamepad input, this function is called by the default control scripts in order to bind the ButtonR2 Enum.KeyCode.

Note that the Enum.UserInputType specified must be Keyboard or Gamepad1 through Gamepad8 in order to be valid.

Parameters

userInputTypeForActivation: Enum.UserInputType

Must be Keyboard or Gamepad1 through Gamepad8.

keyCodesForActivation: Tuple

Returns

void

GetAllBoundActionInfo

GetAllBoundActioninfo returns a table which maps all actions' names (those originally passed to BindAction) to a table returned by GetBoundActionInfo when called with the action name itself. Using this function, you can inspect all presently bound actions. This is useful when debugging their priority levels or stack orders.

Returns

GetBoundActionInfo

GetBoundActionInfo returns a table with the following keys describing a bound action given its name. To get the same information for all actions at once, use GetAllBoundActionInfo.

Name	Type	Description
stackOrder	number	Describes the index of the action on the stack (increasing)
priorityLevel*	number	Describes the priority level of the action
createTouchButton	bool	Describes whether a touch button should be created on TouchEnabled devices
inputTypes	table	The input types passed to BindAction for which this action will trigger
description†	string	The description of action set by SetDescription
title†	string	The title of the action set by SetTitle
image†	string	The image of the action's touch button set by SetImage

* Priority level will still be included even if BindActionAtPriority wasn't used - by default it will be 2000.

† Indicates that this field will be nil if the associated method was not called for the given action.

Parameters

actionName: string

Returns