ContextActionService

메서드

BindAction(actionName : string,functionToBind : function,createTouchButton : boolean,inputTypes : Tuple):()
사용자 입력을 작업 처리 함수에 바인딩하여 작업을 수행합니다.Bind user input to an action given an action handling function.
BindActionAtPriority(actionName : string,functionToBind : function,createTouchButton : boolean,priorityLevel : number,inputTypes : Tuple):()
BindAction와 같은 동작을 하지만 겹치는 입력 유형에 우선 순위를 할당할 수도 있습니다(높음에서 낮음).
BindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodesForActivation : Tuple):()
특정 Enum.KeyCode 와 함께 바인딩하여 이벤트 Enum.UserInputType 및 Tool.Activation 및 ClickDetector 을 트리거합니다.
GetAllBoundActionInfo():Dictionary
모든 바인딩된 작업에 대한 정보 테이블을 가져오십시오(키는 BindAction 에 전달된 이름, 값은 키로 호출할 때 GetBoundActionInfo 의 테이블).
GetBoundActionInfo(actionName : string):Dictionary
처음에 이름으로 전달된 바인딩된 작업에 대한 정보 테이블을 가져옵니다.Get a table of information about a bound action given its name originally passed to BindAction .
GetCurrentLocalToolIcon():string
현재 에 의해 의 를 반환하십시오.
SetDescription(actionName : string,description : string):()
터치 버튼으로 바인딩된 액션의 이름을 지정하여 액션의 설명을 설정합니다.
SetImage(actionName : string,image : string):()
actionName 키에 바인딩된 액션이 있으면 image 터치 버튼의 이미지로 설정됩니다.
SetPosition(actionName : string,position : UDim2):()
터치 버튼으로 바인딩된 액션의 이름을 고려하여 컨텍스트 버튼프레임 내의 버튼 위치를 설정합니다.
SetTitle(actionName : string,title : string):()
터치 버튼으로 바인딩된 액션의 이름을 지정하여 버튼에 표시되는 텍스트를 설정합니다.
UnbindAction(actionName : string):()
이름을 입력받은 액션을 해제합니다.
UnbindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodeForActivation : Enum.KeyCode):()
트리거와 바인딩될 때 와 특정 에서 트리거가 발동되지 않도록 해제하십시오.
UnbindAllActions():()
바인딩된 모든 함수를 제거합니다. 작업 이름이 남지 않습니다. 모든 터치 버튼이 제거됩니다.
GetButton(actionName : string):Instance
생성
만든 터치 입력 버튼이 있는 ImageButton 행동의 bound 을 검색합니다.

이벤트

LocalToolEquipped(toolEquipped : Instance):RBXScriptSignal
현재 플레이어가 Tool를 장착할 때 발생합니다.
LocalToolUnequipped(toolUnequipped : Instance):RBXScriptSignal
현재 플레이어가 Tool를 장비 해제할 때 발생합니다.

속성

메서드

BindAction

()

작업 처리 함수에 사용자 입력에 대한 작업을 바인딩하여 작업을 처리합니다.Bind an action to user input given an action handling function.일치하는 입력이 수행되면 아래에 나열된 인수로 액션 처리기 함수가 호출됩니다.유효한 입력 열거형 항목에는 팔로잉중 하나가 포함됩니다: Enum.KeyCode, Enum.UserInputType 또는 Enum.PlayerActions.플레이어가 컨텍스트에 액션을 수행할 수 있는 상황 에 들어갈 때 이 함수를 호출하십시오.플레이어가 컨텍스트를 떠날 때, 동일한 UnbindAction로 actionName를 호출하십시오.CallFunction를 사용하여 액션의 액션 처리 함수를 수동으로 호출할 수 있습니다.

아래 코드 샘플은 키(), 게임 패드 버튼 또는 터치 스크린 버튼이 누르힐 때 가 어떻게 될 수 있는지 보여줍니다.


local ContextActionService = game:GetService("ContextActionService")

-- 자동차 경적 소리
local honkSound = Instance.new("Sound", workspace)
honkSound.Looped = true
honkSound.SoundId = "rbxassetid://9120386436"

local function handleAction(actionName, inputState, inputObject)
	if actionName == "HonkHorn" then
		if inputState == Enum.UserInputState.Begin then
			honkSound:Play()
		else
			honkSound:Pause()
		end
	end
end

-- 플레이어가 차량에 앉을 때:
ContextActionService:BindAction("HonkHorn", handleAction, true, Enum.KeyCode.H, Enum.KeyCode.ButtonY)

-- 플레이어가 나올 때:
ContextActionService:UnbindAction("HonkHorn")

액션 처리기 매개 변수

액션 처리기 함수는 다음 매개변수로 호출됩니다:


<th>유형</th>

  <th>설명</th>
</tr>

<tr>
  <td>1</td>

  <td><code>문자열</code></td>

  <td>원래 BindAction에 전달된 동일한 문자열†</td>
</tr>

<tr>
  <td>2</td>

  <td><code>Enum.UserInputState</code></td>

  <td>입력 상태(시작, 변경, 종료 또는 취소)*</td>
</tr>

<tr>
  <td>3</td>

  <td><code>입력 개체</code></td>

  <td>입력에 대한 정보가 포함된 개체(사용자 입력 유형에 따라 다름)</td>
</tr>

† 필요한 경우 한 함수가 여러 작업을 한 번에 처리할 수 있도록 합니다.일부 입력이 진행 중이고 다른 작업이 진행 중 입력에 바인딩되었거나 진행 중 바인딩 작업이 unbound 였으면 취소가 전송됩니다.

액션 바인딩 스택

작업 바인딩은 스택처럼 작동합니다: 두 작업이 동일한 사용자 입력에 바인딩되면 가장 최근에 바인딩된 작업 처리기가 사용됩니다.액션 처리기가 Enum.ContextActionResult.Pass 를 반환하면 다음으로 가장 최근에 바인딩된 액션 처리기가 호출되고, 입력을 반환하기 위해 nil 또는 Enum.ContextActionResult.Sink 을 반환할 때까지 계속됩니다.UnbindAction 가 호출되면 액션 처리기가 스택에서 제거됩니다.이 스택 동작은 BindActionAtPriority 를 사용하여 재정의할 수 있으며, createTouchButton 이후의 추가 우선 순위 매개 변수가 작업의 바인딩 순서(높은 순서 전에 낮은 순서)를 재정의할 수 있습니다.

터치 버튼

입력 유형 외에도 이 함수의 세 번째 매개 변수는 버튼이 TouchEnabled 장치에 대해 생성되는지 여부를 제어합니다.처음 터치 버튼의 작품시, "ContextActionGui"라는 이름의 ScreenGui 가 PlayerGui 에 추가됩니다.ScreenGui 내에 "ContextButtonFrame"이라는 것이 추가되었습니다. Frame이 프레임에서는 바인딩된 작업에 대해 ImageButtons 가 부모로 지정되며, 사용자 지정을 위해 GetButton 를 사용하여 이러한 버튼을 검색할 수 있습니다.

매개 변수

actionName: string

수행되는 작업을 나타내는 문자열(예: "HonkHorn" 또는 "OpenDoor").

기본값: ""

functionToBind: function

바인딩된 입력이 트리거될 때 다음 매개변수로 호출되는 작업 처리 함수: string(actionName), Enum.UserInputState 및 InputObject.

기본값: ""

createTouchButton: boolean

터치 입력 장치에 대한 작업에 대해 GUI 버튼을 만들어야 하는지 여부.

기본값: ""

inputTypes: Tuple

액션에 바인딩할 입력을 나타내는 Enum.KeyCode 또는 Enum.UserInputType의 모든 숫자.

기본값: ""

반환

()

코드 샘플

ContextActionService Tool Reload

local ContextActionService = game:GetService("ContextActionService")

local ACTION_RELOAD = "Reload"

local tool = script.Parent

local function handleAction(actionName, inputState, _inputObject)
	if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
		print("Reloading!")
	end
end

tool.Equipped:Connect(function()
	ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)

tool.Unequipped:Connect(function()
	ContextActionService:UnbindAction(ACTION_RELOAD)
end)

This code sample uses ContextActionService to bind an action named "BoundAction" to a general action handler function on the F key. Place this in a LocalScript inside StarterPlayerScripts and press F to see the message "Handling action: BoundAction".

General Action Handler

local ContextActionService = game:GetService("ContextActionService")

local function handleAction(actionName, inputState, inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Handling action: " .. actionName)
		print(inputObj.UserInputType)
	end

	-- Since this function does not return anything, this handler will
	-- "sink" the input and no other action handlers will be called after
	-- this one.
end

ContextActionService:BindAction("BoundAction", handleAction, false, Enum.KeyCode.F)

This code sample demonstrates how BindAction acts like a stack. It binds two actions, FirstAction (Z, X, and C keys) and SecondAction (Z and X keys) to two action handling functions. The second one will pass on a certain input (the X key).

Both actions use the Z and X keys, however the second handler will pass input only if X is pressed. So, when X is pressed, the second handler is called and then the first. The first action is also bound to the C key, and can be triggered even though the other two inputs are "covered" by the second action.

Test this code out by pasting it into a LocalScript within StarterPlayerScripts, then pressing Z, X and C. Observe which action handlers are called with what actions.

Stacked Action Handlers

local ContextActionService = game:GetService("ContextActionService")

-- Define an action handler for FirstAction
local function actionHandlerOne(actionName, inputState, _inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Action Handler One: " .. actionName)
	end
	-- This action handler returns nil, so it is assumed that
	-- it properly handles the action.
end

-- Binding the action FirstAction (it's on the bottom of the stack)
ContextActionService:BindAction("FirstAction", actionHandlerOne, false, Enum.KeyCode.Z, Enum.KeyCode.X, Enum.KeyCode.C)

-- Define an action handler for SecondAction
local function actionHandlerTwo(actionName, inputState, inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Action Handler Two: " .. actionName)
	end

	if inputObj.KeyCode == Enum.KeyCode.X then
		return Enum.ContextActionResult.Pass
	else
		-- Returning nil implicitly Sinks inputs
		return Enum.ContextActionResult.Sink
	end
end

-- Binding SecondAction over the first action (since it bound more recently, it is on the top of the stack)
-- Note that SecondAction uses the same keys as
ContextActionService:BindAction("SecondAction", actionHandlerTwo, false, Enum.KeyCode.Z, Enum.KeyCode.X)

BindActionAtPriority

()

BindActionAtPriority는 BindAction와 같이 동작하지만 바인딩된 액션에 우선 순위를 할당할 수도 있습니다.여러 작업이 동일한 입력에 바인딩되면 작업이 바인딩된 순서와 상관없이 우선 순위가 높은 함수가 호출됩니다.즉, 이 함수는 BindAction의 일반적인 "스택" 동작을 재정의합니다.

매개 변수

actionName: string

수행되는 작업을 나타내는 문자열(예: "HonkHorn" 또는 "OpenDoor").

기본값: ""

functionToBind: function

바인딩된 입력이 트리거될 때 다음 매개변수로 호출되는 작업 처리 함수: string(actionName), Enum.UserInputState 및 InputObject.

기본값: ""

createTouchButton: boolean

터치 입력 장치에 대한 작업에 대해 GUI 버튼을 만들어야 하는지 여부.

기본값: ""

priorityLevel: number

액션을 바인딩해야 하는 우선 순위 레벨(낮은 순으로 고려됨).

기본값: ""

inputTypes: Tuple

액션에 바인딩할 입력을 나타내는 Enum.KeyCode 또는 Enum.UserInputType의 모든 수입니다.

기본값: ""

반환

()

코드 샘플

This code sample demonstrates how ContextActionService:BindActionAtPriority() can be used to bind actions out of order yet still have the same priority levels. Normally, BindAction() would operate on order (last bound action has highest priority), but priority levels override this. You can test this code by pasting it into a Script with RunContext = Client in ReplicatedStorage.

ContextActionService BindAction Priorities

local ContextActionService = game:GetService("ContextActionService")

local INPUT_KEY1 = Enum.KeyCode.Q
local INPUT_KEY2 = Enum.KeyCode.E

local function handleThrow(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
	if inputState ~= Enum.UserInputState.Begin then
		return Enum.ContextActionResult.Pass
	end
	print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)

	return Enum.ContextActionResult.Sink
end

local function handlePunch(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
	if inputState ~= Enum.UserInputState.Begin then
		return Enum.ContextActionResult.Pass
	end
	print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)

	return Enum.ContextActionResult.Sink
end

-- Without specifying priority, the most recently bound action is called first,
-- so pressing INPUT_KEY1 prints "Punch" and then sinks the input.
ContextActionService:BindAction("DefaultThrow", handleThrow, false, INPUT_KEY1)
ContextActionService:BindAction("DefaultPunch", handlePunch, false, INPUT_KEY1)

-- Here we bind both functions in the same order as above, but with explicitly swapped priorities.
-- That is, we give "Throw" a higher priority of 2 so it will be called first,
-- despite "Punch" still being bound more recently.
-- Pressing INPUT_KEY2 prints "Throw" and then sinks the input.
ContextActionService:BindActionAtPriority("PriorityThrow", handleThrow, false, 2, INPUT_KEY2)
ContextActionService:BindActionAtPriority("PriorityPunch", handlePunch, false, 1, INPUT_KEY2)

BindActivate

()

에서 까지 사용할 수 있는 바인딩 을, 에서 까지 이벤트를 활성화하고, 에서 까지 사용할 수 있습니다.지정된 키/버튼이 누르면, 마우스에 전송된 Mouse.Button1Down 이벤트에 대해 Tool.Equipped 이벤트가 발생합니다.이로 인해 Tool.Activated 이벤트가 발생하고 Tool.ManualActivationOnly 가 참으로 설정되지 않으면 이벤트가 발생합니다.게임패드 입력의 경우, 이 함수는 ButtonR2 Enum.KeyCode 을 바인딩하기 위해 기본 제어 스크립트에 의해 호출됩니다.

지정된 Enum.UserInputType 는 유효하려면 Keyboard 또는 Gamepad1 을 통해 Gamepad8 에서 유효해야 합니다.

매개 변수

userInputTypeForActivation: Enum.UserInputType

게임패드8을 통해 키보드 또는 게임패드1여야 합니다.

기본값: ""

keyCodesForActivation: Tuple

기본값: ""

반환

()

GetAllBoundActionInfo

GetAllBoundActioninfo는 모든 작업의 이름(원래 전달된 것은 BindAction )을 액션 이름과 동일한 테이블로 매핑하는 테이블을 반환하며, 액션 이름 자체로 호출되면 GetBoundActionInfo에서 반환된 테이블입니다.이 함수를 사용하여 현재 바인딩된 모든 작업을 검사할 수 있습니다.우선 순위 수준이나 스택 순서를 디버깅할 때 유용합니다.

반환

GetBoundActionInfo

GetBoundActionInfo는 이름에 바인딩된 작업을 지정하는 다음 키가 있는 테이블을 반환합니다.모든 작업에 대해 한 번에 동일한 정보를 가져오려면 GetAllBoundActionInfo를 사용하십시오.


<th>유형</th>

  <th>설명</th>
</tr>

<tr>
  <td><code>스택 순서</code></td><td>번호</td>

  <td>
    스택에서 액션의 인덱스(증가)를 설명합니다
  </td>
</tr>

<tr>
  <td><code>우선 순위 수준</code> \*</td><td>번호</td>

  <td>
    동작의 <code>Class.ContextActionService:BindActionAtPriority()|priority</code> 수준을 설명합니다
  </td>
</tr>

<tr>
  <td><code>터치 버튼 생성</code></td><td>bool</td>

  <td>
    터치 버튼을 <code>Class.UserInputService.TouchEnabled|TouchEnabled</code> 장치에 생성해야 하는지 여부를 설명합니다
  </td>
</tr>

<tr>
  <td><code>입력 유형</code></td><td>테이블</td>

  <td>
    이 작업이 트리거될 <code>Class.ContextActionService:BindAction()|BindAction</code>에 전달된 입력 유형
  </td>
</tr>

<tr>
  <td><code>설명</code> †</td><td>문자열</td>

  <td>
    클래스.ContextActionService에 의해 설정된 작업의 설명 <code>Class.ContextActionService:SetDescription()|SetDescription</code>
  </td>
</tr>

<tr>
  <td><code>타이틀</code> †</td><td>문자열</td>

  <td>
    클래스.ContextActionService에 의해 설정된 작업의 제목 <code>Class.ContextActionService:SetTitle()|SetTitle</code>
  </td>
</tr>

<tr>
  <td><code>이미지</code> †</td><td>문자열</td>

  <td>
    클래스.ContextActionService에 의해 설정된 액션터치 버튼 이미지 <code>Class.ContextActionService:SetImage()|SetImage</code>
  </td>
</tr>

이름

우선 순위 레벨은 사용되지 않았더라도 BindActionAtPriority 포함될 것입니다. 기본값은 2000입니다.

† 연결된 메서드가 지정된 액션대해 호출되지 않은 경우 이 필드가 nil가 될 것임을 나타냅니다.

매개 변수

actionName: string

기본값: ""

반환