jakciehan
117 lines
4.7 KiB
Markdown
117 lines
4.7 KiB
Markdown
# 场景搭建操作指南（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 页 |
|