first commmit

2026-05-06 08:17:32 +08:00
commit 427a33c55b
269 changed files with 20906 additions and 0 deletions
@@ -0,0 +1,116 @@
+# 场景搭建操作指南（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 页 |