docs(stage): add stage system design spec

- Add chapter-stage-section three-level progression design - Define monster growth formula with linear slope (+5%/lv) - Specify elite/boss multipliers (1.5x/3.0x) and spawn rhythm - Include persistence strategy and UI display format
2026-09-10 15:57:04 +08:00
parent ecd6be7a84
commit 270f734a6a
1 changed files with 229 additions and 0 deletions
--- a/docs/superpowers/specs/2026-09-10-stage-system-design.md
+++ b/docs/superpowers/specs/2026-09-10-stage-system-design.md
@@ -0,0 +1,229 @@
+# 关卡系统设计文档（Stage System）
+
+## 1. 背景与目标
+
+### 1.1 现状
+当前游戏为**单场 Boss 战定胜负**模型：
+- 整局只有一场战斗，开局英雄三次三选一后自动开战
+- 怪物从 `BossComboLibrary` 按权重随机抽一组（固定 3 只怪）
+- 战斗开始瞬间一次全量登场，双方立即互相攻击
+- 怪物全灭 → 胜利；英雄全灭 → 失败
+
+### 1.2 目标
+改为**章节-关卡-小节**三级推进结构：
+- **1 章 = 10 关**，每关 = 10 小节，共 100 个小节
+- 显示格式：`1-1`（第 1 章第 1 关）、`1-5-3`（第 1 章第 5 关第 3 节）
+- 第 5 关为**精英关**，第 10 关为**Boss 关**，其余为普通关
+- 玩家线性推进，进度精确到小节并持久化存档
+
+### 1.3 核心约束
+- 每节完全独立：英雄重新三选一，无局内成长，纯数值推进
+- 怪物强度通过等级线性成长，不依赖系数膨胀
+- 架构支持多章节扩展，当前仅配置第 1 章
+
+---
+
+## 2. 关卡结构定义
+
+### 2.1 层级关系
+```
+Chapter（章）
+  └── Stage（关）：1~10
+        └── Section（节）：1~10
+              ├── 普通关（1~4, 6~9）：9 只小怪
+              ├── 精英关（5）：3 只精英
+              └── Boss 关（10）：1 Boss + 2 精英
+```
+
+### 2.2 小节类型
+| 类型 | 触发关卡 | 怪物构成 | 刷怪节奏 |
+|------|---------|---------|---------|
+| Normal | 1~4, 6~9 | 9 小怪 | 前 3 只立即刷，后续每 5s 刷 1 只 |
+| Elite | 5 | 3 精英 | 3 只同时刷出 |
+| Boss | 10 | 1 Boss + 2 精英 | 2 精英先刷，Boss 延迟 1s 刷出 |
+
+### 2.3 刷出位置
+- X = 320（`MonStart.START_X`）
+- Y 按怪物类型分层：近战/Boss → 前排，远程/刺客 → 中排，辅助/召唤 → 后排
+
+---
+
+## 3. 数值设计
+
+### 3.1 英雄强度基准（Lv1）
+| 职业 | HP | AP | DEF | 攻速 | DPS |
+|------|-----|-----|-----|------|-----|
+| Tank | 600 | 20 | 50 | — | — |
+| Warrior | 560 | 22 | 30 | 1.2s | ~18 |
+| Assassin | 560 | 22 | 10 | 0.9s | ~24 |
+| Archer | 280 | 32 | 10 | 1.2s | ~27 |
+| Mage | 280 | 32 | 10 | 1.2s | ~27 |
+| Support | 280 | 32 | 15 | 1.2s | ~27 |
+
+3 英雄队（战+射+法）理论 DPS ≈ **63**。
+
+### 3.2 怪物成长公式
+```
+最终属性 = 基础属性 × 开局系数 × (1 + 成长斜率 × (怪物等级 - 1))
+```
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 开局系数 | 0.8 | 1 级小怪略弱于英雄，给玩家正反馈 |
+| 成长斜率 | +5%/级 | 线性成长，10 级 ≈ 1.45 倍 |
+| 精英倍率 | × 1.5 | 同级普通怪的 1.5 倍 |
+| Boss 倍率 | × 3.0 | 同级普通怪的 3.0 倍（精英 × 2） |
+
+### 3.3 第 1 章数值速查表
+以兽人战士（HP 560 / AP 22）为例：
+
+| 怪物等级 | 普通 HP | 精英 HP | Boss HP | 普通 AP | 精英 AP | Boss AP |
+|---------|--------|--------|--------|--------|--------|--------|
+| Lv1 | 448 | 672 | 1344 | 18 | 26 | 53 |
+| Lv3 | 493 | 740 | 1480 | 19 | 29 | 58 |
+| Lv5 | 538 | 807 | 1615 | 21 | 32 | 63 |
+| Lv8 | 605 | 908 | 1815 | 24 | 36 | 71 |
+| Lv10 | 650 | 975 | 1950 | 26 | 38 | 77 |
+
+### 3.4 关卡-等级映射
+| 关卡 | 小节 | 怪物等级 | 说明 |
+|------|------|---------|------|
+| 1-1 | 1-1 ~ 1-10 | Lv1 | 教学关 |
+| 1-2 | 2-1 ~ 2-10 | Lv2 | 轻度提升 |
+| ... | ... | ... | ... |
+| 1-5 | 5-1 ~ 5-10 | Lv5 | **精英关** |
+| ... | ... | ... | ... |
+| 1-10 | 10-1 ~ 10-10 | Lv10 | **Boss 关** |
+
+> 怪物等级 = 关卡号（1-1 的怪为 Lv1，1-5 的怪为 Lv5，1-10 的怪为 Lv10）。
+
+---
+
+## 4. 架构设计
+
+### 4.1 新增文件：StageSet.ts
+路径：`assets/script/game/common/config/StageSet.ts`
+
+职责：
+- 定义 `SectionType` / `SectionConfig` / `StageConfig` / `ChapterConfig`
+- 硬编码第 1 章配置（10 关 × 10 节）
+- 提供查询接口：`getSectionConfig(chapter, stage, section)`
+- 提供怪物等级计算：`getMonsterLv(stage)`
+
+### 4.2 重构文件：RogueConfig.ts → StageSpawningEngine
+职责：
+- 废弃 `BOSS_COUNT` / `MINION_COUNT` / `MON_HP_MUL` / `MON_AP_MUL` / `BOSS_BASE_HP` / `BOSS_BASE_AP` / `BOSS_HP_BONUS_MUL`
+- 新增 `generateSectionMonsters(chapter, stage, section): GeneratedMonster[]`
+- 按小节类型生成对应怪物列表，属性 = 基础 × 0.8 × (1 + 0.05×(lv-1)) × 类型倍率
+- 保留 `MonSkillPool` / `BossSkillPool` 技能池机制
+- 保留 `TestModeConfig` 测试模式
+
+### 4.3 重构文件：MissionMonComp.ts
+职责：
+- 不再监听 `FightReady` 一次性全刷
+- 改为监听 `SectionStart` 事件，按节奏刷怪：
+  - 普通关：立即刷 3 只，启动 5s 定时器刷剩余 6 只
+  - 精英关：立即刷 3 只精英
+  - Boss 关：立即刷 2 精英，1s 后刷 Boss
+- 维护 `sectionSpawnedCount` / `sectionTargetCount` 供 MissionComp 检测小节结束
+
+### 4.4 重构文件：MissionComp.ts
+职责：
+- 新增 `MissionPhase.SectionEnd` 阶段（小节结束，等待玩家点击"下一节"）
+- 新增当前关卡状态：`currentChapter` / `currentStage` / `currentSection`
+- 怪物全灭检测 → 进入 `SectionEnd` → 显示"下一节"按钮 → 玩家点击 → `SectionStart`
+- 10 节打完 → `StageEnd` → 显示"下一关"按钮
+- 10 关打完 → `ChapterEnd` → 章节结算
+- 进度持久化：读写 `smc.vmdata.mission_data.stage_progress`
+
+---
+
+## 5. 战斗流程
+
+### 5.1 单节流程
+```
+SectionStart
+  → 玩家三选一选英雄（复用现有机制）
+  → 刷怪（按类型节奏）
+  → 战斗中
+  → 怪物全灭
+  → SectionEnd（显示"下一节"按钮）
+  → 玩家点击 → 下一节 SectionStart
+```
+
+### 5.2 大关流程
+```
+1-1-1 → 1-1-2 → ... → 1-1-10 → StageEnd
+  → 显示"1-1 通关" + "下一关"按钮
+  → 玩家点击 → 1-2-1
+```
+
+### 5.3 章节流程
+```
+1-1 → 1-2 → ... → 1-10 → ChapterEnd
+  → 显示"第 1 章通关" + 解锁第 2 章
+```
+
+---
+
+## 6. 数据持久化
+
+### 6.1 存档字段
+```typescript
+// smc.vmdata.mission_data 新增
+stage_progress: {
+    chapter: number;   // 当前章节
+    stage: number;     // 当前关
+    section: number;   // 当前节
+}
+```
+
+### 6.2 读写时机
+- **写入**：每节 `SectionEnd` 时保存当前进度
+- **读取**：游戏启动时恢复上次进度，从该节继续
+
+---
+
+## 7. UI 显示
+
+### 7.1 关卡显示
+- 格式：`第 1-5-3 节`（第 1 章第 5 关第 3 节）
+- 位置：`time_node` 下的 `Phase/Label`（复用现有 UI 节点）
+
+### 7.2 阶段提示
+- `SectionStart`：显示"第 X-Y-Z 节"
+- `StageEnd`：显示"X-Y 通关"
+- `ChapterEnd`：显示"第 X 章通关"
+
+---
+
+## 8. 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| 关卡配置缺失 | 回退到 1-1-1，输出错误日志 |
+| 怪物 UUID 无效 | 回退到默认近战怪（6001），输出警告 |
+| 存档损坏 | 重置为 1-1-1，输出警告 |
+| 战斗超时 | 保留现有 90s 超时强制结算机制 |
+
+---
+
+## 9. 测试策略
+
+1. **单元测试**：`StageSet.getSectionConfig` 边界值（1-1-1 / 1-5-5 / 1-10-10 / 2-1-1）
+2. **集成测试**：完整跑通 1-1-1 → 1-1-10 → 1-2-1 流程
+3. **数值验证**：Lv1/Lv5/Lv10 怪物属性符合公式计算
+4. **存档测试**：中途退出重进，进度恢复正确
+
+---
+
+## 10. 变更文件清单
+
+| 文件 | 变更类型 | 说明 |
+|------|---------|------|
+| `assets/script/game/common/config/StageSet.ts` | 新增 | 关卡配置 |
+| `assets/script/game/map/RogueConfig.ts` | 重构 | 生成引擎改为按小节生成 |
+| `assets/script/game/map/MissionMonComp.ts` | 重构 | 按节奏刷怪 |
+| `assets/script/game/map/MissionComp.ts` | 重构 | 小节状态机 + 进度持久化 |
+| `assets/script/game/common/config/GameEvent.ts` | 修改 | 新增 SectionStart / SectionEnd / StageEnd / ChapterEnd 事件 |
+| `assets/script/game/common/SingletonModuleComp.ts` | 修改 | vmdata.mission_data 新增 stage_progress 字段 |