ContextActionService

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: KeyCode, UserInputType or 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.

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:

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 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 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. A maximum of 7 touch buttons can be created through BindAction().

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.

This function binds functionToBind to input events such as key presses, mouse movement, or controller input. The specific input types the engine listens for are listed as parameters of BindAction. Whenever a player uses any of these input types, the Roblox Engine calls "functionToBind". BindAction sets the priorityLevel via ContextActionPriority to Default.Value, which is 2000. Use ContextActionService:GetButton() to control the priority of bound events.

In addition to input types, BindAction has a createTouchButton parameter. When this is set to true it creates an ImageButton on any device with a touchscreen. A ScreenGui is also created to put the context buttons into named ContextActionGui and is parented to PlayerGui. The created ImageButton is parented to this ContextActionGui. GetButton can be used to retrieve the button that was created.

If an input has more than one function bound to it, each function will be placed on a stack. A stack obeys the principle of last in first out. So the first object placed on the stack will be on the top. The next object placed on the stack becomes the top and the previous object moves one position down (like a stack of books). When the input is triggered, the function at the top of the stack is called. If the function returns ContextActionResult.Pass this will continue down the stack. To remove a function from being called by all input that it was bound by use ContextActionService:UnbindAction().

BindAction allows control over whether or not a bound action should be processed by other actions on the stack using ContextActionResult. If ContextActionResult.Pass is returned in the callback function, every action below it in the stack (last function called gets executed first) will get a chance to process it. Anything other than Pass will be treated as ContextActionResult.Sink, including nil. It will also sink if the callback is yielded.

Bind a KeyCode that can be used with a 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 KeyCode.

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

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.

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.

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

GetButton returns the ImageButton created by BindAction if its third parameter was true and the device is TouchEnabled. The only parameter to this function must match exactly the name of the action originally sent to BindAction.

If no such action was bound or if a button was not created, this function returns nil.

GetCurrentLocalToolIcon will return the BackpackItem.TextureId of a Tool currently equipped by the Player, or nil if there is no such Tool or if the player lacks a Character.

SetDescription will set the description of an action bound by BindAction. In a list of available actions, this would be text that describes the given action.

Although the name may suggest that this method is related to the family of functions that customize a touch button for actions that create them (SetTitle, SetImage and SetPosition), this method does not affect such a button. This method merely sets a text description of an action, and nothing more.

This method sets the image shown on a touch button created by BindAction(). Specifically, it sets the ImageLabel.Image property of the ImageLabel within the ImageButton that would be returned by GetButton. If no such bound action exists (e.g. nothing is returned by GetButton), this function does nothing and throws no error.

This function is part of a family of methods that customize the touch button of an action. Others in this family include SetPosition and SetTitle.

This method sets the position of a touch button created by BindAction(). Specifically, it sets the GuiObject.Position property of the ImageButton that would be returned by GetButton. If no such bound action exists (e.g. nothing is returned by GetButton), this function does nothing and throws no error.

This function is part of a family of methods that customize the touch button of an action. Others in this family include SetImage and SetTitle.

SetTitle will set the text shown on a touch button created by BindAction. Specifically, this sets the TextLabel.Text property of a TextLabel within the ImageButton that would be returned by GetButton. If no such bound action exists (e.g. nothing is returned by GetButton), this function does nothing and throws no error.

This function is part of a family of methods that customize the touch button of an action. Others in this family include SetImage and SetPosition.

UnbindAction will unbind an action by name from user inputs so that the action handler function will no longer be called. Call this function when the context for some action is no longer applicable, such as closing a user interface, exiting a car or unequipping a Tool. See BindAction for more information on how bound actions operate.

This function will not throw an error if there is no such action bound with the given string. Using GetAllBoundActionInfo or the Developer Console's "Action Bindings" tab, you can find out what actions are presently bound.

UnbindActivate unbinds an KeyCode used with an UserInputType for activating a Tool (or a HopperBin) using BindActivate. This function essentially undoes the action performed by that function.

Removes all functions bound. No actionNames will remain. All touch buttons will be removed. If a button was manipulated manually there is no guarantee it will be cleaned up.

Fires when a Tool is added as a child of the local player's Character model, which occurs when the player equips the tool. The toolEquipped parameter is the Tool instance that was equipped.

This event fires only for Tool children added to the character, so it does not fire for non-Tool children. The connection is re-established each time the player's character respawns.

This event is useful for updating contextual action bindings when a tool is equipped. For example, you can call BindAction inside a handler connected to this event to set up tool-specific input, then call UnbindAction in the corresponding ContextActionService.LocalToolUnequipped handler.

Fires when a Tool is removed from the local player's Character model, which occurs when the player unequips the tool. The toolUnequipped parameter is the Tool instance that was unequipped.

This event fires only for Tool children removed from the character, so it does not fire for non-Tool children. The connection is re-established each time the player's character respawns.

This event is useful for tearing down contextual action bindings when a tool is unequipped. For example, you can call UnbindAction inside a handler connected to this event to remove tool-specific input that was bound in the corresponding ContextActionService.LocalToolEquipped handler.