377 lines
13 KiB
Markdown
377 lines
13 KiB
Markdown
# Virtual HUD Input Design
|
|
|
|
## 目标
|
|
|
|
设计一套可在大厅和小游戏中复用的 HUD 输入组件：
|
|
|
|
- 通用摇杆组件：复用当前大厅摇杆视觉和交互体验，输出纯方向输入事件。
|
|
- 通用按键组件：按 MOBA 手游右下角操作区设计，提供 1 个主按键 + 4 个次按键，支持完整技能键手势和状态反馈。
|
|
|
|
组件层只输出输入事件和输入状态，不直接发送网络消息，不绑定大厅移动、小游戏技能、角色职业或服务端协议。大厅和小游戏各自订阅事件，并把事件映射到自己的业务逻辑。
|
|
|
|
## 范围
|
|
|
|
本设计覆盖：
|
|
|
|
- 通用 `VirtualJoystick` 运行时组件。
|
|
- 通用 `VirtualActionButton` 单按钮组件。
|
|
- 通用 `VirtualActionPad` 组合组件。
|
|
- `UI_VirtualJoystick` 和 `UI_VirtualActionPad` 预设描述，沿用 `Doc/UIPrefabCreater/*.json` 到 prefab 的现有管线。
|
|
- 大厅摇杆从 `LobbyWorldController` 私有采样逻辑迁移到通用组件。
|
|
- 小游戏按需加载通用摇杆或右下角按键组，并消费纯输入事件。
|
|
|
|
不覆盖：
|
|
|
|
- 小游戏协议设计。
|
|
- 具体技能系统、伤害、冷却规则、服务器校验。
|
|
- 专用 MOBA 圆形技能切图生产。第一版复用现有 Common UI 资源，后续可替换美术资源而不改变输入 API。
|
|
- Unity 新 Input System 迁移。第一版继续使用当前项目已有的 UGUI/EventSystem/StandaloneInputModule 路线。
|
|
|
|
## 方案选择
|
|
|
|
采用“通用 VirtualInput 组件层”方案。
|
|
|
|
备选方案一是只重构现有大厅摇杆并单独新增技能键。这种方式改动少，但大厅和小游戏输入会快速分叉。
|
|
|
|
备选方案二是新增完整输入服务和动作映射系统。这更接近正式 Input System，但当前项目还没有动作注册、上下文切换、优先级和协议映射基础，第一版过重。
|
|
|
|
推荐方案在中间：新增独立组件层，组件只负责输入采样和视觉反馈，业务层自己映射响应。它能复用现有 UI 管线，也不会把小游戏协议提前写死到客户端框架里。
|
|
|
|
## 架构
|
|
|
|
新增目录：
|
|
|
|
```text
|
|
Client/Assets/Script/xmain/Input/
|
|
```
|
|
|
|
核心组件：
|
|
|
|
```csharp
|
|
namespace XGame.Input
|
|
{
|
|
public sealed class VirtualJoystick : MonoBehaviour
|
|
{
|
|
public Vector2 Value { get; }
|
|
public bool IsActive { get; }
|
|
|
|
public event Action Started;
|
|
public event Action<Vector2, bool> Changed;
|
|
public event Action Ended;
|
|
|
|
public bool IsScreenPositionInAcquireArea(Vector2 screenPosition);
|
|
}
|
|
}
|
|
```
|
|
|
|
`VirtualJoystick` 负责鼠标/触摸捕获、死区、归一化方向、摇杆头视觉偏移。它不负责移动、相机、网络同步。
|
|
|
|
```csharp
|
|
namespace XGame.Input
|
|
{
|
|
public enum ActionButtonId
|
|
{
|
|
Primary,
|
|
Skill1,
|
|
Skill2,
|
|
Skill3,
|
|
Skill4
|
|
}
|
|
|
|
public enum ActionButtonPhase
|
|
{
|
|
Down,
|
|
Drag,
|
|
HoldStart,
|
|
HoldTick,
|
|
HoldEnd,
|
|
Tap,
|
|
Release,
|
|
Cancel,
|
|
Blocked
|
|
}
|
|
|
|
public readonly struct ActionButtonEvent
|
|
{
|
|
public ActionButtonId ButtonId { get; }
|
|
public ActionButtonPhase Phase { get; }
|
|
public Vector2 ScreenPosition { get; }
|
|
public Vector2 LocalVector { get; }
|
|
public Vector2 Direction { get; }
|
|
public float Distance01 { get; }
|
|
public float HeldSeconds { get; }
|
|
public bool IsCanceled { get; }
|
|
public int PointerId { get; }
|
|
}
|
|
}
|
|
```
|
|
|
|
```csharp
|
|
namespace XGame.Input
|
|
{
|
|
public sealed class VirtualActionButton : MonoBehaviour
|
|
{
|
|
public ActionButtonId ButtonId;
|
|
public bool IsInteractable { get; }
|
|
|
|
public event Action<ActionButtonEvent> ButtonEvent;
|
|
|
|
public void SetCooldown(float remainingSeconds, float durationSeconds);
|
|
public void SetCharges(int count);
|
|
public void SetButtonEnabled(bool enabled);
|
|
public void SetCancelArea(RectTransform cancelArea);
|
|
public void SetIcon(Sprite icon);
|
|
}
|
|
}
|
|
```
|
|
|
|
`VirtualActionButton` 是单个技能键状态机。它负责点击、长按、拖拽瞄准、取消、冷却遮罩、次数、禁用视觉。它不关心按钮对应普攻、技能还是道具。
|
|
|
|
```csharp
|
|
namespace XGame.Input
|
|
{
|
|
public sealed class VirtualActionPad : MonoBehaviour
|
|
{
|
|
public event Action<ActionButtonEvent> ButtonEvent;
|
|
|
|
public VirtualActionButton GetButton(ActionButtonId id);
|
|
public void SetCooldown(ActionButtonId id, float remainingSeconds, float durationSeconds);
|
|
public void SetCharges(ActionButtonId id, int count);
|
|
public void SetButtonEnabled(ActionButtonId id, bool enabled);
|
|
public void SetCancelAreaVisible(bool visible);
|
|
}
|
|
}
|
|
```
|
|
|
|
`VirtualActionPad` 管理右下角 5 个按钮，按稳定 ID 转发事件，并提供统一状态刷新 API。
|
|
|
|
## 预设
|
|
|
|
### UI_VirtualJoystick
|
|
|
|
新增：
|
|
|
|
```text
|
|
Doc/UIPrefabCreater/UI_VirtualJoystick.json
|
|
Client/Assets/Game/Art/UI/Prefab/UI_VirtualJoystick.prefab
|
|
```
|
|
|
|
它从现有 `UI_LobbyJoystick` 演进而来，保留：
|
|
|
|
- `Base`
|
|
- `Ring`
|
|
- `Knob`
|
|
|
|
默认布局：
|
|
|
|
- 根节点锚到左下角。
|
|
- 参考分辨率 `2048x1024`。
|
|
- 默认中心位置约 `(260, 220)`。
|
|
- 默认尺寸 `148x148`。
|
|
- 根节点挂 `VirtualJoystick`。
|
|
- 继续复用 `lobby_joystick_base`、`lobby_joystick_ring`、`lobby_joystick_knob`。
|
|
|
|
旧 `UI_LobbyJoystick` 可以先保留，避免已有资源引用断裂。大厅运行时改用 `UI_VirtualJoystick` 后，旧预设可作为兼容资源，后续再清理。
|
|
|
|
### UI_VirtualActionPad
|
|
|
|
新增：
|
|
|
|
```text
|
|
Doc/UIPrefabCreater/UI_VirtualActionPad.json
|
|
Client/Assets/Game/Art/UI/Prefab/UI_VirtualActionPad.prefab
|
|
```
|
|
|
|
默认布局：
|
|
|
|
- 根节点锚到右下角。
|
|
- `Btn_Primary`：主按键，最大，位于右下核心位置。
|
|
- `Btn_Skill1`、`Btn_Skill2`、`Btn_Skill3`：围绕主按键左侧和上方弧形排布。
|
|
- `Btn_Skill4`：更靠上或靠左的小技能键，用于特殊动作、召唤师技能或道具。
|
|
- `CancelArea`：默认在按钮组上方偏中区域，仅拖拽技能时显示。
|
|
|
|
每个按钮标准子节点：
|
|
|
|
- `Icon`
|
|
- `CooldownMask`
|
|
- `CooldownText`
|
|
- `ChargeText`
|
|
- `AimIndicator` 或 `DragArrow`
|
|
|
|
第一版视觉复用现有 Common 资源：
|
|
|
|
- 主按键底图优先使用 `btn_primary_*`。
|
|
- 次按键底图优先使用 `btn_small_*` 或 `btn_warning_*`。
|
|
- 图标先使用 `ico_sword`、`ico_shield`、`ico_star`、`ico_heart`、`ico_item` 等临时示意图标。
|
|
|
|
如果后续补充圆形技能键切图，只需替换 JSON 资源和 prefab，不改变 `VirtualActionButton`/`VirtualActionPad` API。
|
|
|
|
## 摇杆交互
|
|
|
|
`VirtualJoystick` 行为：
|
|
|
|
1. 捕获鼠标左键或触摸。
|
|
2. 按 pointer ID 锁定一次操作，直到松开或取消。
|
|
3. 支持开始捕获区域放大倍率，默认视觉半径 `1.6x` 内都可开始控制。
|
|
4. 计算屏幕指针相对摇杆中心的向量，并归一化到 `[-1, 1]`。
|
|
5. 小于死区时输出 `Value=Vector2.zero` 且 `IsActive=false`。
|
|
6. 大于死区时输出归一化方向且 `IsActive=true`。
|
|
7. `Knob` 最大视觉移动距离由容器半径和 knob 半径计算，避免不同尺寸下越界。
|
|
8. 松开时重置方向、复位 knob、触发 `Ended`。
|
|
|
|
事件：
|
|
|
|
- `Started`：从未激活进入捕获。
|
|
- `Changed(value, active)`：方向或激活状态变化时触发。
|
|
- `Ended`：释放当前 pointer 后触发。
|
|
|
|
`IsScreenPositionInAcquireArea` 提供给相机、点击移动等外部输入排除逻辑复用，避免各业务重复计算摇杆区域。
|
|
|
|
## 按键交互
|
|
|
|
`VirtualActionButton` 行为：
|
|
|
|
- `PointerDown`：记录按下时间、pointer ID，发 `Down`。
|
|
- `PointerDrag`：计算从按钮中心到当前指针的 `LocalVector`、`Direction`、`Distance01`，发 `Drag`。
|
|
- 进入取消区时切换取消悬停视觉，并在事件中设置 `IsCanceled=true`。
|
|
- 按住超过阈值后发一次 `HoldStart`。
|
|
- 按住期间按固定间隔发 `HoldTick`。
|
|
- 松开时：
|
|
- 如果在取消区，发 `Cancel`。
|
|
- 如果拖拽距离超过释放阈值，发 `Release`，并携带方向。
|
|
- 如果未拖拽且未达到长按阈值，发 `Tap`。
|
|
- 如果已经长按，先补 `HoldEnd`，再按最终状态发 `Release` 或 `Cancel`。
|
|
- 冷却中、禁用、次数为 0 时不进入按下流程，只发 `Blocked`。
|
|
|
|
默认阈值：
|
|
|
|
- 长按阈值：`0.35s`。
|
|
- HoldTick 间隔：`0.1s`。
|
|
- 拖拽释放阈值：按钮半径的 `0.25`。
|
|
- 最大拖拽归一化距离：按钮半径的 `1.5`。
|
|
|
|
这些阈值作为序列化字段暴露，允许 prefab 或业务按需调节。
|
|
|
|
## 状态与视觉
|
|
|
|
按钮状态：
|
|
|
|
- Normal：可点击。
|
|
- Pressed：按住。
|
|
- Dragging：拖拽瞄准。
|
|
- CancelHover：拖入取消区。
|
|
- Cooldown：冷却中。
|
|
- Disabled：禁用。
|
|
- EmptyCharges：次数为 0。
|
|
|
|
视觉刷新：
|
|
|
|
- `CooldownMask` 使用 Filled Image 或代码调整 `fillAmount`。
|
|
- `CooldownText` 显示向上取整的剩余秒数。
|
|
- `ChargeText` 在次数大于 0 时显示次数，次数为 0 时按钮进入不可用视觉。
|
|
- `AimIndicator`/`DragArrow` 在拖拽时显示方向，松手后隐藏。
|
|
- `CancelArea` 默认隐藏，进入拖拽瞄准时显示；取消或释放后隐藏。
|
|
|
|
缺少可选节点时跳过对应视觉，不影响事件输出。缺少关键节点时记录日志并禁用该组件。
|
|
|
|
## 大厅接入
|
|
|
|
`LobbyWorldController` 保留大厅业务职责：
|
|
|
|
- 本地角色移动。
|
|
- 远端角色同步。
|
|
- 相机旋转和缩放。
|
|
- 大厅网络移动同步。
|
|
|
|
改动方向：
|
|
|
|
- 移除 `LobbyWorldController` 内部摇杆采样字段和方法。
|
|
- 加载 `UI_VirtualJoystick.prefab` 后获取 `VirtualJoystick`。
|
|
- 订阅 `Changed/Ended`，把 `Vector2` 缓存为大厅移动输入。
|
|
- `GetMoveDirection` 继续把键盘 WASD 和摇杆方向合成世界方向。
|
|
- 相机输入排除摇杆区域时调用 `VirtualJoystick.IsScreenPositionInAcquireArea`。
|
|
- 大厅进入小游戏隔离时，将通用摇杆 root 或 `VirtualJoystick` 列入 `MiniGameStageIsolation` 管理，避免大厅输入穿透。
|
|
|
|
## 小游戏接入
|
|
|
|
小游戏不强制显示这套 HUD。需要时在 `IGameClient.OnEnter` 中加载：
|
|
|
|
- `UI_VirtualJoystick`
|
|
- `UI_VirtualActionPad`
|
|
- 或两者都加载
|
|
|
|
小游戏客户端订阅事件并自行映射：
|
|
|
|
```text
|
|
Primary Tap -> 普攻 opcode
|
|
Skill1 Release -> 带方向释放技能 opcode
|
|
Skill2 Cancel -> 不发送技能，播放本地取消反馈
|
|
Joystick Changed -> 本地移动或发送移动输入
|
|
```
|
|
|
|
`GameClientCtx` 第一版不扩展输入服务，继续保持资源加载和事件订阅模式。这样不会改变小游戏框架合同，也不会影响已有 RPS 小游戏。
|
|
|
|
## 错误处理
|
|
|
|
- 摇杆 prefab 缺少 `Knob`：记录错误日志，禁用 `VirtualJoystick`。
|
|
- 按钮缺少 `Icon`：仍可输出事件，但不显示图标。
|
|
- 按钮缺少 `CooldownMask`、`CooldownText` 或 `ChargeText`：跳过对应视觉刷新。
|
|
- 缺少 `CancelArea`：拖拽取消功能关闭，按钮仍支持点击和拖拽释放。
|
|
- 多点触控按 pointer ID 锁定，同一个按钮未释放前忽略其他 pointer。
|
|
- 不同按钮可以各自捕获不同 pointer。
|
|
- 冷却、禁用、次数为 0 时只发 `Blocked`，不发 `Tap`、`Release` 或 `Cancel`。
|
|
- 组件销毁或禁用时，如果正在按住，需要复位内部状态和视觉，避免残留按下态。
|
|
|
|
## 测试策略
|
|
|
|
EditMode 测试：
|
|
|
|
1. `VirtualJoystick` 死区：小于死区输出 inactive，松开后归零。
|
|
2. `VirtualJoystick` 归一化：超过半径时 clamp 到单位圆。
|
|
3. `VirtualJoystick` knob 行程：按容器和 knob 尺寸计算，不越界。
|
|
4. `VirtualActionButton` 点击：Down -> Tap。
|
|
5. `VirtualActionButton` 拖拽释放：Down -> Drag -> Release，并携带方向。
|
|
6. `VirtualActionButton` 拖拽取消：Down -> Drag -> Cancel。
|
|
7. `VirtualActionButton` 长按：Down -> HoldStart -> HoldTick -> HoldEnd。
|
|
8. `VirtualActionButton` Blocked：冷却中、禁用、次数为 0 时不发释放类事件。
|
|
9. `VirtualActionPad` 能按 `ActionButtonId` 找到 5 个按钮并转发事件。
|
|
10. 标准节点绑定成功，缺少可选节点不抛异常。
|
|
11. 状态 API 能刷新冷却遮罩、冷却文字、次数文字和可用状态。
|
|
|
|
大厅接入测试：
|
|
|
|
- `LobbyWorldController` 消费 `VirtualJoystick` 输出值合成移动方向。
|
|
- 相机输入排除摇杆区域时使用通用组件判断。
|
|
- 小游戏隔离时大厅摇杆不可见或不可交互。
|
|
|
|
手动 Unity 烟测：
|
|
|
|
- PC 鼠标拖动摇杆。
|
|
- 触摸或模拟触摸拖动摇杆。
|
|
- 主按键点击释放。
|
|
- 技能键拖拽瞄准释放。
|
|
- 技能键拖拽到取消区取消。
|
|
- 冷却遮罩和倒计时显示。
|
|
- 次数耗尽后按钮进入不可用态。
|
|
- 退出小游戏后大厅输入恢复。
|
|
|
|
## 实施顺序建议
|
|
|
|
1. 为 `VirtualJoystick` 和 `VirtualActionButton` 写核心状态测试。
|
|
2. 实现 `VirtualJoystick`。
|
|
3. 实现 `VirtualActionButton` 和 `VirtualActionPad`。
|
|
4. 新增 `UI_VirtualJoystick.json` 和 `UI_VirtualActionPad.json`。
|
|
5. 生成并检查 prefab。
|
|
6. 迁移 `LobbyWorldController` 使用 `VirtualJoystick`。
|
|
7. 加测试和手动烟测。
|
|
|
|
## 验收标准
|
|
|
|
- 大厅能继续使用左下角摇杆移动角色。
|
|
- 摇杆输入来自 `VirtualJoystick` 事件，而不是 `LobbyWorldController` 私有采样逻辑。
|
|
- 小游戏能加载右下角 `VirtualActionPad` 并收到 5 个按钮的纯输入事件。
|
|
- 技能键支持点击、长按、拖拽释放、拖拽取消、冷却、次数、禁用。
|
|
- 冷却中或次数为 0 时不会误发释放事件。
|
|
- 缺少可选视觉节点不会导致运行时异常。
|
|
- 现有小游戏框架合同不需要变更。
|