ContextActionService

Gắn một hành động vào đầu vào người dùng được cung cấp chức năng xử lý hành động.Sau khi thực hiện một lần nhập phù hợp, chức năng xử lý hành động sẽ được gọi với các tham số được liệt kê dưới đây.Các mục danh sách nhập hợp lệ bao gồm những mục nằm trong các thành phần theo dõi: Enum.KeyCode , Enum.UserInputType hoặc Enum.PlayerActions .Gọi chức năng này khi một người chơi nhập vào bối cảnh mà một hành động có thể được thực hiện.Khi người chơi rời khỏi bối cảnh, gọi UnbindAction với cùng actionName .Bạn có thể gọi chức năng xử lý hành động của một hành động bằng tay bằng cách sử dụng CallFunction .

Ví dụ mã bên dưới cho thấy cách một Sound có thể played trong khi một chìa khóa ( H ), nút gamepad hoặc nút màn hình cảm ứng được nhấn.

local ContextActionService = game:GetService("ContextActionService")

-- Một tiếng còi xe
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

-- Khi người chơi ngồi trong xe:
ContextActionService:BindAction("HonkHorn", handleAction, true, Enum.KeyCode.H, Enum.KeyCode.ButtonY)

-- Khi người chơi ra ngoài:
ContextActionService:UnbindAction("HonkHorn")

Tham số xử lý hành động

Các chức năng xử lý hành động được gọi với các tham số sau:

<th>Loại</th>

  <th>Mô tả</th>
</tr>

<tr>
  <td>1</td>

  <td><code>chuỗi</code></td>

  <td>Chuỗi tương tự mà ban đầu đã được chuyển cho BindAction†</td>
</tr>

<tr>
  <td>2</td>

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

  <td>Tình trạng của đầu vào (Bắt đầu, Thay đổi, Kết thúc hoặc Hủy)*</td>
</tr>

<tr>
  <td>3</td>

  <td><code>Đối tượng Nhập</code></td>

  <td>Một đối tượng chứa thông tin về đầu vào (thay đổi tùy thuộc vào UserInputType)</td>
</tr>

† Nó cho phép một chức năng xử lý nhiều hành động cùng một lúc, nếu cần thiết.Hủy được gửi nếu một số đầu vào đang thực hiện và một hành động khác được gắn vào đầu vào đang thực hiện, hoặc nếu hành động gắn kết tiến hành đang thực hiện là unbound .

Cấu trúc gắn kết hành động

Các gắn kết hành động hành xử giống như một đống: nếu hai hành động được gắn vào cùng một đầu vào người dùng, hành động xử lý hành động gần đây nhất sẽ được sử dụng.Nếu một xử lý hành động trả về Enum.ContextActionResult.Pass , xử lý hành động gắn kết tiếp theo gần đây nhất sẽ được gọi, và như vậy cho đến khi một xử lý chìm đầu vào (bằng cách trả lại nil hoặc Enum.ContextActionResult.Sink ).Khi UnbindAction được gọi, bộ xử lý hành động được xóa khỏi chồng.Hành vi xếp chồng này có thể bị xóa bỏ bằng cách sử dụng BindActionAtPriority , nơi một tham số ưu tiên bổ sung sau createTouchButton có thể lấy lại thứ tự mà các hành động được gắn kết (cao hơn trước thấp hơn)

Nút chạm

Ngoài các loại nhập, tham số thứ ba của chức năng này kiểm soát xem có tạo nút cho các thiết bị TouchEnabled hay không.Sau khi sản phẩmnút chạm đầu tiên, một ScreenGui có tên là "ContextActionGui" được thêm vào PlayerGui.Bên trong ScreenGui có một Frame gọi là "ContextButtonFrame" được thêm vào.Nó là trong khung này mà ImageButtons cho các hành động gắn kết được cha; bạn có thể sử dụng GetButton để lấy lại các nút như vậy cho tùy chỉnh.

Tham Số

Lợi Nhuận

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)

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)

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 hành xử giống như BindAction nhưng cũng cho phép gán ưu tiên cho hành động gắn kết.Nếu nhiều hành động được gắn vào cùng một đầu vào, chức năng ưu tiên cao hơn được gọi bất kể thứ tự hành động được gắn.Nói cách khác, chức năng này thay thế hành vi "stack" bình thường của BindAction.

Tham Số

Lợi Nhuận

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)

Gắn một Enum.KeyCode có thể được sử dụng với một Enum.UserInputType để kích hoạt sự kiện ClickDetector , Tools và GuiButtons .Khi phím/ nút được cung cấp được nhấn, nó kích hoạt sự kiện Mouse.Button1Down trên chuột được gửi đến Tool.Equipped .Điều này lại kích hoạt sự kiện Tool.Activated nếu Tool.ManualActivationOnly không được đặt thành true.Đối với đầu vào gamepad, chức năng này được gọi bởi các kịch bản điều khiển mặc định để gắn kết nút ButtonR2 Enum.KeyCode .

Lưu ý rằng Enum.UserInputType được định nghĩa phải là Keyboard hoặc Gamepad1 thông qua Gamepad8 để có hiệu lực.

Tham Số

Lợi Nhuận

GetAllBoundActioninfo trả về một bảng mà mọi tên hành động (những người ban đầu được chuyển sang BindAction ) được định danh cho một bảng được trả lại bởi GetBoundActionInfo khi gọi với tên hành động chính nó.Sử dụng chức năng này, bạn có thể kiểm tra tất cả các hành động được gắn hiện tại.Điều này hữu ích khi gỡ lỗi cấp ưu tiên hoặc lệnh xếp chồng của chúng.

Lợi Nhuận

GetBoundActionInfo trả về một bảng với các chìa khóa sau đây mô tả một hành động gắn kết được cho tên của nó.Để nhận được thông tin tương tự cho tất cả các hành động cùng một lúc, hãy sử dụng GetAllBoundActionInfo .

<th>Loại</th>

  <th>Mô tả</th>
</tr>

<tr>
  <td><code>stackOrder</code></td><td>số</td>

  <td>
    Mô tả chỉ mục của hành động trên đống (tăng)
  </td>
</tr>

<tr>
  <td><code>mức ưu tiên</code> \*</td><td>số</td>

  <td>
    Mô tả cấp <code>Class.ContextActionService:BindActionAtPriority()|priority</code> của hành động
  </td>
</tr>

<tr>
  <td><code>tạo nút chạm</code></td><td>bool</td>

  <td>
    Mô tả xem liệu nút chạm có nên được tạo trên <code>Class.UserInputService.TouchEnabled|TouchEnabled</code> thiết bị
  </td>
</tr>

<tr>
  <td><code>loại nhập</code></td><td>bảng</td>

  <td>
    Các loại đầu vào được chuyển đến <code>Class.ContextActionService:BindAction()|BindAction</code> mà hành động này sẽ kích hoạt
  </td>
</tr>

<tr>
  <td><code>mô tả</code> †</td><td>chuỗi</td>

  <td>
    Mô tả hành động được thiết lập bởi <code>Class.ContextActionService:SetDescription()|SetDescription</code>
  </td>
</tr>

<tr>
  <td><code>tiêu đề</code> †</td><td>chuỗi</td>

  <td>
    Tiêu đề của hành động được thiết lập bởi <code>Class.ContextActionService:SetTitle()|SetTitle</code>
  </td>
</tr>

<tr>
  <td><code>hình ảnh</code> †</td><td>chuỗi</td>

  <td>
    Hình ảnh nút chạm của hành động được thiết lập bởi <code>Class.ContextActionService:SetImage()|SetImage</code>
  </td>
</tr>

:* Cấp ưu tiên vẫn sẽ được bao gồm ngay cả khi BindActionAtPriority chưa được sử dụng - mặc định nó sẽ là 2000.

† Chỉ ra rằng trường này sẽ là nil nếu phương pháp liên quan không được gọi cho hành động được cho.

Tham Số

Lợi Nhuận

GetCurrentLocalToolIcon sẽ trả về BackpackItem.TextureId của một Tool hiện tại equipped bởi Player , hoặc nil nếu không có công cụ như vậy hoặc nếu người chơi thiếu một Character .

Lợi Nhuận

SetDescription sẽ đặt mô tả của một hành động được gắn bởi BindAction .Trong danh sách các hành động có sẵn, đây sẽ là văn bản mô tả hành động được cung cấp.

Mặc dù tên có thể gợi ý rằng phương pháp này liên quan đến gia đình các chức năng tùy chỉnh một nút chạm để thực hiện các hành động tạo chúng ( SetTitle , SetImage và SetPosition ), phương pháp này không ảnh hưởng đến một nút như vậy.Phương pháp này chỉ đặt một mô tả văn bản của một hành động, và không có gì hơn thế.

Tham Số

Lợi Nhuận

local ContextActionService = game:GetService("ContextActionService")

local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it

local function handleAction(actionName, inputState, _inputObject)
	if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
		print("Inspecting")
	end
end

-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
	imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

Phương pháp này đặt hình ảnh được hiển thị trên nút chạm được tạo bởi BindAction().Cụ thể, nó đặt thuộc tính ImageLabel.Image của ImageLabel trong ImageButton mà sẽ được trả lại bởi GetButton .Nếu không có hành động gắn kết như vậy (ví dụ: không có gì được trả lại bởi GetButton), chức năng này không làm gì và không phát hiện lỗi.

Chức năng này là một phần trong một gia đình các phương pháp tùy chỉnh nút chạm của một hành động. Những người khác trong gia đình này bao gồm SetPosition và SetTitle .

Tham Số

Lợi Nhuận

local ContextActionService = game:GetService("ContextActionService")

local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it

local function handleAction(actionName, inputState, _inputObject)
	if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
		print("Inspecting")
	end
end

-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
	imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

Phương pháp này đặt vị trí của nút chạm được tạo bởi BindAction() .Cụ thể, nó đặt thuộc tính GuiObject.Position của ImageButton sẽ được trả lại bởi GetButton .Nếu không có hành động gắn kết như vậy (ví dụ: không có gì được trả lại bởi GetButton), chức năng này không làm gì và không phát hiện lỗi.

Chức năng này là một phần trong một gia đình các phương pháp tùy chỉnh nút chạm của một hành động. Những người khác trong gia đình này bao gồm SetImage và SetTitle .

Tham Số

Lợi Nhuận

local ContextActionService = game:GetService("ContextActionService")

local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it

local function handleAction(actionName, inputState, _inputObject)
	if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
		print("Inspecting")
	end
end

-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
	imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

SetTitle sẽ đặt văn bản được hiển thị trên nút chạm được tạo bởi BindAction.Cụ thể, nó đặt thuộc tính TextLabel.Text của một TextLabel trong ImageButton mà sẽ được trả lại bởi GetButton .Nếu không có hành động gắn kết như vậy (ví dụ: không có gì được trả lại bởi GetButton), chức năng này không làm gì và không phát hiện lỗi.

Chức năng này là một phần trong một gia đình các phương pháp tùy chỉnh nút chạm của một hành động. Những người khác trong gia đình này bao gồm SetImage và SetPosition .

Tham Số

Lợi Nhuận

local ContextActionService = game:GetService("ContextActionService")

local ACTION_INSPECT = "Inspect"
local INPUT_INSPECT = Enum.KeyCode.E
local IMAGE_INSPECT = "rbxassetid://1826746856" -- Image of a speech bubble with ? in it

local function handleAction(actionName, inputState, _inputObject)
	if actionName == ACTION_INSPECT and inputState == Enum.UserInputState.End then
		print("Inspecting")
	end
end

-- For touch devices, a button is created on-screen automatically via the 3rd parameter
ContextActionService:BindAction(ACTION_INSPECT, handleAction, true, INPUT_INSPECT)
-- We can use these functions to customize the button:
ContextActionService:SetImage(ACTION_INSPECT, IMAGE_INSPECT)
ContextActionService:SetTitle(ACTION_INSPECT, "Look")
ContextActionService:SetDescription(ACTION_INSPECT, "Inspect something.")
ContextActionService:SetPosition(ACTION_INSPECT, UDim2.new(0, 0, 0, 0))
-- We can manipulate the button directly using ContextActionService:GetButton
local imgButton = ContextActionService:GetButton(ACTION_INSPECT)
if imgButton then -- Remember: non-touch devices won't return anything!
	imgButton.ImageColor3 = Color3.new(0.5, 1, 0.5) -- Tint the ImageButton green
end

UnbindAction sẽ gỡ bỏ một hành động theo tên từ đầu vào của người dùng để chức năng xử lý hành động không còn được gọi.Gọi chức năng này khi ngữ cảnh cho một số hành động không còn hiện hànhdụng nữa, chẳng hạn như đóng giao diện người dùng, thoát khỏi xe hoặc unequipping một Tool .Xem BindAction để có thêm thông tin về cách hoạt động của hành động gắn kết.

Chức năng này sẽ không ném lỗi nếu không có hành động như vậy gắn với chuỗi đã cho.Bằng cách sử dụng GetAllBoundActionInfo hoặc tab "Action Bindings" của Developer Console, bạn có thể tìm ra các hành động hiện đang được gắn kết.

Tham Số

Lợi Nhuận

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)

UnbindActivate bỏ gắn kết một Enum.KeyCode được sử dụng với một Enum.UserInputType để kích hoạt một Tool (hoặc một HopperBin ) bằng cách sử dụng BindActivate .Chức năng này về cơ bản hoàn tác hành động được thực hiện bởi chức năng đó.

Tham Số

Lợi Nhuận

Loại bỏ tất cả các chức năng được gắn kết.Không có tên hành động nào sẽ còn lại.Tất cả các nút chạm sẽ được xóa bỏ.Nếu một nút được thao tác thủ công thì không có đảm bảo nó sẽ được dọn sạch.

Lợi Nhuận

Nút Get trả về ImageButton được tạo bởi BindAction nếu tham số thứ ba là đúng và thiết bị là TouchEnabled .Tham số duy nhất cho chức năng này phải chính xác khớp với tên của hành động ban đầu được gửi đến BindAction.

Nếu không có hành động như vậy được gắn kết hoặc nếu nút không được tạo, chức năng này trả về nil .

Tham Số

Lợi Nhuận

Bắt lửa khi người chơi hiện tại trang bị một Tool .

Tham Số

Bắt lửa khi người chơi hiện tại bỏ trang bị một Tool .

Tham Số