11

2026-05-16 13:37:04 +08:00
parent 6c13817527
commit 87c4a56306
6 changed files with 1933 additions and 1 deletions
--- a/实现/输入设备控制/游戏手柄输入处理.md
+++ b/实现/输入设备控制/游戏手柄输入处理.md
@@ -0,0 +1,428 @@
+# 游戏手柄输入处理
+
+<cite>
+**本文档引用的文件**
+- [gamepadhandler.js](file://client/src/gamepadhandler.js)
+- [inputdevice.js](file://client/src/inputdevice.js)
+- [inputremoting.js](file://client/src/inputremoting.js)
+- [gamepadbutton.js](file://client/src/gamepadbutton.js)
+- [memoryhelper.js](file://client/src/memoryhelper.js)
+- [keymap.js](file://client/src/keymap.js)
+- [mousebutton.js](file://client/src/mousebutton.js)
+- [touchflags.js](file://client/src/touchflags.js)
+- [touchphase.js](file://client/src/touchphase.js)
+- [gamepadEvents.js](file://client/public/videoplayer/js/gamepadEvents.js)
+- [register-events.js](file://client/public/videoplayer/js/register-events.js)
+- [index.html](file://client/public/videoplayer/index.html)
+- [inputdevice.test.js](file://client/test/inputdevice.test.js)
+- [inputremoting.test.js](file://client/test/inputremoting.test.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向需要在浏览器中实现高质量游戏手柄输入处理的开发者，系统性阐述从设备枚举、事件捕获、状态转换到远端传输的完整链路。文档重点覆盖以下方面：
+- 游戏手柄事件处理机制：摇杆值、按钮状态、触发器事件的捕获与转发
+- 设备识别、枚举与状态同步
+- 输入校准、死区处理与输入平滑算法
+- 不同厂商手柄差异的兼容策略
+- 连接状态监控与输入延迟优化
+
+## 项目结构
+客户端采用模块化设计，围绕输入设备抽象、状态序列化与消息封装展开，并在视频播放示例中集成手柄事件监听与发送。
+
+```mermaid
+graph TB
+subgraph "输入设备层"
+ID["InputDevice 抽象类"]
+GP["Gamepad 手柄设备"]
+KB["Keyboard 键盘设备"]
+MS["Mouse 鼠标设备"]
+TS["Touchscreen 触摸屏设备"]
+end
+subgraph "状态模型层"
+GS["GamepadState 状态"]
+KS["KeyboardState 状态"]
+MS["MouseState 状态"]
+TSS["TouchscreenState 状态"]
+end
+subgraph "消息与传输层"
+SE["StateEvent 状态事件"]
+NE["NewEventsMsg 新事件消息"]
+ND["NewDeviceMsg 新设备消息"]
+RM["InputRemoting 远程输入管理"]
+end
+subgraph "浏览器接口层"
+GH["GamepadHandler 扫描器"]
+GE["gamepadEvents.js 事件桥接"]
+RE["register-events.js 事件注册"]
+end
+ID --> GP
+ID --> KB
+ID --> MS
+ID --> TS
+GP --> GS
+KB --> KS
+MS --> MS
+TS --> TSS
+GS --> SE
+SE --> NE
+ID --> ND
+RM --> NE
+RM --> ND
+GH --> GP
+GE --> GP
+RE --> GE
+```
+
+**图表来源**
+- [inputdevice.js:40-127](file://client/src/inputdevice.js#L40-L127)
+- [inputremoting.js:63-169](file://client/src/inputremoting.js#L63-L169)
+- [gamepadhandler.js:1-45](file://client/src/gamepadhandler.js#L1-L45)
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [register-events.js:1-101](file://client/public/videoplayer/js/register-events.js#L1-L101)
+
+**章节来源**
+- [inputdevice.js:1-719](file://client/src/inputdevice.js#L1-L719)
+- [inputremoting.js:1-300](file://client/src/inputremoting.js#L1-L300)
+- [gamepadhandler.js:1-45](file://client/src/gamepadhandler.js#L1-L45)
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [register-events.js:1-101](file://client/public/videoplayer/js/register-events.js#L1-L101)
+
+## 核心组件
+- GamepadHandler：基于 requestAnimationFrame 的周期性扫描与分发，维护控制器索引映射并派发自定义 gamepadupdated 事件。
+- Gamepad/InputDevice：输入设备抽象与手柄状态队列，将事件转换为 GamepadState。
+- GamepadState：将摇杆、触发器与按钮状态打包为二进制缓冲区，包含固定格式标识与字段布局。
+- MemoryHelper：位级写入工具，用于将布尔型按钮状态压缩到字节数组。
+- InputRemoting：订阅本地输入事件，生成设备与事件消息并通过观察者推送。
+- NewEventsMsg/NewDeviceMsg：消息封装，承载设备描述与状态数据。
+- 浏览器事件桥接：gamepadEvents.js 与 register-events.js 将原生 Gamepad API 事件转换为统一格式并发送。
+
+**章节来源**
+- [gamepadhandler.js:1-45](file://client/src/gamepadhandler.js#L1-L45)
+- [inputdevice.js:120-127](file://client/src/inputdevice.js#L120-L127)
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+- [memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+- [inputremoting.js:63-169](file://client/src/inputremoting.js#L63-L169)
+- [inputremoting.js:258-277](file://client/src/inputremoting.js#L258-L277)
+- [inputremoting.js:234-256](file://client/src/inputremoting.js#L234-L256)
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [register-events.js:1-101](file://client/public/videoplayer/js/register-events.js#L1-L101)
+
+## 架构总览
+下图展示了从浏览器手柄事件到远端传输的关键流程，包括事件桥接、状态序列化与消息封装。
+
+```mermaid
+sequenceDiagram
+participant Browser as "浏览器"
+participant GH as "GamepadHandler"
+participant GE as "gamepadEvents.js"
+participant RE as "register-events.js"
+participant ID as "InputDevice/Gamepad"
+participant GS as "GamepadState"
+participant RM as "InputRemoting"
+participant NE as "NewEventsMsg"
+Browser->>GH : "requestAnimationFrame 循环"
+GH->>GH : "_scanGamepad() 枚举并更新控制器"
+GH-->>Browser : "gamepadupdated 事件"
+Browser->>GE : "原生 Gamepad 事件"
+GE->>RE : "统一格式事件按钮/轴"
+RE->>ID : "queueEvent(event)"
+ID->>GS : "构造 GamepadState"
+GS-->>RM : "StateEvent.from(device)"
+RM->>NE : "NewEventsMsg.create(state)"
+NE-->>Browser : "通过观察者推送"
+```
+
+**图表来源**
+- [gamepadhandler.js:22-42](file://client/src/gamepadhandler.js#L22-L42)
+- [gamepadEvents.js:68-94](file://client/public/videoplayer/js/gamepadEvents.js#L68-L94)
+- [register-events.js:42-101](file://client/public/videoplayer/js/register-events.js#L42-L101)
+- [inputdevice.js:120-127](file://client/src/inputdevice.js#L120-L127)
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+- [inputremoting.js:138-141](file://client/src/inputremoting.js#L138-L141)
+- [inputremoting.js:258-277](file://client/src/inputremoting.js#L258-L277)
+
+## 详细组件分析
+
+### 组件一：GamepadHandler（设备扫描与事件派发）
+- 职责：维护控制器映射表，周期性调用 _scanGamepad 更新控制器快照，遍历控制器并派发 gamepadupdated 事件。
+- 关键点：
+  - 使用 window.requestAnimationFrame 驱动循环，避免阻塞主线程。
+  - 通过 navigator.getGamepads() 获取实时控制器集合，按索引覆盖旧状态。
+  - 自定义事件类型 gamepadupdated，便于上层统一处理。
+
+```mermaid
+flowchart TD
+Start(["进入 _updateStatus"]) --> Scan["_scanGamepad() 枚举控制器"]
+Scan --> Loop{"遍历控制器"}
+Loop --> |存在| Dispatch["派发 gamepadupdated 事件"]
+Loop --> |不存在| NextFrame["requestAnimationFrame 下次循环"]
+Dispatch --> NextFrame
+NextFrame --> Start
+```
+
+**图表来源**
+- [gamepadhandler.js:22-42](file://client/src/gamepadhandler.js#L22-L42)
+
+**章节来源**
+- [gamepadhandler.js:1-45](file://client/src/gamepadhandler.js#L1-L45)
+
+### 组件二：Gamepad 与 GamepadState（状态建模与序列化）
+- Gamepad：继承 InputDevice，将事件队列转换为 GamepadState。
+- GamepadState：
+  - 字段：buttons（4字节位图）、leftStick、rightStick（每项浮点）、leftTrigger、rightTrigger（浮点）。
+  - 使用 MemoryHelper 将布尔型按钮状态写入位图，紧凑存储。
+  - buffer 输出固定长度字节块，配合 FourCC 格式标识（'GPAD'）。
+
+```mermaid
+classDiagram
+class InputDevice {
+name
+layout
+deviceId
+usages
+description
+queueEvent(event)
+currentState
+}
+class Gamepad {
+queueEvent(event)
+}
+class IInputState {
+buffer
+format
+}
+class GamepadState {
+buttons
+leftStick
+rightStick
+leftTrigger
+rightTrigger
+buffer
+format
+}
+InputDevice <|-- Gamepad
+IInputState <|-- GamepadState
+Gamepad --> GamepadState : "构造状态"
+```
+
+**图表来源**
+- [inputdevice.js:40-127](file://client/src/inputdevice.js#L40-L127)
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+
+**章节来源**
+- [inputdevice.js:120-127](file://client/src/inputdevice.js#L120-L127)
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+- [memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+
+### 组件三：事件桥接与消息封装（浏览器到远端）
+- gamepadEvents.js：
+  - 存储每个手柄的按钮与轴历史状态，计算差分以检测变化。
+  - 死区阈值 _e 控制轴值是否上报；当从移动回到静止时强制发送归零事件，保证状态一致性。
+  - 通过自定义事件（gamepadButtonDown/Up/Pressed、gamepadAxis）向上游广播。
+- register-events.js：
+  - 注册原生 gamepadconnected/disconnected 事件，委托给 gamepadHandler。
+  - 将统一格式的按钮/轴事件序列化为二进制消息，通过 VideoPlayer 发送。
+- InputRemoting/NewEventsMsg/NewDeviceMsg：
+  - 订阅本地事件，生成 StateEvent 或设备消息，通过观察者推送。
+
+```mermaid
+sequenceDiagram
+participant NW as "navigator.getGamepads()"
+participant GE as "gamepadEvents.js"
+participant RE as "register-events.js"
+participant RM as "InputRemoting"
+participant NE as "NewEventsMsg"
+NW-->>GE : "返回控制器数组"
+GE->>GE : "比较按钮/轴前后状态<br/>应用死区与差分"
+GE-->>RE : "自定义事件按钮/轴"
+RE->>RM : "sendMsg(二进制消息)"
+RM->>NE : "NewEventsMsg.create(state)"
+NE-->>RE : "完成发送"
+```
+
+**图表来源**
+- [gamepadEvents.js:43-94](file://client/public/videoplayer/js/gamepadEvents.js#L43-L94)
+- [register-events.js:42-101](file://client/public/videoplayer/js/register-events.js#L42-L101)
+- [inputremoting.js:138-141](file://client/src/inputremoting.js#L138-L141)
+- [inputremoting.js:258-277](file://client/src/inputremoting.js#L258-L277)
+
+**章节来源**
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [register-events.js:1-101](file://client/public/videoplayer/js/register-events.js#L1-L101)
+- [inputremoting.js:63-169](file://client/src/inputremoting.js#L63-L169)
+- [inputremoting.js:258-277](file://client/src/inputremoting.js#L258-L277)
+
+### 组件四：输入校准、死区与平滑（算法与实现要点）
+- 死区处理：
+  - 轴值绝对值小于阈值 _e 时不发送，避免漂移误触。
+  - 当从移动回到静止时强制发送 (0,0)，确保接收端状态收敛。
+- 平滑与差分：
+  - 通过存储上一帧按钮/轴状态，仅在变化或持续按压时发送，降低冗余。
+- 坐标与方向：
+  - 左右摇杆 Y 轴乘以 _axisYInverted 实现符合预期的朝向。
+  - 触发器值直接取用 buttons[n].value，映射到浮点范围。
+
+```mermaid
+flowchart TD
+S(["开始轮询"]) --> Axes["遍历摇杆轴对"]
+Axes --> AbsCheck{"|x|>|_e| 或 |y|>|_e| ?"}
+AbsCheck --> |是| SendMove["发送轴事件(x,y)"]
+AbsCheck --> |否| PrevAbs{"之前是否移动?"}
+PrevAbs --> |是| SendZero["发送轴事件(0,0)"]
+PrevAbs --> |否| Skip["跳过"]
+SendMove --> Store["保存当前状态"]
+SendZero --> Store
+Skip --> Store
+Store --> Next["下一轴对"]
+Next --> |完成| S
+```
+
+**图表来源**
+- [gamepadEvents.js:43-66](file://client/public/videoplayer/js/gamepadEvents.js#L43-L66)
+
+**章节来源**
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+
+### 组件五：设备识别、枚举与状态同步
+- 设备识别：
+  - 使用 gamepad.id 作为唯一标识，去除空格后作为 Cookie 键，持久化连接时间戳，确保跨刷新一致。
+- 枚举与同步：
+  - GamepadHandler 在每次循环中调用 _scanGamepad，将已知索引的控制器替换为最新快照，保证状态同步。
+- 连接状态监控：
+  - 监听 gamepadconnected/disconnected，分别初始化/清理状态缓存与轮询定时器。
+
+```mermaid
+sequenceDiagram
+participant W as "Window"
+participant GE as "gamepadEvents.js"
+participant GH as "GamepadHandler"
+participant DOC as "Document"
+W->>DOC : "gamepadconnected/disconnected"
+DOC->>GE : "gamepadHandler(connecting)"
+GE->>GE : "初始化/清理状态缓存与定时器"
+GH->>GH : "_scanGamepad() 同步控制器快照"
+```
+
+**图表来源**
+- [gamepadEvents.js:112-146](file://client/public/videoplayer/js/gamepadEvents.js#L112-L146)
+- [gamepadhandler.js:35-42](file://client/src/gamepadhandler.js#L35-L42)
+
+**章节来源**
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [gamepadhandler.js:1-45](file://client/src/gamepadhandler.js#L1-L45)
+
+### 组件六：不同厂商手柄差异与兼容策略
+- 按键与轴数量差异：
+  - 代码假设 buttons 数组长度为 16，axes 数组长度为 4；若实际设备不满足，需在构造 GamepadState 前进行边界检查与默认填充。
+- 按键语义映射：
+  - 通过 GamepadButton 常量将不同厂商的按键映射到统一编号，减少上游分支逻辑。
+- 触发器与肩键：
+  - 触发器值通过 buttons[6]/buttons[7] 获取，注意部分设备可能不支持压力值，应以 pressed/value 双重判断。
+
+**章节来源**
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+- [gamepadbutton.js:1-26](file://client/src/gamepadbutton.js#L1-L26)
+
+## 依赖关系分析
+- 模块内聚与耦合：
+  - InputDevice/GamepadState 与 MemoryHelper 解耦，通过位操作实现紧凑存储。
+  - InputRemoting 通过事件总线与消息封装与输入层解耦。
+- 外部依赖：
+  - 浏览器 Gamepad API 提供原始输入；gamepadEvents.js 与 register-events.js 作为桥接层。
+- 潜在循环依赖：
+  - 当前结构未见循环导入；建议保持事件桥接层独立于输入设备层。
+
+```mermaid
+graph LR
+GE["gamepadEvents.js"] --> RE["register-events.js"]
+RE --> RM["InputRemoting"]
+RM --> NE["NewEventsMsg"]
+ID["InputDevice"] --> GS["GamepadState"]
+GS --> SE["StateEvent"]
+SE --> NE
+MH["MemoryHelper"] --> GS
+```
+
+**图表来源**
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [register-events.js:1-101](file://client/public/videoplayer/js/register-events.js#L1-L101)
+- [inputremoting.js:258-277](file://client/src/inputremoting.js#L258-L277)
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+- [memoryhelper.js:1-28](file://client/src/memoryhelper.js#L1-L28)
+
+**章节来源**
+- [inputdevice.js:1-719](file://client/src/inputdevice.js#L1-L719)
+- [inputremoting.js:1-300](file://client/src/inputremoting.js#L1-L300)
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [register-events.js:1-101](file://client/public/videoplayer/js/register-events.js#L1-L101)
+
+## 性能考虑
+- 采样频率与帧驱动：
+  - 使用 requestAnimationFrame 驱动扫描，避免固定间隔造成的卡顿与能耗。
+- 事件去抖与差分：
+  - 仅在按钮/轴状态变化或持续按压时发送，显著降低带宽占用。
+- 死区与归零：
+  - 通过死区阈值与“从移动到静止”的强制归零，减少无效数据与状态抖动。
+- 序列化开销：
+  - 位图存储按钮状态，单个状态包固定大小，便于批量传输与解析。
+
+[本节为通用性能讨论，无需特定文件来源]
+
+## 故障排除指南
+- 手柄未被识别：
+  - 确认浏览器已启用 Gamepad API，且手柄正确连接；检查 gamepadconnected 事件是否触发。
+- 摇杆无响应或漂移：
+  - 调整死区阈值 _e；确认左右摇杆 Y 轴方向是否正确（_axisYInverted）。
+- 按键状态异常：
+  - 检查按钮索引映射与设备实际按键布局；必要时在构造 GamepadState 前进行边界保护。
+- 事件丢失或延迟：
+  - 确保在 _updateStatus 中持续调用 _scanGamepad；检查 requestAnimationFrame 是否被页面隐藏中断。
+
+**章节来源**
+- [gamepadhandler.js:22-42](file://client/src/gamepadhandler.js#L22-L42)
+- [gamepadEvents.js:1-147](file://client/public/videoplayer/js/gamepadEvents.js#L1-L147)
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+
+## 结论
+该系统通过清晰的分层设计实现了从浏览器手柄输入到远端传输的完整链路：GamepadHandler 负责设备扫描与事件派发，gamepadEvents.js 与 register-events.js 完成事件桥接与消息封装，InputDevice/GamepadState 提供稳定的输入状态模型，InputRemoting 则负责消息生成与推送。通过死区、差分与归零等策略有效降低了冗余与延迟，具备良好的可扩展性与兼容性。
+
+[本节为总结性内容，无需特定文件来源]
+
+## 附录
+
+### A. 数据模型与字段布局（GamepadState）
+- 固定格式标识：FourCC('GPAD')
+- 字段布局（字节偏移）：
+  - buttons：0~3（4字节位图）
+  - leftStick.x：4
+  - leftStick.y：8
+  - rightStick.x：12
+  - rightStick.y：16
+  - leftTrigger：20
+  - rightTrigger：24
+- 总长度：28 字节
+
+**章节来源**
+- [inputdevice.js:540-618](file://client/src/inputdevice.js#L540-L618)
+
+### B. 测试要点（验证输入序列化与消息封装）
+- GamepadState 格式与缓冲区长度验证
+- StateEvent 与 NewEventsMsg 的二进制输出结构
+- 设备消息 NewDeviceMsg 的 JSON 描述序列化
+
+**章节来源**
+- [inputdevice.test.js:102-121](file://client/test/inputdevice.test.js#L102-L121)
+- [inputremoting.test.js:107-121](file://client/test/inputremoting.test.js#L107-L121)
+- [inputremoting.test.js:50-57](file://client/test/inputremoting.test.js#L50-L57)