# 10 · UI 系统规范

> **所属文档集** [← 返回索引](./README.md)  
> **摘要**：游戏 UI 分层架构、HUD 元素规范、菜单系统与 UI 事件契约。

---

## 目录

1. [UI 设计原则](#1-ui-设计原则)
2. [UI 分层架构](#2-ui-分层架构)
3. [HUD 规范](#3-hud-规范)
4. [菜单系统](#4-菜单系统)
5. [UI 数据绑定契约](#5-ui-数据绑定契约)
6. [UI 事件目录](#6-ui-事件目录)

---

## 1. UI 设计原则

| 原则 | 说明 |
|------|------|
| **非侵入** | HUD 元素尽量小，不遮挡游戏视野 |
| **信息即时** | 关键状态变化立即反映（HP减少不延迟）|
| **纯响应式** | UI 不主动查询游戏状态，只响应事件 |
| **逻辑无关** | UI 不包含任何游戏逻辑，仅负责显示与交互 |

---

## 2. UI 分层架构

从最低层到最高层：

| 层级 | 名称 | 内容 | 说明 |
|------|------|------|------|
| Layer 0 | Game World | 游戏本体 | 非 UI |
| Layer 1 | World UI | 对话气泡、头顶血条 | 跟随世界坐标 |
| Layer 2 | HUD | 血量/资源/护符 | 全程显示 |
| Layer 3 | Notification | 弹出提示、成就 | 临时覆盖 |
| Layer 4 | Overlay Menu | 暂停、设置 | 半透明遮罩 |
| Layer 5 | Full-screen | 存档读取、过场动画 | 完全遮盖 |
| Layer 6 | Transition | 场景转场动画 | 最高优先级 |

---

## 3. HUD 规范

### 3.1 HUD 元素列表

| 元素 | 位置 | 显示内容 |
|------|------|---------|
| HP 条 | 左上角 | 当前 HP / 最大 HP，格子式显示 |
| 灵泉指示 | HP 条下方 | 灵泉数量（图标×N）|
| 灵力条 | 左下角 | 当前灵力（填充环形或条形）|
| 魄元条 | 灵力条旁 | 当前魄元 |
| 形态指示 | 右下角 | 当前形态图标 + 三形态小图标 |
| 技能槽 | 形态指示旁 | 当前形态的魂技能/魄技能图标 + 冷却遮罩 |
| Geo 计数 | 右上角（可选）| 当前 Geo 数量 |
| Boss 血条 | 屏幕下方居中 | 仅 Boss 战显示，含阶段分段标记 |

### 3.2 HP 显示规范

- 每格 = 固定 HP 量（如每格 = 50 HP）
- 满格：实心图标
- 半格（受伤未满格）：半空状态
- 空格：空心图标
- 当前 HP < 20%：格子闪烁警告
- HP 变化时：格子动画（减少时格子渐消，恢复时渐现）

### 3.3 形态指示规范

- 当前激活形态：大图标高亮
- 其他两形态：小图标、低亮度
- 切换时：当前形态图标播放切换动画，新形态高亮

---

## 4. 菜单系统

### 4.1 菜单层级

```
主菜单
├── 继续游戏
├── 新游戏
├── 存档选择
└── 设置
    ├── 图像设置
    ├── 音频设置
    ├── 操控设置
    └── 辅助设置

暂停菜单（游戏中）
├── 继续
├── 地图
├── 护符装备
├── 道具/图鉴
├── 设置
└── 返回主菜单（确认弹窗）
```

### 4.2 菜单状态管理

```
菜单系统维护一个菜单栈（Stack）:

打开菜单:
  → 新菜单 push 到栈顶
  → 暂停游戏时间（若为暂停菜单）
  → 新菜单获得输入焦点

关闭/返回:
  → 当前菜单 pop
  → 若栈空 → 游戏恢复运行

关闭所有菜单:
  → 清空栈
  → 游戏立即恢复
```

---

## 5. UI 数据绑定契约

UI 不直接访问游戏数据，通过以下接口获取信息：

```
Interface IHUDDataProvider {
    getPlayerHP()        → {current: Integer, max: Integer}
    getPlayerSoul()      → {current: Integer, max: Integer}
    getPlayerSpirit()    → {current: Integer, max: Integer}
    getSpringCount()     → Integer
    getCurrentForm()     → FormData
    getActiveCharms()    → List<CharmData>
    getGeoAmount()       → Integer
}

Interface IBossHUDProvider {
    getBossHP()          → {current: Integer, max: Integer}
    getBossPhaseCount()  → Integer
    getBossPhaseThresholds() → List<Number>  // 各阶段 HP 百分比
    getBossName()        → String
}
```

UI 监听事件更新显示，不轮询接口（接口仅供初始化或主动请求使用）。

---

## 6. UI 事件目录

| 事件 | 触发者 | UI 响应 |
|------|--------|---------|
| `OnPlayerHPChanged` | 玩家系统 | 刷新 HP 格子 |
| `OnPlayerSoulChanged` | 玩家系统 | 刷新灵力条 |
| `OnPlayerSpiritChanged` | 玩家系统 | 刷新魄元条 |
| `OnSpringCountChanged` | 玩家系统 | 刷新灵泉图标 |
| `OnFormChanged` | 形态系统 | 刷新形态指示 |
| `OnBossEncounterBegin` | 世界系统 | 显示 Boss 血条 |
| `OnBossHPChanged` | Boss | 刷新 Boss 血条 |
| `OnBossPhaseChanged` | Boss | Boss 血条阶段标记动画 |
| `OnBossDefeated` | Boss | 隐藏 Boss 血条（动画）|
| `OnSkillCooldownUpdated` | 技能系统 | 刷新技能冷却遮罩 |
| `OnCharmEquipped` | 进程系统 | 刷新护符栏 |
| `OnNotification` | 任意系统 | 显示弹出通知 |
| `OnMenuOpen` | 输入系统 | 打开暂停菜单 |
| `OnDialogueStarted` | 叙事系统 | 显示对话框 |
| `OnDialogueEnded` | 叙事系统 | 隐藏对话框 |