zeling_v2/Docs/Verification/11_Manual_UIAudioVFX.md

# 手动测试 11 · UI、音频与特效系统

> **测试类型**：Unity Editor 手动测试（Play Mode）  
> **覆盖模块**：`BaseGames.UI`、`BaseGames.Audio`、`BaseGames.VFX`、`BaseGames.Feedback`、`BaseGames.Localization`  
> **依赖组件**：`HUDController`、`AudioManager`、`VFXCatalogSO`、`MMF_Player`（Feel）、`LocalizationManager`  
> **场景要求**：含完整 HUD Canvas、AudioMixer，Feel 的 MMF_Player 绑定到角色

---

## 快速工具

| 工具 | 用途 | 菜单路径 |
|------|------|----------|
| **Validate All ScriptableObjects** | 遍历所有实现 `IValidatable` 的 SO，输出 ✅/❌ 报告（含 HUDController 频道字段、VFXCatalogSO 等） | `BaseGames → Tools → Validate All ScriptableObjects` |

> **注意**：PlayModeDebugOverlay 已移除。HUD 变化测试请通过 Inspector 直接修改对应 Manager 字段（HP、Geo 等），或配置带伤害的敌人触发真实战斗流程。  
> Tab 11 的 Validate HUD Bindings、Ensure AudioMixer、Validate VFX Catalog 等独立检查已合并到 `Validate All ScriptableObjects`，如需单独检查各 SO 字段请在 Console 过滤对应日志。

**典型工作流**：
1. 测试前：`BaseGames → Tools → Validate All ScriptableObjects` 确认 HUD 频道全部绑定、VFX Catalog 无空引用；AudioMixer 检查参照下方 **MT-UI-03** 手动步骤。
2. `MT-UI-01` HUD 绑定：Inspector 中直接修改 `PlayerStats._hp` 字段，观察 HP 条平滑动画。
3. `MT-UI-04` VFX：配置带燃烧效果的敌人攻击玩家，Scene 视图观察 VFX Prefab 实例化。
4. `MT-UI-05` Feel 反馈：配置敌人打玩家触发受击，观察 Camera Shake 和 Chromatic Aberration。

---

## 目录

1. [HUD 与 UI 前置检查](#1-hud-与-ui-前置检查)
2. [MT-UI-01：HUD 实时数据绑定](#mt-ui-01hud-实时数据绑定)
3. [MT-UI-02：UI 面板管理（PanelManager）](#mt-ui-02ui-面板管理panelmanager)
4. [MT-UI-03：AudioManager 混音器快照](#mt-ui-03audiomanager-混音器快照)
5. [MT-UI-04：VFX 目录（VFXCatalogSO）](#mt-ui-04vfx-目录vfxcatalogso)
6. [MT-UI-05：Feel 反馈链（MMF_Player）](#mt-ui-05feel-反馈链mmf_player)
7. [MT-UI-06：本地化（Localization）](#mt-ui-06本地化localization)
8. [MT-UI-07：对话系统（DialogueSystem）](#mt-ui-07对话系统dialoguesystem)

---

## 1. HUD 与 UI 前置检查

| 元素 | 说明 | ✓ |
|------|------|---|
| HUDController | Canvas 下有 `HUDController.cs`，绑定 HP/MP/Geo/Spring 事件频道 | ☐ |
| AudioMixer | `Assets/Settings/MainMixer.mixer` 已创建，含 Master/Music/SFX/UI 子轨道 | ☐ |
| VFXCatalogSO | `Assets/Data/VFX/VFXCatalog.asset` 已配置并引用正确 VFX Prefab | ☐ |
| Feel MMF_Player | 角色 Prefab 上 `PlayerFeedbacks` 组件已绑定 | ☐ |

> **🔧 前置资产创建指导**
>
> **① HUD Canvas 创建（若尚无 Canvas）**：
> 1. Hierarchy 右键 → **UI → Canvas**，命名 `HUD_Canvas`
> 2. 在 `HUD_Canvas` 下添加 `HUDController` 组件
> 3. 运行 `BaseGames → Tools → Validate All ScriptableObjects`，根据 Console ❌ 提示，将以下频道 SO 拖入对应字段：
>    - `_onHPChanged` → `EVT_HPChanged`（IntEventChannelSO）
>    - `_onMaxHPChanged` → `EVT_MaxHPChanged`（IntEventChannelSO）
>    - `_onSoulPowerChanged` → `EVT_SoulPowerChanged`（IntEventChannelSO）
>    - `_onSpiritPowerChanged` → `EVT_SpiritPowerChanged`（IntEventChannelSO）
>    - `_onGeoChanged` → `EVT_GeoChanged`（IntEventChannelSO）
>    - `_onSpringChargesChanged` → `EVT_SpringChargesChanged`（IntEventChannelSO）
>
>    若 SO 资产不存在，先运行菜单 `BaseGames → Tools → Create Event Channel Assets` 生成全部频道资产
>
> **② AudioMixer 创建（无法脚本化，仅可手动）**：
> 1. Project 右键 → **Create → Audio Mixer** → 命名 `MainMixer` → 保存到 `Assets/_Game/Settings/`
> 2. 在 Mixer 窗口（Window → Audio → Audio Mixer）中选中 `Master`，点 **+** 按钮创建三个子组 `Music`、`SFX`、`UI`
> 3. 将 `MainMixer` 资产拖入 `AudioManager._mixer` 字段
>
> **③ VFXCatalogSO 条目填写**：
> 1. 运行 `BaseGames → Tools → Validate All ScriptableObjects` 查看空引用条目
> 2. 在 Project 视图找到 `VFXCatalog.asset`，展开 `_entries` 数组，将制作好的 VFX Prefab 拖入每条的 `prefab` 字段
> 3. ⚠ VFX Prefab 本身需手动制作（ParticleSystem），无法自动生成

---

## MT-UI-01：HUD 实时数据绑定

**目的**：验证 HP/MP/Geo/灵泉 HUD 元素实时响应游戏状态变化。

> **🔧 资源准备（驱动 HUD 数据变化）**
>
> 进入 Play Mode 后，通过 Inspector 直接修改 `PlayerStats._hp` / `_geo` 等字段，观察对应 HUD 元素响应：
> - **HP 变化** — 修改 `PlayerStats._hp`，观察 HP 条减少 / 恢复动效
> - **Geo 变化** — 修改 `PlayerStats._geo`，观察 Geo 数字滚动
> - **灵泉变化** — 修改 `PlayerStats._springCharges`，观察图标变化
>
> 也可配置带伤害的敌人触发真实战斗流程。

### 步骤

**HP 条**：

1. 让玩家受到攻击（HP 减少）

**预期**：
- HP 条动画更新（平滑或直接减少，取决于设计）
- HP 条颜色/动效响应（HP 低时变红或闪烁）

**MP（灵力）条**：

1. 玩家释放技能消耗 MP

**预期**：MP 条立即减少；停止使用后 MP 逐步恢复（如有恢复机制）。

**Geo 计数器**：

1. 拾取 Geo 或购买物品

**预期**：Geo 数字动画更新（计数滚动动效）。

**灵泉图标**：

1. 使用治疗（灵泉 -1）

**预期**：灵泉图标减少一个（图标变暗或消失）。

| 检查点 | 期望 | ✓ |
|--------|------|---|
| HP 实时响应 | 受击后 HP 条即时更新 | ☐ |
| MP 实时响应 | 技能使用后 MP 条即时更新 | ☐ |
| Geo 数字更新 | 拾取/消费后 Geo 即时更新 | ☐ |
| 灵泉图标 | 使用后图标减少 | ☐ |
| 无 UI 错误 | Console 无 UI Null 或 Missing Reference | ☐ |

---

## MT-UI-02：UI 面板管理（PanelManager）

**目的**：验证多个 UI 面板（形态技能一览/装备/任务/暂停）的互斥打开和关闭逻辑。

### 步骤

1. 按形态技能一览快捷键（P）打开 `FormSkillPanel`

**预期**：形态技能一览面板打开，游戏暂停（`Time.timeScale = 0`）。

2. 按装备快捷键（Tab）（在形态技能一览面板开启的情况下）

**预期**：形态技能一览关闭，装备面板打开（面板互斥，不同时显示多个菜单面板）。

3. 按 ESC 键

**预期**：当前打开的任意面板关闭，游戏恢复（`Time.timeScale = 1`）。

4. 打开暂停菜单（ESC 键）

**预期**：暂停菜单显示，`EVT_GamePaused` 事件触发，其他 UI 面板不显示。

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 面板互斥 | 同时只有一个主面板开启 | ☐ |
| ESC 关闭面板 | ESC 关闭当前面板 | ☐ |
| 暂停时 timeScale=0 | 面板打开时游戏暂停 | ☐ |
| 关闭后 timeScale=1 | 面板关闭后游戏恢复 | ☐ |

---

## MT-UI-03：AudioManager 混音器快照

**目的**：验证 `AudioManager` 在不同 GameState 下切换 AudioMixer 快照，正确控制音量。

> **🔧 资源准备（AudioMixer 必须手动创建）**
>
> 1. **手动创建步骤**：
>    - Project 右键 → **Create → Audio Mixer** → 命名 `MainMixer` → 保存到 `Assets/_Game/Settings/`
>    - 打开 Window → Audio → Audio Mixer
>    - 选中 `Master` 轨道，点 `+` 添加子组：`Music`、`SFX`、`UI`
>    - 展开 Snapshots，点 `+` 添加：`Gameplay`、`Pause`、`BossFight`（用于快照切换测试）
>    - 将 `Gameplay` 设为默认快照（右键 → Set as Start Snapshot）
> 2. 将 `MainMixer` 拖入场景 `AudioManager._mixer` 字段
> 3. ⚠ Unity 不支持通过代码创建 AudioMixer 资产（Editor API 无此功能），必须手动完成

### 步骤

**步骤 A：游戏运行快照**

1. 正常 Gameplay 状态下，观察 `Window → Audio → AudioMixer`

**预期**：Master 轨道均衡，`Gameplay` 快照激活，BGM 正常播放。

**步骤 B：暂停快照**

1. 按 ESC 打开暂停菜单

**预期**：
- `Pause` 快照切换（BGM 音量降低或混响增强）
- SFX 暂停或降低音量
- 暂停菜单 BGM 或静音正确切换

**步骤 C：Boss 战快照**

1. 进入 Boss 战触发区域

**预期**：
- `BossFight` 快照激活
- Boss 战 BGM 淡入
- 普通 BGM 淡出

**步骤 D：音量设置持久化**

1. 打开设置菜单，调整 BGM 音量
2. 关闭游戏（退出 Play Mode）并重新进入

**预期**：BGM 音量设置被保存（`PlayerPrefs` 或 `SaveData.Settings.BGMVolume`）。

| 检查点 | 期望 | ✓ |
|--------|------|---|
| Gameplay BGM | 正常播放，音量正常 | ☐ |
| 暂停快照 | BGM 降低/混响变化 | ☐ |
| Boss BGM | Boss 战 BGM 正确切换 | ☐ |
| 音量持久化 | 重进后音量设置保留 | ☐ |

---

## MT-UI-04：VFX 目录（VFXCatalogSO）

**目的**：验证 `VFXCatalogSO` 在各种触发条件下正确播放对应 VFX Prefab（通过对象池）。

> **🔧 资源准备（VFXCatalogSO 条目填写）**
>
> 1. 运行 `BaseGames → Tools → Validate All ScriptableObjects`，Console 显示空引用条目
> 2. 找到 `VFXCatalog.asset`（自定义路径），在 Inspector 展开 `_entries`
> 3. 为每个条目填入对应的 VFX Prefab（ParticleSystem GameObject）：
>
> | Key（示例） | 用途 | Prefab 路径（示例） |
> |------------|------|---------------------|
> | `hit_slash` | 斩击命中 | `Assets/_Game/VFX/Hit_Slash.prefab` |
> | `hit_blunt` | 钝击命中 | `Assets/_Game/VFX/Hit_Blunt.prefab` |
> | `parry_ring` | 弹反 | `Assets/_Game/VFX/Parry_Ring.prefab` |
> | `player_hurt` | 玩家受击 | `Assets/_Game/VFX/Player_Hurt.prefab` |
> | `player_death` | 玩家死亡 | `Assets/_Game/VFX/Player_Death.prefab` |
> | `heal_spring` | 灵泉治疗 | `Assets/_Game/VFX/Heal_Spring.prefab` |
> | `plunge_land` | 下劈落地 | `Assets/_Game/VFX/Plunge_Land.prefab` |
>
> ⚠ VFX Prefab 需手动制作（ParticleSystem + 自定义 Shader），无法自动生成。若当前测试阶段 Prefab 未就绪，可将占位 Cube/Sphere 临时拖入以验证调用链正常。

### 触发点验证列表

执行以下动作，观察对应 VFX 是否播放：

| 触发动作 | 预期 VFX | ✓ |
|---------|---------|---|
| 玩家攻击命中敌人（斩击） | 击中溅血特效（slash hit） | ☐ |
| 玩家攻击命中敌人（钝击） | 击中火花/尘土特效（blunt hit） | ☐ |
| 弹反成功 | 弹反光圈特效（parry ring） | ☐ |
| 玩家受击 | 受击白闪 + 短暂粒子 | ☐ |
| 玩家死亡 | 死亡消散特效 | ☐ |
| 灵泉治疗 | 治疗绿色粒子 | ☐ |
| 下劈反弹 | 落点尘土爆炸 | ☐ |

### 对象池验证

1. 在 Hierarchy 中找到 `VFXPoolRoot`（或 `ObjectPool` GameObject）
2. 执行大量攻击，观察 Hierarchy 的 VFX Pool 子对象

**预期**：VFX 对象被复用（`SetActive(false)` 后再 `SetActive(true)`），不会无限创建新对象。

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 各 VFX 正确播放 | 对应触发点显示正确特效 | ☐ |
| 对象池复用 | 不重复创建新 GameObject | ☐ |

---

## MT-UI-05：Feel 反馈链（MMF_Player）

**目的**：验证 `MMF_Player`（MoreMountains Feel）相机抖动、控制器震动、屏幕冲击等反馈。

### 步骤

**相机抖动（Camera Shake）**：

1. 执行强力攻击（如下劈落地、受到 Boss 重击）

**预期**：相机产生震动效果（`CinemachineImpulseSource` 或 `MMWiggle` 驱动），震动强度与事件大小相符。

**控制器震动（Controller Vibration）**（如在 Windows 上使用 Xbox 手柄）：

1. 受到攻击

**预期**：手柄发生震动（`MMNVibrate` 或 `NiceVibrations` 调用）。

**屏幕闪烁（Screen Flash）**：

1. 使用爆炸性技能或受到大伤害

**预期**：屏幕短暂白色或红色闪烁（`PostProcessing` 或 `Image` Overlay）。

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 相机抖动 | 重攻击/落地时相机抖动 | ☐ |
| 控制器震动 | 受击时手柄震动（手柄测试） | ☐ |
| 屏幕闪烁 | 大伤害时屏幕闪烁 | ☐ |

---

## MT-UI-06：本地化（Localization）

**目的**：验证 `LocalizationManager` 切换语言后 UI 文本正确更新。

### 步骤

1. 在游戏设置中切换语言（如：中文 → 英文）

**预期**：
- HUD 中的提示文本变为英文
- 对话框文本变为英文
- 技能/物品名称变为英文

2. 再切换回中文

**预期**：所有文本恢复中文，无残留英文。

3. 观察是否存在文本溢出（UI 元素装不下翻译后更长的字符串）

**预期**：UI 文本框自适应或截断处理正确，无文字超出边界。

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 语言切换 | UI 文本全部更新 | ☐ |
| 切换回中文 | 无残留英文 | ☐ |
| 文本不溢出 | UI 无字符超出边界 | ☐ |
| 缺失 Key 检测 | Console 无 `Missing Localization Key` 警告 | ☐ |

---

## MT-UI-07：对话系统（DialogueSystem）

**目的**：验证 `DialogueManager` 与 NPC 对话的触发、分支选择、事件链。

### 步骤

1. 走到场景中有对话触发的 NPC，按**交互键**（E）

**预期**：
- 对话 UI 面板打开
- 第一行对话文本正确显示（逐字显示动效）
- 游戏输入暂时切换为"对话输入"（按键 E/Space 翻页，WASD 选择选项）

2. 按 E/Space 翻页

**预期**：逐行显示对话，直到当前节点末尾。

3. 遇到分支选项时（如"同意/拒绝"）

**预期**：
- 分支选项 UI 显示
- 上下移动光标选择
- 按确认键执行对应分支逻辑

4. 对话结束后

**预期**：
- 对话 UI 关闭
- 游戏输入恢复正常
- 若对话触发任务/事件：相关 EventChannel 已触发（EventBusMonitor 可见）

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 对话 UI 打开 | 交互后对话面板显示 | ☐ |
| 逐字显示 | 文字逐字出现动效 | ☐ |
| 分支选择 | 分支选项响应方向键 | ☐ |
| 对话结束 | UI 关闭，输入恢复 | ☐ |
| 事件触发 | 对话触发的事件正确执行 | ☐ |