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)
UnbindAction
특정 문자열에 정의된 입력 동작을 해제합니다.
Parameters
string
ActionName
BindAction()에 의해 정의된 동작의 이름
Return
void
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local ActionName = "JumpAction"
ContextActionService:UnbindAction(ActionName)
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
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")
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)
Events
LocalToolEquipped
플레이어가 도구를 장착할 때 실행되는 이벤트입니다.
Parameters
Instance
Tool
장착한 도구입니다.
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local function OnToolEquipped(tool)
print("OnToolEquipped")
end
ContextActionService.LocalToolEquipped:Connect(OnToolEquipped)
LocalToolUnequipped
플레이어가 장착한 도구를 해제할 때 실행되는 이벤트입니다.
Parameters
Instance
Tool
장착 해제한 도구입니다.
Code Samples
local ContextActionService = game:GetService("ContextActionService")
local function OnToolUnequipped(tool)
print("OnToolUnequipped")
end
ContextActionService.LocalToolUnequipped:Connect(OnToolUnequipped)
See also
모바일 조작 처리Last updated