# 场景搭建操作指南（Scene Setup Guide）

> 适用版本：Cocos Creator 3.8.8  
> 目的：把 `assets/scenes/*.scene` 这 9 个空场景挂上对应的 Scene Entry 组件，让工程可以跑通"Boot → 剧情 → 1-1 → 1-2 → … → Boss → Settlement"完整流程。

---

## 0. 已完成清单（由代码侧补齐）

- ✅ 路径别名 `@data/Interfaces` 已改为相对路径（Cocos 3.8 不支持 tsconfig paths）
- ✅ `GameBoot.ts` 已驱动 `UIFlowMgr.onBoot()` → 自动跳 Story / Menu
- ✅ 新增 `assets/scripts/scene_entries/` 目录（6 个 Scene Entry 组件）
- ✅ **每个 Scene Entry 默认开启 `autoBuildUI`**：挂到 Canvas 后无需手动摆放按钮，组件会用 `Graphics + Label + Button` 动态生成：
  - MainMenu → 居中 "Start" / "Settings" 按钮 + 顶部标题
  - StoryIntro → 全屏 Label + 右下 "Skip" 按钮 + 全屏 Tap 加速
  - Level_1_x → 顶部 "Level x-y" 标题 + 倒计时/击杀 HUD
  - Boss → 顶部标题 + 左右两个 Debug 按钮（Hit Butterfly / Hit Body）
  - Settlement → 标题 + Score Label + 结局旁白 + "Back to Menu" 按钮
- ✅ **占位资产已生成**：37 个 PNG/WAV/MP3 小体积占位文件（总共 156 KB），可通过 `node scripts/gen_placeholder_assets.js` 重新生成。详见 [`assets/resources/ASSETS.md`](../resources/ASSETS.md) 的 § 8 交付跟踪表。

---

## 1. Boot.scene

> 已自动挂好 `GameBoot`，无需操作。

---

## 2. MainMenu.scene

1. 双击打开 `assets/scenes/MainMenu.scene`
2. Hierarchy 右键根节点 → **创建 → 2D 对象 → Canvas**（若已有 UI 根则跳过）
3. 选中 `Canvas` → Inspector **添加组件** → 搜 **MainMenuEntry** → 添加
4. `Ctrl/Cmd + S` 保存

> `autoBuildUI` 默认开启 → 标题、Start、Settings 按钮会自动生成，无需手动摆放。需要自己做 UI 时，把 Inspector 的 `Auto Build UI` 取消勾选，再手动添加 Button 并把 ClickEvents 绑到 `onPressStart` / `onPressSettings`。

---

## 3. StoryIntro.scene

1. 打开 `assets/scenes/StoryIntro.scene`
2. 根节点右键 → **创建 → 2D 对象 → Canvas**
3. 选中 Canvas → 添加组件 **StorySceneEntry**
4. 保存

> `autoBuildUI` 默认开启 → 全屏 Label + 右下 Skip 按钮自动生成；点击屏幕任意位置会调用 `onTap` 加速/翻页。
> 如需指定其他 story，修改 Inspector 里的 `Story Id`（默认 `chapter_1_intro`）。

---

## 4. Level_1_1.scene ~ Level_1_5.scene（5 个场景）

对每一个 `Level_1_x.scene`：

1. 根节点 → **创建 → 2D 对象 → Canvas**
2. 选中 Canvas → 添加组件 **LevelEntry**
3. Inspector 里把 `Level Id` 分别填：
   - `Level_1_1` → `1-1`，`Level_1_2` → `1-2`，以此类推到 `1-5`
4. `Next Scene Name` 留空（会自动 1-1→1-2→…→Boss 推导）
5. 保存

> `autoBuildUI` 默认开启 → 顶部显示 "Level x-y" 标题 + 倒计时/击杀 HUD 自动生成。

---

## 5. Boss_ShuangHuanFang.scene

1. 打开 `assets/scenes/Boss_ShuangHuanFang.scene`
2. 根节点 → **创建 → 2D 对象 → Canvas**
3. 选中 Canvas → 添加组件 **BossEntry**
4. `Boss Id` 保持默认值 `shuang_huan_fang`
5. 保存

> `autoBuildUI` 默认开启 → 顶部标题 + 左右两个 Debug 按钮（Hit Butterfly / Hit Body）自动生成，便于在战斗 HUD 就位前验证流程可达性（先点 Butterfly 再点 Body → 进入 Settlement）。

---

## 6. Settlement.scene

1. 打开 `assets/scenes/Settlement.scene`
2. 根节点 → **创建 → 2D 对象 → Canvas**
3. 选中 Canvas → 添加组件 **SettlementEntry**
4. 保存

> `autoBuildUI` 默认开启 → 标题 + Score Label + 结局旁白（"公主被带走，续章待续…"）+ "Back to Menu" 按钮自动生成。

---

## 7. 项目启动场景配置

1. 菜单 **项目 → 项目设置 → 项目数据**
2. "启动场景"选 `Boot`
3. 确认 "场景构建列表" 勾选了全部 10 个 `.scene` 文件

---

## 8. 验证流程

按 `Ctrl/Cmd + P` 预览，期望：

```
Boot  →  StoryIntro（3 页打字机）  →  Level_1_1  →  1_2  →  1_3  →  1_4  →  1_5
        →  Boss_ShuangHuanFang  →  Settlement  →（点击返回）→ MainMenu
```

---

## 9. 常见问题

| 症状 | 排查 |
|------|------|
| `Module "@xxx/yyy" not found` | 检查运行时代码是否还有 `@common/` `@data/` `@logic/` `@ui/` 别名。只允许在 `tests/` 里出现；`assets/scripts/` 下必须用相对路径。 |
| 场景切换后黑屏 | 确认 Canvas 节点已创建；3D 相机保留也没关系，但 UI 必须在 Canvas 下 |
| Boss 胜利后未跳 Settlement | 检查 `BossEntry.onBodyHit` 是否被触发；临时用 Debug 按钮验证 |
| Story 页卡住不动 | 检查 `configs/stories.json` 的 `chapter_1_intro` 是否有 ≥ 3 页 |