# 07 · 反馈系统

> **命名空间** `BaseGames.Feedback`  
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
> **依赖** Feel v4.3 · `BaseGames.Core.Events` · `BaseGames.Combat`

---

## 目录

1. [设计原则](#1-设计原则)
2. [Feel MMF_Player 体系](#2-feel-mmf_player-体系)
3. [PlayerFeedback — 玩家反馈配置](#3-playerfeedback--玩家反馈配置)
4. [EnemyFeedback — 敌人反馈配置](#4-enemyfeedback--敌人反馈配置)
5. [时间管理：子弹时间集成](#5-时间管理子弹时间集成)
6. [镜头震动集成](#6-镜头震动集成)
7. [音效管理](#7-音效管理)
8. [粒子特效规范](#8-粒子特效规范)
9. [UI 反馈](#9-ui-反馈)
10. [事件频道驱动的全局反馈](#10-事件频道驱动的全局反馈)
11. [FeedbackConfigSO](#11-feedbackconfigso)
12. [编辑器友好设计](#12-编辑器友好设计)

---

## 1. 设计原则

- **零耦合**：所有反馈通过**事件频道**或 `UnityEvent` 触发，GameLogic 不直接调用 Feedback
- **数据驱动**：每种反馈配置为独立 `MMF_Player` 资产，可在 Inspector 中调节，无需修改代码
- **分层设计**：本地反馈（HitBox 命中瞬间）→ 全局反馈（OnHitConfirmed 频道）→ 时间管理（ParrySuccess）
- **像素风格适配**：优先使用 Shader 闪光（Flash）而非粒子，减少视觉噪声

---

## 2. Feel MMF_Player 体系

### MMF_Player 命名规范

所有 `MMF_Player` GameObject 命名格式：`MMF_{Owner}_{EventName}`

示例：
- `MMF_Player_OnHit`（玩家受击）
- `MMF_Player_OnAttackHit`（玩家攻击命中）
- `MMF_Player_OnParrySuccess`（弹反成功）
- `MMF_Enemy_OnHit`（敌人受击）
- `MMF_Enemy_OnDeath`（敌人死亡）

### MMF_Player Feedback 类型速查

| Feel Feedback 类型 | 常用场景 | 关键参数 |
|-------------------|---------|---------|
| `MMF_Flash` | Sprite 受击白闪 | `FlashColor`, `Duration` |
| `MMF_SpriteRenderer` | 闪烁/变色 | `Color`, `Blink Duration` |
| `MMF_Particles` | 命中粒子特效 | `ParticleSystem` 引用 |
| `MMF_AudioSource` | 播放音效 | `AudioClip`, `Volume`, `Pitch Variance` |
| `MMF_CinemachineImpulse` | 镜头震动 | `ImpulseSource`, `Velocity` |
| `MMF_FreezeFrame` | 命中冻帧 | `FreezeDuration` |
| `MMF_TimeScale` | 子弹时间 | `TimeScale`, `Duration` |
| `MMF_TextMeshPro` | 伤害数字弹出 | `Value`, `Animation Curve` |
| `MMF_Position` | 物体位移（扑克震动）| `Displacement`, `Curve` |
| `MMF_Scale` | 冲击缩放（南瓜弹）| `Scale`, `Duration` |
| `MMF_Enable` | 启用/禁用 GameObject | `Target` |

---

## 3. IFeedbackPlayer 接口 — 反馈抽象层

为了让游戏逻辑（`PlayerCombat`、`EnemyBase`）与具体的 Feel/MMF_Player 实现零耦合，所有反馈调用必须通过 `IFeedbackPlayer` 接口进行：

```csharp
/// <summary>
/// 反馈执行器的抽象接口。
/// GameLogic 依赖此接口，而非具体的 MMF_Player 引用。
/// </summary>
public interface IFeedbackPlayer
{
    void PlayHit(HitWeight weight);          // 命中反馈（轻/中/重）
    void PlayParrySuccess();                 // 弹反成功
    void PlayTakeHit();                      // 玩家受击
    void PlayDeath();                        // 死亡演出
    void PlayHeal();                         // 治疗
    void PlayLandImpact();                   // 落地冲击
    void PlayAttackWhoosh();                 // 攻击挥动音效
    void PlayJumpLaunch();                   // 起跳
    void TriggerPreset(string presetId);     // 通过 ID 触发任意预设（动画事件用）
    void PlaySFXById(string sfxId);          // 通过 ID 播放音效（动画事件用）
}
```

**使用规范**：
- `PlayerCombat`、`PlayerMovement` 等逻辑组件持有 `IFeedbackPlayer _feedback`（通过 Inspector 注入）
- 测试时可替换为 `NullFeedbackPlayer`（空实现），完全不需要 Feel 资产
- 新增反馈类型时先在接口声明，再在 `PlayerFeedback` 中实现，保持单一变更点

---

## 4. PlayerFeedback — 玩家反馈配置

`PlayerFeedback` 组件挂载在 Player Prefab 下，实现 `IFeedbackPlayer` 接口，聚合所有玩家相关 `MMF_Player`：

### 受击反馈（OnTakeHit）

| Feedback | 参数 | 视觉效果 |
|----------|------|---------|
| `MMF_Flash` | 白色，0.15s | Sprite 白闪（经典受击感）|
| `MMF_AudioSource` | SFX_Player_Hurt | 受伤音效（随机 Pitch 0.9~1.1）|
| `MMF_CinemachineImpulse` | Medium，0.5强度 | 镜头震动 |
| `MMF_FreezeFrame` | 0.033s | 2帧冻帧 |
| `MMF_Position` | 朝击退反方向 1 unit | 玩家轻微弹开 |

### 攻击命中反馈（OnAttackHit）

| Feedback | 参数 | 说明 |
|----------|------|------|
| `MMF_Particles` | HitSpark Prefab，命中点生成 | 金属火花粒子 |
| `MMF_AudioSource` | SFX_Attack_Hit（随机 3 个变体之一）| 命中音效 |
| `MMF_FreezeFrame` | 0.033s（2帧）| 命中停顿感 |
| `MMF_CinemachineImpulse` | Light，0.2强度 | 轻微镜头震 |

### 弹反成功反馈（OnParrySuccess）

| Feedback | 参数 | 说明 |
|----------|------|------|
| `MMF_Flash` | 金色，0.1s | Sprite 金光闪烁 |
| `MMF_Particles` | ParryFlash Prefab（全屏金色光圈）| 弹反标志性特效 |
| `MMF_AudioSource` | SFX_Parry_Success（金属碰撞音）| 清脆弹反音效 |
| `MMF_CinemachineImpulse` | Parry，0.7强度，带方向 | 有方向性震动 |
| `MMF_TimeScale` | 0.25×，0.2s | 子弹时间（与 ParrySystem 同步）|
| `MMF_FreezeFrame` | 0.066s（4帧）| 更长冻帧强调击中感 |

### 治疗反馈（OnHeal）

| Feedback | 参数 | 说明 |
|----------|------|------|
| `MMF_Flash` | 蓝色，0.2s | 恢复光效 |
| `MMF_Particles` | HealParticle Prefab | 向上飘散的蓝色粒子 |
| `MMF_AudioSource` | SFX_Heal | 回血音效 |

### 死亡反馈（OnDeath）

| Feedback | 参数 | 说明 |
|----------|------|------|
| `MMF_AudioSource` | SFX_Player_Death | 死亡音效 |
| `MMF_CinemachineImpulse` | Heavy，1.0强度 | 强烈震动 |
| `MMF_FreezeFrame` | 0.1s（6帧）| 死亡冻帧 |
| `MMF_Enable` | 禁用 HurtBox | 防止死亡后继续受击 |

---

## 4. EnemyFeedback — 敌人反馈配置

`EnemyFeedback` 挂在每个敌人 Prefab 下：

### 受击反馈（OnHit）

| Feedback | 参数 | 说明 |
|----------|------|------|
| `MMF_Flash` | 白色，0.1s | 受击白闪 |
| `MMF_AudioSource` | SFX_Enemy_Hurt（按敌人类型变体）| 受伤音效 |
| `MMF_Particles` | HitSpark（命中位置）| 命中粒子 |

### 被弹反反馈（OnParried）

| Feedback | 参数 | 说明 |
|----------|------|------|
| `MMF_Flash` | 金色，0.15s | 与玩家弹反视觉对应 |
| `MMF_SpriteRenderer` | 扭曲/Shader 效果 | 硬直视觉反馈 |
| `MMF_AudioSource` | SFX_Parry_Impact | 被弹反音效 |
| `MMF_Position` | 小幅后退 | 轻微击退特效 |

### 死亡反馈（OnDeath）

| Feedback | 参数 | 说明 |
|----------|------|------|
| `MMF_AudioSource` | SFX_Enemy_Death | 死亡音效 |
| `MMF_Particles` | DeathParticle Prefab | 死亡解体粒子 |
| `MMF_Enable` | 禁用 Rigidbody2D / Colliders | 防止尸体物理继续 |
| `MMF_FreezeFrame` | 0.05s（3帧）| 击杀冻帧 |

---

## 5. 时间管理：子弹时间集成

子弹时间通过两套系统协调：

### Feel MMTimeManager（主要）

- 注册所有 `MMTimeManager` Listener
- `ParrySystem.TriggerParrySuccess()` → `MMTimeScaleEvent` 广播
- `MMTimeManager` 接收后修改 `Time.timeScale`
- 时间恢复：Lerp 方式平滑还原（`LerpSpeed = 20`）

### 与 Animancer 的配合

- Animancer 动画默认使用 `Time.timeScale`（跟随子弹时间减速）
- 特例：UI 动画、音频播放必须用 `Time.unscaledDeltaTime`
- 检测敌人动画速率被子弹时间自动降低（无需额外配置）

---

## 6. 镜头震动集成

详见 [02_CameraSystem](./02_CameraSystem.md#6-镜头震动cinemachineimpulse)。

### Feel 与 Cinemachine Impulse 的桥接

Feel `MMF_CinemachineImpulse` → 内部调用 `CinemachineImpulseSource.GenerateImpulse()` → `CinemachineImpulseListener` 响应。

**PlayerFeedback 中每种震动类型对应 ImpulseSource**（Inspector 中拖入引用）：

| 震动类型 | 来源 ImpulseSource | 说明 |
|---------|-------------------|------|
| Light | `ImpulseSource_Light` | 普通命中 |
| Medium | `ImpulseSource_Medium` | 玩家受伤 |
| Heavy | `ImpulseSource_Heavy` | 玩家死亡 / Boss 重击 |
| Parry | `ImpulseSource_Parry` | 弹反成功（带方向性）|

---

## 7. 音效管理

### 音效 SO 资产结构

`AudioEventSO` 封装音效播放参数（非特定 AudioSource），通过事件频道解耦：

| 字段 | 类型 | 说明 |
|------|------|------|
| `Clips` | `AudioClip[]` | 随机选取其中一个播放 |
| `Volume` | `float` | 基础音量（0~1）|
| `PitchMin` | `float` | Pitch 随机范围最小值 |
| `PitchMax` | `float` | Pitch 随机范围最大值 |
| `MixerGroup` | `AudioMixerGroup` | SFX / Music / UI 混音组 |

所有 `MMF_AudioSource` 通过 `AudioEventSO` 播放音效（而非直接引用 `AudioClip`），实现随机音调变化。

### 音效资产路径

```
Assets/Audio/SFX/
├── Player/
│   ├── SFX_Player_Hurt.asset
│   ├── SFX_Player_Death.asset
│   ├── SFX_Attack_Hit.asset        ← 含3个变体Clip
│   ├── SFX_Parry_Success.asset
│   └── SFX_Heal.asset
├── Enemies/
│   ├── SFX_Enemy_Hurt_Generic.asset
│   └── SFX_Enemy_Death_Generic.asset
└── World/
    ├── SFX_Footstep.asset
    └── SFX_Landing.asset
```

---

## 8. 粒子特效规范

| 特效 Prefab | 触发来源 | 生命周期 | 说明 |
|-------------|---------|---------|------|
| `FX_HitSpark` | 攻击命中 | 0.3s 后自销毁 | 金属火花（4~6 粒子）|
| `FX_ParryFlash` | 弹反成功 | 0.5s 后自销毁 | 金色光圈（全屏扩散）|
| `FX_HealParticle` | 玩家治疗 | 1.0s 后自销毁 | 蓝色粒子上飘 |
| `FX_EnemyDeath` | 敌人死亡 | 1.5s 后自销毁 | 解体粒子（按敌人主题色）|
| `FX_DustCloud` | 玩家落地 | 0.5s 后自销毁 | 落地灰尘 |
| `FX_DashTrail` | 玩家冲刺 | 0.4s 后自销毁 | 冲刺残影（Sprite Fade）|

**像素风格适配**：所有粒子使用 `Render Mode: Billboard`，粒子贴图与角色 PPU（32 PPU）保持一致，避免模糊。

---

## 9. UI 反馈

### 伤害数字（FloatingText）

- 触发：`OnHitConfirmed` 事件频道
- 从对象池中取 `FloatingText` Prefab，在命中位置生成
- 数字内容：`DamageInfo.FinalDamage`
- 弹反反击：数字显示为金色 + 粗体（`FinalDamage` 为 3× 时额外标记）
- 动画：向上飘 0.8s + 淡出

### HP 血条动画

- `OnPlayerHPChanged` 事件频道驱动
- 满格 HP 以绿色实心显示，扣除部分以红色渐出动画表示（延迟 0.2s 开始缩短，视觉缓冲）

### Soul 槽动画

- `OnSoulChanged` 事件频道驱动
- 弹反成功 +33 时，Soul 槽显示**扫光动画**（金色高亮流过 1/3 槽）

---

## 10. 事件频道驱动的全局反馈

`GlobalFeedbackController` 组件（单例，挂在 `[Managers]` GO 上）监听全局频道并触发对应 `MMF_Player`：

| 频道 | 触发反馈 |
|------|---------|
| `OnPlayerDied` | 停止音乐、播放死亡演出（慢慢音量淡出，画面泛红）|
| `OnBossFightStarted` | 停止环境音乐、淡入 Boss 战BGM |
| `OnBossFightEnded` | Boss 死亡演出（震动+特效+音乐过渡）|
| `OnRoomEntered` | 淡出 → 淡入（场景切换遮罩）|

---

## 11. FeedbackConfigSO

`FeedbackConfigSO` 全局配置，存放于 `Assets/ScriptableObjects/Config/FeedbackConfigSO.asset`：

| 参数 | 类型 | 推荐值 | 说明 |
|------|------|--------|------|
| `HitFreezeFrames` | `int` | 2 | 命中冻帧帧数 |
| `ParryFreezeFrames` | `int` | 4 | 弹反冻帧帧数 |
| `SfxVolumeMaster` | `float` | 1.0 | SFX 总音量（0~1）|
| `HapticsEnabled` | `bool` | true | 手柄震动开关（P2）|
| `FloatingTextPoolSize` | `int` | 20 | 伤害数字对象池大小 |
| `ParticlePoolSize` | `int` | 30 | 粒子特效对象池大小 |

---

## 12. 编辑器友好设计

### MMF_Player 预览支持

Feel 原生支持在 Editor 非 Play Mode 下预览 `MMF_Player`：

- Inspector 底部的"▶ Play"按钮可单独预览每组反馈
- `Preview in Editor` 模式下验证视觉效果，无需进入 Play Mode

### FX 对象池监控（Play Mode Inspector）

```
┌─ GlobalFeedbackController ──────────────────────┐
│  FloatingText Pool: 14 / 20 available           │
│  Particle Pool   : 28 / 30 available           │
│  ─────────────────────────────────────────────  │
│  [Test: Player Hurt] [Test: Parry Success]      │
│  [Test: Enemy Hit ] [Test: Boss Phase Change]   │
└────────────────────────────────────────────────┘
```

### 反馈效果全局开关（调试用）

`FeedbackDebugOverlay`（编辑器 Play Mode 下叠加）：

- `[Toggle Screen Shake]`：开关镜头震动
- `[Toggle Freeze Frames]`：开关冻帧
- `[Toggle Particles]`：开关粒子特效
- `[Toggle Bullet Time]`：开关子弹时间

方便策划/美术人员单独调试某类反馈。