# ContextActionService

ContextActionService : `Instance`

## Overview

특정 조건에서만 활성화되는 동작을 사용자 입력과 연결해주는 시스템으로, 플레이어가 특정 도구를 장착했을 때나, 어떤 위치에 있을 때만 버튼 입력이 작동하도록 설정할 수 있습니다.

각 입력 동작은 문자열로 정의되며, 이를 통해 어떤 입력 기능인지 구분할 수 있습니다. 동일한 이름에 여러 동작이 연결된 경우, 가장 최근에 바인딩된 동작이 우선 적용되며, 해제되면 이전에 연결된 동작이 다시 활성화됩니다.

이 시스템은 클라이언트 환경에서만 사용되며, 컨텍스트 기반으로 입력을 관리할 수 있어, 복잡한 상태 확인 없이도 상황에 따라 적절한 동작을 적용할 수 있습니다.

또한, 키보드나 터치 입력이 함께 연동되어 다양한 플랫폼에서 일관된 사용자 경험을 제공할 수 있습니다.

## Properties

## Methods

### BindAction

특정 문자열에 입력 동작을 정의하고, 해당 입력이 발생했을 때 연결된 함수가 호출되도록 설정할 수 있습니다.

지정한 키보드 키나 터치 버튼이 눌릴 경우, 입력 정보와 입력 상태가 연결된 함수에 인자로 전달됩니다.

#### Parameters

| `string` ActionName       | 동작을 식별하기 위한 이름입니다.                                                                                                                                                                                                                                             |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` FunctionToBind    | <p>입력이 감지되었을 때 실행되는 함수로, 연결된 함수에는 다음과 같은 인자들이 전달됩니다:</p><ul><li><code>string</code> ActionName: BindAction()에 의해 정의된 동작의 이름</li><li><code>Enum.UserInputState</code>: 입력 상태</li><li><code>InputObject</code> InputObject: 입력과 관련된 세부 정보를 포함하는 객체입니다.</li></ul> |
| `bool` bCreateTouchButton | 동작을 실행할 버튼을 화면에 표시할지 여부입니다.                                                                                                                                                                                                                                    |
| `Tuple` InputType         | Enum.KeyCode를 사용하여 동작을 실행할 키를 지정할 수 있으며, 여러 개의 키를 설정하는 것도 가능합니다.                                                                                                                                                                                               |

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

바인딩된 모든 액션 정보를 테이블 형태로 반환합니다.

반환된 테이블은 각 액션의 이름을 키로 하며, 해당 이름을 GetBoundActionInfo()에 전달했을 때 얻을 수 있는 상세 정보가 값으로 포함됩니다.

여러 액션이 동시에 바인딩되어 있을 때 우선순위가 올바르게 적용되고 있는지, 또는 어떤 액션이 덮어쓰기 되었는지를 확인할 때 유용하게 사용할 수 있습니다.

#### Parameters

#### Return

| `Dictionary` | 바인딩된 모든 액션 정보가 구성된 딕셔너리입니다. |
| ------------ | --------------------------- |

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

특정 액션 이름을 기준으로, 그 액션에 바인딩된 입력 정보와 속성들을 반환합니다.

#### Parameters

| `string` ActionName | BindAction()에 의해 정의된 동작의 이름 |
| ------------------- | --------------------------- |

#### Return

| `Dictionary` | 액션 정보가 구성된 딕셔너리입니다. |
| ------------ | ------------------- |

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

BindAction()을 통해 생성된 터치 버튼을 ImageButton 객체로 반환합니다.

터치 버튼을 사용하지 않는 액션인 경우, nil을 반환합니다.

#### Parameters

| `string` ActionName | BindAction()에 의해 정의된 동작의 이름 |
| ------------------- | --------------------------- |

#### Return

| `Instance` | 생성된 터치 버튼입니다. |
| ---------- | ------------- |

#### Code Samples

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

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

### SetDescription

BindAction()을 통해 정의된 액션에 설명 텍스트를 설정하는 기능입니다.

설정한 텍스트는 UI직접 표시되지는 않으며, 액션에 대한 정보를 설명하거나 구분하기 위한 용도로만 사용됩니다.

#### Parameters

| `string` ActionName    | BindAction()에 의해 정의된 동작의 이름 |
| ---------------------- | --------------------------- |
| `string` InDescription | 설정할 설명입니다.                  |

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

BindAction()을 통해 생성된 터치 버튼에 이미지를 설정하는 기능입니다.

#### Parameters

| `string` ActionName | BindAction()에 의해 정의된 동작의 이름 |
| ------------------- | --------------------------- |
| `string` ImageId    | 터치 버튼에 표시할 이미지의 AssetId입니다. |

#### Return

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

#### Code Samples

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

### SetPosition

BindAction()을 통해 생성된 터치 버튼의 화면 내 위치를 설정하는 기능입니다.

#### Parameters

| `string` ActionName | BindAction()에 의해 정의된 동작의 이름 |
| ------------------- | --------------------------- |
| `UDim2` InPosition  | 설정할 위치입니다.                  |

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

BindAction()을 통해 생성된 터치 버튼에 표시되는 글자를 설정하는 기능입니다.

#### Parameters

| `string` ActionName | BindAction()에 의해 정의된 동작의 이름 |
| ------------------- | --------------------------- |
| `string` InTitle    | 설정할 내용입니다.                  |

#### Return

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

#### Code Samples

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

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

### UnbindAction

특정 문자열에 정의된 입력 동작을 해제합니다.

#### Parameters

| `string` ActionName | BindAction()에 의해 정의된 동작의 이름 |
| ------------------- | --------------------------- |

#### Return

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

#### Code Samples

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

ContextActionService:UnbindAction(ActionName)
```

## Events

### LocalToolEquipped

플레이어가 도구를 장착할 때 실행되는 이벤트입니다.

#### Parameters

| `Tool` Tool | 장착한 도구입니다. |
| ----------- | ---------- |

#### Code Samples

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

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

### LocalToolUnequipped

플레이어가 장착한 도구를 해제할 때 실행되는 이벤트입니다.

#### Parameters

| `Tool` 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="../../../manual/script-manual/input-and-controls/contextactionservice" %}
[contextactionservice](https://docs.overdare.com/korean/manual/script-manual/input-and-controls/contextactionservice)
{% endcontent-ref %}