304 lines
11 KiB
Markdown
304 lines
11 KiB
Markdown
# Input Flow And Frame Semantics
|
||
|
||
## 这篇指南解决什么问题
|
||
|
||
这篇文档不是“列 API 名称”，而是解释 XCEngine 当前输入系统到底按什么规则工作。它直接基于当前这些实现和测试：
|
||
|
||
- `engine/src/Input/InputManager.cpp`
|
||
- `engine/include/XCEngine/Input/InputManager.h`
|
||
- `tests/Input/test_input_manager.cpp`
|
||
|
||
如果你在游戏层、编辑器运行态桥接、脚本绑定或平台输入后端里使用 `InputManager`，最重要的不是记住方法名，而是先建立一致的语义模型。
|
||
|
||
## 设计理念
|
||
|
||
当前输入系统刻意做成两层：
|
||
|
||
- `InputModule`
|
||
- 负责接平台消息，把 `WM_KEYDOWN`、`WM_MOUSEMOVE` 这类原始系统消息翻译成引擎调用
|
||
- `InputManager`
|
||
- 负责保存状态、提供轮询 API、同步分发事件
|
||
|
||
这种设计接近商业引擎里常见的“平台适配层 + 游戏语义层”分工。好处是：
|
||
|
||
- 游戏逻辑和编辑器逻辑不需要直接依赖 Win32 之类的平台细节
|
||
- 平台后端可以替换，输入查询接口可以保持稳定
|
||
- 轮询和事件可以共享同一份底层状态，不需要上层再维护第二套缓存
|
||
|
||
从使用风格上看，它也明显借鉴了 Unity 旧版 `Input Manager` 的思想：
|
||
|
||
- 支持具名轴，如 `Horizontal`、`Vertical`
|
||
- 支持具名按钮，如 `Jump`、`Fire1`
|
||
- 以 `GetAxis()`、`GetButton()` 一类游戏层查询接口为中心
|
||
|
||
但它当前还是一个轻量级、同步、帧驱动的输入管理器，不是完整的设备抽象框架。
|
||
|
||
## 输入流到底怎么走
|
||
|
||
当前一帧内的典型流向是：
|
||
|
||
1. 平台窗口系统产生键盘、鼠标消息。
|
||
2. 平台后端把消息翻译成 `ProcessKeyDown()`、`ProcessKeyUp()`、`ProcessMouseMove()`、`ProcessMouseButton()`、`ProcessMouseWheel()` 等调用。
|
||
3. `InputManager` 立即更新内部缓存，并同步触发 `OnKeyEvent()`、`OnMouseMove()` 等事件。
|
||
4. 游戏逻辑、编辑器运行态桥接或脚本绑定在当前帧查询 `IsKeyDown()`、`GetAxis()`、`GetButtonDown()` 等 API。
|
||
5. 帧末或统一帧边界调用 `Update()`，清空瞬时输入缓存，准备下一帧。
|
||
|
||
这说明一个关键点：`Update()` 不是“收集输入”，而是“推进帧边界并清空瞬时状态”。
|
||
|
||
## 为什么同时提供事件和轮询
|
||
|
||
商业级引擎通常不会强迫所有系统只用一种输入风格。XCEngine 当前的取舍也是一样：
|
||
|
||
- 事件更适合 UI、文本输入、编辑器面板、平台桥接
|
||
- 轮询更适合角色移动、相机控制、游戏规则判断
|
||
|
||
`InputManager` 把两者放在同一个状态中心里，能减少几类常见问题：
|
||
|
||
- 上层不需要再手写“本帧按下 / 本帧释放”缓存
|
||
- 事件订阅者和轮询调用者看到的是同一组真实状态
|
||
- 平台输入桥接和游戏输入消费不需要重复实现状态机
|
||
|
||
## 帧边界语义
|
||
|
||
当前实现里，`Update()` 会清理这些瞬时状态：
|
||
|
||
- `m_keyDownThisFrame`
|
||
- `m_keyUpThisFrame`
|
||
- `m_mouseButtonDownThisFrame`
|
||
- `m_mouseButtonUpThisFrame`
|
||
- `m_mouseDelta`
|
||
- `m_mouseScrollDelta`
|
||
|
||
因此下面这些接口都天然是“本帧有效，过帧清空”：
|
||
|
||
- `IsKeyPressed()`
|
||
- `IsKeyReleased()`
|
||
- `IsMouseButtonClicked()`
|
||
- `IsMouseButtonReleased()`
|
||
- `GetButtonDown()`
|
||
- `GetButtonUp()`
|
||
- `IsAnyKeyPressed()`
|
||
- `GetMouseDelta()`
|
||
- `GetMouseScrollDelta()`
|
||
|
||
推荐实践只有三条，但都很重要：
|
||
|
||
1. 每帧只调用一次 `Update()`
|
||
2. 保持调用时机稳定，不要一会儿逻辑前一会儿逻辑后
|
||
3. 先消费瞬时输入，再执行 `Update()`
|
||
|
||
## 四类最常用的输入语义
|
||
|
||
先按语义理解 API，比按方法名死记更可靠。
|
||
|
||
| 语义 | 典型 API | 当前真正含义 |
|
||
|------|------|------|
|
||
| 按住态 | `IsKeyDown()`、`IsMouseButtonDown()`、`GetButton()`、`GetAxis()`、`GetAxisRaw()`、`IsAnyKeyDown()` | 当前是否仍处于按住状态 |
|
||
| 抬起态 | `IsKeyUp()`、`IsMouseButtonUp()` | 当前没有按住，不包含“本帧刚释放”含义 |
|
||
| 按下边沿 | `IsKeyPressed()`、`IsMouseButtonClicked()`、`GetButtonDown()`、`IsAnyKeyPressed()` | 本帧出现按下消息 |
|
||
| 释放边沿 | `IsKeyReleased()`、`IsMouseButtonReleased()`、`GetButtonUp()` | 本帧出现释放消息 |
|
||
|
||
这也是很多团队最容易踩错的地方：`Up` 和 `Released` 不是同义词。
|
||
|
||
## `Up` 和 `Released` 为什么必须分开
|
||
|
||
这是当前模块最需要讲透的概念。
|
||
|
||
- `IsKeyUp()` / `IsMouseButtonUp()`
|
||
- 只表示“现在没有按住”
|
||
- 本质上等价于 `!IsKeyDown()` / `!IsMouseButtonDown()`
|
||
- 即使未初始化或索引越界，当前实现里也会表现为 `true`
|
||
- `IsKeyReleased()` / `IsMouseButtonReleased()`
|
||
- 只表示“这一帧刚收到释放消息”
|
||
- 由 `ProcessKeyUp()` / `ProcessMouseButton(..., false, ...)` 写入
|
||
- 会在下一次 `Update()` 时被清空
|
||
|
||
为什么商业引擎通常都要保留这两套语义：
|
||
|
||
- “当前没按住”适合状态判断
|
||
- “这一帧刚释放”适合一次性触发逻辑
|
||
|
||
例如“角色是否仍在蓄力”更像 `IsKeyDown()` / `IsKeyUp()` 问题；“松开蓄力键时发射一次”则应该看 `IsKeyReleased()`。
|
||
|
||
## `Pressed` 当前到底是不是“首次按下”
|
||
|
||
不是严格意义上的“首次物理按下”。
|
||
|
||
源码里 `ProcessKeyDown()` 的当前行为是：
|
||
|
||
- 无论 `repeat` 为 `true` 还是 `false`
|
||
- 都会把 `m_keyDown[index] = true`
|
||
- 也都会把 `m_keyDownThisFrame[index] = true`
|
||
|
||
这带来一个很关键的结果：
|
||
|
||
- `IsKeyPressed()`
|
||
- `GetButtonDown()`
|
||
- `IsAnyKeyPressed()`
|
||
|
||
它们当前表达的更准确含义是“这一帧收到了按下消息”，而不是“从这次物理按下开始到松开之前只触发一次”。
|
||
|
||
如果平台在后续帧继续发送自动重复 `KeyDown`：
|
||
|
||
- `OnKeyEvent()` 会把事件类型标成 `KeyEvent::Repeat`
|
||
- 但按下边沿缓存仍会被写入
|
||
- 所以上述查询接口仍可能在这些帧再次返回 `true`
|
||
|
||
如果业务真的需要“严格首次按下”，需要在平台层或更高层自己过滤 repeat。
|
||
|
||
## 轴和按钮映射的真实行为
|
||
|
||
### 逻辑轴
|
||
|
||
当前 `RegisterAxis()` 把一个名字映射到“正方向键 + 负方向键”。
|
||
|
||
`GetAxis()` 和 `GetAxisRaw()` 目前都直接读 `IsKeyDown()`：
|
||
|
||
- 正方向键按住时加 `1.0f`
|
||
- 负方向键按住时减 `1.0f`
|
||
- 同时按下则抵消为 `0.0f`
|
||
|
||
当前两者没有行为差异。它们都：
|
||
|
||
- 不读取 `InputAxis::m_value`
|
||
- 不做平滑、重力、灵敏度或死区处理
|
||
- 不会因为只是“本帧刚按下”而产生非零值
|
||
|
||
这和很多商业引擎早期的“raw axis / smoothed axis”区分还不一样，当前实现更接近“两个名字不同但逻辑相同的持续态接口”。
|
||
|
||
### 逻辑按钮
|
||
|
||
当前 `RegisterButton()` 只是把名字映射到一个 `KeyCode`。
|
||
|
||
- `GetButton()` 转发到 `IsKeyDown()`
|
||
- `GetButtonDown()` 转发到 `IsKeyPressed()`
|
||
- `GetButtonUp()` 转发到 `IsKeyReleased()`
|
||
|
||
因此按钮系统当前不是独立状态机，而只是对键盘查询的命名包装。
|
||
|
||
## 和 Unity 的关系
|
||
|
||
如果你熟悉 Unity，这里最容易建立直觉，但也最容易因为“看起来像”而误判。
|
||
|
||
相似点：
|
||
|
||
- 都有具名轴和具名按钮
|
||
- 都强调游戏层直接查询，而不是让业务处理原始平台消息
|
||
- 都适合快速搭建角色控制、相机控制和简单交互
|
||
|
||
不同点：
|
||
|
||
- 当前没有 Unity 旧版 Input Manager 里的 gravity、sensitivity、dead zone、snap 等参数
|
||
- `GetAxisRaw()` 目前并不比 `GetAxis()` 更“底层”，两者等价
|
||
- 默认注册的 `Mouse X` / `Mouse Y` 还没有绑定到鼠标移动增量
|
||
- `GetButtonUp()` 是释放边沿，不是“当前按钮没按着就算 up”
|
||
|
||
所以，当前更适合把它理解成“Unity 风格接口外观 + XCEngine 当前真实实现语义”，而不是直接按 Unity 经验套用全部行为。
|
||
|
||
## `any-key` 目前到底统计什么
|
||
|
||
当前 `any-key` 会把鼠标按钮也算进去。
|
||
|
||
- `IsAnyKeyDown()`
|
||
- 扫描 `m_keyDown` 和 `m_mouseButtonDown`
|
||
- `IsAnyKeyPressed()`
|
||
- 扫描 `m_keyDownThisFrame` 和 `m_mouseButtonDownThisFrame`
|
||
|
||
它目前不包含：
|
||
|
||
- 触摸
|
||
- 滚轮
|
||
- 文本输入
|
||
- 摇杆或手柄输入
|
||
|
||
同时，`IsAnyKeyPressed()` 也继承键盘 repeat 语义。只要平台后端在某一帧再次调用 `ProcessKeyDown()`，它就可能再次成立。
|
||
|
||
## 默认映射与当前落地程度
|
||
|
||
初始化后默认注册这些逻辑项：
|
||
|
||
- 轴
|
||
- `Horizontal`: `D / A`
|
||
- `Vertical`: `W / S`
|
||
- `Mouse X`: `None / None`
|
||
- `Mouse Y`: `None / None`
|
||
- 按钮
|
||
- `Jump`: `Space`
|
||
- `Fire1`: `LeftCtrl`
|
||
- `Fire2`: `LeftAlt`
|
||
- `Fire3`: `LeftShift`
|
||
|
||
这说明当前默认配置的实际可用性是分层的：
|
||
|
||
- `Horizontal` / `Vertical` 可以直接驱动基础移动逻辑
|
||
- `Jump` / `Fire1-3` 可以直接用于具名按钮查询
|
||
- `Mouse X` / `Mouse Y` 当前更像预留命名位，而不是已经接通的鼠标轴
|
||
|
||
## 平台桥接为什么值得保留独立层
|
||
|
||
当前 Windows 路径里，`WindowsInputModule::HandleMessage()` 会把 Win32 消息翻译成 `InputManager::Process*()` 调用。
|
||
|
||
这种分层设计的直接收益是：
|
||
|
||
- 游戏层不用理解平台消息细节
|
||
- 测试可以绕开平台窗口系统，直接驱动 `InputManager::Process*()` 来验证行为
|
||
- 将来替换平台层时，输入消费方可以尽量保持不变
|
||
|
||
这也是为什么现有测试大多直接命中 `InputManager`，而不是依赖完整窗口消息环境。
|
||
|
||
## 当前版本最该知道的限制
|
||
|
||
- `KeyCode` 底层值当前存在重复项，部分按键会共享状态槽。
|
||
- Windows 路径当前不能准确区分左右 Ctrl / Alt / Shift。
|
||
- 触摸与摇杆接口大多还是预留位。
|
||
- 事件回调同步执行，不是异步消息队列。
|
||
- `Shutdown()` 会清空状态和映射，但不会清空事件监听器。
|
||
- `ClearAxes()` 当前会同时清空轴和按钮映射。
|
||
|
||
## 推荐接入方式
|
||
|
||
初始化阶段：
|
||
|
||
```cpp
|
||
using namespace XCEngine::Input;
|
||
|
||
InputManager::Get().Initialize(windowHandle);
|
||
```
|
||
|
||
平台消息阶段：
|
||
|
||
```cpp
|
||
windowsInputModule.HandleMessage(hwnd, msg, wParam, lParam);
|
||
```
|
||
|
||
游戏逻辑阶段：
|
||
|
||
```cpp
|
||
if (InputManager::Get().GetButton("Jump")) {
|
||
// 持续按住态
|
||
}
|
||
|
||
if (InputManager::Get().GetButtonDown("Jump")) {
|
||
// 本帧按下边沿
|
||
}
|
||
|
||
if (InputManager::Get().GetButtonUp("Jump")) {
|
||
// 本帧释放边沿
|
||
}
|
||
```
|
||
|
||
帧边界阶段：
|
||
|
||
```cpp
|
||
InputManager::Get().Update(deltaTime);
|
||
```
|
||
|
||
如果你把 `Update()` 放错位置，或者在同一帧里调用多次，最先出问题的通常就是 `Pressed` / `Released` / `MouseDelta` 这些瞬时语义。
|
||
|
||
## 相关 API
|
||
|
||
- [Input](../../XCEngine/Input/Input.md)
|
||
- [InputManager](../../XCEngine/Input/InputManager/InputManager.md)
|
||
- [InputModule](../../XCEngine/Input/InputModule/InputModule.md)
|
||
- [InputTypes](../../XCEngine/Input/InputTypes/InputTypes.md)
|