Reference API Roblox

Engine API

Website

Related

Reference API Roblox

ContextActionService

A service used to bind user input to contextual actions.

This class is not creatable. Instances of this class cannot be created with Instance.new.
This class is a service. It is a singleton that may be acquired with GetService.
Tags: [NotCreatable, Service]

Member index 30

HistoryMember
573BindAction(actionName: string, functionToBind: Function, createTouchButton: bool, inputTypes: Tuple): null
573BindActionAtPriority(actionName: string, functionToBind: Function, createTouchButton: bool, priorityLevel: int, inputTypes: Tuple): null
573BindActionToInputTypes(actionName: string, functionToBind: Function, createTouchButton: bool, inputTypes: Tuple): null
573BindActivate(userInputTypeForActivation: UserInputType, keyCodesForActivation: Tuple): null
573BindCoreAction(actionName: string, functionToBind: Function, createTouchButton: bool, inputTypes: Tuple): null
573BindCoreActionAtPriority(actionName: string, functionToBind: Function, createTouchButton: bool, priorityLevel: int, inputTypes: Tuple): null
573BindCoreActivate(userInputTypeForActivation: UserInputType, keyCodesForActivation: Tuple): null
462CallFunction(actionName: string, state: UserInputState, inputObject: Instance): Tuple
573FireActionButtonFoundSignal(actionName: string, actionButton: Instance): null
462GetAllBoundActionInfo(): Dictionary
462GetAllBoundCoreActionInfo(): Dictionary
462GetBoundActionInfo(actionName: string): Dictionary
462GetBoundCoreActionInfo(actionName: string): Dictionary
462GetButton(actionName: string): Instance
462GetCurrentLocalToolIcon(): string
573SetDescription(actionName: string, description: string): null
573SetImage(actionName: string, image: string): null
573SetPosition(actionName: string, position: UDim2): null
573SetTitle(actionName: string, title: string): null
573UnbindAction(actionName: string): null
573UnbindActivate(userInputTypeForActivation: UserInputType, keyCodeForActivation: KeyCode = Unknown): null
573UnbindAllActions(): null
573UnbindCoreAction(actionName: string): null
573UnbindCoreActivate(userInputTypeForActivation: UserInputType, keyCodeForActivation: KeyCode = Unknown): null
462BoundActionAdded(actionAdded: string, createTouchButton: bool, functionInfoTable: Dictionary, isCore: bool)
462BoundActionChanged(actionChanged: string, changeName: string, changeTable: Dictionary)
462BoundActionRemoved(actionRemoved: string, functionInfoTable: Dictionary, isCore: bool)
462GetActionButtonEvent(actionName: string)
462LocalToolEquipped(toolEquipped: Instance)
462LocalToolUnequipped(toolUnequipped: Instance)
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553ClassName: string
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
553className: string
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
486GetChildren(): Objects
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
462GetPropertyChangedSignal(property: string): RBXScriptSignal
641GetStyled(name: string): Variant
576GetTags(): Array
576HasTag(tag: string): bool
486IsA(className: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
580IsPropertyModified(name: string): bool
573Remove(): null
576RemoveTag(tag: string): null
580ResetPropertyToDefault(name: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
553children(): Objects
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
553getChildren(): Objects
462isA(className: string): bool
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462Changed(property: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
553childAdded(child: Instance)

Removed member index 3

HistoryMember
145ContextButtonEnabled: bool
145ActivateLocalTool(): void
145DeactivateLocalTool(): void

Description

Allows an experience to bind user input to contextual actions, or actions that are only enabled under some condition or period of time. For example, allowing a player to open a door only while close by. In code, an action is simply a string (the name of the action) used by the service to differentiate between unique actions. The action string is provided to BindAction and UnbindAction, among other member functions. If two actions are bound to the same input, the most recently bound will take priority. When the most recent action is unbound, the one bound before that takes control again. Since this service deals with user input, you can only use it in client-side LocalScripts.

Context and Action

A context is simply a condition during which a player may perform some action. Some examples include holding a Tool, being seated in a car or standing near a door. Whatever the case may be, it is up to your LocalScripts to call BindAction when the context is entered and UnbindAction when the context is left.

An action is simply some input that can be performed by the player while in that context. Such an action could open/close some menu, trigger a secondary tool action or send a request to the server using RemoteFunction:InvokeServer(). An action is identified by a unique string as the first parameter of both BindAction and UnbindAction. The string can be anything, but it should reflect the action being performed, not the input being used. For example, don't use "KeyH" as an action name - use "CarHorn" instead. It is best to define your actions as a constant at the top of your script since you will use it in at least three different places in your code.

Binding Actions Contextually

It's better to use ContextActionService's BindAction than UserInputService.InputBegan for most cases. For UserInputService.InputBegan, your connected function would have to check if the player is in the context of the action being performed. In most cases, this is harder than just calling a function when a context is entered/ left. For example, if you want to have the H key trigger a car horn sound while the player is sitting in it, the player might type "hello" in chat or otherwise use the H key for something else. It is harder to determine if something else is using the H key (like chat) - the car might honk when the player didn't mean to. If you instead use BindAction and UnbindAction when the player enters/leaves the car, ContextActionService will make sure that H key presses trigger the honk action only when it is the most recently bound action. If something else (like chat) takes control, you won't have to worry about checking that.

Inspecting Bound Actions

To see a list of actions and their bound inputs, you can inspect the "Action Bindings" tab in the Developer Console (F9 while in game). This shows all bindings, including those bound by Roblox core scripts and default camera/control scripts too. This is useful for debugging if your actions are being bound/unbound at the correct times, or if some other action is stealing input from your actions. For example, if you are attempting to bind WASD, it may be the case that default character movement scripts are binding over those same keys. Similarly, the camera control script can steal right-click input if the script runs after yours.

Keyboardless Input

This service is especially useful for supporting gamepad and touch input. For gamepad input, you might choose to bind the B button to an action that returns the user to the previous menu when they enter another menu. For touch, on-screen touch buttons can be used in place of key presses: these buttons display only while the action is bound, and the position, text and/or images of these buttons can be configured through this service. They're somewhat limited in the amount of customization provided by this service; it's usually a better idea to make your own on-screen buttons using ImageButton or TextButton.

History 92

Members 30

BindAction

Parameters (4)
actionNamestring
functionToBindFunction
createTouchButtonbool
inputTypesTuple
Returns (1)
null

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
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:

#TypeDescription
1stringThe same string that was originally passed to BindAction†
2UserInputStateThe state of the input (Begin, Change, End or Cancel)*
3InputObjectAn 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 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.

History 5

BindActionAtPriority

Parameters (5)
actionNamestring
functionToBindFunction
createTouchButtonbool
priorityLevelint
inputTypesTuple
Returns (1)
null

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.

History 3

BindActionToInputTypes

Parameters (4)
actionNamestring
functionToBindFunction
createTouchButtonbool
inputTypesTuple
Returns (1)
null

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.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work. BindAction should be used instead.

History 7

Tags: [Deprecated]

BindActivate

Parameters (2)
userInputTypeForActivationUserInputType
keyCodesForActivationTuple
Returns (1)
null

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.

History 4

BindCoreAction

Parameters (4)
actionNamestring
functionToBindFunction
createTouchButtonbool
inputTypesTuple
Returns (1)
null

History 3

BindCoreActionAtPriority

Parameters (5)
actionNamestring
functionToBindFunction
createTouchButtonbool
priorityLevelint
inputTypesTuple
Returns (1)
null

History 3

BindCoreActivate

Parameters (2)
userInputTypeForActivationUserInputType
keyCodesForActivationTuple
Returns (1)
null

History 2

BoundActionAdded

Parameters (4)
actionAddedstring
createTouchButtonbool
functionInfoTableDictionary
isCorebool

History 3

BoundActionChanged

Parameters (3)
actionChangedstring
changeNamestring
changeTableDictionary

History 2

BoundActionRemoved

Parameters (3)
actionRemovedstring
functionInfoTableDictionary
isCorebool

History 3

CallFunction

Parameters (3)
actionNamestring
stateUserInputState
inputObjectInstance
Returns (1)
Tuple

History 3

FireActionButtonFoundSignal

Parameters (2)
actionNamestring
actionButtonInstance
Returns (1)
null

History 3

GetActionButtonEvent

Parameters (1)
actionNamestring

History 2

GetAllBoundActionInfo

Parameters (0)
No parameters.
Returns (1)
Dictionary

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.

History 2

GetAllBoundCoreActionInfo

Parameters (0)
No parameters.
Returns (1)
Dictionary

History 2

GetBoundActionInfo

Parameters (1)
actionNamestring
Returns (1)
Dictionary

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.

NameTypeDescription
stackOrdernumber

Describes the index of the action on the stack (increasing)

priorityLevel*number

Describes the priority level of the action

createTouchButtonbool

Describes whether a touch button should be created on TouchEnabled devices

inputTypestable

The input types passed to BindAction for which this action will trigger

descriptionstring

The description of action set by SetDescription

titlestring

The title of the action set by SetTitle

imagestring

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.

History 2

GetBoundCoreActionInfo

Parameters (1)
actionNamestring
Returns (1)
Dictionary

History 2

GetButton

Parameters (1)
actionNamestring
Returns (1)
Instance

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.

This function yields. It will block the calling thread until completion.

History 2

Tags: [Yields]

GetCurrentLocalToolIcon

Parameters (0)
No parameters.
Returns (1)
string

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.

History 2

LocalToolEquipped

Parameters (1)
toolEquippedInstance

Fires when the current player equips a Tool.

History 2

LocalToolUnequipped

Parameters (1)
toolUnequippedInstance

Fires when the current player unequips a Tool.

History 2

SetDescription

Parameters (2)
actionNamestring
descriptionstring
Returns (1)
null

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.

History 3

SetImage

Parameters (2)
actionNamestring
imagestring
Returns (1)
null

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.

History 3

SetPosition

Parameters (2)
actionNamestring
positionUDim2
Returns (1)
null

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.

History 3

SetTitle

Parameters (2)
actionNamestring
titlestring
Returns (1)
null

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.

History 3

UnbindAction

Parameters (1)
actionNamestring
Returns (1)
null

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.

History 3

UnbindActivate

Parameters (2)Default
userInputTypeForActivationUserInputType
keyCodeForActivationKeyCodeUnknown
Returns (1)
null

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.

History 3

UnbindAllActions

Parameters (0)
No parameters.
Returns (1)
null

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.

History 3

UnbindCoreAction

Parameters (1)
actionNamestring
Returns (1)
null

History 3

UnbindCoreActivate

Parameters (2)Default
userInputTypeForActivationUserInputType
keyCodeForActivationKeyCodeUnknown
Returns (1)
null

History 2

Removed members 3

ActivateLocalTool

Parameters (0)
No parameters.
Returns (1)
void

History 2

ContextButtonEnabled

TypeDefault
bool

History 2

DeactivateLocalTool

Parameters (0)
No parameters.
Returns (1)
void

History 2

Settings