unity-input-system

Unity 输入系统（新）

通过 Unity 的 Input System package（com.unity.inputsystem，1.x）读取输入 — 基于操作、不依赖设备且可重新绑定。面向 Unity 6.3 LTS。这是对旧版 Input.GetAxis/Input.GetKey Input Manager 的现代替代方案。

适用场景

• 设置移动／跳跃／开火输入、定义包含操作映射和控制方案的 .inputactions 资源、配置 PlayerInput 组件、读取 Vector2 摇杆／WASD 值，或使用同一组操作处理手柄、键盘和触控输入时。
• Packages/manifest.json 中包含 com.unity.inputsystem，或项目中有 *.inputactions 资源时。

不适用场景： 跨引擎的可重新绑定控制架构 → input-systems（此技能介绍的是 Unity 专用 API）。已有输入向量后移动角色 → unity-physics / unity-csharp-scripting。

核心工作流

1. 检查 Active Input Handling（Project Settings → Player）。只有将其设为 Input System Package (New) 或 Both 时，该程序包才会接收输入。如果仍有旧版 Input.GetAxis 代码，则必须设为 Both。
2. 创建 .inputactions 资源。 添加一个操作映射（例如 Gameplay），添加操作（Move = Value/Vector2，Jump = Button，Fire = Button），并将它们绑定到控件和复合绑定（WASD = 2D Vector 复合绑定）。
3. 选择读取方式：
   • PlayerInput 组件（方便设计人员使用）— 将它添加到玩家对象上，指定资源，并选择一个行为（Send Messages / Broadcast / Invoke Unity Events / Invoke C# Events）。最适合单人／本地合作玩家。
   • 在代码中直接读取（InputActionReference / InputActionAsset）— 控制力最强；需要调用 Enable() 启用操作并读取其值。最适合系统和工具。
4. 启用要读取的操作／映射。 PlayerInput 会自动启用其默认映射；自行引用的操作必须调用 .Enable()（并在清理时禁用）。
5. 根据上下文切换操作映射（游戏玩法 ↔ UI／菜单），而不是在每个处理函数中添加条件判断。
6. 验证：使用 Input Debugger（Window → Analysis → Input Debugger）确认设备正常，并检查操作是否触发。

模式

1. 使用“Send Messages”的 PlayerInput（处理函数位于同一个 GameObject 上）

using UnityEngine;
using UnityEngine.InputSystem;

// PlayerInput (Behavior = Send Messages) calls On<ActionName>(InputValue) by name.
public class PlayerInputReceiver : MonoBehaviour
{
    private Vector2 _move;

    private void OnMove(InputValue value) => _move = value.Get<Vector2>();   // Move action
    private void OnJump(InputValue value) { if (value.isPressed) Jump(); }   // Button action

    private void Update() { /* drive movement from _move */ }
    private void Jump() { }
}

2. 在代码中直接读取操作（轮询值）

using UnityEngine;
using UnityEngine.InputSystem;

public class DirectMover : MonoBehaviour
{
    [SerializeField] private InputActionReference moveAction;  // assign the Move action

    private void OnEnable()  => moveAction.action.Enable();    // REQUIRED or it reads zero
    private void OnDisable() => moveAction.action.Disable();

    private void Update()
    {
        Vector2 move = moveAction.action.ReadValue<Vector2>(); // continuous value
        transform.Translate(new Vector3(move.x, 0, move.y) * (5f * Time.deltaTime));
    }
}

3. 事件回调与切换操作映射（游戏玩法 ↔ UI）

[SerializeField] private InputActionAsset actions;

private void OnEnable()
{
    actions.FindAction("Gameplay/Fire").performed += OnFire;  // edge event: fires once
    actions.FindActionMap("Gameplay").Enable();
}
private void OnDisable() => actions.FindAction("Gameplay/Fire").performed -= OnFire;

private void OnFire(InputAction.CallbackContext ctx) => Shoot();  // ctx.ReadValue<T>() if needed

private void OpenPauseMenu()                       // change context, don't sprinkle if-checks
{
    actions.FindActionMap("Gameplay").Disable();
    actions.FindActionMap("UI").Enable();
}
private void Shoot() { }

常见问题

• 完全没有输入 → Active Input Handling 仍为 Input Manager (Old)，或者忘记调用 Enable() 启用操作／映射。PlayerInput 会自动启用；原始 InputAction 不会。
• 出现有关旧输入后端的 InvalidOperationException → 某个脚本仍在 Active Input Handling 设为 New 时调用 Input.GetAxis/Input.GetKey。迁移代码或将其设为 Both。
• 通过 ReadValue 读取按钮时结果为 0 → 按钮按下属于边沿事件；应使用 performed 回调（或 WasPressedThisFrame()），不要每帧通过 ReadValue 读取触发器。
• Send Messages 处理函数从不触发 → 接收脚本必须与 PlayerInput 位于同一个 GameObject 上；Broadcast Messages 也会发送到子对象。
• 订阅未清理 → 在 OnDisable 中取消订阅（-=）；在未取消订阅的情况下于 OnEnable 中重新订阅会导致处理函数重复。
• 未检测到触控／手柄 → 启用对应的控制方案，并在 Input Debugger 中确认设备；Vector2 复合绑定需要设置全部四个绑定。

参考资料

• 有关交互式控制重新绑定（PerformInteractiveRebinding）、以 JSON 格式保存／加载绑定，以及使用 PlayerInputManager 实现本地多人游戏，请阅读 references/rebinding.md。
• 主要文档：Unity Manual“Input System” （https://docs.unity3d.com/Manual/com.unity.inputsystem.html）。

相关技能

• input-systems — 与引擎无关的输入架构（重新绑定、缓冲、多设备）。
• unity-csharp-scripting — 这些处理程序所在的 MonoBehaviour。
• unity-physics — 将输入向量应用于 Rigidbody。