IInputAction

重要 注意 提醒

Coding Style wiki

---

IInputAction 是 InputSystem 的輸入行為介面 (通用訊號派送者)：實作者負責將 Unity New InputSystem 或其他輸入控制插件的輸入轉換為 C# 事件進行派送，讓遊戲中的控制邏輯只需訂閱事件，不需知道平台裝置區分；透過 Inputs.IA.RegisterInputAction 註冊、Inputs.IA.DriveUpdate 驅動。

命名空間	OxGKit.InputSystem
類型	public interface IInputAction
原始碼	IInputAction.cs

using OxGKit.InputSystem;

快速上手

using System;
using OxGKit.InputSystem;
using UnityEngine;
using UnityEngine.InputSystem;

public class PlayerAction : IInputAction
{
    // 自定義輸入事件 (由訂閱者訂閱)
    public event Action<Vector2> onMove;

    public void OnCreate()
    {
        // 註冊時進行事件綁定 (以 Unity New InputSystem 為例)
        var ctrls = Inputs.CM.GetControlMap<PlayerControls>();
        if (ctrls == null) return;
        ctrls.Player.Move.performed += this._OnMove;
        ctrls.Player.Move.canceled += this._OnMove;
    }

    public void OnUpdate(float dt)
    {
        // 可選的輪詢式輸入檢測 (由 Inputs.IA.DriveUpdate 驅動)
    }

    public void RemoveAllListeners()
    {
        this.onMove = null;
    }

    private void _OnMove(InputAction.CallbackContext ctx)
    {
        // 重新派送為遊戲層級的輸入訊號
        this.onMove?.Invoke(ctx.ReadValue<Vector2>());
    }
}

通用規則

生命週期

1. OnCreate：由 RegisterInputAction 註冊時自動呼叫一次，於此綁定 Control Map 或初始其他輸入插件。
2. OnUpdate：由 DriveUpdate 每幀驅動，用於輪詢式輸入檢測 (可留空實作)。
3. RemoveAllListeners：需自行於適當時機呼叫 (例如場景轉換或功能退場)，清除所有已訂閱事件。

注意 遊戲/功能程式碼應只訂閱 IInputAction 派送的事件，避免在專案中散落原生 InputAction 的直接讀取，才能維持控制邏輯與平台裝置解耦。

提醒 功能退場時記得退訂事件；場景/Domain 轉換時可呼叫 RemoveAllListeners() 清除訂閱，避免殘留過期委派 (stale delegates)。

方法總覽

方法	說明
OnCreate	註冊時呼叫 (於此綁定 Control Map 或插件輸入)。
OnUpdate	每幀輪詢 (由 Inputs.IA.DriveUpdate 驅動)。
RemoveAllListeners	清除所有已訂閱事件。

---

OnCreate

void OnCreate()

由 Inputs.IA.RegisterInputAction 註冊時自動呼叫，通常於此透過 Inputs.CM.GetControlMap 取得控制表進行事件綁定，或初始其他輸入插件的訊號來源。

重要 若於 OnCreate 取得 Control Map，必須先註冊該 Control Map，否則 GetControlMap 會回傳 null，導致綁定被靜默略過。

OnUpdate

void OnUpdate(float dt)

由 Inputs.IA.DriveUpdate 每幀驅動 (傳入 dt)，可於此進行輪詢式輸入檢測 (例如非事件型插件的輸入取樣)；若無輪詢需求可留空實作。

RemoveAllListeners

void RemoveAllListeners()

清除所有已訂閱的事件 (將事件設為 null)，需自行於適當時機呼叫 (例如場景轉換或功能退場)。

Inputs.IA.GetInputAction<PlayerAction>().RemoveAllListeners();

---

腳本模板

Template Input Action.cs

透過 Right-Click Create/OxGKit/Input System/Template Input Action.cs (Input Interface For Any) 快速建立 IInputAction 實作腳本 (通用訊號派送者，可自由實作任何輸入來源)。

建立後的啟用流程 (於遊戲開始時)：

1. (若使用 Unity New InputSystem) 先以 Inputs.CM.RegisterControlMap 註冊控制表。
2. 以 Inputs.IA.RegisterInputAction 註冊 Input Action (自動觸發 OnCreate 進行事件綁定)。
3. 由主迴圈 (Main MonoBehaviour) 呼叫 Inputs.IA.DriveUpdate(dt) 驅動更新 (完整範例參考模塊介紹)。

Template Input Binding Composite.cs

透過 Right-Click Create/OxGKit/Input System/New Input System (Extension)/Template Input Binding Composite.cs (For Unity New Input System) 建立 Unity New InputSystem 的 Binding Composite 腳本，將多個輸入部件合成單一自定義輸入值 (例如「修飾鍵 + 方向鍵」合成移動輸入)：

• 模板繼承 InputBindingComposite<TValue> 並定義自定義值結構 (struct)。
• 透過 [InputControl(layout = "...")] 宣告組合部件 (Button / Integer / Vector2 / Axis)。
• 於 ReadValue 中讀取各部件數值，運算後回傳自定義值。
• 透過 [InitializeOnLoad] (Editor) 與 [RuntimeInitializeOnLoadMethod] 觸發靜態建構子執行 InputSystem.RegisterBindingComposite 自動註冊。

建立後的啟用流程：

1. 模板的靜態建構子會於啟動時自動註冊 (InputSystem.RegisterBindingComposite)，無需手動呼叫。
2. 開啟 Input Action Asset，對目標 Action Add Binding，於 Composite 清單中選擇你的自定義 Composite 並指派各部件按鍵。
3. 於 Input Action 的事件回呼中以 context.ReadValue 讀取自定義值 (如下例)。

// 於 Input Action 的事件回呼中讀取自定義 Composite 值 (以 Demo 的 MoveInputComposite 為例)
protected void OnMoveAction(InputAction.CallbackContext context)
{
    // Read your composite values
    var moveInput = context.ReadValue<MoveInputComposite.MoveInput>();
    this.onMoveAction?.Invoke(moveInput);
}

提醒 Composite 必須在綁定首次使用前完成註冊；若要於 Input Action Asset 編輯器中顯示，需由 Edit Mode 執行的程式碼註冊。完整範例可參考 Samples InputSystem Demo 的 MoveInputComposite 與 PlayerControls.inputactions。