# 14 · 进程系统（区域组织·能力门·Boss 进程）

> **命名空间** `BaseGames.Progression`  
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
> **依赖** `BaseGames.Core.Events` · `BaseGames.World`（SaveSystem）· `BaseGames.Player`（能力查询）

---

## 目录

1. [系统总览](#1-系统总览)
2. [区域（Region）划分](#2-区域region划分)
3. [能力门（AbilityGate）](#3-能力门abilitygate)
4. [进程锁（ProgressLock）](#4-进程锁progresslock)
5. [Boss 进程管理](#5-boss-进程管理)
6. [HP 容器升级流程](#6-hp-容器升级流程)
7. [收集品进度追踪](#7-收集品进度追踪)
8. [SaveData 字段扩展](#8-savedata-字段扩展)
9. [区域解锁与地图联动](#9-区域解锁与地图联动)
10. [事件频道](#10-事件频道)
11. [编辑器友好设计](#11-编辑器友好设计)

---

## 1. 系统总览

进程系统解决"类银河恶魔城游戏如何组织超大地图进程"的核心问题：

```
进程系统职责:
  ├─ 区域划分          → RegionDefinitionSO 定义区域元数据
  ├─ 能力门            → AbilityGate 阻挡没有对应能力的玩家
  ├─ 进程锁            → ProgressLock 阻挡未满足条件的通路
  ├─ Boss 进程         → Boss 击败解锁通往新区域的大门
  ├─ HP 容器升级       → 拾取后 MaxHP++ 并触发 UI 演出
  └─ 收集品追踪        → 完成度百分比（成就/结局条件）
```

---

## 2. 区域（Region）划分

### 区域枚举

游戏世界分为以下区域，按开放顺序排列：

| 区域 ID | 中文名 | 特点 | Boss | 开放条件 |
|---------|--------|------|------|---------|
| `Forest` | 扎根森林 | 初始区域，基础敌人 | 蛛网守卫 | 无（起始区域）|
| `Cave` | 腐蚀洞穴 | 黑暗区域，大量陷阱 | 蚀骨蠕虫 | 击败蛛网守卫 |
| `Ruins` | 坍塌废墟 | 需要冲刺能力 | 废墟遗骑士 | 获得冲刺能力 |
| `Abyss` | 深渊裂隙 | 需要双跳，垂直地图 | 深渊之喉 | 击败废墟遗骑士 |
| `Core` | 核心熔炉 | 终局区域 | 最终Boss | 击败深渊之喉 |

### RegionDefinitionSO

每个区域一个 SO 资产，集中管理区域元数据：

```csharp
[CreateAssetMenu(menuName = "Progression/RegionDefinition")]
public class RegionDefinitionSO : ScriptableObject
{
    public string  regionId;             // 如 "Cave"（与 AudioZone 的 regionId 一致）
    public string  displayName;          // 如 "腐蚀洞穴"
    public Color   mapColor;             // 地图 UI 上该区域的颜色标识
    public Sprite  mapIconSprite;        // P1：地图图标

    [Header("解锁条件")]
    public string  requiredBossDefeated; // 空字符串 = 无条件
    public AbilityType requiredAbility;  // None = 无要求

    [Header("关联房间")]
    public string[] roomSceneNames;      // 该区域包含的所有场景名
    public string   bossSceneName;       // Boss 房间场景名
    public string   entrySceneName;      // 从外部进入该区域的第一个房间
}
```

资产路径：`Assets/ScriptableObjects/Progression/Regions/`

---

## 3. 能力门（AbilityGate）

`AbilityGate` 阻止未解锁对应能力的玩家通过，是 Metroidvania 空间门控的核心组件：

```csharp
public class AbilityGate : MonoBehaviour
{
    [SerializeField] AbilityType _requiredAbility;     // 需要的能力类型
    [SerializeField] GameObject  _blockingObject;      // 阻挡碰撞体（如悬崖、矮墙、荆棘）
    [SerializeField] GameObject  _hintUI;              // 提示 UI（如能力图标 + "???"）

    void Start()
    {
        // 零耦合：从注入的 SaveData 查询，而非通过 SaveManager.Instance
        bool hasAbility = _saveData != null
            ? _saveData.HasAbility(_requiredAbility)
            : false;
        _blockingObject.SetActive(!hasAbility);
        _hintUI.SetActive(!hasAbility);
    }

    // _saveData 由 GameInitializer 在场景加载时注入
    SaveData _saveData;

    // 监听能力解锁事件，实时更新（玩家在已进入的区域解锁能力时即时生效）
    void OnEnable()  => _onAbilityUnlocked.OnEventRaised += OnAbilityUnlocked;
    void OnDisable() => _onAbilityUnlocked.OnEventRaised -= OnAbilityUnlocked;

    void OnAbilityUnlocked(string abilityId)
    {
        if (abilityId != _requiredAbility.ToString()) return;
        _blockingObject.SetActive(false);
        // P1：播放解锁动画（如荆棘收缩、道路开通特效）
    }
}
```

### AbilityGate 类型对照表

| 能力 | 门控表现形式 | 场景示例 |
|------|------------|---------|
| `DoubleJump` | 过高的空中平台，单跳无法到达 | 无法单跳到达的洞穴上层 |
| `Dash` | 跨越无平台的水平间隙（距离 > 单跳能到） | 废墟区域宽沟壑 |
| `WallJump` | 两侧光滑高墙的竖井，无法借力 | 深渊垂直上升通道 |
| `Swim` | P1：充满液体的通道，无法通过 | 深渊底部的地下湖 |

---

## 4. 进程锁（ProgressLock）

`ProgressLock` 是单向/永久性阻挡，需满足特定条件（如击败特定 Boss 或持有特定道具）才能解锁：

```csharp
public class ProgressLock : MonoBehaviour
{
    [Header("解锁条件")]
    [SerializeField] string _requiredBossId;    // 空 = 不检查Boss
    [SerializeField] string _requiredItemId;    // 空 = 不检查道具（P1）

    [Header("物理表现")]
    [SerializeField] GameObject _lockedVisuals;   // 锁住状态的视觉（如大门、封印石）
    [SerializeField] GameObject _unlockedVisuals; // 开启状态的视觉（可选，或直接禁用）
    [SerializeField] Collider2D _blockCollider;

    [Header("存档")]
    [SerializeField] string _lockId;              // 唯一 ID，存档中记录开启状态

    void Start()
    {
        bool isUnlocked = CheckUnlocked();
        ApplyState(isUnlocked);
    }

    bool CheckUnlocked()
    {
        var save = SaveManager.Instance.Data;
        if (!string.IsNullOrEmpty(_requiredBossId) && !save.defeatedBosses.Contains(_requiredBossId))
            return false;
        if (!string.IsNullOrEmpty(_requiredItemId) && !save.ownedItems.Contains(_requiredItemId))
            return false;
        return save.unlockedProgressLocks.Contains(_lockId);
    }

    void ApplyState(bool unlocked)
    {
        _blockCollider.enabled  = !unlocked;
        _lockedVisuals.SetActive(!unlocked);
        if (_unlockedVisuals != null)
            _unlockedVisuals.SetActive(unlocked);
    }
}
```

### 典型用途

| 场景 | lockId 示例 | 解锁条件 |
|------|------------|---------|
| Forest → Cave 的大门 | `Lock_Forest_ToCave` | 击败蛛网守卫（bossId=`Boss_SpiderGuard`）|
| 废墟入口封印石 | `Lock_Ruins_Entry` | 持有冲刺符文（itemId=`Item_DashRune`）|
| 深渊入口遗迹门 | `Lock_Abyss_Entry` | 击败废墟遗骑士 |

---

## 5. Boss 进程管理

Boss 击败信息集中存储在 `SaveData.defeatedBosses` 字符串集合中，由各 `ProgressLock` 和 `RegionDefinitionSO` 查询。

### BossProgressTracker（轻量辅助组件）

挂载在 Boss 房间的 `BossTrigger` 同一对象上：

```csharp
public class BossProgressTracker : MonoBehaviour
{
    [SerializeField] string _bossId;                  // 如 "Boss_SpiderGuard"
    [SerializeField] string[] _unlocksProgressLockIds; // 击败后解锁哪些 ProgressLock

    void OnEnable()  => _onBossDefeated.OnEventRaised += OnBossDefeated;
    void OnDisable() => _onBossDefeated.OnEventRaised -= OnBossDefeated;

    void OnBossDefeated(string bossId)
    {
        if (bossId != _bossId) return;

        // 1. 通过事件频道通知 SaveSystem 记录（零耦合）
        _onBossDefeatedForSave.Raise(new BossDefeatedPayload
        {
            bossId            = bossId,
            progressLockIds   = _unlocksProgressLockIds,
        });

        // 2. 广播区域解锁事件（地图 UI 更新）
        _onRegionUnlocked.Raise(bossId);
    }
}
```

---

## 6. HP 容器升级流程

HP 容器（Heart Container）是永久 MaxHP 增量物件，拾取后触发完整 UI 演出：

```csharp
public class HPContainerPickup : MonoBehaviour
{
    [SerializeField] string _collectibleId;       // 存档用唯一 ID

    void OnTriggerEnter2D(Collider2D other)
    {
        if (!other.CompareTag("Player")) return;
        // 通过注入的 SaveData 引用检查，而非 SaveManager.Instance
        if (_saveData != null && _saveData.collectedItems.Contains(_collectibleId)) return;

        StartCoroutine(PickupSequence(other.transform));
    }

    SaveData _saveData;  // 由 GameInitializer 在 Awake 时注入

    IEnumerator PickupSequence(Transform player)
    {
        // 1. 禁用玩家输入（进入短暂无敌+输入锁定状态）
        _inputReader.EnableGameplayInput(false);

        // 2. 隐藏本物件
        gameObject.SetActive(false);

        // 3. 播放获取特效（中央放大的心形光效，全屏暗化）
        // Feel MMF_Player: Flash + Scale + Particles

        // 4. 等待特效完成（0.8s）
        yield return new WaitForSeconds(0.8f);

        // 5. MaxHP + 2（每个容器增加 2 HP）
        // 零耦合：通过事件频道通知 SaveSystem，携带新 MaxHP 值
        _onMaxHPContainerPickedUp.Raise(new HPContainerPayload { collectibleId = _collectibleId });
        // SaveSystem 收到事件后执行：data.maxHP += 2; data.currentHP = data.maxHP; data.collectedItems.Add(id); Save();

        // 6. 广播给 UI 系统更新显示（SaveSystem 修改完数据后再广播真实值，这里仅预估触发动画）
        _onMaxHPChanged.Raise(_saveData != null ? _saveData.maxHP : 0);
        _onHPChanged.Raise(_saveData != null ? _saveData.maxHP : 0);

        // 8. 恢复输入
        yield return new WaitForSeconds(0.5f);
        _inputReader.EnableGameplayInput(true);
    }
}
```

**UI 演出细节**：
- 全屏轻微暗化（Canvas_Overlay 半透明黑色遮罩淡入淡出）
- HPContainer 新增的心形图标从中央飞入到 HUD 左上角
- Soul 槽短暂闪烁
- 音效：SFX_HPContainer_Pickup（神圣感上升音效）

---

## 7. 收集品进度追踪

```csharp
// SaveData 扩展字段（见 §8）
// collectionProgress 记录各类收集品的拾取状态

public static class ProgressCalculator
{
    // 完成度百分比（用于主菜单存档槽显示 / P2 成就）
    public static float GetCompletionPercent(SaveData data, RegionDefinitionSO[] allRegions)
    {
        int total   = /* 所有可收集物件总数，硬编码在 GameConstantsSO 中 */;
        int collected = data.collectedItems.Count
                      + data.defeatedBosses.Count * 5   // Boss 击败权重更高
                      + data.visitedRooms.Count;        // P1：房间探索率
        return Mathf.Clamp01((float)collected / total) * 100f;
    }
}
```

---

## 8. SaveData 字段扩展

在 [08_WorldSystem.md §5](./08_WorldSystem.md) 的 SaveData JSON Schema 基础上，进程系统新增字段：

```json
{
  "player": {
    "maxHP": 6,
    "unlockedAbilities": ["Dash", "DoubleJump"],
    "ownedItems": ["Item_DashRune"]
  },
  "progression": {
    "defeatedBosses": ["Boss_SpiderGuard"],
    "unlockedProgressLocks": ["Lock_Forest_ToCave"],
    "unlockedFastTravelIds": ["FT_Forest_01", "FT_Cave_01"],
    "visitedRooms": ["Room_Forest_01", "Room_Forest_02"],
    "collectedItems": ["HC_Forest_01", "HC_Cave_01"]
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `maxHP` | `int` | 当前最大 HP（初始值 6，每个容器 +2）|
| `unlockedAbilities` | `HashSet<string>` | 已解锁的能力 ID 集合 |
| `defeatedBosses` | `HashSet<string>` | 已击败 Boss 的 bossId 集合 |
| `unlockedProgressLocks` | `HashSet<string>` | 已解锁的 ProgressLock.lockId 集合 |
| `unlockedFastTravelIds` | `HashSet<string>` | 已激活的 Bench 传送点 ID 集合 |
| `visitedRooms` | `HashSet<string>` | P1：已访问房间的场景名，用于地图显示 |
| `collectedItems` | `HashSet<string>` | 所有可收集物件的唯一 ID（HP容器/能力道具等）|

> **性能规范**：所有需要 `.Contains()` 查询的集合字段均使用 `HashSet<string>`（O(1) 查询），禁止使用 `string[]` 或 `List<string>`（O(n) 遍历）。JSON 序列化使用 `Newtonsoft.Json`（`JsonConvert.DeserializeObject<SaveData>`），Newtonsoft 原生支持 `HashSet<T>` 的序列化/反序列化，无需额外转换。

### C# SaveData 结构体（部分）

```csharp
[Serializable]
public class SaveData
{
    // 玩家状态
    public int    maxHP            = 6;
    public int    geoCount         = 0;
    public int    soulCount        = 0;

    // 进程集合 — 全部 HashSet<string> 保证 O(1) Contains
    public HashSet<string> unlockedAbilities      = new();
    public HashSet<string> defeatedBosses         = new();
    public HashSet<string> unlockedProgressLocks  = new();
    public HashSet<string> unlockedFastTravelIds  = new();
    public HashSet<string> visitedRooms           = new();
    public HashSet<string> collectedItems         = new();
    public HashSet<string> exploredRooms          = new(); // 地图探索（16_MapSystem）

    // 辅助方法
    public bool HasAbility(AbilityType ability)
        => unlockedAbilities.Contains(ability.ToString());

    public bool HasDefeatedBoss(string bossId)
        => defeatedBosses.Contains(bossId);
}
```

---

## 9. 区域解锁与地图联动

当 `OnRegionUnlocked` 事件触发时，地图系统（P1）更新对应区域的显示状态：

```
区域解锁流程:
  BossProgressTracker.OnBossDefeated()
  → SaveData.defeatedBosses.Add(bossId)
  → OnRegionUnlocked.Raise(bossId)
    ├─ 相邻 ProgressLock: 检测条件满足 → ApplyState(unlocked=true)（门开启）
    ├─ P1 MapManager: 将下一区域标记为"可探索"（地图上显示区域轮廓）
    └─ P1 UIManager: 短暂显示"新区域解锁"提示（屏幕上方滑入 ToastNotification）
```

---

## 10. 事件频道

新增频道（`Assets/ScriptableObjects/Events/Progression/`）：

| 资产名 | 类型 | 触发时机 |
|--------|------|---------|
| `OnAbilityUnlocked.asset` | `StringEventChannelSO` | 玩家获得新能力，传递 abilityId |
| `OnBossDefeated.asset` | `StringEventChannelSO` | Boss 击败，传递 bossId（由 BossBase 触发）|
| `OnRegionUnlocked.asset` | `StringEventChannelSO` | Boss 击败后，传递解锁的区域 ID |
| `OnMaxHPChanged.asset` | `IntEventChannelSO` | MaxHP 增加（HP容器拾取后），HPContainer UI 响应 |
| `OnProgressLockOpened.asset` | `StringEventChannelSO` | ProgressLock 开启，传递 lockId（P1：地图动效）|

> `OnAbilityUnlocked.asset` 与 [08_WorldSystem.md §8](./08_WorldSystem.md) 的 `AbilityUnlock` 组件共用同一频道。

---

## 11. 编辑器友好设计

- `AbilityGate` Gizmo：在 Scene View 显示对应能力图标（叠加在阻挡碰撞体上方），红色=阻挡中，绿色=已解锁
- `ProgressLock` Custom Inspector：显示当前 lockId、解锁条件、运行时是否满足（绿色勾选 / 红色叉）
- `RegionDefinitionSO` Custom Inspector：列出该区域所有房间场景，并标注是否存在（路径是否有效）
- EditorWindow `ProgressionChecker`：扫描全部场景，列出所有 AbilityGate / ProgressLock，检测是否有孤立（lockId 未被任何 BossProgressTracker 引用）的进程锁（UI Toolkit `ListView` + `MultiColumnListView`，`CreateGUI()` 实现）

---

## 12. 序列越级防护矩阵（Sequence Break Prevention）

> 配合 [49_AntiSoftlockSystem.md](./49_AntiSoftlockSystem.md) 使用。本节定义各区域的越级风险等级与应对策略。

**越级（Sequence Break）**定义：玩家在未获得预期能力的情况下，提前进入设计意图为后续区域的内容。

### 12.1 各区域越级风险矩阵

| 越级路径 | 所需绕过的 AbilityGate | 风险等级 | 处理策略 |
|---------|----------------------|---------|---------|
| Forest → Cave（跳过 FlorestBoss）| `AbilityGate_Cave_Entrance` (无要求)  | 🟢 低 | 允许（Cave 入口无能力要求）|
| Forest → Ruins（跳过 Cave）| `AbilityGate_Ruins_MainGate` (需 Dash) | 🟡 中 | Dash 门严格，绕行需精确跳跃（允许但罕见）|
| Cave → Abyss（跳过 Ruins）| `AbilityGate_Abyss_Bridge` (需 DoubleJump) | 🟡 中 | 允许序列越级（速通路线）；HardAbilityGate：显示越级警告 |
| 任意区域 → Core（最终区域）| `AbilityGate_Core_Gate` (需 Swim+Dash+DoubleJump) | 🔴 高 | 三能力全部严格验证，不允许物理绕过 |
| 获得 Swim 前进入液体深区 | `AbilityGate_DeepWater` (需 Swim) | 🟡 中 | 无 Swim = 液体中失血，玩家自然死亡重生（不软锁）|
| 获得 WallJump 前进入攀墙区 | `AbilityGate_VerticalShaft` (需 WallJump) | 🟢 低 | 可从底部进入，无能力时 SoftlockDetector 兜底 |

### 12.2 HardAbilityGate（强制门）规范

**普通 AbilityGate** vs **HardAbilityGate** 的区别：

| 属性 | AbilityGate | HardAbilityGate |
|------|------------|----------------|
| 物理阻挡 | 碰撞体阻挡 | 碰撞体阻挡 + Trigger 警告 |
| 绕过提示 | 无 | 显示"此路需要 [能力] 才能安全通过" |
| 序列越级标记 | 无 | `sequenceBreakRisk = true`（供 QA 分析用）|
| 应用场景 | 普通进程门 | 核心区域入口、不可逆操作前 |

```csharp
// HardAbilityGate 仅在 Core 区入口和高风险路径使用
// 其余区域用普通 AbilityGate，保留速通路线可能性
[SerializeField] bool sequenceBreakRisk = false;
[SerializeField] string warningLocKey;  // 若 sequenceBreakRisk = true，显示此警告
```

### 12.3 序列越级分析工具

`EscapeGuaranteeValidator`（见 49_AntiSoftlockSystem §6）在执行 BFS 分析时，同时标注所有可能的序列越级路径，输出报告供关卡设计师审查：

```
[越级路径报告]
✓ Forest → Ruins (via precision jump above AbilityGate_Ruins_SideGate)
  风险: 低 | 已知速通路线 | SoftlockDetector: 覆盖
⚠ Cave_B3 → Abyss_Top (via wall clip at X=234, Y=89)
  风险: 中 | 玩家可能卡在 Abyss 无 DoubleJump | SoftlockDetector: 覆盖
✗ Ruins → Core (无已知越级路径)
  HardAbilityGate 三重验证
```