輸入動作系統

跨平台的 輸入動作系統 讓您能夠連接 動作 並安排 綁定 在各種硬體輸入上。結合 上下文，您可以輕鬆配置和編輯一個模組化的輸入系統，該系統可以在任何設備的任何遊玩階段運作。使用案例包括：

• 一個第一人稱射擊系統，根據玩家是否處於戰鬥模式或觀眾模式，動作動態切換。
• 一個全面的駕駛系統，配備加速/減速、汽車增壓器和加油站。
• 在格鬥遊戲中為能力系統設置熱鍵，無縫切換動作，讓玩家不會錯過出拳。

輸入上下文

InputContext 是一組動作的集合，持有相關的 輸入動作，例如 PlayContext 用於遊戲中的角色控制，NavContext 用於導航 UI 菜單的控制。您可以通過其 Enabled 屬性 啟用/禁用上下文（及其相應的動作），例如在打開物品清單時啟用 NavContext，然後在玩家關閉菜單並返回主要遊玩時切換到 PlayContext。

即使遊戲最初可能不使用多個輸入上下文，建議在任何輸入系統的頂層創建一個主要上下文，例如在遊玩期間發生輸入的 PlayContext 實例。

1. 建議

   在 ReplicatedStorage 中創建一個名為 Inputs 的 Folder 以容納各種輸入上下文。

   

2. 在資料夾中插入一個新的 InputContext 並將其重新命名為 PlayContext。

   

3. 可選

   在 屬性 窗口中，將 Priority 設置為 2000 並啟用 Sink。啟用 Sink 的上下文會在其優先級級別消耗其綁定的 KeyCodes 的輸入事件，阻止這些輸入到達較低優先級的上下文。這在像物品清單這樣的用例中是實用的，當它打開時應該抑制特定的遊玩輸入。在這個例子中，PlayContext 被賦予足夠高的 Priority 以在默認的 PlayerScripts 上下文處理它們之前沉沒其綁定的輸入。

   

輸入動作

InputAction 定義了一個遊玩動作機制，例如「跳躍」、「衝刺」或「射擊」。這些動作然後通過 輸入綁定 映射到硬體輸入。

InputAction 可以根據其 Type 屬性（Enum.InputActionType）有幾種變體。默認為 Bool，設計用於接收來自按下/釋放的輸入的 true/false 值，例如 ButtonA、E 或 MouseLeftButton。

要測試一個簡單角色衝刺的 InputAction：

1. 建議

   在 資源管理器 中選擇頂層的 Workspace 對象，然後在 屬性 窗口中，將 PlayerScriptsUseInputActionSystem 屬性設置為 Enabled。

2. 在 ReplicatedStorage 的 PlayContext 上下文中創建一個新的 InputAction。將其重新命名為 CharacterSprint 以指示其專用動作。

   

3. 在 屬性 窗口中，注意動作的 Type 是 Bool（默認）。這是一個邏輯類型，適用於簡單角色衝刺作為布林 true/false 動作（角色要麼在衝刺，要麼不在衝刺）。

   

輸入綁定

InputBinding 定義了哪個硬體綁定應觸發父 InputAction，例如按鍵、遊戲手柄按鈕或觸控設備上的點擊。為了實現 跨平台 兼容性，每個 InputAction 應該有一個 遊戲手柄、鍵盤/滑鼠 和 觸控 的 InputBinding，如圖所示。

分配給父 InputAction 的 Type 直接影響哪些一般輸入類型（鍵/按鈕/點擊、類比觸發器、搖桿等）對子 InputBinding 實例是有效的。反過來，發送到父動作的連接事件的值取決於綁定所選的輸入類型。請參見 輸入事件 以獲取有關動作類型、綁定和返回值之間關聯的詳細信息。

要為簡單角色衝刺設置綁定：

1. 在 CharacterSprint 動作中插入一個新的 InputBinding 並將其重新命名為 KeyboardBinding。然後將綁定的 KeyCode 屬性設置為 LeftShift。

   

   

2. 在 CharacterSprint 動作中插入第二個 InputBinding 並將其重新命名為 GamepadBinding。然後將綁定的 KeyCode 屬性設置為 ButtonY。

   

   

3. 在 StarterGui 中的 ScreenGui 容器內創建一個 螢幕按鈕，將其重新命名為 SprintButton，並根據需要 定位/調整大小。

   

4. 在 CharacterSprint 動作中插入第三個 InputBinding 並將其重新命名為 TouchBinding。然後，在 屬性 窗口中，將綁定的 UIButton 屬性鏈接到您之前在 StarterGui 中創建的 SprintButton 按鈕。

   

   

輸入事件

InputAction 實例有三個內建的 事件 來處理來自 InputBindings 的玩家輸入。

• Pressed — 當輸入動作的 Type 設置為 Bool 時，該事件僅在狀態從 false 轉變為 true 時觸發。
• Released — 當輸入動作的 Type 設置為 Bool 時，該事件僅在狀態從 true 轉變為 false 時觸發。
• StateChanged — 此事件在所有輸入動作類型的狀態變更時觸發，除非狀態嘗試轉變為相同狀態。

根據輸入動作的 Type（Bool、Direction1D、Direction2D、Direction3D 或 ViewportPosition）和來自子 InputBinding 的一般輸入類型（鍵/按鈕/點擊、類比觸發器、搖桿等），不同的值會返回給 Pressed、Released 和 StateChanged 事件處理程序。檢查以下表格以更好地理解關聯。

Bool 類型最適合觸發的動作，例如跳躍、射擊、衝刺等，支持類比輸入的按下/釋放閾值。

要連接簡單角色衝刺的事件：

1. 在 CharacterSprint 樹中插入一個新的 Script，與各種輸入綁定並排。然後將其 RunContext 設置為 Client，並將其重新命名為 OnActivate。

   

2. 將以下代碼粘貼到 OnActivate 腳本中。注意第 13 到 15 行的 Pressed 事件連接，當衝刺輸入綁定被按下時，這會將角色的行走速度加倍，對應的 Released 事件連接在第 16 到 18 行，當衝刺輸入綁定被釋放時，這會將行走速度重置為默認值。

   OnActivate (客戶端腳本)

   local Players = game:GetService("Players")
   
   local player = Players.LocalPlayer
   local character = player.Character
   if not character or character.Parent == nil then
   	character = player.CharacterAdded:Wait()
   end
   local humanoid = character:WaitForChild("Humanoid")
   local defaultWalkSpeed = humanoid.WalkSpeed
   
   local inputAction = script.Parent
   
   inputAction.Pressed:Connect(function()
   	humanoid.WalkSpeed = defaultWalkSpeed * 2
   end)
   inputAction.Released:Connect(function()
   	humanoid.WalkSpeed = defaultWalkSpeed
   end)

3. 測試您的遊戲並使用您之前選擇的 綁定 測試角色衝刺動作：鍵盤的 LeftShift、遊戲手柄的 ButtonY，以及觸控設備的螢幕 SprintButton。請記住，您可以使用 控制器模擬器 在 Roblox Studio 中直接測試遊戲手柄輸入。

上下文變更

一旦您擁有一個 輸入上下文，例如 PlayContext，您可以通過腳本在遊玩期間啟用/禁用它，改變其 Priority 以確定哪些動作優先於其他動作，並 Sink 輸入以防止在較低優先級的上下文中處理。

1. 為了方便從其他腳本切換上下文，請在 ReplicatedStorage 中的輸入資料夾中插入一個新的 BindableEvent，並將其重新命名為 ContextEvent。

   

2. 在同一層級創建一個新的 Script，將其 RunContext 設置為 Client，並將其重新命名為 UpdateContext。

   

3. 在 UpdateContext 腳本中粘貼以下代碼：

   UpdateContext (客戶端腳本)

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   -- 連接可綁定事件
   contextEvent.Event:Connect(function(targetContext, enabled)
   	local context = inputsFolder:FindFirstChild(targetContext)
   	if context then
   		context.Enabled = enabled
   		print(context.Name .. ": " .. tostring(context.Enabled))
   	else
   		warn("未找到 InputContext！")
   	end
   end)

4. 有了 UpdateContext 腳本，您現在可以通過觸發可綁定事件來更新命名的 InputContext，例如從一個驅動 GuiButton 的 LocalScript。

   

   按鈕腳本

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   local button = script.Parent
   button.Activated:Connect(function()
   	-- 觸發可綁定事件，帶有目標輸入上下文和啟用狀態
   	contextEvent:Fire("PlayContext", true)
   end)

顯示綁定

一旦您設置了 動作 和 綁定，您通常需要通過螢幕上的 輔助提示 向玩家顯示觸發每個動作的鍵或按鈕：

輸入動作系統提供了兩種方法：

• 建議

  InputActionLabel — 一個無需編碼的拖放 GuiObject，自動顯示每個平台的正確輸入。
• 中級

  PreferredBinding — 一個只讀的 InputAction 屬性，供希望完全控制如何在自定義 UI 中顯示綁定的創作者使用。

InputActionLabel 是一個 GuiObject，您可以將其插入到任何 ScreenGui 或 SurfaceGui 中。一旦其 InputAction 屬性設置為引用現有的 InputAction 實例，它會自動解析並顯示玩家當前輸入設備的正確鍵綁定 — 無需編碼。當玩家切換設備（例如，在使用鍵盤後拿起遊戲手柄）或重新綁定控制時，標籤會立即更新。

要添加 InputActionLabel：

1. 在 StarterGui 中的 ScreenGui 容器內，像其他 GuiObject 一樣插入一個 InputActionLabel。

2. 在 屬性 窗口中，將其 InputAction 屬性設置為您想要顯示的 InputAction 實例（例如，您在 ReplicatedStorage 下的「衝刺」動作），並根據需要 定位/調整大小。

3. 當標籤解析要顯示的內容時，它會按順序檢查以下內容：

   1. 自定義圖像 — 如果子 InputBindings 的 DisplayImage 屬性已設置，則標籤會直接渲染這些圖像。

   2. 平台鍵圖像 — 如果缺少自定義圖像，則標籤會通過 UserInputService:GetImageForKeyCode() 渲染子 InputBindings 的平台提供的圖像（如果有這些圖像）。組合綁定與修飾符顯示多個圖標，並用 + 分隔。

   3. 自定義名稱 — 如果缺少可用圖像，則如果子 InputBindings 的 DisplayName 屬性已設置，則標籤會使用標籤的樣式屬性渲染該文本。

   4. 平台鍵字符串 — 如果以上所有內容都缺失，則標籤會通過 UserInputService:GetStringForKeyCode() 渲染平台提供的字符串。

   5. 如果未分配任何 InputAction 或不存在子 InputBinding，則標籤會渲染佔位符圖標。

輸入動作管理器

輸入動作管理器 工具是一個統一的矩陣式界面，用於設計、審核和擴展您的輸入架構。

要訪問它，請導航到 Studio 的 窗口 菜單並選擇 輸入 ⟩ 輸入動作管理器。如果您的遊戲已經使用輸入 上下文、動作 或 綁定，管理器將自動掃描 DataModel 並將這些現有實例提取到編輯器網格中。任何新的與輸入相關的實例將自動填充到 ReplicatedStorage 中的 Inputs 資料夾中。

要配置 角色衝刺 的輸入設置，如上面各節所述：

1. 建議

   在 資源管理器 中選擇頂層的 Workspace 對象，然後在 屬性 窗口中，將 PlayerScriptsUseInputActionSystem 屬性設置為 Enabled。

2. 在 StarterGui 的 ScreenGui 容器內創建一個 螢幕按鈕，將其重新命名為 SprintButton，並根據需要 定位/調整大小。

   

3. 在 輸入動作管理器 中，將鼠標懸停在 上下文 列標題上，然後單擊 ＋ 按鈕。輸入新上下文的適當名稱，例如 PlayContext，然後按 Enter。一個匹配名稱的 InputContext 出現在 ReplicatedStorage 中。

   

   

4. 將鼠標懸停在新上下文上，然後單擊 ＋ 按鈕。在彈出菜單中，選擇 Bool，輸入動作的名稱為 CharacterSprint，然後按 Enter。一個匹配名稱的 InputAction 出現在上下文下方。

   

   

5. 在新的 CharacterSprint 行中，為每個輸入類型分配綁定：

   1. 鍵盤和滑鼠 — 單擊箭頭按鈕，從選擇菜單中選擇 LeftShift。
   2. 觸控 — 單擊單元格，然後在 資源管理器 階層中單擊您之前插入的 SprintButton 對象。
   3. 遊戲手柄 — 單擊箭頭按鈕，從選擇菜單中選擇 ButtonY。

   

   當您分配綁定時，請注意 UI 中的警告/錯誤圖標。黃色警告 (⚠) 表示缺少綁定以實現 跨平台 兼容性，而紅色警告 (⚠) 表示在同一上下文中動作的綁定重複。

6. 在 CharacterSprint 樹中插入一個新的 Script，與各種輸入綁定並排。然後將其 RunContext 設置為 Client，並將其重新命名為 OnActivate。

   

7. 將以下代碼粘貼到 OnActivate 腳本中。注意第 13 到 15 行的 Pressed 事件連接，當衝刺輸入綁定被按下時，這會將角色的行走速度加倍，對應的 Released 事件連接在第 16 到 18 行，當衝刺輸入綁定被釋放時，這會將行走速度重置為默認值。

   OnActivate (客戶端腳本)

   local Players = game:GetService("Players")
   
   local player = Players.LocalPlayer
   local character = player.Character
   if not character or character.Parent == nil then
   	character = player.CharacterAdded:Wait()
   end
   local humanoid = character:WaitForChild("Humanoid")
   local defaultWalkSpeed = humanoid.WalkSpeed
   
   local inputAction = script.Parent
   
   inputAction.Pressed:Connect(function()
   	humanoid.WalkSpeed = defaultWalkSpeed * 2
   end)
   inputAction.Released:Connect(function()
   	humanoid.WalkSpeed = defaultWalkSpeed
   end)