BindAction

Function of:

Description:

BindAction will bind an action to user input given an action handling function. The action handler function will be called when some input matches the provided user input enums. Call this function when a player enters the context in which an action can be performed, then call ContextActionService/UnbindAction|UnbindAction with the same actionName when that context is left. You can call the action handling function of an action by using ContextActionService/CallFunction|CallFunction.

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 ContextActionService/UnbindAction|UnbindAction is called, the action handler is removed from the stack. This stack behavior can be overridden using ContextActionService/BindActionAtPriority|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 UserInputService/TouchEnabled|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 ImageButton|ImageButtons for bound actions are parented; you can use ContextActionService/GetButton|GetButton to retrieve such buttons for customization.

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 ContextActionService/UnbindAction|unbound.

Parameters

Name	Type	Default	Description
Name actionName	Type string	Default	Summary A string representing the action being performed (e.g. “HonkHorn” or “OpenDoor”)
Name functionToBind	Type Function	Default	Summary The action-handling function, called with the following parameters when the bound inputs are triggered: string (actionName), Enum.UserInputState and an InputObject
Name createTouchButton	Type bool	Default	Summary Whether a GUI button should be created for the action on touch input devices
Name inputTypes	Type Tuple	Default	Summary Any number of Enum.KeyCode or Enum.UserInputType representing the inputs to bind to the action

Returns

Return Type	Summary
Return Type void	Summary

Code Samples

General Action Handler

This code sample uses ContextActionService to bind an action named “BoundAction” to a general action handler function on the F key. Place this in a LocalScript inside StarterPlayerScripts and press F to see the message “Handling action: BoundAction”.

				
					General Action Handler
				
					Expected Output
				
					Expand
					
			local ContextActionService = game:GetService("ContextActionService")

-- Setting up the action handling function
local function handleAction(actionName, inputState, inputObj)
    if inputState == Enum.UserInputState.Begin then
        print("Handling action: " .. actionName)
    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

-- Bind the action to the handler
ContextActionService:BindAction("BoundAction", handleAction, false, Enum.KeyCode.F)
		
				Copy Code
			
				Light Theme

Stacked Action Handlers

This code sample demonstrates how BindAction acts like a stack. It binds two actions, FirstAction (Z, X, and C keys) and SecondAction (Z and X keys) to two action handling functions. The second one will pass on a certain input (the X key).

Both actions use the Z and X keys, however the second handler will pass input only if X is pressed. So, when X is pressed, the second handler is called and then the first. The first action is also bound to the C key, and can be triggered even though the other two inputs are “covered” by the second action.

Test this code out by pasting it into a LocalScript within StarterPlayerScripts, then pressing Z, X and C. Observe which action handlers are called with what actions.

				
					Stacked Action Handlers
				
					Expected Output
				
					Expand
					
			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)
		
				Copy Code
			
				Light Theme

ContextActionService Tool Reload

This example properly shows how to use ContextActionService in binding user input to a contextual action. The context is the tool being equipped; the action is reloading some weapon. Test this code sample by placing it in a LocalScript parented to a Tool. When the Tool is equipped, a “Reload” action is bound, and when the Tool is unequipped the “Reload” action is unbound. When the player presses R with the Tool equipped, the message “Reloading!” will appear.

				
					ContextActionService Tool Reload
				
					Expected Output
				
					Expand
					
			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)
		
				Copy Code
			
				Light Theme

BindAction

Action Bindings Stack

Touch Buttons

Action Handler Parameters

Parameters

actionName

functionToBind

createTouchButton

inputTypes

Returns

void

Code Samples

General Action Handler

Stacked Action Handlers

ContextActionService Tool Reload