ContextActionService

ContextActionService : Instance

Overview

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

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

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

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

Properties

Methods

BindAction

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

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

Parameters

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

Return

void

Code Samples

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

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

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

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

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

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

SetPosition

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

Parameters

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

Return

void

Code Samples

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

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

ContextActionService:SetTitle(ActionName, "Action")

UnbindAction

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

Parameters

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

Return

void

Code Samples

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

ContextActionService:UnbindAction(ActionName)

Events

LocalToolEquipped

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

Parameters

Tool Tool	장착한 도구입니다.

Code Samples

local ContextActionService = game:GetService("ContextActionService")

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

LocalToolUnequipped

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

Parameters

Tool Tool	장착 해제한 도구입니다.

Code Samples

local ContextActionService = game:GetService("ContextActionService")

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

See also

모바일 조작 처리