KateLegend2_proj/assets/scenes/SETUP_GUIDE.md

场景搭建操作指南（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 的 § 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 页