# 游戏启动流程开发手册

> 文件位置：`Docs/Guides/01_BootFlow_Setup_Guide.md`  
> 版本：1.0 · 适用项目：zeling_v2

---

## 目录

1. [架构概览](#1-架构概览)  
2. [完整启动时序图](#2-完整启动时序图)  
3. [关键脚本说明](#3-关键脚本说明)  
4. [事件频道速查表](#4-事件频道速查表)  
5. [分步配置教程](#5-分步配置教程)  
   - 5.1 [创建事件频道资产（Step 1）](#51-创建事件频道资产step-1)  
   - 5.2 [配置 Persistent 场景（Step 2）](#52-配置-persistent-场景step-2)  
   - 5.3 [配置 Splash 演出（Step 2 续）](#53-配置-splash-演出step-2-续)  
   - 5.4 [配置 Loading 画面（Step 2 续）](#54-配置-loading-画面step-2-续)  
   - 5.5 [创建并配置主菜单场景（Step 3）](#55-创建并配置主菜单场景step-3)  
   - 5.6 [Build Settings 配置（Step 4）](#56-build-settings-配置step-4)  
6. [使用编辑器向导工具](#6-使用编辑器向导工具)  
7. [FSM 状态转换关系](#7-fsm-状态转换关系)  
8. [自定义扩展指南](#8-自定义扩展指南)  
9. [常见问题排查](#9-常见问题排查)  

---

## 1. 架构概览

启动流程由以下四个程序集中的组件协同完成，通过事件频道（`ScriptableObject` 事件总线）彻底解耦：

```
BaseGames.Core                     BaseGames.UI
─────────────────────────────      ─────────────────────────────
GameManager          ◄──────────── SplashScreenController
  └─ BootSequencer   ────────────► (via EVT_SplashStartRequest)
  └─ GameStateMachine              MainMenuController
                                   LoadingScreenManager
BaseGames.Core.Events (共享)
─────────────────────────────
VoidEventChannelSO              FloatEventChannelSO
IntEventChannelSO               StringEventChannelSO
SceneLoadRequestEventChannelSO
```

**核心设计原则：**
- `BaseGames.Core` 不依赖 `BaseGames.UI`，所有跨程序集通信通过 SO 事件频道进行。
- 所有场景加载请求都汇聚到 `EVT_SceneLoadRequest`，GameManager 和 SceneService 共享同一 SO 实例。
- GameStateMachine 是状态权威，所有 UI 面板的显隐跟随 `EVT_GameStateChanged` 事件。

---

## 2. 完整启动时序图

```
应用启动（首场景加载前）
    │
    ├── [RuntimeInitializeOnLoadMethod] GameBootstrap
    │       └── 以 Additive 模式加载 Scene_Persistent
    │
    ▼
Scene_Persistent 加载完成
    │
    ├── GameServiceRegistrar.Awake(-2000)
    │       └── 向 ServiceLocator 注册：SceneService、DeathRespawnService、
    │           EventChannelRegistry、GameSaveManager、…
    │
    ├── GameManager.Awake(-1000)
    │       ├── DontDestroyOnLoad(root)
    │       ├── FSM.TransitionTo(Initializing)
    │       └── 注册所有 FSM 状态
    │
    └── GameManager.Start()
            ├── Raise(EVT_GameStateChanged, Initializing)
            └── StartCoroutine(BootCoroutine)
                    │
                    ├── BootSequencer.RunBootSequenceCoroutine()
                    │       ├── Raise(EVT_SplashStartRequest)       ──►  SplashScreenController 开始
                    │       │                                             播放演出（工作室 Logo →
                    │       │                                             游戏标题）可任意键跳过
                    │       │
                    │       ├── [并行] PreloadCoroutine()
                    │       │       └── Addressables.DownloadDependenciesAsync("Preload")
                    │       │           每帧 Raise(EVT_LoadingProgressUpdated, progress*0.9)
                    │       │
                    │       └── WaitUntil(SplashDone && PreloadDone)
                    │               SplashScreenController 结束 → Raise(EVT_SplashComplete)
                    │
                    └── SceneService.LoadMainMenuCoroutine()
                            └── SceneLoader.LoadSceneCoroutine(Scene_MainMenu)
                                    └── 加载成功 → Raise(EVT_SceneLoaded, "Scene_MainMenu")
                                            └── GameManager.HandleSceneLoaded
                                                    └── FSM: Initializing → MainMenu
                                                        Raise(EVT_GameStateChanged, MainMenu)

─────────────────────────────────────────────────────────────────────────────

主菜单激活
    │
    ├── MainMenuController.OnEnable()
    │       └── 订阅 EVT_GameStateChanged / EVT_SlotConfirmed
    │
    └── MainMenuController 响应 EVT_GameStateChanged(MainMenu)
            └── 播放入场动画（菜单面板下滑）
                └── RefreshContinueButton()（检查存档是否存在）

─────────────────────────────────────────────────────────────────────────────

新游戏 / 继续
    │
    ├── 玩家点击「新游戏」或「继续」
    │       └── 显示 SaveSlotPanel（选择存档槽 0/1/2）
    │
    ├── SaveSlotController → Raise(EVT_SlotConfirmed, slotIndex)
    │
    ├── MainMenuController.HandleSlotConfirmed()
    │       └── 关闭 SaveSlotPanel
    │           Raise(EVT_SceneLoadRequest, {firstGameSceneKey, Scene, ShowLoadingScreen=true})
    │
    ├── GameManager.HandleSceneLoadRequest()
    │       └── FSM: MainMenu → LoadingScene
    │           Raise(EVT_GameStateChanged, LoadingScene)
    │
    ├── SceneLoader.LoadSceneCoroutine()
    │       ├── Raise(EVT_LoadingStarted)     → LoadingScreenManager 显示进度画面
    │       ├── 每帧 Raise(EVT_LoadingProgressUpdated, p*0.9)
    │       ├── Raise(EVT_LoadingProgressUpdated, 1.0)
    │       └── Raise(EVT_LoadingComplete)    → LoadingScreenManager 隐藏
    │           Raise(EVT_SceneLoaded, gameSceneName)
    │
    └── GameManager.HandleSceneLoaded()
            └── FSM: LoadingScene → Gameplay
                Raise(EVT_GameStateChanged, Gameplay)

─────────────────────────────────────────────────────────────────────────────

暂停 → 返回主菜单
    │
    ├── PauseMenuController.GoToMainMenu()
    │       └── Raise(EVT_SceneLoadRequest, {Scene_MainMenu, Scene, ShowLoadingScreen=false})
    │
    ├── GameManager.HandleSceneLoadRequest()
    │       └── 目标为 Scene_MainMenu → 跳过 LoadingScene 中间状态
    │
    └── SceneLoader 加载完成 → Raise(EVT_SceneLoaded, "Scene_MainMenu")
            └── FSM: Paused → MainMenu
```

---

## 3. 关键脚本说明

### `GameManager`（Core/GameManager.cs）
全局游戏管理器，持有 FSM 并协调所有顶层服务。

| 新增字段 | 用途 |
|---|---|
| `_bootSequencer` | 引用 Persistent 场景中的 BootSequencer |
| `_onSceneLoadRequest` | 监听场景加载请求（与 SceneService 共享同一 SO）|
| `_onSceneLoaded` | 监听 SceneLoader 加载完成（携带场景名）|

`Start()` 启动 `BootCoroutine()`，`HandleSceneLoadRequest()` / `HandleSceneLoaded()` 自动驱动 FSM 转换。

---

### `BootSequencer`（Core/BootSequencer.cs）
挂载在 Persistent 场景，驱动 Splash 演出与 Addressable 预热并行执行。

| Inspector 字段 | 说明 |
|---|---|
| `_preloadLabel` | Addressable 预热标签（留空则跳过预热）|
| `_onSplashStartRequest` | 赋 `EVT_SplashStartRequest`（Raise）|
| `_onSplashComplete` | 赋 `EVT_SplashComplete`（Listen）|
| `_onPreloadProgress` | 赋 `EVT_LoadingProgressUpdated`（可选，供进度条显示）|

**重要：** `_onSplashComplete` 留空时，BootSequencer 不等待 Splash，直接进入主菜单。适合调试阶段快速跳过 Splash。

---

### `SplashScreenController`（UI/Splash/SplashScreenController.cs）
挂载在 `Canvas_Splash`（排序层 100），播放两段淡入/淡出动画，任意键可跳过。

| Inspector 字段 | 说明 |
|---|---|
| `_studioLogoGroup` | 工作室 Logo 的 CanvasGroup |
| `_gameTitleGroup` | 游戏标题的 CanvasGroup |
| `_onSplashStartRequest` | 赋 `EVT_SplashStartRequest`（Listen）|
| `_onSplashComplete` | 赋 `EVT_SplashComplete`（Raise）|
| `_fadeDuration` | 淡入/淡出时长（秒，默认 1.0）|
| `_holdDuration` | 每帧持续时长（秒，默认 1.5）|

---

### `MainMenuController`（UI/MainMenu/MainMenuController.cs）
挂载在主菜单场景的 Canvas 上，管理按钮、子面板、入场动画。

| Inspector 字段 | 说明 |
|---|---|
| `_onGameStateChanged` | 赋 `EVT_GameStateChanged`（Listen）|
| `_onSceneLoadRequest` | 赋 `EVT_SceneLoadRequest`（Raise）|
| `_onSlotConfirmed` | 赋 `EVT_SlotConfirmed`（Listen）|
| `_firstGameSceneKey` | 第一个游戏场景的 Addressable Key（**必填**）|
| `_btnNewGame/Continue/Settings/Credits/Quit` | 各按钮引用 |
| `_menuPanel` | 主按钮区 GameObject（用于入场动画）|
| `_saveSlotPanel / _settingsPanel / _creditsPanel` | 子面板 |
| `_saveSlotController` | SaveSlotController 引用 |

---

### `SceneLoader`（Core/SceneLoader.cs）
加载时序改为逐帧轮询，当 `ShowLoadingScreen = true` 时自动发布进度事件。

| 新增字段 | 用途 |
|---|---|
| `_onLoadingStarted` | 赋 `EVT_LoadingStarted`（Raise 给 LoadingScreenManager）|
| `_onLoadingComplete` | 赋 `EVT_LoadingComplete`（Raise 给 LoadingScreenManager）|
| `_onLoadingProgressUpdated` | 赋 `EVT_LoadingProgressUpdated`（Raise 进度值 0~1）|

---

## 4. 事件频道速查表

| SO 资产名 | 类型 | 发布者 | 监听者 | 说明 |
|---|---|---|---|---|
| `EVT_SplashStartRequest` | VoidEventChannelSO | BootSequencer | SplashScreenController | 触发 Splash 演出开始 |
| `EVT_SplashComplete` | VoidEventChannelSO | SplashScreenController | BootSequencer | Splash 结束通知 |
| `EVT_LoadingStarted` | VoidEventChannelSO | SceneLoader | LoadingScreenManager | 加载开始，显示进度画面 |
| `EVT_LoadingComplete` | VoidEventChannelSO | SceneLoader | LoadingScreenManager | 加载结束，隐藏进度画面 |
| `EVT_LoadingProgressUpdated` | FloatEventChannelSO | SceneLoader / BootSequencer | LoadingScreenManager | 进度值 0~1 |
| `EVT_SlotConfirmed` | IntEventChannelSO | SaveSlotController | MainMenuController | 存档槽选择完成（携带槽索引）|
| `EVT_SceneLoadRequest` | SceneLoadRequestEventChannelSO | MainMenuController / PauseMenuController / … | GameManager + SceneService | 场景加载请求（共享同一 SO）|
| `EVT_SceneLoaded` | StringEventChannelSO | SceneLoader | GameManager | 加载完成（携带场景名）|
| `EVT_GameStateChanged` | GameStateEventChannelSO | GameManager | MainMenuController / UIManager / … | FSM 状态改变通知 |

> **注意：** `EVT_SceneLoadRequest` 和 `EVT_SceneLoaded` 在 Inspector 中必须使用同一个 SO 实例赋给所有相关组件。不同组件使用不同 SO 实例是最常见的配置错误。

---

## 5. 分步配置教程

### 5.1 创建事件频道资产（Step 1）

**方法 A — 一键创建（推荐）：**

1. 打开菜单 **BaseGames → Tools → Boot Flow Wizard**。
2. 在 **Step 1** 区域点击 **「一键创建所有缺失资产」**。
3. 资产将创建在 `Assets/_Game/Data/Events/UI/Splash/`、`UI/Loading/`、`UI/MainMenu/`、`Core/` 目录下。
4. 检查清单全部变绿后进入下一步。

**方法 B — 手动创建：**

在 Project 窗口右键 → Create，按以下清单逐一创建：

```
Assets/_Game/Data/Events/UI/Splash/
    EVT_SplashStartRequest.asset    (VoidEventChannelSO)
    EVT_SplashComplete.asset        (VoidEventChannelSO)

Assets/_Game/Data/Events/UI/Loading/
    EVT_LoadingStarted.asset        (VoidEventChannelSO)
    EVT_LoadingComplete.asset       (VoidEventChannelSO)
    EVT_LoadingProgressUpdated.asset (FloatEventChannelSO)

Assets/_Game/Data/Events/UI/MainMenu/
    EVT_SlotConfirmed.asset         (IntEventChannelSO)
```

---

### 5.2 配置 Persistent 场景（Step 2）

**前置条件：** 已完成 Step 1，`Scene_Persistent` 已在 Hierarchy 中打开。

**方法 A — 自动脚手架（推荐）：**

1. 在 Hierarchy 中打开 `Scene_Persistent`（双击或在 Build Settings 中打开）。
2. 打开 **BaseGames → Tools → Boot Flow Wizard**，点击 **Step 2** 中的 **「脚手架 Persistent 场景」**。
3. 工具将自动：
   - 在 `[Services]` 下创建 `BootSequencer` GameObject 并挂载组件。
   - 在 `[UI]` 下创建 `Canvas_Splash`（排序层 100）并挂载 `SplashScreenController`。
   - 在 `[UI]` 下创建 `Canvas_Loading`（排序层 99）并挂载 `LoadingScreenManager`。
   - 自动绑定所有存在的事件频道 SO。
   - 为 `GameManager` 绑定 `_bootSequencer`、`_onSceneLoadRequest`、`_onSceneLoaded`。
   - 为 `SceneLoader` 绑定三个加载事件频道。
4. 保存场景（Ctrl+S）。

**方法 B — 手动配置（如需精细控制）：**

1. 在 `[Services]` 下新建空 GameObject 命名为 `BootSequencer`，挂载 `BootSequencer` 组件。
2. 在 Inspector 中赋值：
   - `_onSplashStartRequest` → `EVT_SplashStartRequest`
   - `_onSplashComplete` → `EVT_SplashComplete`
   - `_onPreloadProgress` → `EVT_LoadingProgressUpdated`（可选）
   - `_preloadLabel` → Addressable 标签名（如 `"Preload"`，留空则跳过）
3. 在 `GameManager` 组件 Inspector 中赋值：
   - `_bootSequencer` → 上述 BootSequencer 组件
   - `_onSceneLoadRequest` → `EVT_SceneLoadRequest`
   - `_onSceneLoaded` → `EVT_SceneLoaded`
4. 在 `SceneLoader` 组件 Inspector 中赋值：
   - `_onLoadingStarted` → `EVT_LoadingStarted`
   - `_onLoadingComplete` → `EVT_LoadingComplete`
   - `_onLoadingProgressUpdated` → `EVT_LoadingProgressUpdated`

---

### 5.3 配置 Splash 演出（Step 2 续）

1. 找到 `Canvas_Splash` GameObject。
2. 在子节点中创建两个 Image + CanvasGroup 结构：
   ```
   Canvas_Splash (SplashScreenController)
   └── StudioLogo          <- 工作室 Logo 图片
       └── CanvasGroup
   └── GameTitle           <- 游戏标题图片/文字
       └── CanvasGroup
   ```
3. 将 `StudioLogo` 的 CanvasGroup 赋给 `SplashScreenController._studioLogoGroup`。
4. 将 `GameTitle` 的 CanvasGroup 赋给 `SplashScreenController._gameTitleGroup`。
5. 调整 `_fadeDuration`（淡入/淡出时长）和 `_holdDuration`（停留时长）。

**跳过 Splash（调试模式）：**
- 将 `BootSequencer._onSplashComplete` 留空，BootSequencer 不会等待 Splash 完成，直接进入主菜单。

---

### 5.4 配置 Loading 画面（Step 2 续）

1. 找到 `Canvas_Loading` GameObject（默认已由脚手架创建，初始 `SetActive(false)`）。
2. 为 `LoadingScreenManager` 创建所需 UI 子节点：
   ```
   Canvas_Loading (LoadingScreenManager)
   └── LoadingPanel (背景遮罩 + 内容)
       └── ProgressBar (Slider)
       └── TipText (可选：随机提示文字)
   ```
3. 在 `LoadingScreenManager` Inspector 中赋值：
   - `_loadingPanel` → `LoadingPanel` GameObject
   - `_progressBar` → `ProgressBar` Slider 组件
   - `_onLoadingStarted` → `EVT_LoadingStarted`（已由脚手架绑定）
   - `_onLoadingComplete` → `EVT_LoadingComplete`（已由脚手架绑定）
   - `_onLoadingProgressUpdated` → `EVT_LoadingProgressUpdated`（已由脚手架绑定）

---

### 5.5 创建并配置主菜单场景（Step 3）

**创建场景：**

1. 在 Project 窗口右键 → Create → Scene，命名为 `Scene_MainMenu`。
2. 将其放置在 `Assets/_Game/Scenes/` 目录下。
3. 双击打开场景。

**自动脚手架：**

1. 打开 **Boot Flow Wizard → Step 3**，点击 **「脚手架 MainMenu 场景」**。
2. 工具将在场景中生成：
   ```
   [MainMenu]
   └── Canvas_MainMenu (Canvas, CanvasScaler, GraphicRaycaster, MainMenuController)
       └── MenuPanel (VerticalLayoutGroup)
           ├── Btn_NewGame  (Image, Button)
           ├── Btn_Continue (Image, Button)
           ├── Btn_Settings (Image, Button)
           ├── Btn_Credits  (Image, Button)
           └── Btn_Quit     (Image, Button)
       ├── SaveSlotPanel   (SetActive=false, SaveSlotController)
       ├── SettingsPanel   (SetActive=false)
       └── CreditsPanel    (SetActive=false)
   ```
3. **必须手动填写** `MainMenuController._firstGameSceneKey`：
   - 在 Inspector 中输入第一个游戏场景的 Addressable Key（字符串）。
   - 例如：`"Scene_Prologue"` 或 `"Scene_Town_01"`。

**SaveSlotPanel 配置：**

1. 打开 `SaveSlotPanel`。
2. 为 `SaveSlotController` 补充三个存档槽按钮引用（`_slot0Btn`、`_slot1Btn`、`_slot2Btn`）。
3. 为每个按钮添加适当的 UI 样式（背景图、存档信息文本等）。

**SettingsPanel / CreditsPanel：**  
这两个面板为空节点，由各自项目美术/策划填充内容。`MainMenuController` 通过 `_settingsPanel.SetActive(true/false)` 控制其显隐。

---

### 5.6 Build Settings 配置（Step 4）

1. 打开菜单 **File → Build Settings**（或 Boot Flow Wizard 中点击 **「打开 Build Settings」**）。
2. 将以下场景加入 Scenes in Build（顺序重要）：
   | 索引 | 场景 | 说明 |
   |---|---|---|
   | 0 | `Assets/_Game/Scenes/Scene_Boot.unity` | 启动入口（仅包含 `GameBootstrap`）|
   | — | `Assets/_Game/Scenes/Scene_Persistent.unity` | DontDestroyOnLoad 场景（不需要显式索引）|
   | — | `Assets/_Game/Scenes/Scene_MainMenu.unity` | 主菜单（通过 Addressables 加载）|
3. 确保 `Scene_Boot` 为索引 0（Player 设置中的第一场景）。

> **注意：** 其他所有游戏场景（关卡等）应通过 Addressables 打包，**不应**加入 Build Settings 的 Scene 列表，以避免包体膨胀。

---

## 6. 使用编辑器向导工具

### Boot Flow Wizard

菜单：**BaseGames → Tools → Boot Flow Wizard**

窗口提供四个步骤的实时状态检查：

- **✅（绿色）** = 该项已正确配置  
- **⬜（灰色）** = 该项尚未完成  

| 步骤 | 功能 |
|---|---|
| Step 1 | 检测所有 8 个启动流程事件频道资产，一键创建缺失项 |
| Step 2 | 检测 Persistent 场景中 9 个组件/字段绑定状态，一键脚手架 |
| Step 3 | 检测主菜单场景组件状态，一键脚手架，快速打开 Build Settings |
| Step 4 | 运行全量验证并在 Console 输出带位置信息的报告 |

底部状态栏实时显示 `通过 N / 总计 M 项检查`。

### Create Event Channel Assets

菜单：**BaseGames → Tools → Create Event Channel Assets**

在 `Assets/_Game/Data/Events/` 目录下批量创建**所有**系统所需事件频道（含启动流程部分）。已存在资产自动跳过（幂等操作）。

### Scaffold Persistent Scene / Scaffold Main Menu Scene

菜单：**BaseGames → Tools → Scaffold Persistent Scene**  
菜单：**BaseGames → Tools → Scaffold Main Menu Scene**（优先级 202）

独立的脚手架工具，适合不打开向导窗口时直接执行。

---

## 7. FSM 状态转换关系

启动流程涉及的 GameStateMachine 转换：

```
Initializing
    │
    └──(EVT_SceneLoaded: Scene_MainMenu)──► MainMenu
                                              │
                        ┌─────────────────────┤
                        │                     │
                    (新游戏/继续)            (其他)
                        │
                        ▼
                   LoadingScene
                        │
                        └──(EVT_SceneLoaded: GameScene)──► Gameplay
                                                              │
                                                   ┌──────────┤
                                                   │          │
                                              (Pause)    (PlayerDied)
                                                   │          │
                                                Paused     Dead
                                                   │
                                    ┌──────────────┤
                                    │              │
                               (Resume)     (GoToMainMenu)
                                    │              │
                                Gameplay        MainMenu

GameOver ──(EVT_SceneLoaded: Scene_MainMenu)──► MainMenu
```

**`HandleSceneLoadRequest` 逻辑（GameManager）：**
- `TransitionType.Scene` + 目标 ≠ `Scene_MainMenu` → FSM 当前在 MainMenu/Gameplay/BossFight → 转换到 `LoadingScene`
- `TransitionType.Scene` + 目标 = `Scene_MainMenu` → 不经过 `LoadingScene`，由 `HandleSceneLoaded` 直接转换
- `TransitionType.Room` → 完全忽略，状态保持 Gameplay

---

## 8. 自定义扩展指南

### 添加第三段 Splash（如游戏内 IP 授权方 Logo）

在 `SplashScreenController` 中 `PlayAsync()` 方法末尾追加：

```csharp
// 第三段：IP Logo
if (_ipLogoGroup != null)
{
    yield return StartCoroutine(Fade(_ipLogoGroup, 0f, 1f, _fadeDuration));
    yield return new WaitForSeconds(_holdDuration);
    yield return StartCoroutine(Fade(_ipLogoGroup, 1f, 0f, _fadeDuration));
}
```

同时在 Inspector 中添加 `[SerializeField] private CanvasGroup _ipLogoGroup;` 字段。

---

### 修改 Loading 画面为视频背景

1. 给 `Canvas_Loading` 添加 `RawImage` 组件用于显示视频。
2. 在 `LoadingScreenManager` 的 `Show()` 中启动 `VideoPlayer.Play()`，`Hide()` 中停止。
3. 使用 `EVT_LoadingStarted` / `EVT_LoadingComplete` 频道触发视频播放/停止。

---

### 新游戏时跳过存档选择（单存档模式）

在 `MainMenuController` 中，将 `OnNewGameClicked` 修改为直接触发槽 0：

```csharp
private void OnNewGameClicked()
{
    // 单存档：直接使用槽 0
    HandleSlotConfirmed(0);
}
```

---

### 添加主菜单背景音乐

在 `MainMenuController.Start()` 或响应 `EVT_GameStateChanged(MainMenu)` 时：

```csharp
_onBGMRequest?.Raise("BGM_MainMenu"); // 赋值 EVT_BGMRequest 频道
```

AudioManager 的 `EVT_BGMRequest` 监听器会自动淡入播放。

---

## 9. 常见问题排查

### ❌ 游戏启动后停在黑屏，不显示 Splash 也不进入主菜单

**原因：** `GameManager._bootSequencer` 未绑定，BootCoroutine 无法执行。  
**解决：** 打开 Boot Flow Wizard → Step 2，检查 `GameManager._bootSequencer 已绑定` 是否为绿色；否则重新执行脚手架。

---

### ❌ Splash 演出播放完毕后一直黑屏（不进入主菜单）

**原因 1：** `GameManager._onSceneLoaded` 未绑定或绑定了错误的 SO 实例，`HandleSceneLoaded` 从未被调用。  
**解决：** 确认 `GameManager._onSceneLoaded` 与 `SceneLoader._onSceneLoaded` 绑定同一个 `EVT_SceneLoaded.asset`。

**原因 2：** `ISceneService` 未注册（`GameServiceRegistrar` 未正确引用 `SceneService`）。  
**解决：** Console 中搜索 `[GameManager] ISceneService 未注册`，检查 Persistent 场景中的 `GameServiceRegistrar._sceneService` 引用。

---

### ❌ 点击「新游戏」后进入黑屏，加载进度条不出现

**原因 1：** `LoadingScreenManager._onLoadingStarted` 未绑定。  
**原因 2：** `LoadingScreenManager._loadingPanel` 为空（未赋值 UI 根节点）。  
**解决：** 检查 Boot Flow Wizard Step 2 中 `SceneLoader._onLoadingStarted 已绑定` 状态。

---

### ❌ `MainMenuController._firstGameSceneKey` 填写后仍报 Addressable 加载失败

**原因：** Key 填写有误，或对应场景未在 Addressables 中标记。  
**解决：**  
1. 打开 **Window → Asset Management → Addressables → Groups**。  
2. 找到目标场景资产，确认其 Address 与 `_firstGameSceneKey` 完全一致（大小写敏感）。  
3. 确保该场景已勾选 Include in Build。

---

### ❌ 返回主菜单时 FSM 报 Invalid transition 警告

**原因：** 通常是从 `Dead` 或 `GameOver` 状态直接触发 `HandleSceneLoaded(MainMenu)`，而这两个状态的 `ValidNextStates` 不包含 `MainMenu`。  
**解决：** 确保 `DeathRespawnService.StartGameOverCoroutine()` 在加载主菜单场景**之前**已调用 `GameManager.RequestTransition(GameOver)`。参见 `BuiltinGameStates.cs` 中 `GameOverState.ValidNextStates`。

---

### ❌ 编辑器中运行正常，打包后 Splash 不显示

**原因：** `Canvas_Splash` 上的 Image Sprite 未加入 Addressable Build 或 Sprite Atlas。  
**解决：** 将 Splash 使用的所有 Texture/Sprite 加入 Addressable Group（标签 `"Preload"` 以便启动时预热），或直接内嵌进默认 Resources。

---

*文档最后更新：2026-05-19*