mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-12 05:08:58 +08:00
ebbef321ad
- 新增输入绑定 DTO、设备上下文和 UI 语义桥接契约。 - 实现 Game 默认输入绑定存储、动作映射和 UI 分发桥接。 - 落地 Godot InputMap 适配、测试覆盖与配套文档。 - 更新 ai-plan 恢复点、worktree 映射与采用入口。
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
---
|
|
title: 输入系统
|
|
description: 说明 GFramework.Game 与 GFramework.Game.Abstractions 当前提供的统一输入契约、默认运行时与 UI 语义桥接边界。
|
|
---
|
|
|
|
# 输入系统
|
|
|
|
`GFramework.Game.Abstractions.Input` 与 `GFramework.Game.Input` 提供的是“动作绑定管理”和“UI 语义桥接”这一层输入系统，
|
|
而不是直接替代任何具体引擎的输入 API。
|
|
|
|
当前 v1 聚焦三件事：
|
|
|
|
- 用稳定 DTO 描述动作绑定，而不是把引擎原生输入事件暴露给业务层
|
|
- 允许导出 / 导入绑定快照，并支持主绑定替换、冲突交换和默认恢复
|
|
- 把逻辑动作名桥接到现有 `UiInputAction`，继续复用 `UiRouterBase` 的输入仲裁
|
|
|
|
## 契约层入口
|
|
|
|
`GFramework.Game.Abstractions.Input` 当前公开这些核心类型：
|
|
|
|
- `InputBindingDescriptor`
|
|
- 描述一个动作绑定使用的设备族、绑定类型、稳定码值和展示名称
|
|
- `InputActionBinding`
|
|
- 描述单个逻辑动作当前持有的绑定集合
|
|
- `InputBindingSnapshot`
|
|
- 描述一组动作绑定的可持久化快照
|
|
- `IInputBindingStore`
|
|
- 定义查询、主绑定替换、快照导入导出与默认恢复契约
|
|
- `IInputDeviceTracker`
|
|
- 定义当前活跃输入设备上下文查询入口
|
|
- `IUiInputActionMap` / `IUiInputDispatcher`
|
|
- 定义逻辑动作名到 `UiInputAction` 的桥接边界
|
|
|
|
这里仍然保留字符串动作名，而不是额外发明新的动作 ID 类型。对 Godot 项目来说，这意味着可以直接继续使用
|
|
`project.godot` 生成出来的 `InputActions.*` 常量。
|
|
|
|
## 默认运行时
|
|
|
|
`GFramework.Game.Input` 当前提供的默认实现是：
|
|
|
|
- `InputBindingStore`
|
|
- 纯托管输入绑定存储
|
|
- 管理默认快照、当前快照、主绑定替换与冲突交换
|
|
- `InputDeviceTracker`
|
|
- 可由宿主侧更新的活跃设备上下文持有者
|
|
- `UiInputActionMap`
|
|
- 默认把 `ui_cancel` / `cancel` 映射到 `UiInputAction.Cancel`
|
|
- 默认把 `ui_accept` / `confirm` / `submit` 映射到 `UiInputAction.Confirm`
|
|
- `UiInputDispatcher`
|
|
- 把逻辑动作名继续分发给 `IUiRouter.TryDispatchUiAction(...)`
|
|
|
|
也就是说，`Game` 层现在只负责统一输入语义与默认运行时行为；实际的物理输入事件采集仍由宿主层负责。
|
|
|
|
## 最小接入方式
|
|
|
|
如果你的项目已经有动作名常量，只想先接入统一输入绑定和 UI 桥接，可以从这组最小组合开始：
|
|
|
|
```csharp
|
|
using GFramework.Game.Abstractions.Input;
|
|
using GFramework.Game.Abstractions.UI;
|
|
using GFramework.Game.Input;
|
|
|
|
var defaultSnapshot = new InputBindingSnapshot(
|
|
[
|
|
new InputActionBinding(
|
|
"ui_accept",
|
|
[
|
|
new InputBindingDescriptor(
|
|
InputDeviceKind.KeyboardMouse,
|
|
InputBindingKind.Key,
|
|
"key:13",
|
|
"Enter")
|
|
])
|
|
]);
|
|
|
|
var bindingStore = new InputBindingStore(defaultSnapshot);
|
|
var dispatcher = new UiInputDispatcher(new UiInputActionMap(), uiRouter);
|
|
```
|
|
|
|
随后由项目自己的宿主层决定：
|
|
|
|
- 什么时候读取物理输入
|
|
- 什么时候调用 `SetPrimaryBinding(...)`
|
|
- 什么时候触发 `dispatcher.TryDispatch(...)`
|
|
|
|
## 当前边界
|
|
|
|
- 这套输入抽象当前不尝试复刻完整 `PlayerInput` / `ActionMap` 系统
|
|
- 当前只统一动作绑定管理、快照导入导出与 UI 语义桥接
|
|
- 设备品牌识别、平台差异文案、震动等宿主专属能力不在 `Game.Abstractions` 契约层
|
|
- 触摸 / 手柄轴向等更复杂输入源当前只保证 DTO 能表达，不保证 `Game` 层自带完整采集策略
|
|
|
|
## 相关主题
|
|
|
|
- [UI 系统](./ui.md)
|
|
- [Godot 输入集成](../godot/input.md)
|
|
- [Godot 集成教程](../tutorials/godot-integration.md)
|