Unity InputSystem 自定义输入设备：从物理按钮到一个真正的 InputDevice

做硬件接入、展会互动、模拟驾驶这类项目时，你大概率撞过这个墙：手里明明只有一个物理按钮，Unity的InputSystem却只认识键盘、鼠标、手柄这些“标准货”。硬把按钮映射成空格键当然能跑，但等需求变成“左右各一个物理按钮”“恢复出厂设置键”“防误触长按键”时，逻辑会迅速变得一团糟。更好的解法是：为这个按钮定义一个真正属于它的输入设备。

这次我把自己在实际项目里做自定义InputDevice的完整过程整理出来，以“一个Button”作为最小可运行示例，把涉及的核心概念、状态结构、运行时注册、InputAction绑定和常见坑一次讲清楚。适合已经对InputSystem有基础了解、但还没碰过自定义设备的开发者，也适合准备接入自制外设、串口硬件、展会互动装置的朋友参考。

1. 什么场景下需要自定义InputDevice——先从键盘代偿说起

1.1 一个物理按钮引发的“语义混乱”

先说你最可能遇到的实际场景：产品那边拿来一个USB按钮，硬件上本质是一个串口设备，按下时返回“1”，松开返回“0”。Unity项目要用它控制翻页、确认动作或者触发某个机关。

很多人的第一反应是：让硬件把按钮模拟成键盘按键，然后在InputSystem里监听Key。我一开始也这么干过，但很快就发现了问题。

第一个问题是语义完全丢失。业务代码里到处都是Keyboard.current.spaceKey.wasPressedThisFrame，看代码的人完全不知道这个空格键是“物理红色大按钮”，一个月后你自己看都费劲。

第二个问题是多设备冲突。现场如果同时接了两个按钮，都模拟成空格键，你根本分不清谁是谁。或者展位上有一个工作人员专用按键，做了同样映射，两边就串了。

第三个问题是调试困难。键盘输入经过了系统层和硬件层的多次转换，一旦按键没反应，你很难定位问题出在硬件、驱动、映射脚本还是InputSystem本身。

自定义InputDevice就是为这类问题设计的。它让“一个按钮”成为一个设备，有自己的Layout名字、自己的控件名、自己的事件流。业务代码不关心它背后的硬件是USB还是串口，只需要监听“某个设备上的某个按钮”。

1.2 自定义设备解决的是什么

InputSystem的核心抽象就是设备（Device）、控件（Control）、状态（State）三者。设备是顶层对象，比如键盘、鼠标、手柄；控件是设备上的输入元素，比如按键、摇杆、滚轮；状态是设备上报给系统的原始数据快照。

自定义InputDevice做的事情很简单：告诉InputSystem“我这里有一个新设备，它带一个按钮控件”，然后把按钮的状态实时喂给InputSystem。喂进去之后，剩下的工作全部交给InputSystem的原有机制——InputAction、事件回调、输入调试器都能正常工作。

这带来的好处很明显：

• 语义清晰：业务代码里直接写某设备/某按钮，可读性远高于“把物理键映射成空格”。
• 可扩展：一个设备类可以声明多个Button、Axis、Vector2控件，之后接摇杆、触摸板、旋转编码器都不需要重新设计架构。
• 可调试：Input Debugger窗口能直接看到自定义设备的状态数据，比在驱动层打日志容易多了。
• 可统一：无论硬件是串口、UDP、还是厂商SDK回传的数据，最终都转换成InputSystem的StateEvent，业务层完全无感。

1.3 官方自带设备与自定义设备的边界

不是说所有输入都该自定义设备。对于标准键鼠、手柄、触摸、XR手柄，直接用官方内置设备就行。需要自定义的典型情况是这几类：

一个简单的判断标准：这个输入能不能被InputSystem的“标准设备”自然表达？如果能，就别自己折腾；如果不能，才轮到自定义InputDevice出场。

2. 自定义设备前必须吃透的三角关系：Device、Control、State

2.1 Layout是设备描述的核心

在InputSystem里，每个设备都对应一个Layout。Layout描述了“这个设备长什么样”：它有哪些控件、每个控件的数据类型是什么、控件的数据位在状态结构体的哪个位置。内置设备（Keyboard、Gamepad）用的是系统预制Layout，自定义设备则是你通过C#类定义的。

给设备类加上[InputControlLayout]特性，就是告诉InputSystem：这个类是一个设备Layout。关键参数是stateType，它指向一个实现了IInputStateTypeInfo的状态结构体，这个结构体决定了设备的原始数据结构。

整个过程是反射驱动的：只要你的类在程序集里，并且继承了InputDevice、带[InputControlLayout]特性，InputSystem启动时就会自动注册。这个机制极大简化了自定义流程——你不需要手动写JSON配置。

2.2 状态结构体：与InputSystem签下的内存契约

IInputStateTypeInfo接口要求你提供一个FourCC格式标识，用来唯一标识这个状态类型。InputSystem在处理设备状态时，会拿这个标识做校验，确保StateEvent的数据格式和设备Layout匹配。如果FourCC不一致，事件会被拒绝，这是比较隐蔽的坑。

状态结构体本身就是一个明确内存布局的struct。每个字段代表一块原始数据，字段上通过[InputControl]特性告诉系统该字段对应什么控件。系统内部会为这个结构体计算状态块的偏移、大小、格式，然后映射到控件上。

打个比方：状态结构体像一份合同，写明了“偏移0字节处是按钮数据，占1bit”；[InputControl]特性是批注，标明“这块数据归button控件管”；FourCC是合同编号，保证双方拿的是同一份。

2.3 InputControl特性的关键参数

[InputControl]特性有十几个参数，但实际项目里最常用的就这几个，我直接列个表：

这里重点是Bit和Byte的关系。一个Button在极限情况下只需要1bit就能表示按下/松开，所以很多自定义设备会用一个byte字段，但控件只读取其中1bit。这样做的好处是后面扩展多个按钮时，可以打包在同一个字段里，减少状态结构体体积，也可以直接对应硬件的寄存器位。

2.4 ButtonControl的底层读取逻辑

ButtonControl不是直接返回“按下/松开”两个枚举值，它继承自AxisControl，最终以float的形式返回按键力度。对于数字按钮，读取到的值只有0和1；对于模拟扳机键，读取值会是一个0到1之间的浮点数。

它的状态块格式默认是BIT，也就是说当状态数据是bit位时，ButtonControl能从指定bit位置读取0或1。你不需要自己写任何解析代码，只要在[InputControl]里声明layout是Button，系统就会用ButtonControl的解析逻辑。

这也是为什么自定义InputDevice时，Button是最适合入门的选择：底层逻辑最简单，不涉及信号处理、阈值过滤这类复杂机制。

3. 单Button自定义设备的完整代码与逐段拆解

3.1 先看完整代码

整个最小示例就两个类加一个MonoBehaviour，代码量不大，但每一段都有讲究。我先把完整代码贴出来，再逐段拆。

csharp复制using System.Runtime.InteropServices;
using UnityEngine;
using UnityEngine.InputSystem;
using UnityEngine.InputSystem.Controls;
using UnityEngine.InputSystem.Layouts;
using UnityEngine.InputSystem.LowLevel;
using UnityEngine.InputSystem.Utilities;

[InputControlLayout(stateType = typeof(MyButtonDeviceState), displayName = "My Button Device")]
public class MyButtonDevice : InputDevice
{
    public ButtonControl button { get; private set; }

    protected override void FinishSetup()
    {
        base.FinishSetup();
        button = GetChildControl<ButtonControl>("button");
    }
}

[StructLayout(LayoutKind.Explicit, Size = 1)]
public struct MyButtonDeviceState : IInputStateTypeInfo
{
    public FourCC format => new FourCC('M', 'B', 'T', 'N');

    [FieldOffset(0)]
    [InputControl(name = "button", layout = "Button", format = "BIT", sizeInBits = 1, bit = 0)]
    public byte button;
}

然后是负责设备生命周期和状态上报的MonoBehaviour：

csharp复制public class ButtonDeviceHub : MonoBehaviour
{
    private MyButtonDevice _device;

    private void OnEnable()
    {
        _device = InputSystem.AddDevice<MyButtonDevice>();
    }

    private void OnDisable()
    {
        if (_device != null)
        {
            InputSystem.RemoveDevice(_device);
            _device = null;
        }
    }

    private void Update()
    {
        if (_device == null)
            return;

        // 这里替换成你自己的硬件读取逻辑
        bool pressed = MyExternalHardware.ReadButton(0);
        var state = new MyButtonDeviceState
        {
            button = pressed ? (byte)1 : (byte)0
        };
        InputSystem.QueueStateEvent(_device, state);
    }
}

public static class MyExternalHardware
{
    public static bool ReadButton(int index)
    {
        // 模拟：你可以在这里读串口、读UDP、读厂商SDK
        return false;
    }
}

3.2 设备类为什么必须重写FinishSetup

FinishSetup是InputSystem创建设备内部控件树时调用的回调。在基类完成控件创建后，我们需要把自己关心的控件引用保存下来，方便后续直接访问。

注意两个关键点：第一，一定要先调用base.FinishSetup()，否则控件还没创建；第二，GetChildControl<ButtonControl>("button")里的名字必须和[InputControl]特性里的name一致，拼错一个字符就返回null。

这里我习惯用只读属性暴露控件，而不是public字段，这样外部代码只能读取控件，不能随意给设备状态赋值，减少出错的可能。

3.3 状态结构体为什么用StructLayout.Explicit

StructLayout(LayoutKind.Explicit)表示结构体的每个字段都显式指定偏移。自定义设备状态结构体的内存布局必须稳定，因为InputSystem会按照这个布局去解释收到的二进制数据。如果让编译器自动布局，不同版本、不同平台的字段偏移可能不同，状态解析就会错位。

在单按钮例子里，我们用[FieldOffset(0)]把button字段放在第0字节，整个结构体大小固定为1字节。结构体越小，每个状态事件的数据量就越小，性能开销也越低。

3.4 控件声明与设备结构的关系

状态结构体里写[InputControl(name = "button", layout = "Button", format = "BIT", sizeInBits = 1, bit = 0)]，这行声明做了三件事：

• 把状态结构体的第0bit映射到名为"button"的控件；
• 指定这个控件用Button的Layout规则解析；
• 声明这个控件的数据块是1个bit。

当设备创建时，InputSystem会读取这个特性，在设备内部建立一个名为button的ButtonControl子控件。设备类里GetChildControl<ButtonControl>("button")拿到的就是它。

3.5 多种注册方式的取舍

添加自定义设备有三种常见方式，我实际用过前两种：

csharp复制// 方式一：泛型方式，最简洁
_device = InputSystem.AddDevice<MyButtonDevice>();

// 方式二：注册Layout后再添加
InputSystem.RegisterLayout<MyButtonDevice>();
_device = (MyButtonDevice)InputSystem.AddDevice(new InputDeviceDescription
{
    product = "MyButtonDevice"
});

// 方式三：使用InputDeviceBuilder，适合动态组合Layout

方式一适合绝大多数项目，代码最少。方式二适合需要在运行时决定是否注册、或需要在不同平台注册不同设备的情况。方式三偏进阶，适合完全动态构建设备的场景，日常项目用不上。

如果你遇到“类定义了但AddDevice找不到Layout”的情况，大概率是代码裁剪或程序集扫描问题。可以在静态构造函数或[RuntimeInitializeOnLoadMethod]里手动调用一次InputSystem.RegisterLayout<MyButtonDevice>()：

csharp复制[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
private static void Register()
{
    InputSystem.RegisterLayout<MyButtonDevice>();
}

4. 状态上报：让物理按钮变成InputAction可识别的输入

4.1 状态事件是怎么流动的

InputSystem里设备状态不是直接“写”到设备上的，而是通过事件队列传递。调用InputSystem.QueueStateEvent(_device, state)时，系统会创建一个StateEvent对象，里面包含了设备ID、状态格式FourCC和实际数据，然后把这个事件投递到全局输入事件队列。

在下一帧的输入系统更新阶段，这些事件会被逐一处理，更新对应设备的状态。处理完成后，InputSystem会触发状态变更通知，进而驱动InputAction的performed、canceled回调。

这个机制保证了多设备、多线程环境下状态的一致性。你不应该直接修改设备的内部状态内存，而是通过事件队列上报。

4.2 为什么要在Update里持续发送状态

我的示例代码里，Update中每帧都发送一次完整状态，即使按钮状态没变化也发。这是一种相对保守但很可靠的做法。

优点有两个：一是逻辑简单，不需要检测“从按下变松开”或“从松开变按下”的边沿，只要把当前状态发出去，InputSystem自己会判断变化；二是能应对外部硬件掉线重连的情况，状态恢复后下一帧就自动拉回正确值。

缺点是每帧都产生一次状态事件，对于单按钮设备来说开销可以忽略。如果你未来做的是一个8轴、20按钮的高频设备，可以考虑只在状态变化时发送，但那是优化阶段的事，不必一开始就做。

4.3 让InputAction能绑定到自定义设备

设备创建好、状态持续上报之后，怎么让业务代码接收按钮事件？两种方式都行：直接轮询控件，或者用InputAction绑定。

直接轮询控件的代码比较朴素：

csharp复制public class ButtonTester : MonoBehaviour
{
    private void Update()
    {
        MyButtonDevice device = InputSystem.GetDevice<MyButtonDevice>();
        if (device != null && device.button.wasPressedThisFrame)
        {
            Debug.Log("物理按钮被按下");
        }
    }
}

这种方式适合快速验证设备是否工作，但不适合正式项目，因为业务逻辑和设备类型耦合了。更好的方式是InputAction：

csharp复制public class ButtonActionTester : MonoBehaviour
{
    private InputAction _pressAction;

    private void OnEnable()
    {
        _pressAction = new InputAction(
            name: "PhysicalButton",
            type: InputActionType.Button,
            binding: "<MyButtonDevice>/button");

        _pressAction.performed += ctx => Debug.Log("按钮被按下");
        _pressAction.Enable();
    }

    private void OnDisable()
    {
        _pressAction?.Dispose();
        _pressAction = null;
    }
}

binding路径<MyButtonDevice>/button里的MyButtonDevice就是Layout的名字。它默认取自类名，所以如果你改了[InputControlLayout(layoutName = "...")]，这里也要跟着改，这是常见的坑之一。

4.4 设备生命周期管理

设备的添加和移除要保证成对出现。我在OnEnable里添加设备，在OnDisable里移除设备，这样能避免场景切换或脚本失活时设备残留。

一个常见的错误是设备在场景卸载后仍然存在，下次进入场景又重复添加。这时InputSystem的设备列表里会有多个同名设备，InputAction的binding路径可能匹配到其中一个，行为变得不可预测。

如果你的设备是全局唯一的，可以考虑把添加动作放到[RuntimeInitializeOnLoadMethod]里，而不是挂在某个场景对象上。这样设备生命周期和游戏流程一致，不会因为场景切换而丢失。

5. 踩坑与扩展：从单按钮到多按钮的实践锦囊

5.1 FourCC冲突与设备识别

FourCC是四个字符的标识，用来识别状态类型。官方设备使用的FourCC有"KBD"、"MSE"、"GPD"等，自定义设备只要不撞车就行。

我习惯用项目缩写加功能缩写，比如"MBTN"代表MyButton。如果还是担心冲突，可以在调试时打印设备的layout和state格式，在Input Debugger里能看到设备当前使用的FourCC。真冲突了系统会报格式错误事件，按日志提示改掉就好。

5.2 控件读不到值的排查套路

如果你发现自定义设备的button永远读不到值，优先检查这几个地方：

其中“bit参数超出字段位宽”这个坑比较容易踩。比如一个byte字段只有8bit，你却写了bit=9，InputSystem不会在编译期报错，但运行时该控件读到的数据永远是0。

5.3 多按钮设备如何优化状态结构

单按钮示例是入门，实际项目里往往是一排按钮。这时用bit位打包的收益就显现了。假设有8个按钮，我习惯这样定义状态结构体：

csharp复制[StructLayout(LayoutKind.Explicit, Size = 1)]
public struct MyButtonPanelState : IInputStateTypeInfo
{
    public FourCC format => new FourCC('M', 'B', 'P', 'N');

    [FieldOffset(0)]
    [InputControl(name = "button0", layout = "Button", bit = 0)]
    [InputControl(name = "button1", layout = "Button", bit = 1)]
    [InputControl(name = "button2", layout = "Button", bit = 2)]
    [InputControl(name = "button3", layout = "Button", bit = 3)]
    [InputControl(name = "button4", layout = "Button", bit = 4)]
    [InputControl(name = "button5", layout = "Button", bit = 5)]
    [InputControl(name = "button6", layout = "Button", bit = 6)]
    [InputControl(name = "button7", layout = "Button", bit = 7)]
    public byte buttons;
}

这样8个按钮只占1字节，状态事件体积非常小。设备类里则写8个ButtonControl属性，每个都从状态里读自己那个bit。如果硬件本身就是把多个按键打包在一个寄存器字节里的，这种布局几乎和硬件一一对应。

但要注意：一个字段塞太多控件后，代码可读性会下降。我一般超过4个按钮就拆成两个byte字段，或者用uint字段，根据硬件实际情况来定，不必强行追求最小体积。

5.4 IL2CPP打包时的Layout注册问题

开发阶段在Editor里一切正常，但打包Android/iOS后自定义设备没了，这是典型的IL2CPP代码裁剪问题。InputSystem靠反射扫描程序集，而IL2CPP在裁剪模式下可能把未被引用的类型移除，导致Layout丢失。

解决办法有几种：

• 在场景里保留一个对该类型的引用，比如设备的MonoBehaviour里持有一个_device字段；
• 或者在[RuntimeInitializeOnLoadMethod]里手动RegisterLayout；
• 更保险的是加[Preserve]特性：

csharp复制[Preserve]
[InputControlLayout(stateType = typeof(MyButtonDeviceState), displayName = "My Button Device")]
public class MyButtonDevice : InputDevice
{
    // ...
}

UnityEngine.Scripting.Preserve命名空间下的这个特性能阻止裁剪器处理这个类型。发布前最好用Development Build测试一遍，别等用户反馈才查。

5.5 关于按下和松开事件的边界

ButtonControl默认的pressPoint是0.5，也就是读取值大于等于0.5算按下。我们的bit数据只有0和1，天然满足。但如果未来换成模拟按钮，读取值可能在0.3附近抖动，就需要设置pressPoint参数：

csharp复制[InputControl(name = "button", layout = "Button", format = "BIT", sizeInBits = 1, bit = 0, parameters = "pressPoint=0.5")]
public byte button;

parameters参数可以直接传给控件的构造参数，很多内置控件都支持这种注入方式。这是我在踩过模拟按钮误触发后才注意到的细节，文档里不容易一眼看到。

5.6 Editor调试与远程设备

Input Debugger面板（Window > Analysis > Input Debugger）是排查自定义设备问题的利器。打开后能看到所有设备列表、每个设备当前的控件状态和值。如果你的自定义设备已经注册成功，这里会显示设备名，并且button的值会随着你发送的状态实时变化。

如果设备没出现在列表里，说明Layout注册或设备Add环节有问题；如果设备在但值不变，说明状态事件没送到。这个二分定位法能省下大量猜测时间。

另外，InputSystem.onDeviceChange事件也可以用来调试设备的生命周期：

csharp复制InputSystem.onDeviceChange += (device, change) =>
{
    if (device is MyButtonDevice)
        Debug.Log($"{change}: {device}");
};

这个回调在设备添加、移除、断开、重新连接时都会触发，适合验证设备生命周期是否正常。

回到开头那个物理按钮的问题。在我看来，自定义InputDevice的意义不只是让一个按钮能被Unity识别，而是让项目里每个输入源都有明确的身份和语义。单按钮是练习成本最低的切入点，等你把这个流程跑通，后面接多按钮面板、模拟摇杆、串口传感器就都顺理成章了。我自己做完这个示例之后，最大感受是：InputSystem的自定义能力并没有想象中那么复杂，它只是把“设备描述”和“状态上报”这两件事拆得足够清楚，你按这个思路走，就不会迷路。