From 270f734a6a6a85394fc9d5174ab1a2acadd9e332 Mon Sep 17 00:00:00 2001 From: pan Date: Thu, 10 Sep 2026 15:57:04 +0800 Subject: [PATCH] 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 --- .../specs/2026-09-10-stage-system-design.md | 229 ++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-10-stage-system-design.md diff --git a/docs/superpowers/specs/2026-09-10-stage-system-design.md b/docs/superpowers/specs/2026-09-10-stage-system-design.md new file mode 100644 index 00000000..0a2a5dad --- /dev/null +++ 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 字段 |