zeling_v2/Docs/DesignSpec/10_UISystem.md

10 · UI 系统规范

所属文档集 ← 返回索引
摘要：游戏 UI 分层架构、HUD 元素规范、菜单系统与 UI 事件契约。

---

目录

1. UI 设计原则
2. UI 分层架构
3. HUD 规范
4. 菜单系统
5. 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	叙事系统	隐藏对话框