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

ContextActionService

Deprecated

ContextActionService

Deprecated

The ContextActionService is a game service that allows a game 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 string is provided to BindAction and UnbindAction, among other member functions. If two actions are bound to the same input, the most recent takes priority. When the most recent action is unbound, the one bound before that takes control again.

You can inspect the currently bound actions in the developer console under the “Action Bindings” tab. You’ll also see bindings from the Roblox engine too. This is useful in checking if your actions are binding/unbinding at the correct times, or if some other action is stealing input from your actions. For exmaple, if you are attempting to bind WASD, it may be the case that character movement scripts is binding over those same keys.

ContextActionService is especially useful for supporting keyboard-less players, in which on-screen touch buttons can be used in place of key presses. The buttons will display only when the action is bound, and the position, text and/or images of these buttons can be configured through this service.

It’s better to use ContextActionService’s BindAction than UserInputService’s InputBegan for most cases. For example, if you want to use the R key to reload a weapon while it is equipped, the player might type “roblox is fun” in chat or otherwise use the R key for something else. The weapon could reload when the player didn’t mean to! If you instead use BindAction and UnbindAction when the weapon is equipped/unequipped, ContextActionService will make sure that R key presses trigger the reload action only when it is the most recently bound action.

Properties

Inherited from Instance: Show Hide

int

DataCost

[ReadOnly] [NotReplicated]
The cost of saving the instance using data persistence.
Instance

Parent

Determines the hierarchical parent of the `Instance`.
bool

RobloxLocked

If true, the `Instance` and its descendants cannot be indexed or edited by a `Script` or `LocalScript` and will throw an error if it is attempted.
string

ClassName

[ReadOnly] [NotReplicated]
A read-only string representing the class this `Instance` belongs to.
string

Name

A non-unique identifier of the `Instance`.
bool

Archivable

Determines if an `Instance` can be cloned using `/Instance/Clone` or saved to file.

Functions

void

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

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

void

BindActionAtPriority ( string actionName , Function functionToBind , bool createTouchButton , int priorityLevel , Tuple inputTypes )

Binds function to fire when specified inputTypes occur. Allows the priority of the bound action to be specified.

void

BindActivate ( UserInputType userInputTypeForActivation , KeyCode keyCodeForActivation )

Specifies the Enum/KeyCode that can be used with a Enum/UserInputType to activate a Tool, or a HopperBin.

Dictionary

GetAllBoundActionInfo ( )

Returns a table with all bound action info.

Dictionary

GetBoundActionInfo ( string actionName )

Returns a table with info regarding the function bound with actionName.

Instance

GetButton ( string actionName )

[Yields]

If actionName key contains a bound action, then this will return the touch button (if was created). Returns nil if a touch button was not created.

string

GetCurrentLocalToolIcon ( )

Returns the BackpackItem/TextureId of a tool currently equipped by the Player, if one is equipped.

void

SetDescription ( string actionName , string description )

If actionName key contains a bound action, then description is set as the description of the bound action.

void

SetImage ( string actionName , string image )

If actionName key contains a bound action, then image is set as the image of the touch button.

void

SetPosition ( string actionName , UDim2 position )

If actionName key contains a bound action, then position is set as the position of the touch button.

void

SetTitle ( string actionName , string title )

If actionName key contains a bound action, then title is set as the title of the touch button.

void

UnbindAction ( string actionName )

Unbind an action from input given its name.

void

UnbindActivate ( UserInputType userInputTypeForActivation , KeyCode keyCodeForActivation )

Undos the specification of a Enum/KeyCode that can be used with a Enum/UserInputType to activate a Tool, or a HopperBin, if it was set earlier using ContextActionService/BindActivate.

void

UnbindAllActions ( )

Removes all functions bound. No actionNames will remain. All touch buttons will be removed.

Inherited from Instance: Show Hide

Array

GetDescendants ( )

[CustomLuaState]
Returns an array containing all of the `Instance`'s descendants.
bool

IsAncestorOf ( Instance descendant )

Returns true if an `Instance` is an ancestor of the given descendant.
bool

IsDescendantOf ( Instance ancestor )

Returns true if an `Instance` is a descendant of the given ancestor.
Instance

FindFirstChildWhichIsA ( string className , bool recursive )

Returns the first child of the `Instance` for whom `Instance/IsA` returns true for the given className.
Instance

FindFirstChildOfClass ( string className )

Returns the first child of the `Instance` whose `Instance/ClassName|ClassName` is equal to the given className.
Instance

FindFirstChild ( string name , bool recursive )

Returns the first child of the `Instance` found with the given name.
Instance

FindFirstAncestorWhichIsA ( string className )

Returns the first ancestor of the `Instance` for whom `Instance/IsA` returns true for the given className.
Instance

FindFirstAncestorOfClass ( string className )

Returns the first ancestor of the `Instance` whose `Instance/ClassName` is equal to the given className.
Instance

FindFirstAncestor ( string name )

Returns the first ancestor of the `Instance` whose `Instance/Name` is equal to the given name.
bool

IsA ( string className )

Returns true if an `Instance`'s class matches or inherits from a given class
Instance

WaitForChild ( string childName , double timeOut )

[CustomLuaState] [CanYield]
Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.
RBXScriptSignal

GetPropertyChangedSignal ( string property )

Get an event that fires when a given property of an object changes.
string

GetFullName ( )

Returns a string showing the `Instance`'s ancestry.
string

GetDebugId ( int scopeLength )

[NotBrowsable]
Returns a coded string of the `Instance`s DebugId used internally by Roblox.
Objects

GetChildren ( )

Returns an array containing all of the `Instance`'s children.
void

Destroy ( )

Sets the `Instance/Parent` property to nil, locks the `Instance/Parent` property, disconnects all connections and calls Destroy on all children.
Instance

Clone ( )

Create a deep copy of a Roblox instance and descendants where `Archivable = true`.
void

ClearAllChildren ( )

This function destroys all of an `Instance`'s children.

Events

RBXScriptSignal

LocalToolEquipped ( Instance toolEquipped )

Fires when the current player equips a Tool.

RBXScriptSignal

LocalToolUnequipped ( Instance toolUnequipped )

Fires when the current player unequips a Tool.

Inherited from Instance: Show Hide

RBXScriptSignal

AncestryChanged ( Instance child , Instance parent )

Fires when the `Instance/Parent` property of the object or one of its ancestors is changed.
RBXScriptSignal

ChildAdded ( Instance child )

Fires when an object is parented to this `Instance`.
RBXScriptSignal

ChildRemoved ( Instance child )

Fires when a child is removed from this `Instance`.
RBXScriptSignal

DescendantAdded ( Instance descendant )

Fires when a descendant is added to the `Instance`.
RBXScriptSignal

DescendantRemoving ( Instance descendant )

Fires immediately before a descendant of the `Instance` is removed.
RBXScriptSignal

Changed ( string property )

Fired immediately after a property of an object changes.