# Phase 0 · 项目基础设施

> **周期**：1 周  
> **前置条件**：Unity 2022.3 LTS 项目已创建，以下 Package 已导入：Cinemachine 3、New Input System、2D Pixel Perfect、Addressables、Newtonsoft Json、Kybernetik Animancer Pro、PathBerserker2d、Behavior Designer、Feel（More Mountains）  
> **产出物**：编译无错；能运行 Persistent 场景；能读写 JSON 存档；asmdef 依赖方向验证通过

---

## 目录

1. [实施顺序总览](#1-实施顺序总览)
2. [Day 1：文件夹与 asmdef 骨架](#2-day-1文件夹与-asmdef-骨架)
3. [Day 2：SO 事件系统](#3-day-2so-事件系统)
4. [Day 3：Core 模块](#4-day-3core-模块)
5. [Day 4：Addressables 与对象池骨架](#5-day-4addressables-与对象池骨架)
6. [Day 5：SaveData 骨架 + Persistent 场景验证](#6-day-5savedata-骨架--persistent-场景验证)
7. [完成标准检查清单](#7-完成标准检查清单)

---

## 1. 实施顺序总览

```
Day 1: 文件夹结构 → asmdef 文件 → 依赖验证
  ↓
Day 2: BaseEventChannelSO 基类 → 所有具体频道类型 → Data/Events/ 资产
  ↓
Day 3: GameState + GameManager 骨架 → SceneLoader → SettingsManager + GlobalSettingsSO
  ↓
Day 4: AddressKeys → AssetLoader → GlobalObjectPool + PooledObject
  ↓
Day 5: SaveData C# 结构 → SaveManager 骨架 → Persistent 场景组装 → 全链路验证
```

**关键原则**：每步完成后确认编译无错再继续。asmdef 创建顺序遵循依赖图（无依赖的先创建）。

---

## 2. Day 1：文件夹与 asmdef 骨架

### 2.1 创建文件夹结构

按 `01_ProjectStructure §1` 在 `Assets/` 下创建以下文件夹（Unity 中不存在同名 .meta 则空文件夹不提交，用 `.gitkeep` 占位）：

```
Assets/
├── Scripts/
│   ├── Core/
│   │   ├── Events/
│   │   └── Save/
│   ├── Input/
│   ├── Camera/
│   ├── Player/
│   │   └── States/
│   ├── Combat/
│   │   └── StatusEffects/
│   ├── Parry/
│   ├── Enemies/
│   │   ├── AI/
│   │   ├── Boss/
│   │   │   └── Patterns/
│   │   └── Navigation/
│   ├── Feedback/
│   ├── World/
│   │   ├── Map/
│   │   └── Shop/
│   ├── UI/
│   ├── Audio/
│   ├── Progression/
│   ├── Dialogue/
│   ├── Equipment/
│   ├── Cutscene/
│   ├── Animation/
│   ├── Spells/
│   ├── Localization/
│   ├── Tutorial/
│   ├── Platform/
│   └── Editor/
│
├── Data/
│   ├── Events/
│   │   ├── Core/
│   │   ├── Player/
│   │   ├── Combat/
│   │   ├── World/
│   │   └── UI/
│   ├── Player/
│   ├── Combat/
│   ├── Enemies/
│   ├── Progression/
│   ├── Audio/
│   ├── World/
│   ├── UI/
│   └── Settings/
│
├── Prefabs/
│   ├── Player/
│   ├── Enemies/
│   ├── World/
│   ├── UI/
│   ├── Combat/
│   ├── Effects/
│   └── Persistent/
│
└── Scenes/
```

### 2.2 创建 Assembly Definition 文件

**创建顺序（依赖图自底向上）**：

| 顺序 | 文件路径 | Assembly 名 | 引用 |
|------|---------|-------------|------|
| 1 | `Scripts/Core/Events/BaseGames.Core.Events.asmdef` | `BaseGames.Core.Events` | 无 |
| 2 | `Scripts/Core/Save/BaseGames.Core.Save.asmdef` | `BaseGames.Core.Save` | Core.Events, Newtonsoft.Json |
| 3 | `Scripts/Core/BaseGames.Core.asmdef` | `BaseGames.Core` | Core.Events, Core.Save |
| 4 | `Scripts/Input/BaseGames.Input.asmdef` | `BaseGames.Input` | Core.Events, Unity.InputSystem |
| 5 | `Scripts/Camera/BaseGames.Camera.asmdef` | `BaseGames.Camera` | Core.Events, Cinemachine |
| 6 | `Scripts/Combat/BaseGames.Combat.asmdef` | `BaseGames.Combat` | Core.Events |
| 7 | `Scripts/Combat/StatusEffects/BaseGames.Combat.StatusEffects.asmdef` | `BaseGames.Combat.StatusEffects` | Combat |
| 8 | `Scripts/Parry/BaseGames.Parry.asmdef` | `BaseGames.Parry` | Combat |
| 9 | `Scripts/Feedback/BaseGames.Feedback.asmdef` | `BaseGames.Feedback` | Core.Events, Combat |
| 10 | `Scripts/Player/BaseGames.Player.asmdef` | `BaseGames.Player` | Core, Input, Combat, Parry, Feedback, Animancer |
| 11 | `Scripts/Player/States/BaseGames.Player.States.asmdef` | `BaseGames.Player.States` | Player |
| 12 | `Scripts/Enemies/BaseGames.Enemies.asmdef` | `BaseGames.Enemies` | Core, Combat, Feedback, Animancer |
| 13 | `Scripts/Enemies/AI/BaseGames.Enemies.AI.asmdef` | `BaseGames.Enemies.AI` | Enemies, BehaviorDesigner.Runtime |
| 14 | `Scripts/Enemies/Navigation/BaseGames.Enemies.Navigation.asmdef` | `BaseGames.Enemies.Navigation` | Enemies, PathBerserker2d |
| 15 | `Scripts/World/BaseGames.World.asmdef` | `BaseGames.World` | Core, Combat, Animancer |
| 16 | `Scripts/UI/BaseGames.UI.asmdef` | `BaseGames.UI` | Core.Events |
| 17 | `Scripts/Audio/BaseGames.Audio.asmdef` | `BaseGames.Audio` | Core.Events |
| 18 | `Scripts/Progression/BaseGames.Progression.asmdef` | `BaseGames.Progression` | Core, Player |
| 19 | `Scripts/Equipment/BaseGames.Equipment.asmdef` | `BaseGames.Equipment` | Core.Events, Player |
| 20 | `Scripts/Spells/BaseGames.Spells.asmdef` | `BaseGames.Spells` | Core.Events, Player, Combat |
| 21 | `Scripts/World/Map/BaseGames.World.Map.asmdef` | `BaseGames.World.Map` | World, Core.Save |
| 22 | `Scripts/World/Shop/BaseGames.World.Shop.asmdef` | `BaseGames.World.Shop` | World, Core.Events |
| 23 | `Scripts/Dialogue/BaseGames.Dialogue.asmdef` | `BaseGames.Dialogue` | Core.Events |
| 24 | `Scripts/Cutscene/BaseGames.Cutscene.asmdef` | `BaseGames.Cutscene` | Core.Events, Dialogue |
| 25 | `Scripts/Animation/BaseGames.Animation.asmdef` | `BaseGames.Animation` | Core.Events, Animancer |
| 26 | `Scripts/Enemies/Boss/Patterns/BaseGames.Enemies.Boss.Patterns.asmdef` | `BaseGames.Enemies.Boss.Patterns` | Enemies, Combat |
| 27 | `Scripts/Localization/BaseGames.Localization.asmdef` | `BaseGames.Localization` | Core.Events |
| 28 | `Scripts/Platform/BaseGames.Platform.asmdef` | `BaseGames.Platform` | Core.Events |
| 29 | `Scripts/Tutorial/BaseGames.Tutorial.asmdef` | `BaseGames.Tutorial` | Core.Events, World |
| 30 | `Scripts/Editor/BaseGames.Editor.asmdef` | `BaseGames.Editor` | 全部（Editor Only，`includePlatforms: ["Editor"]`） |

### 2.3 放置占位脚本

每个 asmdef 目录放一个 `_Placeholder.cs`（仅 namespace 声明），确保 Unity 不报"asmdef 无脚本"警告：

```csharp
// _Placeholder.cs
namespace BaseGames.Core { }  // 各目录对应 namespace
```

### 2.4 验证依赖方向

在 Unity Editor 打开 **Edit → Project Settings → Player → Other Settings** 确认无编译错误。  
确认底层 asmdef 的引用列表里**没有**高层 asmdef 名称。

---

## 3. Day 2：SO 事件系统

**参考文档**：`02_EventSystem.md`

### 3.1 实现基类（`Assets/Scripts/Core/Events/`）

按顺序创建以下文件：

```
BaseEventChannelSO.cs              ← 泛型基类 + VoidBaseEventChannelSO
VoidEventChannelSO.cs              ← [CreateAssetMenu]
BoolEventChannelSO.cs
IntEventChannelSO.cs
FloatEventChannelSO.cs
StringEventChannelSO.cs
Vector2EventChannelSO.cs
TransformEventChannelSO.cs
GameState.cs                       ← 枚举（顺便在此处定义）
GameStateEventChannelSO.cs
SceneLoadRequest.cs                ← struct（sceneName + entryId + loadingScreen）
SceneLoadRequestEventChannelSO.cs
DifficultyLevel.cs                 ← 枚举（Easy/Normal/Hard/SteelSoul）
DifficultyChangedEventChannel.cs   ← Phase 2 难度系统用（按架构命名，非 DifficultyEventChannelSO）
DamageInfoEventChannelSO.cs        ← Combat 伤害事件（EVT_DamageDealt）
HitInfo.cs                         ← struct（DamageInfo + HitPoint Vector3）
HitConfirmedEventChannelSO.cs      ← VFX 命中事件（EVT_HitConfirmed，洛载类型 HitInfo）
ShopPurchaseEvent.cs               ← struct（⚠️ 架构 15_MapShopModule §2.3：ShopPurchaseEvent { Item, Price }；非旧版 ShopTransactionEvent）
ShopPurchaseEventChannelSO.cs      ← 商店购买事件（EVT_ItemPurchased，⚠️ 架构 15 §2.3；非旧版 EVT_ShopTransactionCompleted）
DialogueEventChannelSO.cs          ← 对话请求事件（EVT_DialogueStartRequest，⚠️ payload 为 DialogueDataSO SO 引用，非 struct；无 DialogueRequest 类，架构 02 §3）
LiquidEventChannelSO.cs            ← 液体进出事件（EVT_LiquidEntered / EVT_LiquidExited）
AbilityType.cs                     ← `[Flags] uint` 枚举（WallCling/WallJump/Dash/...）  ⚠️ 位于 Scripts/Player/（程序集 BaseGames.Player），非 Scripts/Progression/（架构 09_ProgressionModule §1）
AbilityTypeEventChannelSO.cs       ← 能力解锁事件（仅内部保留；⚠️ EVT_AbilityUnlocked 实际使用 StringEventChannelSO，架构 02 §4）
// ── Quest 事件频道（22_QuestChallengeModule §5）──────────────────────────────
QuestState.cs                      ← 枚举（Unavailable/Available/Active/Completed/Failed）
QuestStateChangedEvent.cs          ← struct { string QuestId; QuestState State; }
QuestStateChangedEventChannel.cs   ← 任务状态变更（⚠️ 按架构命名，无 SO 后缀）
QuestObjectiveEventChannelSO.cs    ← 任务目标进度（payload: QuestObjectiveEvent{QuestId, ObjectiveId, Progress, Required}，架构 02 §3）
StatusEffectEventChannelSO.cs      ← 状态效果施加/过期（payload: StatusEffectType 枚举，架构 02 §3）
// ── Boss 技能事件频道（23_BossSkillModule §11）─────────────────────────────
BossSkillEventChannelSO.cs         ← Boss 技能开始/结束（payload: (string bossId, string skillId)）
BossPhaseEventChannelSO.cs         ← Boss 阶段切换（payload: (string bossId, int phase)）
// ── 可访问性事件频道（16_SupportingModules §AccessibilityManager）──────────
ColorblindMode.cs                  ← 枚举（None/Deuteranopia/Protanopia/Tritanopia）
ColorblindModeEventChannelSO.cs    ← 色觉模式切换事件（EVT_ColorblindModeChanged）
// ── 导航标记事件频道（21_LiquidPuzzleModule §14）─────────────────────────────
WorldMarkerEventChannelSO.cs       ← 导航标记激活/失活（EVT_WorldMarkerActivated / EVT_WorldMarkerDeactivated）
```

### 3.2 在 `Assets/Data/Events/` 下预建全局 SO 资产

命名规范：`EVT_{EventName}.asset`（不含模块前缀中的下划线，与架构 `02_EventSystem` 一致）

**Core 事件**（`Data/Events/Core/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_PlayerDied` | `VoidEventChannelSO` |
| `EVT_PlayerRespawned` | `VoidEventChannelSO` |
| `EVT_PauseRequested` | `VoidEventChannelSO` |
| `EVT_DeathScreenConfirmed` | `VoidEventChannelSO` |
| `EVT_GameStateChanged` | `GameStateEventChannelSO` |
| `EVT_SceneLoadRequest` | `SceneLoadRequestEventChannelSO` |
| `EVT_SceneLoaded` | `StringEventChannelSO` |
| `EVT_SavePointActivated` | `StringEventChannelSO` |
| `EVT_DifficultyChanged` | `DifficultyChangedEventChannel` |

**UI 事件**（`Data/Events/UI/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_FadeIn` | `VoidEventChannelSO` |
| `EVT_FadeOut` | `VoidEventChannelSO` |
| `EVT_FastTravelOpen` | `VoidEventChannelSO` |
| `EVT_ShopOpened` | `StringEventChannelSO` |
| `EVT_ShopClosed` | `VoidEventChannelSO` |
| `EVT_MapOpen` | `VoidEventChannelSO` |
| `EVT_ShowPanel` | `StringEventChannelSO`（panelId） |
| `EVT_HidePanel` | `StringEventChannelSO`（panelId） |

**Player 事件**（`Data/Events/Player/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_HPChanged` | `IntEventChannelSO` |
| `EVT_MaxHPChanged` | `IntEventChannelSO` |
| `EVT_SoulPowerChanged` | `IntEventChannelSO` |
| `EVT_SpiritPowerChanged` | `IntEventChannelSO` |
| `EVT_SpringChargesChanged` | `IntEventChannelSO` |
| `EVT_GeoChanged` | `IntEventChannelSO` |
| `EVT_PlayerFormChanged` | `IntEventChannelSO` |
| `EVT_AbilityUnlocked` | `StringEventChannelSO`（abilityId，⚠️ 非 AbilityTypeEventChannelSO，架构 02 §4） |
| `EVT_SkillSetChanged` | `VoidEventChannelSO`（发布: FormController，订阅: SkillHUD） |
| `EVT_ShieldHPChanged` | `IntEventChannelSO`（发布: ShieldComponent，订阅: HUDController） |
| `EVT_ShieldBroken` | `VoidEventChannelSO` |
| `EVT_ShieldRestored` | `VoidEventChannelSO` |

**Combat 事件**（`Data/Events/Combat/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_EnemyDied` | `TransformEventChannelSO` |
| `EVT_DamageDealt` | `DamageInfoEventChannelSO` |
| `EVT_HitConfirmed` | `HitConfirmedEventChannelSO` |
| `EVT_ParrySuccess` | `VoidEventChannelSO` |
| `EVT_BossFightStarted` | `StringEventChannelSO`（bossId；⚠️ 属战斗事件，架构 02 §4，非 Core 事件） |
| `EVT_BossFightEnded` | `BoolEventChannelSO`（⚠️ 属战斗事件，架构 02 §4，非 Core 事件） |
| `EVT_BossFightToggled` | `BoolEventChannelSO`（true=开始，false=结束） |
| `EVT_BossHPChanged` | `IntEventChannelSO` |
| `EVT_BossNameSet` | `StringEventChannelSO`（bossName） |
| `EVT_BossHPMaxSet` | `IntEventChannelSO` |
| `EVT_NailClash` | `VoidEventChannelSO` |
| `EVT_StatusEffectApplied` | `StatusEffectEventChannelSO` |
| `EVT_StatusEffectExpired` | `StatusEffectEventChannelSO` |
| `EVT_BossSkillStarted` | `BossSkillEventChannelSO` |
| `EVT_BossSkillEnded` | `BossSkillEventChannelSO` |
| `EVT_BossVulnerabilityWindowOpened` | `StringEventChannelSO` |
| `EVT_BossPhaseChanged` | `BossPhaseEventChannelSO` |

**World 事件**（`Data/Events/World/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_CollectiblePickup` | `StringEventChannelSO` |
| `EVT_RoomEntered` | `StringEventChannelSO` |
| `EVT_RoomTransitionRequest` | `SceneLoadRequestEventChannelSO` |
| `EVT_MapUpdated` | `StringEventChannelSO` |
| `EVT_LiquidEntered` | `LiquidEventChannelSO` |
| `EVT_LiquidExited` | `LiquidEventChannelSO` |
| `EVT_DrownProgress` | `FloatEventChannelSO`（0–1 进度） |
| `EVT_PlayerDrowned` | `VoidEventChannelSO` |
| `EVT_GeoRecovered` | `StringEventChannelSO` |
| `EVT_ShowInteractPrompt` | `StringEventChannelSO` |
| `EVT_HideInteractPrompt` | `VoidEventChannelSO` |
| `EVT_WorldMarkerActivated` | `WorldMarkerEventChannelSO` |
| `EVT_WorldMarkerDeactivated` | `WorldMarkerEventChannelSO` |
| `EVT_ItemPurchased` | `ShopPurchaseEventChannelSO` |

**Audio 事件**（`Data/Events/Audio/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_PlayBGM` | `StringEventChannelSO` |
| `EVT_StopBGM` | `VoidEventChannelSO` |
| `EVT_PlaySFX` | `StringEventChannelSO` |
| `EVT_RegionEntered` | `StringEventChannelSO` |

**Dialogue 事件**（`Data/Events/Dialogue/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_DialogueStartRequest` | `DialogueEventChannelSO` |
| `EVT_DialogueStarted` | `VoidEventChannelSO` |
| `EVT_DialogueEnded` | `VoidEventChannelSO` |
| `EVT_NpcDialogueCompleted` | `StringEventChannelSO` |
| `EVT_CutsceneStarted` | `VoidEventChannelSO` |
| `EVT_CutsceneEnded` | `VoidEventChannelSO` |

**Quest 事件**（`Data/Events/Quest/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_QuestStarted` | `StringEventChannelSO`（questId，⚠️ 架构命名，对应 QuestManager.StartQuest()，架构 02 §4） |
| `EVT_QuestCompleted` | `StringEventChannelSO`（questId） |
| `EVT_QuestFailed` | `StringEventChannelSO`（questId） |
| `EVT_ObjectiveUpdated` | `QuestObjectiveEventChannelSO`（QuestObjectiveEvent） |
| `EVT_QuestStateChanged` | `QuestStateChangedEventChannel` |
| `EVT_ChallengeCompleted` | `StringEventChannelSO` |
| `EVT_ChallengeFailed` | `StringEventChannelSO` |

**事件链 / EventChain 事件**（`Data/Events/EventChain/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_ChainCompleted` | `StringEventChannelSO` |
| `EVT_DoorOpened` | `StringEventChannelSO` |
| `EVT_FlagChanged` | `StringEventChannelSO` |

**Save 事件**（`Data/Events/Save/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_SaveIndicatorVisible` | `BoolEventChannelSO` |

**Accessibility 事件**（`Data/Events/Accessibility/`）：

| 资产名 | 类型 |
|--------|------|
| `EVT_AchievementUnlocked` | `StringEventChannelSO` |
| `EVT_SoftlockDetected` | `VoidEventChannelSO` |
| `EVT_ColorblindModeChanged` | `ColorblindModeEventChannelSO` |
| `EVT_SubtitlesToggled` | `BoolEventChannelSO` |
| `EVT_HighContrastToggled` | `BoolEventChannelSO` |

> **说明**：DamageInfoEventChannelSO、HitConfirmedEventChannelSO 等具体 channel 类型的脚本在 Day 2 §3.1 中一并创建；对应 SO 资产在创建完类型后立即在 Inspector 中创建。所有事件频道资产后续在各模块实现时如需补充，按此规范追加。

### 3.3 验证

在 Editor 中创建一个临时 `TestEventChannel.cs`，订阅 `EVT_PlayerDied.OnEventRaised` 并打印日志，在 Inspector 点击"Raise"按钮（需在 `BaseEventChannelSO` Editor 脚本里添加测试按钮）确认事件触发。

---

## 4. Day 3：Core 模块

**参考文档**：`03_CoreModule.md`

### 4.1 实现文件列表（`Assets/Scripts/Core/`）

```
GameStateId.cs            ← struct（替代旧 enum GameState，可扩展的状态 ID）
IGameState.cs             ← 状态接口（OnEnter / OnExit / Tick）
GameStateMachine.cs       ← 驱动所有 IGameState 切换的状态机
GameStates.cs             ← 静态工厂：提供 8 个内置状态实例（MainMenu/Gameplay/Paused/BossFight/Cutscene/Loading/Dead/GameOver）
IGameStateFactory.cs      ← DLC/扩展工厂接口（注册自定义状态）
GameManager.cs            ← 字段 + 接口签名（Awake/Start 骨架；内嵌 GameStateMachine）
GameStateEventChannelSO.cs ← payload 改为 GameStateId（⚠️ 非旧枚举）
SceneLoader.cs            ← LoadAsync 骨架（监听 EVT_SceneLoadRequest）
SettingsManager.cs        ← Load/Save 设置
GlobalSettingsSO.cs       ← SO 数据类
// ── 服务层骨架（03_CoreModule §11-13）───────────────────────────────────────
ServiceLocator.cs         ← 静态类（Register/Get/GetOrDefault/OverrideForTest/Reset）
GameServiceRegistrar.cs   ← MonoBehaviour，ExecutionOrder -2000，DontDestroyOnLoad
IAudioService.cs          ← 音频服务接口
ISaveService.cs           ← 存档服务接口
ISceneService.cs          ← 场景加载服务接口（UniTask-based）
IDeathRespawnService.cs   ← 死亡/重生服务接口（UniTask-based）
IEventChannelRegistry.cs  ← SO 事件频道查找接口
NullAudioService.cs       ← IAudioService 的空实现（测试兜底）
DeathRespawnService.cs    ← IDeathRespawnService 骨架（Phase 1 实现完整逻辑）
SceneService.cs           ← ISceneService 骨架（封装 SceneLoader，Phase 1 完整实现）
```

> **⚠️ 架构升级**：`GameState` 枚举已全面替换为 `GameStateId` struct + `IGameState` 接口体系（架构 03_CoreModule §2）。
> 旧写法 `TransitionTo(GameState.Gameplay)` 改为 `TransitionTo(GameStates.Gameplay)`；
> 订阅方将收到 `GameStateId` 而非枚举值。

### 4.2 GameManager 实现优先级

Day 3 只实现**骨架部分**，不实现完整死亡/复活流程（Phase 1 完成）：

```csharp
// Day 3 实现范围
// GameStateId 是 struct，不是 enum，通过 GameStates 静态类获取内置实例
// IGameState 接口：void OnEnter(); void OnExit(); void Tick(float dt);
// GameStateMachine 包含 TransitionTo(IGameState next)，GameManager 内嵌实例

void Awake()  
{
    // 1. 单例检查（DontDestroyOnLoad 由 Persistent 场景保证）
    // 2. 订阅事件频道（6个监听）
    // 3. _stateMachine.TransitionTo(GameStates.MainMenu) — 占位
    Debug.Log($"[GameManager] Awake v{Application.version}");
}

// 占位实现（不报错即可）
public void TransitionTo(IGameState newState) { _stateMachine.TransitionTo(newState); }
public void Pause()  { TransitionTo(GameStates.Paused); }
public void Resume() { TransitionTo(GameStates.Gameplay); }
```

### 4.3 SceneLoader 实现

```csharp
// Day 3 实现范围
// 订阅 EVT_SceneLoadRequest，执行 Addressables.LoadSceneAsync
// 加载完成后发布 EVT_SceneLoaded
// _currentRoomScene 记录当前场景名，用于 Unload
```

### 4.4 GlobalSettingsSO

```csharp
// ⚠️ 字段名、menuName、结构均必须与架构 03_CoreModule §7 一致
[CreateAssetMenu(menuName = "Settings/GlobalSettings")]
public class GlobalSettingsSO : ScriptableObject
{
    [Header("Audio")]
    public float DefaultMasterVolume  = 1f;
    public float DefaultBGMVolume     = 0.8f;
    public float DefaultSFXVolume     = 1f;
    public float DefaultAmbientVolume = 0.8f;   // ⚠️ 与 AudioMixerKeys.Ambient 对应

    [Header("Display")]
    public int   DefaultTargetFPS    = 60;
    public bool  DefaultVSync        = false;

    [Header("Language")]
    public string DefaultLocaleCode  = "zh-CN";

    [Header("Accessibility")]
    public bool DefaultHighContrast  = false;
    public bool DefaultScreenShake   = true;
}

[System.Serializable]
public class GlobalSettingsData
{
    public float MasterVolume;
    public float BGMVolume;
    public float SFXVolume;
    public float AmbientVolume;   // ⚠️ 与 AudioMixerKeys.Ambient 对应
    public int   TargetFPS;
    public bool  VSync;
    public string LocaleCode;
    public bool  HighContrast;
    public bool  ScreenShake;
}
```

`SettingsManager.Awake()` 从 `PlayerPrefs` 恢复设置到 `GlobalSettingsData`；`Apply()` 方法将数据应用到 Unity `QualitySettings`/`Screen`/`PlayerPrefs`。

---

## 5. Day 4：Addressables 与对象池骨架

**参考文档**：`13_AssetPoolModule.md`

### 5.1 AddressKeys

```csharp
// Assets/Scripts/Core/Assets/AddressKeys.cs
// ⚠️ 命名规则：camelCase（无下划线分隔），字符串值保持原样（架构 13_AssetPoolModule §1 patch）
public static class AddressKeys
{
    // Scenes
    public const string ScenePersistent = "Scene_Persistent";  // ⚠️ 值为 "Scene_Persistent"（非 "Persistent"）
    public const string SceneMainMenu   = "Scene_MainMenu";
    public const string SceneTestRoom   = "Scene_TestRoom";    // Phase 1 测试房间

    // Player
    public const string PrefabPlayer    = "PLY_Player";        // ⚠️ camelCase（非 Prefab_Player）

    // 其余常量在各 Phase 按需追加（统一 camelCase 命名规则）
}
```

### 5.2 AssetLoader

```csharp
// Assets/Scripts/Core/Assets/AssetLoader.cs
// ⚠️ 架构使用标准 Task（非 UniTask），见 13_AssetPoolModule §5
public static class AssetLoader
{
    // 异步加载单个资产（带缓存）
    public static async Task<T> LoadAsync<T>(string addressKey) where T : UnityEngine.Object;

    // 释放（减引用计数）
    public static void Release(string addressKey);

    // 释放全部缓存
    public static void ReleaseAll();
}
```

### 5.3 GlobalObjectPool

```csharp
// Assets/Scripts/Core/Pool/GlobalObjectPool.cs
// ⚠️ 最终 API 见 13_AssetPoolModule §3；Phase 0 仅建骨架，不实现全量
[DefaultExecutionOrder(-800)]
public class GlobalObjectPool : MonoBehaviour
{
    // 预热：按 _warmupConfigs 配置批量实例化所有条目（无参数，以 Task 返回）
    public async Task WarmupAsync();

    // 获取对象（正式操作: Spawn）
    public T Spawn<T>(string addressKey, Vector3 position, Quaternion rotation) where T : Component;

    // 归还对象（正式操作: Despawn）
    public void Despawn(string addressKey, GameObject instance);
}
```

### 5.3.1 WarmupManifestSO（Phase 1 优化，架构 13 §12）

> Phase 0 仅建骨架；Phase 1 Vertical Slice 阶段完善 `SceneService.LoadSceneAsync()` 时一并实现。

```csharp
// Assets/Scripts/Core/Pool/WarmupManifestSO.cs
[CreateAssetMenu(menuName = "Core/Pool/Warmup Manifest")]
public class WarmupManifestSO : ScriptableObject
{
    [Serializable]
    public struct WarmupEntry
    {
        public string          AddressKey;       // AddressKeys 常量
        public int             InitialCount;     // 预热实例数
        public WarmupCategory  Category;
    }

    public enum WarmupCategory { Enemy = 0, Projectile = 1, VFX = 2, UI = 3, Other = 99 }

    public WarmupEntry[] Entries;
    [Range(1, 20)] public int InstancesPerFrame = 5;  // 每帧最多实例化数量（防卡顿）
}

// GlobalObjectPool 新增方法（Phase 1 补充）：
// public async UniTask WarmupFromManifestAsync(WarmupManifestSO manifest, CancellationToken ct)
// → 分帧预热：每帧最多实例化 manifest.InstancesPerFrame 个，await UniTask.Yield() 让出帧

// SceneService.LoadSceneAsync() 调用：
// await GlobalObjectPool.Instance.WarmupFromManifestAsync(_warmupManifest, ct);

// 资产路径：Assets/Data/Pool/Warmup/Global_Warmup.asset、{SceneName}_Warmup.asset 等
```

### 5.4 PooledObject

```csharp
// Assets/Scripts/Core/Pool/PooledObject.cs
// ⚠️ 完整实现（对齐架构 13_AssetPoolModule §4）；Phase 0 先创建此完整版本，后续直接使用
public class PooledObject : MonoBehaviour
{
    public string AddressKey { get; private set; }  // ⚠️ 属性而非公共字段（架构 13 §4）
    private GlobalObjectPool _pool;

    // 由 GlobalObjectPool.SpawnInternal 调用，注入 key 和 pool 引用
    public void Setup(string key, GlobalObjectPool pool)
    {
        AddressKey = key;
        _pool = pool;
    }

    // 子类可覆盖（从池中取出时调用）
    public virtual void OnSpawn()  { }

    // 子类可覆盖（归还到池时调用）
    public virtual void OnDespawn(){ }

    // 便利方法：自归还
    public void ReturnToPool() => _pool?.Despawn(AddressKey, gameObject);

    // 延迟归还（定时销毁型 VFX / 弹射物常用）
    public void ReturnToPoolDelayed(float delay) => StartCoroutine(DelayedReturn(delay));
    private IEnumerator DelayedReturn(float delay)
    {
        yield return new WaitForSeconds(delay);
        ReturnToPool();
    }
}
```

### 5.5 AssetReleaseTracker

```csharp
// Assets/Scripts/Core/Assets/AssetReleaseTracker.cs
// ⚠️ 完整实现对齐架构 13_AssetPoolModule §8：事件驱动，订阅 SceneLoadRequestEventChannelSO
// ⚠️ 不使用 RegisterForScene/ReleaseScene 显式注册 API（SceneLoader 不主动调用本类）
public class AssetReleaseTracker : MonoBehaviour
{
    [Header("Event Channels")]
    [SerializeField] private SceneLoadRequestEventChannelSO _onSceneLoadRequest;

    private string _lastLoadedScene;

    private void OnEnable()
        => _onSceneLoadRequest.OnEventRaised += OnSceneLoadRequested;
    private void OnDisable()
        => _onSceneLoadRequest.OnEventRaised -= OnSceneLoadRequested;

    private void OnSceneLoadRequested(SceneLoadRequest req)
    {
        if (!string.IsNullOrEmpty(_lastLoadedScene))
        {
            // 清除旧场景的对象池（⚠️ GlobalObjectPool.ClearPool 方法存在，架构 13_AssetPoolModule §3）
            GlobalObjectPool.Instance.ClearPool(AddressKeys.PrefabEnemyGrunt);
            // ... 其他场景对象（按需追加）
        }
        _lastLoadedScene = req.SceneName;
    }
}
```

### 5.6 Editor 验证工具

在 `Assets/Scripts/Editor/AddressKeysValidator.cs` 创建菜单项 `Tools/Validate AddressKeys`：
- 反射读取 `AddressKeys` 所有 `const string`
- 对照 `Addressables.ResourceLocators` 验证每个 key 是否存在
- 不匹配的 key 输出 Warning

---

## 6. Day 5：SaveData 骨架 + Persistent 场景验证

**参考文档**：`12_SaveModule.md §1-4`

### 6.1 SaveData C# 数据结构

创建 `Assets/Scripts/Core/Save/` 下所有数据类（完整结构）：

```
SaveData.cs                ← 顶层 + JsonExtensionData
SaveMeta.cs                ← 版本号、难度、游戏时间
PlayerSaveData.cs          ← HP、位置、灵力、形态等
EquipmentSaveData.cs       ← 护符相关（⚠️ 工具槽数据在独立的 ToolsSaveData，见架构 12_SaveModule §2）
WorldSaveData.cs           ← 房间状态、已破坏地形、已触发机关
MapSaveData.cs             ← 已探索房间列表
QuestSaveData.cs           ← 任务进度
AchievementSaveData.cs
ToolsSaveData.cs
StatsSaveData.cs
DeathShadeSaveData.cs
ChallengeRoomsSaveData.cs  ← 挑战房间进度（架构 12_SaveModule §1）
EventChainsSaveData.cs     ← 事件链状态（架构 12_SaveModule §1）
ShopsSaveData.cs           ← 商店已购记录（架构 12_SaveModule §1）
NGPlusSaveData.cs          ← New Game+ 数据（架构 12_SaveModule §1）
```
⚠️ `SaveData` 类**不含** `Tutorial` 字段（架构 12 §1 无 `TutorialSaveData`），教程进度应通过 `PlayerPrefs` 或独立 JSON 文件持久化，不经过存档系统。

### 6.2 ISaveStorage + LocalFileStorage

```csharp
// Assets/Scripts/Core/Save/ISaveStorage.cs
// ⚠️ 接口方法操作原始 JSON 字符串（架构 12_SaveModule §2）；序列化/校验由 SaveManager 负责
// ⚠️ 返回类型为标准 Task（非 UniTask）
public interface ISaveStorage
{
    Task WriteAsync(int slotIndex, string json);
    Task<string> ReadAsync(int slotIndex);
    Task DeleteAsync(int slotIndex);
    bool Exists(int slotIndex);
    IEnumerable<int> GetExistingSlots();
}

// Assets/Scripts/Core/Save/LocalFileStorage.cs
// ⚠️ 类名无 Save 前缀（架构 12_SaveModule §2）
// 存档路径: Application.persistentDataPath/saves/save_{slot}.json
public class LocalFileStorage : ISaveStorage { }
```

### 6.3 SaveManager 骨架

```csharp
// Assets/Scripts/Core/Save/SaveManager.cs
// ⚠️ 返回类型为标准 Task（非 UniTask），见架构 12_SaveModule §4
[DefaultExecutionOrder(-900)]
public class SaveManager : MonoBehaviour
{
    // 存档当前状态（由 EVT_SavePointActivated 触发）
    public async Task SaveAsync(int slot = -1);     // 遍历 _saveables → 序列化 → WriteAsync
    // 读取并恢复存档（返回 false 表示槽位不存在或校验失败）
    public async Task<bool> LoadAsync(int slot);    // ReadAsync → 反序列化 → 遍历 _saveables
    public bool SlotExists(int slot);
    public IEnumerable<int> GetExistingSlots();
    public void Register(ISaveable saveable);
    public void Unregister(ISaveable saveable);
}
```

### 6.4 组装 Persistent 场景

在 `Persistent.unity` 创建以下 GameObject 层级（组件留空或骨架绑定）：

```
[Managers]
├── GameManager        ← GameManager.cs，Inspector 绑定所有 EVT_ SO 资产
├── SceneLoader        ← SceneLoader.cs
├── GlobalObjectPool  ← GlobalObjectPool.cs
├── SaveManager        ← SaveManager.cs
└── SettingsManager    ← SettingsManager.cs + GlobalSettingsSO 资产引用
```

### 6.5 全链路验证

创建 `Scenes/TestRoom_Phase0.unity`（空房间，一个平台的 Tilemap）并完成以下验证：

| 验证项 | 方法 |
|--------|------|
| Persistent 场景加载 + GameManager Awake 打印版本号 | Play `Persistent.unity`，Console 看 Log |
| `SaveAsync(0)` 写入 JSON 存档文件（Phase 0 新游戏可手动构造初始 SaveData 后调用） | 菜单调用，检查 `persistentDataPath/saves/save_0.json` |
| `LoadAsync(0)` 读取并填充 `CurrentSave` | Debug.Log 打印 `CurrentSave.Meta.PlayTime` |
| `EVT_PlayerDied` Raise → `GameManager` 收到并打印 | Inspector "Raise" 按钮 |
| `AddressKeys.SceneTestRoom` 能被 `SceneLoader` 加载 | 调用 `GameManager.LoadRoom` |

---

## 7. 完成标准检查清单

```
✅ Unity 编译无错，Console 无 Error（脚本层全部创建完毕，2026-05-07）
✅ 所有 asmdef 依赖方向正确（低层不引用高层）
✅ SO 事件系统：Raise 能触发订阅者，OnDisable 能正确取消订阅
□ GlobalSettingsSO 序列化/反序列化无 JSON 报错（待 Unity Editor 运行验证）
□ SaveManager.SaveAsync(0) → 磁盘生成 save_0.json（待 Unity Editor 运行验证）
□ SaveManager.LoadAsync → CurrentSave 非 null，数据匹配（待 Unity Editor 运行验证）
□ SceneLoader 能 Additive 加载/卸载 TestRoom 场景（待 TestRoom 场景创建后验证）
□ GlobalObjectPool.Spawn<PooledObject> 能返回实例，Despawn 能归还（待 Unity Editor 运行验证）
□ AddressKeysValidator 无 Warning（当前定义的 key 均已在 Addressables 分组中）
□ Persistent 场景 GameManager.Awake 打印版本号（待 Persistent 场景组装后验证）
```

> **Phase 0 代码层完成于 2026-05-07。** 运行时验证项待 Phase 1 场景组装完成后一并执行。

**Phase 0 完成后进入 Phase 1。**