# ContextActionService

ContextActionService : `Instance`

## Overview

This is a system that links actions to user inputs under specific conditions, such as enabling button inputs only when a player equips a certain tool or is in a particular location

Each input action is defined as a string, allowing identification of the specific input function. When multiple actions are linked to the same name, the most recently bound action takes precedence, with previously linked actions reactivated upon unbinding.

This system operates exclusively in the client environment and manages inputs based on context, enabling appropriate actions to be applied without complex state checks.

It also allows keyboard and touch inputs, providing a consistent user experience across platforms.

## Properties

## Methods

### BindAction

Input actions can be defined for specific strings, calling associated functions when the input occurs.

When a designated keyboard key or touch button is pressed, input details and state are passed as arguments to the linked function.

#### Parameters

| `string` ActionName         | This name is used to identify the action.                                                                                                                                                                                                                                                                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Value` FunctionToBind      | <p>The function is executed upon input detection, and the following arguments are passed to the linked functions:</p><ul><li><code>string</code> ActionName: The name of the action defined by BindAction()</li><li><code>Enum.UserInputState</code>: The input state</li><li><code>InputObject</code> InputObject: An object containing detailed input information.</li></ul> |
| `boolean` CreateTouchButton | Specifies whether to display an action button on the screen.                                                                                                                                                                                                                                                                                                                   |
| `Tuple` InputType           | The key for executing the action can be specified using Enum.KeyCode, and also multiple keys can be assigned if needed.                                                                                                                                                                                                                                                        |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
local IsCreateTouchButton = true
local KeyCode = Enum.KeyCode.F

local function OnAction(actionName, inputState, inputObject)
    if inputState == Enum.UserInputState.Begin then
        print(actionName .. " triggered!")
    end
end
ContextActionService:BindAction(ActionName, OnAction, IsCreateTouchButton, KeyCode)
```

### GetAllBoundActionInfo

Returns all bound action information in a table format.

The returned table uses the name of each action as a key, with values containing detailed information that can be retrieved when the names are passed to GetBoundActionInfo().

This is useful for verifying correct priority application or identifying overridden actions when multiple actions are bound simultaneously.

#### Parameters

#### Return

| `Value` | A table of all bound action information, keyed by action name. |
| ------- | -------------------------------------------------------------- |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
local AllActions = ContextActionService:GetAllBoundActionInfo()

for actionName, actionInfo in pairs(AllActions) do
    print("Action Name : ", actionName)
    print("Input Types : ", actionInfo.InputTypes)
end
```

### GetBoundActionInfo

Returns input information and properties bound to a specific action name.

#### Parameters

| `string` ActionName | The name of the action defined by BindAction() |
| ------------------- | ---------------------------------------------- |

#### Return

| `Value` | A table containing the input types and properties bound to the specified action. |
| ------- | -------------------------------------------------------------------------------- |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
local ActionInfo = ContextActionService:GetBoundActionInfo(ActionName)

if ActionInfo then
    print("Action Name : ", ActionName)
    print("Input Types : ", ActionInfo.InputTypes)
else
    print("Action not found.")
end
```

### GetButton

Returns the touch button created via BindAction() as an ImageButton object. Returns nil for actions not using a touch button.

#### Parameters

| `string` ActionName | The name of the action defined by BindAction() |
| ------------------- | ---------------------------------------------- |

#### Return

| `Value` | The ImageButton created for the action's touch button, or nil if none exists. |
| ------- | ----------------------------------------------------------------------------- |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

local ActionButton = ContextActionService:GetButton(ActionName)
print(ActionButton)
```

### SetDescription

Sets descriptive text for an action defined via BindAction().

The set text is not displayed directly in the UI and is used solely for describing or distinguishing the action.

#### Parameters

| `string` ActionName    | The name of the action defined by BindAction() |
| ---------------------- | ---------------------------------------------- |
| `string` InDescription | The description to be set.                     |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
​
ContextActionService:SetDescription(ActionName, "Press the button to jump.")
​
for actionName, actionInfo in pairs(AllActions) do
    print("Action Name : ", actionName)
    print("Description : ", actionInfo.Description)
end
```

### SetImage

Sets an image for a touch button created via BindAction().

#### Parameters

| `string` ActionName | The name of the action defined by BindAction()           |
| ------------------- | -------------------------------------------------------- |
| `string` ImageId    | The AssetId of the image to display on the touch button. |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
ContextActionService:SetImage(ActionName, "ovdrassetid://1234")
```

### SetPosition

Sets the on-screen position of a touch button created via BindAction().

#### Parameters

| `string` ActionName | The name of the action defined by BindAction() |
| ------------------- | ---------------------------------------------- |
| `UDim2` InPosition  | The position to be set.                        |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

ContextActionService:SetPosition(ActionName, UDim2.new(0.5, 0, 0.8, 0))
```

### SetTitle

Sets the text displayed on a touch button created via BindAction().

#### Parameters

| `string` ActionName | The name of the action defined by BindAction() |
| ------------------- | ---------------------------------------------- |
| `string` InTitle    | The content to be set.                         |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

ContextActionService:SetTitle(ActionName, "Action")
```

### UnbindAction

Unbinds an input action defined for a specific string.

#### Parameters

| `string` ActionName | The name of the action defined by BindAction() |
| ------------------- | ---------------------------------------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"

ContextActionService:UnbindAction(ActionName)
```

## Events

### LocalToolEquipped

This event triggers when a player equips a tool.

#### Parameters

| `Tool` Tool | The equipped tool. |
| ----------- | ------------------ |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")

local function OnToolEquipped(tool)
    print("OnToolEquipped")
end
ContextActionService.LocalToolEquipped:Connect(OnToolEquipped)
```

### LocalToolUnequipped

This event triggers when a player unequips a tool.

#### Parameters

| `Tool` Tool | The unequipped tool. |
| ----------- | -------------------- |

#### Code Samples

```lua
local ContextActionService = game:GetService("ContextActionService")

local function OnToolUnequipped(tool)
    print("OnToolUnequipped")
end
ContextActionService.LocalToolUnequipped:Connect(OnToolUnequipped)
```

## See also

{% content-ref url="/pages/MS4oQBHYxUxZLKzFIpSr" %}
[Mobile Input Handling](/manual/script-manual/input-and-controls/contextactionservice.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/development/api-reference/classes/contextactionservice.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.