输入系统 · 架构解析

源设计起源 · 为什么要做这个模块

• 先说清边界：它是通用输入，不是帧同步输入：帧同步那套要求输入变成可序列化的帧命令、精度量化成整数、按帧号算节拍，还要 seq + 确认 + 补发；通用项目没有那个同步层，本地输入也没有丢包，照搬只会凭空多出间接层和纯成本。可复用的是"机制"（设备抽象、采集与判定分离、零分配、手感参数化），不可复用的是"为确定性付出的代价"。
• 没有它，每处输入都要自己处理一堆杂事：改键、屏蔽、缓冲、多指抢占、切后台复位……全都散在业务里。本模块把它们收进一个内核，业务只认动作名、不认键位（改键 / 屏蔽 / 缓冲都在同一个抽象上做，业务代码里没有键位字面量）。
• 参考实现缺什么，这里就补什么：键盘 / 鼠标支持、多点触控的 id 出口、多种手势 + 八向滑动、输入缓冲窗口、失焦 / 切后台复位、可精确到指针的屏蔽栈、可断言的内核、绑定文本往返 + 冲突检测。
• 为什么坚持纯 C# 内核 + 热路径零分配：死区、双击窗口、滑动阈值、多指抢占这些"最容易写错"的手感参数必须能脱机断言；而输入是逐帧热路径，零分配是硬指标，所以就地 try/catch、不传 lambda（否则每次都要分配一个闭包）。

本篇只讲为什么；怎么用见同目录《使用说明》。

0三句话速览（完整用法见《使用说明》）

① 绑定     RevInput.Bind("Jump", RevKey.Space, RevKey.JoystickButton0);   // 业务只认动作名，不认键位
② 订阅     RevInput.OnPressed("Jump", Jump, owner: this);               // 或 AddListener(this) 一次收全部
③ 退订     RevInput.OffAllOf(this);                                    // 事件 + 屏蔽一起清

就这三步。剩下的都是这三步背后的设计取舍。

1定位：通用输入系统，不是帧同步输入

先说清边界，否则后面每条设计都会被问"为什么不按帧同步那套来"。

2分层与文件地图

RevInput/
├── Core/            纯 C#（零引擎依赖，可脱机断言）
│   ├── RevInputDefines    词汇表：设备类型 / 相位 / 手势 / 屏蔽 / 错误码 / 全部默认值
│   ├── RevInputCodes      键位码表（名字对齐 Unity KeyCode）+ RevKeyMask（零分配键位掩码）
│   ├── RevInputSnapshot   一帧快照：键位三份掩码 + 鼠标 + 指针数组（复用实例，零分配）
│   ├── RevInputBinding    一个动作的绑定（键位 / 鼠标键 / 轴）+ 预计算掩码
│   ├── RevInputActionTable 绑定表 + 全部动作状态（三态 / 轴 / 连发 / 缓冲 / 文本往返 / 冲突检测）
│   ├── RevGestureRecognizer 7 种手势的识别状态机（阈值全可调）
│   ├── RevInputBlock      屏蔽句柄
│   └── RevInputListener   事件驱动接入面：监听者接口 + 空实现基类（登记一次，输入推给你）
├── Facade/RevInput   唯一入口（业务只读这个）
├── Implementation/
│   ├── RevInputCore  内核：一帧的流水线 + 屏蔽栈 + 事件派发 + 失败上报
│   └── RevInputLog   日志出口（正常路径一条不打）
└── Support/          引擎适配（全模块唯一碰 UnityEngine 的地方）
    ├── RevInputDriver        隐藏宿主：每帧采集 + 失焦/切后台自动复位
    ├── RevInputUnityDevice   默认设备：键鼠 / 触屏 / 手柄 → 快照
    ├── RevInputUnityHooks    进 Play 复位 / 日志接线 / UI 命中判定
    └── RevInputScope         作用域：出块自动解除屏蔽 + 退订事件

3一帧到底做了什么

顺序上有三个刻意安排：

• 相位先算、事件后派：事件回调里读到的状态和业务在同一帧读到的一致（不会"回调里读到的是上一帧"）；
• 屏蔽判定在采集之后、判定之前：被屏蔽时设备照样采集（指针位置可读），但动作相位与手势按"无输入"处理；
• 事件驱动与轮询同帧同源：监听者、OnPressed 这类委托、轮询 API 读的是同一份状态；而 ⑦⑧⑨ 在"没有订阅者 / 没有监听者"时提前 return，零开销（不影响逐帧性能）。

4十一个关键设计决策

5与参考实现的对照

参考实现是一套为帧同步设计的输入体系（分层清晰、手感观测做得很扎实）。这里逐条说明"借鉴了什么 / 为什么没搬 / 补了什么"。

5.1 借鉴过来的机制

5.2 刻意没有搬过来的

5.3 参考实现缺、本模块补上的（这类最多）

6验收（都是跑出来的）

7本期没做的（可扩展）