# 10 · UI 系统

> **命名空间** `BaseGames.UI`  
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
> **依赖** `BaseGames.Core.Events` · `BaseGames.Combat`（Boss HP）· TextMeshPro · DOTween（P1 过渡动画）

---

## 目录

1. [设计原则](#1-设计原则)
2. [Canvas 架构](#2-canvas-架构)
3. [UIManager](#3-uimanager)
4. [HUD 组件](#4-hud-组件)
5. [Boss HP 条](#5-boss-hp-条)
6. [主菜单（MainMenu）](#6-主菜单mainmenu)
7. [Pause 菜单](#7-pause-菜单)
8. [死亡画面](#8-死亡画面)
9. [加载过渡遮罩](#9-加载过渡遮罩)
10. [设置菜单](#10-设置菜单)
11. [UI 事件频道](#11-ui-事件频道)
12. [编辑器友好设计](#12-编辑器友好设计)
13. [加载画面（Loading Screen）](#13-加载画面loading-screen)
14. [无障碍设计（Accessibility）](#14-无障碍设计accessibility)
15. [UIManager 解耦改进说明](#15-uimanager-解耦改进说明)
16. [存档点交互 & 存档槽选择界面](#16-存档点交互--存档槽选择界面)
17. [存档进行中指示（Save Indicator）](#17-存档进行中指示save-indicator)
18. [通知系统（Toast / 成就 / 任务）](#18-通知系统toast--成就--任务)
19. [HUD 扩展：工具槽 & 形态指示](#19-hud-扩展工具槽--形态指示)
20. [全屏功能界面索引](#20-全屏功能界面索引)
21. [UI 音效系统](#21-ui-音效系统)
22. [控制器导航 & 面板栈](#22-控制器导航--面板栈)
23. [输入设备图标自动切换](#23-输入设备图标自动切换)
24. [浮动战斗文字（伤害数字）](#24-浮动战斗文字伤害数字)
25. [HUD 自适应可见性 & 过场隐藏](#25-hud-自适应可见性--过场隐藏)
26. [安全区（Safe Area）适配](#26-安全区safe-area适配)
27. [首次启动序列（Logo & 法务公告）](#27-首次启动序列logo--法务公告)
28. [PC 平台光标管理](#28-pc-平台光标管理)
29. [本地化深度集成](#29-本地化深度集成)

---

## 1. 设计原则

- **状态驱动**：`UIManager` 监听 `GameState` 变化，自动激活/隐藏对应 Canvas Root，由中央管理器决定何时显示什么
- **像素风适配**：UI 字体使用 TextMeshPro + 像素字体，UI 元素整数像素对齐，Canvas Scaler 使用 `Scale With Screen Size`（参考分辨率 1920×1080）
- **零耦合**：HUD 只订阅事件频道（`OnPlayerHPChanged`、`OnPlayerSoulChanged`），不持有 `PlayerStats` 直接引用
- **分层 Canvas**：HUD / Menu / Overlay 三个独立 Canvas，各自管理 Sorting Order，互不干扰

---

## 2. Canvas 架构

所有 UI Canvas 挂载在 **Persistent 场景**中，随游戏全程常驻：

```
[UI Root]                         ← Persistent 场景内
├── Canvas_HUD       Sorting Order: 10   (Screen Space - Overlay)
├── Canvas_Menu      Sorting Order: 20   (Screen Space - Overlay)
└── Canvas_Overlay   Sorting Order: 30   (Screen Space - Overlay，最顶层)
```

### Canvas_HUD 子结构

```
Canvas_HUD
├── HUDPanel                 (RectTransform: 全屏铺满)
│   ├── HPContainer          (左上角，心形容器列表，水平布局组)
│   ├── SoulGauge            (下方居中，弧形灵魂槽)
│   ├── GeoCounter           (右上角，Geo 图标 + TextMeshPro 数字)
│   └── AbilityHint          (右下角，P1：当前解锁能力图标列)
└── BossHPBar                (下方居中，默认隐藏，Boss 战激活)
    ├── BossNameText         (TextMeshPro)
    ├── HPBarBackground      (Image)
    ├── HPBarFill            (Image，FillAmount 驱动)
    └── PhaseMarkers         (P1：阶段分割线列表)
```

### Canvas_Menu 子结构

```
Canvas_Menu
├── MainMenuPanel            (默认激活)
│   ├── TitleImage
│   ├── MenuButtonGroup      (垂直布局)
│   └── VersionText
├── PauseMenuPanel           (默认隐藏)
├── DeathScreenPanel         (默认隐藏)
└── SettingsPanel            (默认隐藏，从主菜单/暂停菜单叠加打开)
```

### Canvas_Overlay 子结构

```
Canvas_Overlay
├── LoadingOverlay           (黑色全屏 Image，默认 alpha=0)
│   └── LoadingSpinner       (P1：旋转加载动画)
└── DialogueBox              (底部，默认隐藏；见 15_DialogueSystem.md)
    ├── SpeakerNameText
    ├── DialogueText
    └── ContinuePrompt
```

---

## 3. UIManager

`UIManager` 常驻 Persistent 场景，订阅 `GameState` 变化事件并驱动 Canvas 显隐。

### 类结构

```csharp
namespace BaseGames.UI
{
    [DefaultExecutionOrder(+50)]
    public class UIManager : MonoBehaviour
    {
        [Header("Canvas Roots")]
        [SerializeField] GameObject _hudRoot;
        [SerializeField] GameObject _pauseMenuRoot;
        [SerializeField] GameObject _mainMenuRoot;
        [SerializeField] GameObject _deathScreenRoot;
        [SerializeField] GameObject _settingsPanel;
        [SerializeField] LoadingOverlay _loadingOverlay;

        [Header("Event Channels")]
        [SerializeField] GameStateEventChannelSO _onGameStateChanged;

        // 公开接口（供 GameManager Coroutine 调用）
        public IEnumerator FadeIn()  => _loadingOverlay.FadeIn();
        public IEnumerator FadeOut() => _loadingOverlay.FadeOut();
        public void OpenSettings()   => _settingsPanel.SetActive(true);
        public void CloseSettings()  => _settingsPanel.SetActive(false);

        void OnEnable()  => _onGameStateChanged.OnEventRaised += HandleGameStateChanged;
        void OnDisable() => _onGameStateChanged.OnEventRaised -= HandleGameStateChanged;

        void HandleGameStateChanged(GameState newState)
        {
            _hudRoot.SetActive(newState is GameState.Gameplay or GameState.BossFight);
            _pauseMenuRoot.SetActive(newState == GameState.Paused);
            _mainMenuRoot.SetActive(newState == GameState.MainMenu);
            _deathScreenRoot.SetActive(newState == GameState.Dead);
        }
    }
}
```

### GameStateEventChannelSO

新增事件频道类型（`BaseGames.Core.Events`）：

```csharp
[CreateAssetMenu(menuName = "Events/GameState Channel")]
public class GameStateEventChannelSO : ScriptableObject
{
    public event Action<GameState> OnEventRaised;
    public void Raise(GameState state) => OnEventRaised?.Invoke(state);
}
```

---

## 4. HUD 组件

### 4.1 HP 心形容器（HPContainer）

HP 以**心形图标列**表示，而非连续血条（像素风标准做法）：

```csharp
public class HPContainer : MonoBehaviour
{
    [SerializeField] IntEventChannelSO _onHPChanged;
    [SerializeField] IntEventChannelSO _onMaxHPChanged;
    [SerializeField] GameObject _heartPrefab;       // 完整心 Sprite
    [SerializeField] Sprite _heartEmptySprite;      // 空心 Sprite（替换 Image.sprite）

    // Start() → 根据 SaveData.maxHP 生成心形图标列表
    // OnHPChanged(int newHP) → 更新填充/空心数量，对应位置播放消失动画
    // OnMaxHPChanged(int newMax) → 动态添加新心形图标（Heart Container 升级时）
}
```

| 状态 | 显示 | 动画 |
|------|------|------|
| `HP == MaxHP` | 全部填充心 | 无 |
| `HP < MaxHP` | 右侧显示空心 | 受伤时对应心图标 Shake（`MMF_Position`）|
| `HP == 0` | 全部空心 | 最后一颗心 Scale 缩小到 0（`MMF_Scale`）|
| MaxHP 增加 | 新心从右侧弹入 | 弹入动画（`MMF_Scale` 0→1）|

行宽规则：最多 8 个心/行，超出自动换行（最多 3 行，即 MaxHP 上限 24）。

---

### 4.2 Soul 灵魂槽（SoulGauge）

弧形进度条，`Image.type = Filled`，`Fill Method = Radial 360`：

```
SoulGauge (Image)
  fillAmount = Soul / MaxSoul（0.0 ~ 1.0）
  颜色渐变：  0%  → 深蓝灰 (#1A1A2E)
             50%  → 蓝色   (#4A90E2)
            100%  → 亮蓝白 (#8BE8FF)
  满槽特效：  MMF_Flash 白色光晕 0.1s（订阅 OnPlayerSoulChanged 满时触发）
```

订阅 `OnPlayerSoulChanged.asset (IntEventChannelSO)`，每帧不直接 Lerp，而是在收到事件时**立即更新** fillAmount（像素风不需要血条追尾）。

---

### 4.3 Geo 计数器（GeoCounter）

```
GeoCounter
├── GeoIcon      (Sprite Image，Geo 硬币图标)
└── GeoText      (TextMeshPro，白色 + 黑色描边，像素字体)

拾取弹出：FloatingText（"+N"）从 GeoIcon 位置飞出并淡出（ObjectPool 驱动）
数字更新：直接 SetText，不做 Tween（像素风即时更新风格）
```

订阅 `OnPlayerGeoChanged.asset (IntEventChannelSO)`。

---

## 5. Boss HP 条

Boss 战开始时从屏幕下方滑入，Boss 死亡后延迟 1s 淡出隐藏：

```csharp
public class BossHPBar : MonoBehaviour
{
    [SerializeField] BoolEventChannelSO  _onBossFightToggled;  // true=开始，false=结束
    [SerializeField] IntEventChannelSO   _onBossHPChanged;
    [SerializeField] StringEventChannelSO _onBossNameSet;

    [SerializeField] Image       _hpBarFill;
    [SerializeField] TMP_Text    _bossNameText;
    [SerializeField] RectTransform _barRoot;

    int _maxHP;

    void OnBossFightToggled(bool started)
    {
        if (started) StartCoroutine(SlideIn());   // barRoot.anchoredPosition.y: -80 → 0（0.4s）
        else          StartCoroutine(SlideOut());  // 延迟 1s → y: 0 → -80（0.3s）
    }

    void OnBossHPChanged(int hp) => _hpBarFill.fillAmount = (float)hp / _maxHP;
}
```

**P1 扩展**：`PhaseMarkers`——根据 `BossPhaseConfigSO` 的 HP 阈值在 HP 条上绘制分割竖线（`UI.Image` 子对象，按比例定位）。

---

## 6. 主菜单（MainMenu）

### 布局

```
MainMenuPanel
├── TitleImage            (像素艺术标题图，居中偏上)
├── MenuButtonGroup       (垂直布局，居中)
│   ├── Button_NewGame
│   ├── Button_Continue   (无存档时 interactable=false，颜色变灰)
│   ├── Button_Settings
│   └── Button_Quit
└── VersionText           (右下角，TextMeshPro 小字)
```

### 存档槽选择

点击 Continue 时，若存在多存档槽（最多 3 个），弹出存档槽选择面板：

```
SaveSlotPanel              (叠在 MainMenuPanel 上方)
├── SaveSlot_01            [区域名 | 游戏时长 | HP容器数 | 进度%]
├── SaveSlot_02
├── SaveSlot_03
└── Button_Back
```

单存档模式（MVP）：只有 1 个槽，Continue 直接加载，不弹面板。

### 按钮响应

```
Button_NewGame    → SaveManager.DeleteSave() → GameManager.StartNewGame()
Button_Continue   → GameManager.LoadGame(slotIndex)
Button_Settings   → UIManager.OpenSettings()
Button_Quit       → Application.Quit()
```

---

## 7. Pause 菜单

通过 `InputReaderSO.PauseEvent`（`Escape` / 手柄 `Start`）触发：

```
PauseMenuPanel
├── PauseTitle              ("- PAUSED -"，像素字体)
├── ButtonGroup
│   ├── Button_Resume       → GameManager.ResumeGame()
│   ├── Button_Settings     → UIManager.OpenSettings()
│   └── Button_QuitToMenu   → 弹出确认对话框 → GameManager.QuitToMainMenu()
└── InputHints              (底部图标提示："[ESC] 继续 [Q] 退出")
```

**时间缩放**：Pause 时 `Time.timeScale = 0`。所有菜单 `MMF_Player` 设置 `TimescaleIndependent = true`（Feel 已内置该选项），保证菜单弹入动画不受暂停影响。

---

## 8. 死亡画面

```
DeathScreenPanel           (全屏黑底 CanvasGroup，alpha 从 0 渐入到 1)
├── DeathText              ("你死了"，像素大字，慢速淡入，delay 0.3s)
├── GeoLostText            ("遗失 {N} Geo"，有 Shade 机制时显示；P1)
└── PromptText             ("按任意键继续"，1s 延迟后出现，闪烁循环)
```

**时序由 GameManager 协程控制**（详见 [11_GameManager.md §5](./11_GameManager.md)）：

| 时刻 | 事件 |
|------|------|
| 0.0s | `OnPlayerDied` 触发，`GameState → Dead`，DeathScreenPanel 开始渐入 |
| 1.2s | 玩家死亡动画结束 |
| 2.0s | DeathScreenPanel 完全可见（alpha=1） |
| 2.0s~ | 等待玩家按键（或 3s 超时自动继续） |
| +0.3s | LoadingOverlay 淡入遮盖 → 场景加载 → 淡出 |

---

## 9. 加载过渡遮罩

`LoadingOverlay` 是 `Canvas_Overlay` 下的全黑 `Image`，通过 `CanvasGroup.alpha` 控制淡入淡出：

```csharp
public class LoadingOverlay : MonoBehaviour
{
    [SerializeField] CanvasGroup _canvasGroup;
    [SerializeField] float _fadeDuration = 0.3f;

    public IEnumerator FadeIn()
    {
        _canvasGroup.gameObject.SetActive(true);
        float t = 0f;
        while (t < _fadeDuration)
        {
            _canvasGroup.alpha = t / _fadeDuration;
            t += Time.unscaledDeltaTime;   // 使用 unscaledDeltaTime，暂停/死亡时也能工作
            yield return null;
        }
        _canvasGroup.alpha = 1f;
    }

    public IEnumerator FadeOut()
    {
        float t = _fadeDuration;
        while (t > 0f)
        {
            _canvasGroup.alpha = t / _fadeDuration;
            t -= Time.unscaledDeltaTime;
            yield return null;
        }
        _canvasGroup.alpha = 0f;
        _canvasGroup.gameObject.SetActive(false);
    }
}
```

**使用方**：`SceneLoader` 在异步加载前调用 `yield return FadeIn()`，场景激活后调用 `yield return FadeOut()`。不由 `UIManager` 直接驱动，而是由 `GameManager` 协程在特定时序中显式调用。

---

## 10. 设置菜单

`SettingsPanel` 叠加在 MainMenuPanel 或 PauseMenuPanel 上方（Sorting Order 相同，z-order 靠后）：

```
SettingsPanel
├── Tab_Audio
│   ├── Slider_MasterVolume    (0.0 ~ 1.0，初始值读自 SettingsManager)
│   ├── Slider_BGMVolume
│   ├── Slider_SFXVolume
│   └── Toggle_Haptics
├── Tab_Controls               (P1：键位重映射)
│   └── KeyBindingsList        (InputSystem PlayerInput rebind API)
├── Tab_Display                (P1)
│   ├── Toggle_PixelPerfect
│   └── Dropdown_Resolution
└── Button_Back                → UIManager.CloseSettings()，保存设置
```

### 音量应用逻辑

```csharp
// SettingsUI.cs
// Slider.onValueChanged → AudioManager.SetBGMVolume(value)
//                       → audioMixer.SetFloat("BGMVolume", LinearToDecibel(value))
//
// 线性值 → 分贝转换：
float LinearToDecibel(float linear)
    => linear > 0.0001f ? 20f * Mathf.Log10(linear) : -80f;
```

设置持久化通过 `SettingsManager`（独立于存档，写入 `Application.persistentDataPath/settings.json`）。

---

## 11. UI 事件频道

新增频道（存放于 `Assets/ScriptableObjects/Events/UI/`）：

| 资产名 | 类型 | 用途 |
|--------|------|------|
| `OnGameStateChanged.asset` | `GameStateEventChannelSO` | UIManager 监听，驱动 Canvas 切换 |
| `OnMaxHPChanged.asset` | `IntEventChannelSO` | HPContainer 增加心形图标 |
| `OnBossHPChanged.asset` | `IntEventChannelSO` | BossHPBar 更新 fillAmount |
| `OnBossNameSet.asset` | `StringEventChannelSO` | BossHPBar 显示 Boss 名称 |
| `OnBossHPMaxSet.asset` | `IntEventChannelSO` | BossHPBar 初始化 MaxHP |

> `OnBossFightToggled.asset`（BoolEventChannelSO）已存在于 `Events/Camera/`，BossHPBar 直接复用。

---

## 12. 编辑器友好设计

- `UIManager` Custom Inspector：实时显示当前 GameState 文字标签 + 各 Canvas Root 激活状态（绿/红标记）
- Editor Only 测试按钮（UI Toolkit `Button` + `Toggle`，`CreateInspectorGUI()` 中实现）：
  - `[Simulate: Gameplay]` — 模拟进入 Gameplay 状态（测试 HUD 显示）
  - `[Simulate: Dead]` — 模拟死亡（测试 DeathScreen 渐入）
  - `[Simulate: Boss Start]` — 模拟 Boss 战开始（测试 BossHPBar 滑入）
- UI Prefab 存放：`Assets/Prefabs/UI/` 按模块分子文件夹（HUD / Menus / Overlays）
- RectTransform 规范：按设计区域固定锚点（左上/居中/右上），禁止拉伸式动态布局，防止不同分辨率下错位

---

## 13. 加载画面（Loading Screen）

### 13.1 组件布局

```
Canvas_Overlay
└── LoadingScreen（默认 SetActive(false)）
    ├── Background_Art     → 黑色基底 + 加载时随机区域概念图（Sprite）
    ├── ProgressBar
    │   ├── ProgressBarBG  → 灰色底条
    │   └── ProgressBarFill→ 白色填充（Image.fillAmount）
    ├── TipText            → TextMeshPro，显示游戏技巧
    └── LoadingIcon        → 旋转的像素风齿轮（DOTween Rotate 无限）
```

### 13.2 LoadingScreenManager

```csharp
public class LoadingScreenManager : MonoBehaviour
{
    [SerializeField] GameObject _root;
    [SerializeField] Image      _progressFill;
    [SerializeField] TMP_Text   _tipText;
    [SerializeField] Sprite[]   _backgroundArts;   // 各区域概念图
    [SerializeField] string[]   _tipKeys;           // LocalizationKeys（游戏技巧）

    [SerializeField] VoidEventChannelSO   _onLoadingStarted;
    [SerializeField] VoidEventChannelSO   _onLoadingComplete;
    [SerializeField] FloatEventChannelSO  _onLoadingProgressUpdated;
    [SerializeField] LanguageManagerSO    _langMgr;

    void OnEnable()
    {
        _onLoadingStarted.OnEventRaised          += Show;
        _onLoadingComplete.OnEventRaised         += Hide;
        _onLoadingProgressUpdated.OnEventRaised  += UpdateProgress;
    }

    void OnDisable()
    {
        _onLoadingStarted.OnEventRaised          -= Show;
        _onLoadingComplete.OnEventRaised         -= Hide;
        _onLoadingProgressUpdated.OnEventRaised  -= UpdateProgress;
    }

    void Show()
    {
        _root.SetActive(true);
        // 随机背景
        _root.GetComponentInChildren<Image>().sprite =
            _backgroundArts[Random.Range(0, _backgroundArts.Length)];
        // 随机提示
        string key = _tipKeys[Random.Range(0, _tipKeys.Length)];
        _tipText.text = _langMgr.Get(key, "UI_Table");
        _progressFill.fillAmount = 0f;
    }

    void Hide()
    {
        // 先确保进度条跑满再淡出
        DOTween.To(() => _progressFill.fillAmount, v => _progressFill.fillAmount = v, 1f, 0.2f)
            .OnComplete(() => _root.SetActive(false));
    }

    void UpdateProgress(float progress)
        => _progressFill.fillAmount = progress;
}
```

### 13.3 游戏技巧文本（Localization）

提示字符串统一放在 `UI_Table` 中，键名格式 `ui.loading.tip.{index}`（0~19）：

```
ui.loading.tip.0 = "弹反成功可以回复灵魂值"
ui.loading.tip.1 = "按住方向键向下可以穿过单向平台"
ui.loading.tip.2 = "冥影会守护你离开的地方——记得取回你的 Geo"
ui.loading.tip.3 = "壁跳需要连续交替踩两侧墙壁才能持续上升"
// ... 更多提示
```

---

## 14. 无障碍设计（Accessibility）

### 14.1 色盲模式

提供三种色盲辅助模式，通过 URP 后处理 Volume 切换：

| 模式 | Volume Override | 说明 |
|------|----------------|------|
| 关闭（默认） | None | 原始色彩 |
| 色盲模式 A（红绿色盲）| `CC_Deuteranopia.asset` | 使用蓝黄色调区分敌我 |
| 色盲模式 B（蓝黄色盲）| `CC_Tritanopia.asset` | 使用红绿色调区分 |
| 高对比度 | `CC_HighContrast.asset` | 边缘增强 + 提高对比度 |

```csharp
public class AccessibilityManager : MonoBehaviour
{
    [SerializeField] Volume[] _colorBlindVolumes;  // 索引对应 AccessibilityMode 枚举
    [SerializeField] AccessibilitySettingsSO _settings;

    public void SetColorBlindMode(int modeIndex)
    {
        for (int i = 0; i < _colorBlindVolumes.Length; i++)
            _colorBlindVolumes[i].weight = (i == modeIndex) ? 1f : 0f;

        _settings.colorBlindMode = modeIndex;
        PlayerPrefs.SetInt("ColorBlindMode", modeIndex);
    }
}
```

### 14.2 难度辅助选项

| 选项 | 默认 | 说明 |
|------|------|------|
| 无敌帧时长 | 1.8s（正常） | 可调至 2.5s（辅助）|
| 土狼时间 | 0.15s | 可调至 0.25s（辅助）|
| 弹反窗口 | 0.28s | 可调至 0.45s（辅助）|
| 输入缓冲 | 见 §23 | 可整体 +50%（辅助）|
| 死亡惩罚 | 掉落 Geo + 生成 Shade | 可设"仅重生无其他惩罚"（辅助）|

这些选项存储于 `AccessibilitySettingsSO`，不写入存档（账户级设置），通过 `PlayerPrefs` 持久化。

### 14.3 字幕与文本

- 对话中 NPC 名称用颜色区分（色盲模式下替换为形状图标区分）
- 字体大小可在设置页调整（Small/Normal/Large，对应 TMP 字体大小 × 0.85 / 1.0 / 1.2）
- 所有 UI 动画支持"减少动态效果"选项（关闭非关键过渡动画，仅保留淡入淡出）

### 14.4 手柄震动控制

```
设置 > 游戏手感 > 手柄震动
  整体震动强度: [0% ─────────●────── 100%]（默认 80%）
  攻击命中:  [✓] 开启
  受到伤害:  [✓] 开启
  BOSS 演出: [✓] 开启
  行走震动:  [ ] 关闭（默认关闭，避免疲劳）
```

震动设置乘以 `PlayerPrefs.GetFloat("VibrationMultiplier", 0.8f)` 后传入 Lofelt Nice Vibrations API。

### 14.5 键位自定义（控制重映射）

`10_UISystem §10` 的设置菜单扩展：

```
设置 > 按键设置 > 控制器  /  键鼠
  [按下想要修改的操作，然后按目标按键/键位...]
  
  操作          当前绑定      默认绑定
  攻击          [J]           [Z]
  跳跃          [K]           [X]
  冲刺          [L]           [C]
  弹反          [U]           [A]
  ...
  [恢复默认]
```

通过 `PlayerInput` 的 `InputActionRebindingExtensions.PerformInteractiveRebinding()` 实现，绑定存储于 `PlayerPrefs["InputBindings_Controller"]`（JSON 格式）。

---

## 15. UIManager 解耦改进说明

### 15.1 当前依赖关系与问题

`UIManager` 目前通过 `asmdef` 依赖 `BaseGames.Combat`，原因是 **BossHP 条需要读取 `DamageInfo`**（当前 HP / Max HP 来自 Boss 的 `EnemyStats`）。

```
BaseGames.UI.asmdef
  └── 依赖: BaseGames.Core · BaseGames.Combat  ← 仅为 BossHP 条
```

这带来潜在风险：若 UI 层将来需要引用 Dialogue、Equipment 等系统，可能形成循环依赖（Combat 不应反向依赖 UI）。

### 15.2 改进方案：IBossHPProvider 接口

将 Boss HP 信息通过接口隔离，UI 只依赖接口，不依赖 Combat 层：

```csharp
// Assets/Scripts/Core/Interfaces/IBossHPProvider.cs
// 归属: BaseGames.Core.asmdef（接口层，所有系统均可访问）
namespace BaseGames.Core
{
    public interface IBossHPProvider
    {
        int   CurrentHP  { get; }
        int   MaxHP      { get; }
        int   PhaseCount { get; }
        int   CurrentPhase { get; }
        float NormalizedHP => (float)CurrentHP / MaxHP;

        event System.Action<int, int> OnHPChanged;  // (current, max)
        event System.Action<int>      OnPhaseChanged;
    }
}
```

```csharp
// EnemyBase（Combat 层）实现接口
public class EnemyBase : MonoBehaviour, IBossHPProvider { /* ... */ }

// BossHPBar（UI 层）仅依赖接口，不 using BaseGames.Combat
public class BossHPBar : MonoBehaviour
{
    IBossHPProvider _boss;

    // 由 BossEventChannelSO 传入（泛型参数改为 IBossHPProvider）
    [SerializeField] BossEventChannelSO _onBossFightStarted;

    void OnEnable()
        => _onBossFightStarted.OnEventRaised += RegisterBoss;

    void RegisterBoss(IBossHPProvider boss)
    {
        _boss = boss;
        _boss.OnHPChanged += UpdateBar;
    }
}
```

### 15.3 迁移路径

改动成本较低，分两步完成：

| 步骤 | 操作 | 影响范围 |
|------|------|---------|
| 1 | 在 `BaseGames.Core.asmdef` 中新增 `IBossHPProvider` 接口文件 | 仅新增文件 |
| 2 | `EnemyBase` 实现 `IBossHPProvider`，`BossHPBar` 改为依赖接口 | `EnemyBase.cs` + `BossHPBar.cs` 各约 10 行改动 |
| 3 | `BaseGames.UI.asmdef` 的依赖列表中移除 `BaseGames.Combat` | 编辑 `.asmdef` 文件 |

> **P2 优先级**：当前 Combat → UI 路径并未造成循环依赖，改进非紧急。仅在 UI 层需要引入新的跨层依赖前执行。

---

## 16. 存档点交互 & 存档槽选择界面

### 16.1 存档点交互提示（InteractPrompt）

玩家靠近存档点时，在存档点上方显示交互提示气泡：

```
Canvas_Overlay
└── SavePointPrompt    (World Space Canvas，跟随存档点世界坐标)
    ├── PromptIcon     (键盘图标 [E] / 手柄图标 [South Button])
    └── PromptText     ("存档"，本地化键 ui.savepoint.interact)
```

交互后播放存档动画（主角坐下动画由 Animancer 控制），存档完成后显示"已保存"指示（见 §17）。

### 16.2 存档槽选择面板（SaveSlotPanel）

**触发时机**：主菜单点击「继续游戏」且存在多个有效存档槽时弹出。  
**Canvas 层级**：`Canvas_Menu`（Sorting Order 20），叠在 `MainMenuPanel` 上方。

```
SaveSlotPanel
├── Title                   ("选择存档"，像素字体)
├── SlotList                (垂直布局，3 个 SaveSlotCard)
│   ├── SaveSlotCard_0
│   ├── SaveSlotCard_1
│   └── SaveSlotCard_2
└── Button_Back
```

#### SaveSlotCard 布局

```
SaveSlotCard
├── BgImage                 (Image；异步加载 savePointBgImageKey Sprite；加载中显示占位色块)
│   └── BgDimOverlay        (半透明黑色蒙层，确保文字可读)
├── SlotEmptyPanel          (无存档时显示："空槽" + "[新游戏]" 按钮)
└── SlotDataPanel           (有存档时显示)
    ├── SavePointNameText   (TMP，查 savePointLocKey 本地化)
    ├── HPContainer         (心形图标列，只读展示)
    ├── PlaytimeText        ("游玩 Xh Xm"，由 playtime 秒格式化)
    ├── LastSavedText       ("最后存档：yyyy-MM-dd HH:mm"，UTC→本地时区转换)
    ├── NgPlusBadge         (仅 ngPlusCount > 0 时显示，"◆ NG+N" 金色标签)
    └── DeleteButton        (默认隐藏；长按 0.5s 触发确认弹窗)
```

#### SaveSlotCard C# 实现骨架

```csharp
public class SaveSlotCard : MonoBehaviour
{
    [SerializeField] Image        _bgImage;
    [SerializeField] TMP_Text     _savePointName;
    [SerializeField] HPContainer  _hpDisplay;      // 复用 HUD HPContainer（只读模式）
    [SerializeField] TMP_Text     _playtimeText;
    [SerializeField] TMP_Text     _lastSavedText;
    [SerializeField] GameObject   _ngPlusBadge;
    [SerializeField] TMP_Text     _ngPlusText;
    [SerializeField] GameObject   _emptyPanel;
    [SerializeField] GameObject   _dataPanel;
    [SerializeField] LanguageManagerSO _lang;

    public async void Bind(SaveSlotSummary summary)
    {
        if (summary == null)
        {
            _emptyPanel.SetActive(true);
            _dataPanel.SetActive(false);
            return;
        }

        _emptyPanel.SetActive(false);
        _dataPanel.SetActive(true);

        // 存档点名称（本地化）
        _savePointName.text = _lang.Get(summary.Meta.SavePointLocKey, "UI_Table");

        // 游玩时长格式化
        int totalMin = (int)(summary.Meta.Playtime / 60);
        _playtimeText.text = $"游玩 {totalMin / 60}h {totalMin % 60}m";

        // 最后存档时间（UTC → 本地时区）
        if (DateTimeOffset.TryParse(summary.Meta.LastSaved, out var dt))
            _lastSavedText.text = $"最后存档：{dt.LocalDateTime:yyyy-MM-dd HH:mm}";

        // HP 展示
        _hpDisplay.SetReadOnly(summary.Player.CurrentHP, summary.Player.MaxHP);

        // NG+ 标记
        bool isNgPlus = summary.Meta.NgPlusCount > 0;
        _ngPlusBadge.SetActive(isNgPlus);
        if (isNgPlus) _ngPlusText.text = $"NG+{summary.Meta.NgPlusCount}";

        // 背景图（Addressable 异步加载，不阻塞主线程）
        if (!string.IsNullOrEmpty(summary.Meta.SavePointBgImageKey))
        {
            var handle = Addressables.LoadAssetAsync<Sprite>(summary.Meta.SavePointBgImageKey);
            _bgImage.sprite = await handle.Task;
        }
    }
}
```

**删除确认弹窗**：

```
ConfirmDeleteDialog
├── TitleText    ("确认删除存档？此操作不可撤销")
├── Button_Yes   → SaveManager.DeleteSlotAsync(slot) → RefreshPanel()
└── Button_Cancel
```

---

## 17. 存档进行中指示（Save Indicator）

存档触发（存档点交互 / `WriteDirty`）后，在 HUD 右下角显示短暂存档状态动画：

```
Canvas_HUD
└── SaveIndicator               (右下角，默认 CanvasGroup.alpha=0)
    ├── SaveIcon                (旋转像素风图标，DOTween 持续旋转)
    └── SaveText                ("正在保存..." / "已保存")
```

```csharp
public class SaveIndicator : MonoBehaviour
{
    [SerializeField] CanvasGroup   _cg;
    [SerializeField] TMP_Text      _text;
    [SerializeField] RectTransform _icon;

    [SerializeField] BoolEventChannelSO _onSaveStateChanged; // true=成功

    void OnEnable()  => _onSaveStateChanged.OnEventRaised += OnSaveState;
    void OnDisable() => _onSaveStateChanged.OnEventRaised -= OnSaveState;

    public void ShowSaving()
    {
        _text.text = "正在保存...";
        _cg.DOFade(1f, 0.15f);
        _icon.DORotate(new Vector3(0, 0, -360f), 1f, RotateMode.FastBeyond360)
             .SetLoops(-1).SetEase(Ease.Linear);
    }

    void OnSaveState(bool success)
    {
        _icon.DOKill();
        _text.text = success ? "已保存" : "保存失败";
        DOTween.Sequence()
            .AppendInterval(1.2f)
            .Append(_cg.DOFade(0f, 0.3f));
    }
}
```

`SaveManager.SaveAsync` 开始前通过 `OnSaveStarted`（`VoidEventChannelSO`）触发 `ShowSaving()`，结束后通过 `OnSaveStateChanged` 传递成功/失败结果。

---

## 18. 通知系统（Toast / 成就 / 任务）

### 18.1 架构

```
Canvas_Overlay
└── NotificationArea              (右上角，垂直布局，最多 3 条并排)
    └── [NotificationCard]        (动态生成，ObjectPool 管理)
        ├── IconImage
        ├── TitleText
        └── BodyText
```

### 18.2 通知类型与持续时间

| 类型 | 触发时机 | 持续时间 |
|------|---------|--------|
| `SaveComplete` | 存档成功后 | 1.5s |
| `Achievement` | 成就解锁 | 4s |
| `QuestNew` | 接取新任务 | 3s |
| `QuestUpdate` | 任务目标推进 | 2.5s |
| `QuestComplete` | 任务完成 | 3.5s |
| `SystemWarning` | 存档失败等错误 | 5s |

### 18.3 NotificationManager

```csharp
[DefaultExecutionOrder(+60)]
public class NotificationManager : MonoBehaviour
{
    [SerializeField] NotificationCard   _cardPrefab;
    [SerializeField] Transform          _area;
    [SerializeField] int                _maxVisible = 3;

    [SerializeField] BoolEventChannelSO    _onSaveStateChanged;
    [SerializeField] StringEventChannelSO  _onAchievementUnlocked;
    [SerializeField] StringEventChannelSO  _onQuestNew;
    [SerializeField] StringEventChannelSO  _onQuestUpdated;
    [SerializeField] StringEventChannelSO  _onQuestCompleted;

    readonly Queue<NotificationData> _queue = new();

    void OnEnable()
    {
        _onSaveStateChanged.OnEventRaised    += ok =>
            Enqueue(ok ? NotificationType.SaveComplete : NotificationType.SystemWarning,
                    ok ? "已保存" : "存档失败");
        _onAchievementUnlocked.OnEventRaised += id => Enqueue(NotificationType.Achievement, id);
        _onQuestNew.OnEventRaised            += id => Enqueue(NotificationType.QuestNew, id);
        _onQuestUpdated.OnEventRaised        += id => Enqueue(NotificationType.QuestUpdate, id);
        _onQuestCompleted.OnEventRaised      += id => Enqueue(NotificationType.QuestComplete, id);
    }

    void Enqueue(NotificationType type, string payload)
    {
        _queue.Enqueue(new(type, payload));
        TryShowNext();
    }

    void TryShowNext()
    {
        if (_area.childCount >= _maxVisible || _queue.Count == 0) return;
        var card = Instantiate(_cardPrefab, _area);
        card.Show(_queue.Dequeue(), OnCardDismissed);
    }

    void OnCardDismissed() => TryShowNext();
}
```

### 18.4 NotificationCard 动画

右侧滑入 → 停留 → 淡出右侧退出：

```csharp
public void Show(NotificationData data, Action onDone)
{
    _icon.sprite    = IconLibrary.Get(data.Type);
    _titleText.text = LocalizationHelper.GetNotificationTitle(data);
    _bodyText.text  = LocalizationHelper.GetNotificationBody(data);

    DOTween.Sequence()
        .Append(transform.DOLocalMoveX(0, 0.2f).From(220f).SetEase(Ease.OutCubic))
        .AppendInterval(NotificationDurations[data.Type])
        .Append(_cg.DOFade(0f, 0.25f))
        .OnComplete(() => { onDone?.Invoke(); Destroy(gameObject); });
}
```

---

## 19. HUD 扩展：工具槽 & 形态指示

### 19.1 工具槽 HUD（ToolSlotHUD）

详细设计见 [37_ToolSystem](./37_ToolSystem.md)。Canvas 挂载：

```
Canvas_HUD
└── ToolSlotHUD              (右下角，水平布局)
    ├── ToolSlot_0
    │   ├── ToolIconBg       (槽位背景框)
    │   ├── ToolIcon         (当前工具图标；空槽显示占位图)
    │   └── CooldownOverlay  (圆形 FillAmount 冷却覆盖层)
    └── ToolSlot_1
        └── ...
```

- 订阅 `OnToolEquipped(int slot, string toolId)` 更新图标
- 订阅 `OnToolCooldownChanged(int slot, float normalized)` 更新冷却蒙层
- 当前激活槽白色描边高亮，非激活槽降低亮度

### 19.2 形态切换指示（FormIndicator）

详细设计见 [21_SpellSystem](./21_SpellSystem.md)。Canvas 挂载：

```
Canvas_HUD
└── FormIndicator            (左下角，灵魂槽右侧)
    ├── FormIconCurrent      (当前形态图标，全亮，Scale 略大)
    └── FormIconRow          (已解锁形态小图标列，切换时高亮目标)
```

- 订阅 `OnFormChanged(string formId)` 切换高亮图标
- 形态图标资产命名规范：`{formId}_Icon.png`，存放于 `Assets/Sprites/UI/Forms/`
- 切换时 Scale 0.8→1.0 脉冲动画（0.15s DOTween）

---

## 20. 全屏功能界面索引

以下全屏功能界面各有专属文档，本文档仅说明挂载点和打开方式：

| 界面 | 文档 | 打开方式 | Canvas 挂载 |
|------|------|---------|------------|
| **地图** | [16_MapSystem](./16_MapSystem.md) | 暂停内 / 快捷键 `M` | `Canvas_Menu` |
| **护符/装备** | [17_EquipmentSystem](./17_EquipmentSystem.md) | 暂停内 / 快捷键 `C` | `Canvas_Menu` |
| **技能/形态** | [21_SpellSystem](./21_SpellSystem.md) | 暂停内 | `Canvas_Menu` |
| **任务日志** | [38_QuestSystem](./38_QuestSystem.md) §QuestLogUI | 暂停内 / 快捷键 `J` | `Canvas_Menu` |
| **商店** | [28_ShopSystem](./28_ShopSystem.md) | NPC 交互触发 | `Canvas_Menu` |
| **对话框** | [15_DialogueSystem](./15_DialogueSystem.md) | 对话事件触发 | `Canvas_Overlay` |
| **挑战房间结算** | [39_ChallengeRoomSystem](./39_ChallengeRoomSystem.md) | 挑战完成事件 | `Canvas_Overlay` |
| **难度选择** | [29_DifficultyModesGuide](./29_DifficultyModesGuide.md) §9 | 新游戏流程 | `Canvas_Menu` |

**全屏界面统一规范**：

- 打开时 `Time.timeScale = 0`（对话框除外，对话框在游戏运行中叠加）
- 背景使用 `FullscreenDimOverlay`（`Canvas_Overlay` 下，`CanvasGroup.alpha = 0.65f`）
- 关闭时发送 `OnGameStateChanged(GameState.Gameplay)` 恢复时间缩放
- 所有全屏界面支持 `Escape` / 手柄 `East Button (B)` 关闭

---

## 21. UI 音效系统

所有 UI 交互均需音效反馈。统一通过 `UIAudioManager`（订阅 UI 事件频道）发声，**不在各 UI 组件中内嵌 AudioSource**，保证集中管理和统一调节。

### 21.1 音效事件表

| 触发时机 | 音效分类 | 资产键示例 | 备注 |
|---------|---------|----------|------|
| 按钮 Hover（鼠标 / 导航移入）| `ui_hover` | `SFX_UI_Hover` | 音量较小，避免密集重复刺耳 |
| 按钮 Click（确认）| `ui_confirm` | `SFX_UI_Confirm` | |
| 按钮 Click（取消/返回）| `ui_cancel` | `SFX_UI_Cancel` | |
| 面板 Open | `ui_panel_open` | `SFX_UI_PanelOpen` | |
| 面板 Close | `ui_panel_close` | `SFX_UI_PanelClose` | |
| 错误操作（不可用按钮）| `ui_error` | `SFX_UI_Error` | |
| 存档成功 | `ui_save_done` | `SFX_UI_SaveDone` | 轻柔提示音 |
| 成就解锁 | `ui_achievement` | `SFX_Achievement` | 较隆重的提示音 |
| Pause 开启 | `ui_pause` | `SFX_UI_Pause` | 时间停止感 |
| 死亡画面淡入 | `ui_death` | `SFX_UI_Death` | |

### 21.2 UIAudioManager

```csharp
[DefaultExecutionOrder(+55)]
public class UIAudioManager : MonoBehaviour
{
    [SerializeField] AudioSource _uiAudioSource;   // 独立 AudioMixer Group: UI
    [SerializeField] UISoundLibrarySO _library;    // ScriptableObject，键→AudioClip 映射

    // 事件频道订阅
    [SerializeField] StringEventChannelSO _onUISound;  // payload = 音效键名

    void OnEnable()  => _onUISound.OnEventRaised += Play;
    void OnDisable() => _onUISound.OnEventRaised -= Play;

    public void Play(string key)
    {
        if (_library.TryGet(key, out var clip))
            _uiAudioSource.PlayOneShot(clip);
    }
}
```

### 21.3 Button 组件扩展

```csharp
// UIButton.cs — 替换所有 UI 中的普通 Button 使用
[RequireComponent(typeof(Button))]
public class UIButton : MonoBehaviour, ISelectHandler, IPointerEnterHandler
{
    [SerializeField] string _hoverSound   = "ui_hover";
    [SerializeField] string _confirmSound = "ui_confirm";
    [SerializeField] StringEventChannelSO _onUISound;

    void Awake() => GetComponent<Button>().onClick.AddListener(
        () => _onUISound.Raise(_confirmSound));

    public void OnPointerEnter(PointerEventData _) => _onUISound.Raise(_hoverSound);
    public void OnSelect(BaseEventData _)           => _onUISound.Raise(_hoverSound);
}
```

> 不可交互按钮（`interactable = false`）点击时发送 `"ui_error"` 音效，在 `UIButton.OnPointerClick` 中通过 `!button.interactable` 判断触发。

### 21.4 AudioMixer 组

```
AudioMixer
└── Master
    ├── BGM
    ├── SFX_Gameplay
    └── SFX_UI          ← UI 独立通道，设置菜单中单独音量控制
```

---

## 22. 控制器导航 & 面板栈

### 22.1 EventSystem 导航规范

Unity EventSystem 的导航必须**显式配置**，不使用 `Automatic` 模式（`Automatic` 模式在复杂布局下跳跃不可预测）：

```
每个交互 Panel 规范：
1. Panel 激活时调用 EventSystem.SetSelectedGameObject(_firstSelected)
2. 所有 Button/Slider/Toggle 的 Navigation 设置为 Explicit
3. 最后一个元素的 Down 导航回到第一个（循环导航）
4. Panel 关闭时保存并还原前一 Panel 的焦点对象
```

```csharp
public class NavigablePanelBase : MonoBehaviour
{
    [SerializeField] GameObject _firstSelected;  // Inspector 中指定第一个获得焦点的元素

    protected virtual void OnEnable()
        => StartCoroutine(FocusNextFrame());   // 必须等一帧 EventSystem 才能接收

    IEnumerator FocusNextFrame()
    {
        yield return null;
        EventSystem.current?.SetSelectedGameObject(_firstSelected);
    }

    protected virtual void OnDisable()
        => EventSystem.current?.SetSelectedGameObject(null);
}
```

所有 Panel（`PauseMenuPanel`、`SettingsPanel`、`SaveSlotPanel` 等）继承 `NavigablePanelBase`。

### 22.2 面板栈（PanelStack）

解决「从暂停→设置→按 Back 应回到暂停而非主菜单」的问题：

```csharp
public class PanelStack : MonoBehaviour
{
    readonly Stack<(GameObject panel, GameObject prevFocus)> _stack = new();

    /// <summary>打开新面板，将当前面板推入栈</summary>
    public void Push(GameObject newPanel)
    {
        var prevFocus = EventSystem.current?.currentSelectedGameObject;

        if (_stack.TryPeek(out var top))
            top.panel.SetActive(false);   // 隐藏（不销毁）前面板

        _stack.Push((newPanel, prevFocus));
        newPanel.SetActive(true);
    }

    /// <summary>关闭当前面板，恢复上一层</summary>
    public void Pop()
    {
        if (_stack.Count == 0) return;

        var (cur, _) = _stack.Pop();
        cur.SetActive(false);

        if (_stack.TryPeek(out var prev))
        {
            prev.panel.SetActive(true);
            StartCoroutine(RestoreFocusNextFrame(prev.prevFocus));
        }
    }

    IEnumerator RestoreFocusNextFrame(GameObject focus)
    {
        yield return null;
        EventSystem.current?.SetSelectedGameObject(focus);
    }
}
```

**集成点**：`UIManager` 持有 `PanelStack` 引用，所有 `OpenSettings()`、`OpenSaveSlot()` 等调用改为 `_panelStack.Push(panel)`；所有 Back 按钮调用 `_panelStack.Pop()`。

### 22.3 手柄 Back 按钮全局处理

```csharp
// 在 InputReaderSO 中添加 UICancel 事件（对应手柄 East Button / 键盘 Escape）
// UIManager 订阅，调用 _panelStack.Pop()（若栈非空）
// 若栈为空且当前在 Pause 状态，则调用 ResumeGame()
```

---

## 23. 输入设备图标自动切换

多平台商业游戏要求按钮提示图标跟随**最后活跃输入设备**自动切换（键鼠 / Xbox / PS4 / PS5 / Switch）。

### 23.1 InputIconLibrarySO

```csharp
[CreateAssetMenu(menuName = "UI/Input Icon Library")]
public class InputIconLibrarySO : ScriptableObject
{
    [Serializable]
    public struct IconSet
    {
        public DeviceType device;
        public Sprite[] icons;   // 按 InputActionID 索引
    }

    public IconSet[] iconSets;

    public Sprite Get(DeviceType device, string actionId)
    {
        // 通过 actionId 查找对应图标
    }
}

public enum DeviceType { KeyboardMouse, Xbox, PlayStation4, PlayStation5, Switch }
```

### 23.2 InputDeviceDetector

```csharp
[DefaultExecutionOrder(-100)]
public class InputDeviceDetector : MonoBehaviour
{
    public static DeviceType Current { get; private set; } = DeviceType.KeyboardMouse;

    [SerializeField] DeviceTypeEventChannelSO _onDeviceChanged;

    void OnEnable()
        => InputSystem.onActionChange += OnActionChange;

    void OnDisable()
        => InputSystem.onActionChange -= OnActionChange;

    void OnActionChange(object obj, InputActionChange change)
    {
        if (change != InputActionChange.ActionPerformed) return;
        if (obj is not InputAction action) return;

        var device = action.activeControl?.device;
        var newType = device switch
        {
            Gamepad g when g.name.Contains("DualSense") || g.name.Contains("DualShock")
                => g.name.Contains("DualSense") ? DeviceType.PlayStation5 : DeviceType.PlayStation4,
            Gamepad g when g.name.Contains("Switch")
                => DeviceType.Switch,
            Gamepad => DeviceType.Xbox,
            _ => DeviceType.KeyboardMouse
        };

        if (newType != Current)
        {
            Current = newType;
            _onDeviceChanged.Raise(Current);
        }
    }
}
```

### 23.3 InputPromptImage 组件

替换所有显示按钮提示图标的 `Image`：

```csharp
public class InputPromptImage : MonoBehaviour
{
    [SerializeField] string _actionId;   // 如 "Jump"、"Attack"
    [SerializeField] Image _image;
    [SerializeField] InputIconLibrarySO _library;
    [SerializeField] DeviceTypeEventChannelSO _onDeviceChanged;

    void OnEnable()
    {
        _onDeviceChanged.OnEventRaised += Refresh;
        Refresh(InputDeviceDetector.Current);
    }

    void OnDisable() => _onDeviceChanged.OnEventRaised -= Refresh;

    void Refresh(DeviceType device)
        => _image.sprite = _library.Get(device, _actionId);
}
```

> 凡是在 InteractPrompt、PauseMenu、HUD 底部提示（InputHints）中出现的按键图标，均使用 `InputPromptImage` 而非静态 Sprite。

---

## 24. 浮动战斗文字（伤害数字）

### 24.1 设计规范

动作类游戏标配，以像素风格呈现：

| 类型 | 颜色 | 字号 | 动画 |
|------|------|------|------|
| 普通伤害 | 白色 | 16px | 向上飘动 0.6s + 淡出 |
| 暴击伤害 | 黄色 + 大 1.3× | 21px | 弹入(Scale 1.4→1) + 上飘 + 淡出 |
| 玩家受伤 | 红色 | 14px | 向上偏移 + 快速淡出 0.4s |
| 治疗 | 绿色 | 14px | 向上飘动 + 淡出 |
| 格挡/弹反 | 蓝色 | 16px | 晃动后淡出 |
| 免疫（弹反护体）| 灰色 | 12px | "IMMUNE" 文字，短暂显示 |

### 24.2 FloatingTextManager

```csharp
[DefaultExecutionOrder(+40)]
public class FloatingTextManager : MonoBehaviour
{
    [SerializeField] FloatingText    _prefab;
    [SerializeField] Transform       _worldCanvas;   // World Space Canvas，Sorting Order 15
    [SerializeField] Camera          _cam;

    [SerializeField] DamageInfoEventChannelSO _onDamageDealt;  // DamageInfo 包含伤害值、类型、世界坐标
    [SerializeField] HealInfoEventChannelSO   _onHealReceived;

    ObjectPool<FloatingText> _pool;

    void Awake() => _pool = new(Create, null, null, null, false, 20, 40);

    void OnEnable()
    {
        _onDamageDealt.OnEventRaised  += SpawnDamage;
        _onHealReceived.OnEventRaised += SpawnHeal;
    }

    void SpawnDamage(DamageInfo info)
    {
        var ft = _pool.Get();
        ft.transform.position = WorldToCanvasPos(info.WorldPosition);
        ft.Play(info.Amount.ToString(), DamageTypeToStyle(info.Type), () => _pool.Release(ft));
    }

    Vector3 WorldToCanvasPos(Vector3 worldPos)
    {
        var vp = _cam.WorldToViewportPoint(worldPos);
        var rt = _worldCanvas as RectTransform;
        return new Vector3(
            (vp.x - 0.5f) * rt.sizeDelta.x,
            (vp.y - 0.5f) * rt.sizeDelta.y,
            0f);
    }
}
```

### 24.3 FloatingText 动画

```csharp
public class FloatingText : MonoBehaviour
{
    [SerializeField] TMP_Text   _text;
    [SerializeField] CanvasGroup _cg;

    public void Play(string content, FloatingTextStyle style, Action onDone)
    {
        _text.text  = content;
        _text.color = style.color;
        transform.localScale = Vector3.one * style.scale;

        DOTween.Sequence()
            .Append(transform.DOLocalMoveY(transform.localPosition.y + style.riseY, style.duration)
                .SetEase(Ease.OutQuad))
            .Join(_cg.DOFade(0f, style.duration).SetDelay(style.duration * 0.4f))
            .OnComplete(() => onDone?.Invoke());
    }
}
```

---

## 25. HUD 自适应可见性 & 过场隐藏

### 25.1 过场/演出期间 HUD 隐藏

| 触发条件 | HUD 状态 | 过渡方式 |
|---------|---------|--------|
| 进入 Boss 开场演出 | 隐藏 | `CanvasGroup.DOFade(0, 0.3f)` |
| 演出结束（玩家可操控）| 显示 | `CanvasGroup.DOFade(1, 0.2f)` |
| 对话触发 | 隐藏（仅保留 DialogueBox）| 即时 |
| 加载场景 | 隐藏（被 LoadingOverlay 覆盖）| N/A |
| 死亡画面 | 隐藏 | DeathScreen 全覆盖 |

```csharp
public class HUDVisibilityController : MonoBehaviour
{
    [SerializeField] CanvasGroup _hudCg;

    [SerializeField] VoidEventChannelSO  _onCutsceneStarted;
    [SerializeField] VoidEventChannelSO  _onCutsceneEnded;
    [SerializeField] VoidEventChannelSO  _onDialogueStarted;
    [SerializeField] VoidEventChannelSO  _onDialogueEnded;

    void OnEnable()
    {
        _onCutsceneStarted.OnEventRaised += () => SetHUD(false, 0.3f);
        _onCutsceneEnded.OnEventRaised   += () => SetHUD(true,  0.2f);
        _onDialogueStarted.OnEventRaised += () => SetHUD(false, 0.15f);
        _onDialogueEnded.OnEventRaised   += () => SetHUD(true,  0.15f);
    }

    void SetHUD(bool visible, float duration)
    {
        _hudCg.DOFade(visible ? 1f : 0f, duration)
              .SetUpdate(true);   // 不受 timeScale 影响
        _hudCg.interactable    = visible;
        _hudCg.blocksRaycasts  = visible;
    }
}
```

### 25.2 非战斗 HUD 自动淡出（Hollow Knight 风格）

```
设置 > 游戏 > HUD 可见性：
  ○ 始终显示
  ● 非战斗时淡出（默认）
  ○ 仅受伤时显示
```

```csharp
public class HUDAutoFade : MonoBehaviour
{
    [SerializeField] CanvasGroup _hudCg;
    [SerializeField] float       _fadeDelay  = 4f;   // 离开战斗后 N 秒开始淡出
    [SerializeField] float       _fadedAlpha = 0.25f;

    [SerializeField] BoolEventChannelSO  _onInCombatChanged;  // true=进战斗,false=离开战斗
    [SerializeField] VoidEventChannelSO  _onPlayerDamaged;

    float _timer;
    bool  _inCombat;

    void OnEnable()
    {
        _onInCombatChanged.OnEventRaised += b => { _inCombat = b; if (b) ShowFull(); };
        _onPlayerDamaged.OnEventRaised   += ShowFull;
    }

    void ShowFull()
    {
        _hudCg.DOFade(1f, 0.15f);
        _timer = _fadeDelay;
    }

    void Update()
    {
        if (_inCombat) return;
        _timer -= Time.unscaledDeltaTime;
        if (_timer < 0f) _hudCg.DOFade(_fadedAlpha, 1.5f).SetUpdate(true);
    }
}
```

---

## 26. 安全区（Safe Area）适配

针对 iOS 刘海屏、Android 打孔屏、主机 TV 边距（Action-Safe Area），所有 HUD 内容必须在安全区内。

### 26.1 SafeAreaAnchor 组件

```csharp
/// <summary>
/// 挂载在 Canvas_HUD 的根 RectTransform 上，
/// 运行时根据 Screen.safeArea 自动调整 offsetMin/offsetMax。
/// </summary>
public class SafeAreaAnchor : MonoBehaviour
{
    RectTransform _rt;
    Rect          _lastSafeArea = Rect.zero;

    void Awake()  => _rt = GetComponent<RectTransform>();
    void Update() => ApplyIfChanged();

    void ApplyIfChanged()
    {
        var safe = Screen.safeArea;
        if (safe == _lastSafeArea) return;
        _lastSafeArea = safe;
        Apply(safe);
    }

    void Apply(Rect safe)
    {
        var screen = new Vector2(Screen.width, Screen.height);
        _rt.anchorMin = new Vector2(safe.xMin / screen.x, safe.yMin / screen.y);
        _rt.anchorMax = new Vector2(safe.xMax / screen.x, safe.yMax / screen.y);
        _rt.offsetMin = _rt.offsetMax = Vector2.zero;
    }
}
```

**挂载策略**：
- `Canvas_HUD` 的 `HUDPanel`：挂载 `SafeAreaAnchor`（心形容器/Geo 等不能被刘海遮挡）
- `Canvas_Menu`：**不挂载**（全屏菜单背景允许延伸到不安全区）
- `Canvas_Overlay`：**不挂载**（全屏遮罩需覆盖整个屏幕）

### 26.2 TV Safe Area 预设

对主机平台，在设置中提供「UI 边距」滑块（默认 0%，最高 10%），在 `SafeAreaAnchor` 基础上叠加额外边距：

```csharp
float tvMargin = PlayerPrefs.GetFloat("TVSafeMargin", 0f);  // 0.0~0.1
```

---

## 27. 首次启动序列（Logo & 法务公告）

商业发行必须在主菜单前展示发行商/开发商 Logo 及法律声明，且**不可跳过前 N 秒**（部分平台平台政策要求）。

### 27.1 启动流程

```
游戏启动
  ↓ [BootScene 加载]
  ↓ SplashSequenceManager 运行
  ├── 显示 Unity Logo（BuildSettings 中关闭时可省略）
  ├── 发行商 Logo（2.5s，0.5s 淡入 + 1.5s 停留 + 0.5s 淡出）
  ├── 开发商 Logo（2.0s，同上）
  ├── 技术许可声明（TextMeshPro 全屏，0.5s 后允许跳过）
  ├── 法务/评级声明（ESRB/CERO 评级图标，1s 后允许跳过）
  └── → AsyncLoadScene(MainMenuScene)
```

### 27.2 SplashSequenceManager

```csharp
public class SplashSequenceManager : MonoBehaviour
{
    [SerializeField] SplashEntry[] _entries;   // 可配置的 Logo 序列
    [SerializeField] CanvasGroup   _bg;
    [SerializeField] Image         _logo;
    [SerializeField] TMP_Text      _legalText;

    [Serializable]
    public struct SplashEntry
    {
        public Sprite  sprite;        // null 则显示 legalText
        public string  legalTextKey;  // 文字公告时使用
        public float   displayTime;
        public float   minBeforeSkip; // 最少显示时长（不可跳过）
    }

    async void Start()
    {
        foreach (var entry in _entries)
        {
            await ShowEntry(entry);
        }
        SceneManager.LoadSceneAsync("MainMenu");
    }

    async Task ShowEntry(SplashEntry entry)
    {
        // 淡入显示 → 等待 → 监听跳过输入（minBeforeSkip 后才响应）→ 淡出
        _bg.alpha = 0f;
        _logo.sprite = entry.sprite;

        await _bg.DOFade(1f, 0.4f).AsyncWaitForCompletion();

        float elapsed = 0f;
        while (elapsed < entry.displayTime)
        {
            elapsed += Time.unscaledDeltaTime;
            bool canSkip = elapsed >= entry.minBeforeSkip;
            if (canSkip && Input.anyKeyDown) break;
            await Task.Yield();
        }

        await _bg.DOFade(0f, 0.3f).AsyncWaitForCompletion();
    }
}
```

### 27.3 评级图标规范

```
Assets/Sprites/UI/Ratings/
  ├── Rating_ESRB_T.png      (T for Teen)
  ├── Rating_ESRB_M.png
  ├── Rating_CERO_B.png      (日本)
  ├── Rating_PEGI_12.png     (欧洲)
  └── Rating_USK_12.png      (德国)
```

评级图标在法务声明页右下角显示，尺寸遵循各评级机构官方规范。

---

## 28. PC 平台光标管理

PC 版在游戏中必须隐藏鼠标光标，在菜单中显示；同时支持锁定到屏幕中心（防止多显示器误操作）。

### 28.1 CursorManager

```csharp
[DefaultExecutionOrder(+50)]
public class CursorManager : MonoBehaviour
{
    [SerializeField] GameStateEventChannelSO _onGameStateChanged;

    void OnEnable()  => _onGameStateChanged.OnEventRaised += HandleState;
    void OnDisable() => _onGameStateChanged.OnEventRaised -= HandleState;

    void HandleState(GameState state)
    {
        bool showCursor = state is
            GameState.MainMenu or
            GameState.Paused or
            GameState.Settings;

        Cursor.visible   = showCursor;
        Cursor.lockState = showCursor
            ? CursorLockMode.None
            : CursorLockMode.Confined;  // Confined 限制在窗口内，防止多显示器误移
    }
}
```

### 28.2 平台条件编译

```csharp
void HandleState(GameState state)
{
#if UNITY_STANDALONE_WIN || UNITY_STANDALONE_OSX || UNITY_STANDALONE_LINUX
    // 仅 PC 平台执行光标管理
    bool showCursor = state is GameState.MainMenu or GameState.Paused or GameState.Settings;
    Cursor.visible   = showCursor;
    Cursor.lockState = showCursor ? CursorLockMode.None : CursorLockMode.Confined;
#endif
    // 主机/移动平台：光标始终隐藏，Cursor 代码不执行
}
```

### 28.3 手柄模式下的虚拟光标

手柄操作时不使用系统光标，改用 EventSystem 的 `StandaloneInputModule` 导航（已在 §22 覆盖）。切换到手柄后额外隐藏系统光标：

```csharp
// InputDeviceDetector 中，切换到 Gamepad 时：
Cursor.visible   = false;
Cursor.lockState = CursorLockMode.Locked;

// 切回 KeyboardMouse，处于菜单状态时：
Cursor.visible   = true;
Cursor.lockState = CursorLockMode.None;
```

---

## 29. 本地化深度集成

### 29.1 多语言字体资产策略

不同语系需要不同字体资产（TMP Font Asset），不可混用：

| 语系 | 字体资产 | 备注 |
|------|---------|------|
| 中文简体 | `TMP_PixelCJK_SC.asset` | 需包含全部 GB2312 常用汉字 |
| 中文繁体 | `TMP_PixelCJK_TC.asset` | 繁体字形 |
| 日语 | `TMP_PixelJP.asset` | 含假名 + 常用汉字 |
| 韩语 | `TMP_PixelKR.asset` | 含谚文全套 |
| 英语/欧洲 | `TMP_PixelLatin.asset` | 含拉丁扩展字符集（法语重音等）|
| 阿拉伯语（P2）| `TMP_Arabic.asset` | RTL 布局，需 TextMeshPro RTL 支持 |

```csharp
// LocalizedFontSetter.cs — 挂载在所有 TMP_Text 对象上（或通过基类统一处理）
public class LocalizedFontSetter : MonoBehaviour
{
    [SerializeField] TMP_Text _text;
    [SerializeField] FontLibrarySO _fontLibrary;
    [SerializeField] LocaleEventChannelSO _onLocaleChanged;

    void OnEnable()
    {
        _onLocaleChanged.OnEventRaised += Apply;
        Apply(LanguageManager.CurrentLocale);
    }

    void Apply(string locale)
        => _text.font = _fontLibrary.GetForLocale(locale);
}
```

### 29.2 文本溢出策略

| 场景 | 策略 | 实现 |
|------|------|------|
| 按钮文字 | `Overflow = Truncate` + `...` 后缀 | 设计时留出 20% 扩展空间 |
| 对话框 | `Overflow = ScrollRect`（纵向滚动）| 对话框高度固定，内容超出可滚动 |
| HUD 计数器 | 字号随数字位数缩小 | `TMP AutoSize` 设最大/最小字号 |
| 通知卡片 | 单行强制截断，Tooltip 显示全文 | `TMP Overflow = Truncate` |
| 任务日志 | 固定宽度内换行，不截断 | `TMP Overflow = Overflow`（纵向延伸）|

**设计规范**：UI 设计稿以中文为参考（字符密度最高），其他语言文本不超出中文的 2 倍宽度（德语/芬兰语文本极长，需特别测试）。

### 29.3 本地化图片替换

Logo、含文字的 UI 图（标题图、成就图标描述部分）需按语言替换：

```csharp
[CreateAssetMenu(menuName = "UI/Localized Sprite")]
public class LocalizedSpriteSO : ScriptableObject
{
    [Serializable] public struct LocaleSprite { public string locale; public Sprite sprite; }
    public LocaleSprite[] sprites;
    public Sprite fallback;

    public Sprite Get(string locale)
    {
        foreach (var ls in sprites)
            if (ls.locale == locale) return ls.sprite;
        return fallback;
    }
}
```

### 29.4 数字/日期格式本地化

```csharp
// 格式化时始终传入 CultureInfo，不使用系统默认文化（主机平台可能为 InvariantCulture）
string FormatPlaytime(double seconds)
{
    int h = (int)(seconds / 3600);
    int m = (int)(seconds % 3600 / 60);
    // 使用 LanguageManager 提供的格式字符串（避免硬编码中文"h"/"m"）
    return _lang.Format("ui.playtime.format", h, m);
    // zh: "{0}时{1}分" | en: "{0}h {1}m" | ja: "{0}時間{1}分"
}
```