PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience
Collapse Sidebar

BindAction

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.

The method behaves like a stack: if two actions are bound to the same user input, only the most recent action handler will be called. When UnbindAction is called, the action handler is removed from the stack. If an action handler returns Enum.ContextActionResult.Pass, an input will call to the next most recently bound action handler.

Parameters

Name Type Default Description

Returns

Return Type Summary

Code Samples


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.

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)

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”.

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)