ContextActionService¶

Supported Class Services NotCreatable Service

A service used to bind user input to contextual actions.

Note: Action binding and touch button creation are present.

24 Nova members · 9 modern Roblox members not implemented yet

Description¶

BindAction and the related binding methods of this service aren't recommended for new work and are planned for deprecation. Use the Input Action System instead, which is built for cross-platform input. You create InputContext, InputAction and InputBinding instances rather than binding actions from scripts. Each action holds bindings for keyboard, mouse, gamepad and touch, so the same action works on every platform and responds to whichever device the player is using, without separate code for each one.

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.

Inheritance¶

Object → Instance → ContextActionService

Nova inheritance: Instance → ContextActionService

Methods¶

BindAction Supported Function Bind user input to an action given an action handling function.

ContextActionService:BindAction(string actionName, Function functionToBind, bool createTouchButton, Tuple inputTypes)

Bind user input to an action given an action handling function.

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:

#	Type	Description
1	`string`	The same string that was originally passed to `Class.ContextActionService:BindAction()\|BindAction()`. This allows one function to handle multiple actions at once, if necessary.
2	`Enum.UserInputState`	The state of the input. `Enum.UserInputState\|Cancel` is sent if some input was in progress and another action bound over that in-progress input, or if the in-progress bound action was unbound through `Class.ContextActionService:UnbindAction()\|UnbindAction()`.
3	`InputObject`	An object that contains information about the input (varies based on `Enum.UserInputType`). The `Class.InputObject` sometimes won't match the inputs the action was bound to: when the `Enum.UserInputState\|Cancel` state is sent, this object will be `Enum.KeyCode.Unknown` and `Enum.UserInputType.None`.

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

Roblox reference signature

ContextActionService:BindAction(actionName: string, functionToBind: Function, createTouchButton: bool, inputTypes: Tuple): null

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

Member	Signature	Status	Notes	Flags
`BindActionAtPriority`	`ContextActionService:BindActionAtPriority(actionName: string, functionToBind: Function, createTouchButton: bool, priorityLevel: int, inputTypes: Tuple): null`	Not yet	Behaves like BindAction but also allows a priority to be assigned to the bound action for overlapping input types (higher before lo…	—
`BindCoreActionAtPriority`	`ContextActionService:BindCoreActionAtPriority(actionName: string, functionToBind: Function, createTouchButton: bool, priorityLevel: int, inputTypes: Tuple): null`	Not yet	—	RobloxScriptSecurity
`BindCoreActivate`	`ContextActionService:BindCoreActivate(userInputTypeForActivation: UserInputType, keyCodesForActivation: Tuple): null`	Not yet	—	RobloxScriptSecurity
`GetAllBoundCoreActionInfo`	`ContextActionService:GetAllBoundCoreActionInfo(): Dictionary`	Not yet	—	RobloxScriptSecurity
`GetBoundCoreActionInfo`	`ContextActionService:GetBoundCoreActionInfo(actionName: string): Dictionary`	Not yet	—	RobloxScriptSecurity
`GetInputContexts`	`ContextActionService:GetInputContexts(): Instances`	Not yet	—	RobloxScriptSecurity
`GetInputSchemaKeyCodeTree`	`ContextActionService:GetInputSchemaKeyCodeTree(): Dictionary`	Not yet	—	RobloxScriptSecurity
`UnbindCoreActivate`	`ContextActionService:UnbindCoreActivate(userInputTypeForActivation: UserInputType, keyCodeForActivation: KeyCode = None): null`	Not yet	—	RobloxScriptSecurity

ContextActionService¶

Description¶

Context and Action¶

Binding Actions Contextually¶

Inspecting Bound Actions¶

Keyboardless Input¶

Inheritance¶

Methods¶

Action Handler Parameters¶

Action Bindings Stack¶

Touch Buttons¶

Events¶

Inherited members¶

Methods¶

Events¶