docs: game design document v0.1

2026-05-02 05:36:16 +08:00
parent 13891ff3c9
commit 612748569f
4 changed files with 357 additions and 20 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -27,4 +27,4 @@ Build/
 __pycache__/

 # Doxygen output (generated, not committed)
-docs/html/
+Docs/html/
--- a/Docs/game-design.md
+++ b/Docs/game-design.md
@@ -0,0 +1,287 @@
+# MM — 游戏设计文档
+
+> 版本：0.1 | 更新：2026-05-02
+
+---
+
+## 一、游戏概述
+
+- **类型**：俯视角即时动作刷怪（类暗黑破坏神）
+- **风格**：Fate 系列 Seven Classes 职业体系
+- **人数**：4-5 人组队联机
+- **引擎**：Unreal Engine 5.7
+- **技术栈**：GAS（Gameplay Ability System）、纯 C++ 驱动
+
+### 核心玩法循环
+
+```
+选择职业/角色
+    ↓
+进入关卡（多房间随机生成）
+    ↓
+阶段1：割草（大量小怪，清场爽快）
+    ↓
+阶段2：精英怪混入（血厚有特殊技能，需要走位）
+    ↓
+阶段3：Boss 战（独特机制，需要配合）
+    ↓
+结算（经验/装备/材料）
+    ↓
+强化角色（装备/技能树/宝具）→ 进入下一关
+```
+
+---
+
+## 二、职业体系
+
+### Seven Classes
+
+| 职业 | 定位 | 武器 | 核心机制 |
+|------|------|------|---------|
+| Saber | 近战 / 平衡 | 剑 | 剑技连招，格挡反击 |
+| Archer | 远程 / 输出 | 弓 | 蓄力射击，陷阱走位 |
+| Lancer | 近战 / 突击 | 枪 | 突进刺击，高机动 |
+| Caster | 远程 / 法术 | 法杖 | AOE，元素链，蓄力施法 |
+| Assassin | 近战 / 爆发 | 匕首 | 隐身背刺，暴击连击 |
+| Berserker | 近战 / 狂战 | 重武器 | 狂暴模式，血越少越强 |
+| Rider | 近战 / 坦克 | 剑盾 | 格挡吸收，团队前排 |
+
+### 宝具系统
+
+每个职业拥有一个终极技能——**宝具**。
+
+**充能方式（三种均会充能）：**
+- **击杀** → 进攻型玩家充得快
+- **闪避** → 操作流玩家充得快
+- **反击** → 防反型玩家充得快
+
+**设计原则：**
+- 宝具充满后手动释放
+- 每个宝具风格不同（大范围 / 单体极致爆发 / 全屏元素等）
+- 有简短但冲击感的演出效果
+
+---
+
+## 三、战斗系统
+
+### 战斗节奏
+
+- 前期割草：大量小怪，玩家爽快感强
+- 中期混入精英怪：血厚有特殊技能，需要走位和配合
+- 后期 Boss：独特机制，需要团队配合
+
+### 属性框架
+
+#### 核心属性（角色面板）
+
+| 属性 | 说明 |
+|------|------|
+| 生命值 / 最大生命值 | 角色生存基础 |
+| 攻击力 | 物理伤害基础 |
+| 防御力 | 物理减伤基础 |
+| 暴击率 | 暴击触发概率 |
+| 暴击伤害 | 暴击时的伤害倍率 |
+| 攻击速度 | 影响攻击频率和技能施放速度 |
+| 移动速度 | 角色移动快慢 |
+
+#### 战斗属性（隐藏）
+
+| 属性 | 说明 |
+|------|------|
+| 命中 | 影响攻击是否命中 |
+| 闪避 | 影响是否躲开攻击 |
+| 穿甲 | 忽略目标部分防御 |
+| 免伤 | 直接减少受到的伤害百分比 |
+| 格挡率 | Rider 专属，格挡概率 |
+| 宝具充能效率 | 宝具充能速度加成 |
+| 技能冷却缩减 | 技能 CD 缩短比例 |
+| 元素抗性 | 各种元素伤害减免 |
+
+### 伤害计算流程（草案）
+
+```
+原始伤害 = 攻击力 × 技能倍率 × (暴击 ? 暴击伤害 : 1.0)
+命中率检定 = 基础命中 - 目标闪避
+命中后：
+  实际防御 = 目标防御 × (1 - 穿甲率)
+  减伤后伤害 = 原始伤害 × (1 - 免伤率) - 实际防御
+  最终伤害 = max(减伤后伤害, 1)
+```
+
+---
+
+## 四、装备系统
+
+### 品质分级
+
+| 品质 | 颜色 | 词条数 | 技能 |
+|------|------|--------|------|
+| 普通 | 白 | 0-1 | 无 |
+| 魔法 | 绿 | 1-2 | 无 |
+| 稀有 | 蓝 | 2-3 | 无 |
+| 传奇 | 紫 | 3-4 | 可能有1个 |
+| 神话 | 橙 | 4-5 | 必有1个 |
+
+品质越高，基础属性底数越高，词条越多越强，高级装备可能附带技能。
+
+### 词条池
+
+**进攻类：**
+- 攻击力 %
+- 暴击率
+- 暴击伤害
+- 攻击速度 %
+- 穿甲
+- 元素伤害加成
+
+**防御类：**
+- 生命值 %
+- 防御力 %
+- 闪避率
+- 免伤
+- 格挡率
+- 元素抗性
+
+**特殊类：**
+- 技能冷却缩减
+- 宝具充能效率
+- 经验加成
+- 掉落加成
+- 移动速度 %
+
+### 装备操作
+
+- **强化**：消耗材料提升装备基础属性
+- **分解**：拆装备获得材料
+- **合成**：材料合成新装备（有随机性）
+
+---
+
+## 五、技能树系统
+
+- 每个职业独立技能树
+- 包含主动技能 + 被动强化节点
+
+### 技能点来源（三种）
+
+- **升级获得**：每次升级给技能点
+- **任务/成就**：完成特定挑战给额外点数
+- **技能书掉落**：刷怪掉落技能书，使用后解锁或强化技能
+
+---
+
+## 六、关卡系统
+
+### 结构：多房间随机生成
+
+- 每次进入关卡，房间布局随机生成
+- 房间类型：战斗房 / 精英房 / Boss房 / 宝箱房 / 商店房
+- 关卡难度随层数递增
+- 房间之间有走廊/门连接
+
+### 关卡流程
+
+```
+起始房间
+  ↓
+随机战斗房（割草小怪）
+  ↓
+随机战斗房（混入精英怪）
+  ↓
+...（随机路径）
+  ↓
+Boss 房（关卡最终挑战）
+  ↓
+结算房间（经验/掉落/奖励展示）
+```
+
+---
+
+## 七、联机系统
+
+- 4-5 人组队
+- 基于 GAS 原生网络复制
+- 支持 Listen Server / Dedicated Server
+- 同步内容：角色状态、技能释放、怪物 AI、掉落物
+
+---
+
+## 八、MVP 计划（Phase 1）
+
+### 目标：跑通核心循环
+
+**职业：** Saber + Archer（一近一远）
+
+**关卡：** 1 个随机生成关卡（3-5 房间，1 Boss）
+
+**装备：** 简化版
+- 2 品质（普通白、稀有蓝）
+- 2-3 条词条
+- 不含装备技能
+- 不做强化/分解/合成
+
+**技能树：** 简化版
+- 每个职业 3-4 个技能节点
+- 仅升级给点
+
+**宝具：** 先做 1 个（Saber）
+
+**不含：** 联机（先单机跑通）
+
+### MVP 里程碑
+
+| 阶段 | 内容 |
+|------|------|
+| M1 | 项目骨架：GAS 集成、角色基类、AttributeSet、基础移动 |
+| M2 | 战斗基础：普攻、受击、死亡、伤害计算 |
+| M3 | Saber 技能：3-4 个主动技能 + 宝具 |
+| M4 | Archer 技能：3-4 个主动技能 + 宝具 |
+| M5 | 怪物 AI：小怪行为树、精英怪、Boss |
+| M6 | 关卡生成：多房间随机生成 |
+| M7 | 装备掉落：简化版掉落 + 词条 |
+| M8 | 技能树：简化版 UI + 点数分配 |
+| M9 | 打磨整合：完整循环跑通 |
+
+---
+
+## 九、技术架构概要
+
+```
+Source/MM/
+├── Core/
+│   ├── MMGameMode.cpp          # 游戏模式
+│   ├── MMPlayerController.cpp  # 玩家控制器
+│   └── MMCharacterBase.cpp     # 角色基类（含 GAS AbilitySystemComponent）
+├── GAS/
+│   ├── AbilitySystem/
+│   │   ├── MMAbilitySystemComponent.cpp    # ASC 扩展
+│   │   └── MMAttributeSet.cpp              # 全属性集
+│   ├── Abilities/
+│   │   ├── MMGameplayAbility.cpp           # 技能基类
+│   │   ├── Saber/                          # Saber 技能
+│   │   └── Archer/                         # Archer 技能
+│   └── Effects/
+│       ├── MMGameplayEffect_Base.cpp       # GE 基类
+│       └── MMGameplayEffect_Damage.cpp     # 伤害 GE
+├── Combat/
+│   ├── DamageCalculation.cpp    # 伤害计算（含命中/闪避/穿甲/免伤）
+│   └── ProjectileBase.cpp       # 投射物基类
+├── Equipment/
+│   ├── ItemDefinition.cpp       # 物品定义（DataAsset）
+│   ├── EquipmentComponent.cpp   # 装备管理组件
+│   └── AffixTable.cpp           # 词条表
+├── AI/
+│   ├── MMAIController.cpp       # AI 控制器
+│   ├── MMBossAIController.cpp   # Boss AI
+│   └── Behaviors/               # 行为树任务
+├── Level/
+│   ├── RoomGenerator.cpp        # 房间随机生成
+│   └── RoomData.cpp             # 房间数据定义
+├── UI/
+│   ├── MMHUD.cpp                # HUD
+│   ├── MainMenuWidget.cpp       # 主菜单
+│   └── SkillTreeWidget.cpp      # 技能树 UI
+└── Player/
+    ├── SaberCharacter.cpp       # Saber 角色
+    └── ArcherCharacter.cpp      # Archer 角色
+```
--- a/Docs/workflow.md
+++ b/Docs/workflow.md
@@ -12,9 +12,9 @@
 | Agent | Profile | 模型 | 职责 |
 |-------|---------|------|------|
 | 大总管 | default | glm-5.1 | 需求讨论、设计文档、中央调度 |
-| game-main | game-main | deepseek-v4-flash | 任务拆解、生成 codex exec prompt |
-| operator | operator | deepseek-v4-flash | codex 执行、git 操作 |
-| techlead | techlead | deepseek-v4-pro | 代码审核 |
+| game-main | game-main | deepseek-v4-flash | 任务拆解、依赖排序、生成 ``codex exec`` prompt |
+| operator | operator | deepseek-v4-flash | 创建 worktree、执行 ``codex exec``、提交任务分支 |
+| techlead | techlead | deepseek-v4-pro | 代码审核、架构检查、验证结果复核 |
 | xie | xie | glm-5.1 | 剧情文案（独立，不走流水线） |

 ## 流水线
@@ -25,24 +25,25 @@
             ├ 1. 讨论需求，确认方向
             ├ 2. 输出设计文档
             │
-             ↓ terminal("game-main chat -q '...'")
+             ↓ terminal("game-main chat -Q -q '...'")
          【game-main】
             │
             ├ 3. 拆解为子任务
-             ├ 4. 为每个子任务生成 codex exec prompt
+             ├ 4. 为每个子任务生成 task spec 和 codex exec prompt
             ├ 5. 排列依赖关系
             │
-             ↓ terminal("operator chat -q '...'")
+             ↓ terminal("operator chat -Q -q '...'")
          【operator】
             │
-             ├ 6. codex exec --full-auto（worktree 隔离）
-             ├ 7. 收集输出 / diff
+             ├ 6. 创建任务分支和 worktree
+             ├ 7. codex exec（workspace-write + never approval）
+             ├ 8. 提交任务分支，收集输出 / diff / 验证结果
             │
-             ↓ terminal("techlead chat -q '...'")
+             ↓ terminal("techlead chat -Q -q '...'")
          【techlead】
             │
-             ├ 8. 审核代码质量、架构、安全性
-             ├ ✅ 通过 → operator 执行 git commit / merge
+             ├ 9. 审核代码质量、架构、安全性
+             ├ ✅ 通过 → 大总管汇报，等待用户确认合并 main
             └ ❌ 打回 → game-main 重写 prompt → 重来（最多3次）
             │
             ↓
@@ -51,31 +52,81 @@

 ## 调度方式

-**中央调度**：大总管通过 `terminal("<profile> chat -q '...'")` 依次调用各 profile。
+**中央调度**：大总管通过 `terminal("<profile> chat -Q -q '...'")` 依次调用各 profile。
+
+`-Q` 表示 quiet 模式，用于脚本化调用时只输出最终回复和必要会话信息。交互调试时可以去掉 `-Q`。

 用户全程只跟大总管对话。

+## 交接格式
+
+### game-main 输出
+
+每个子任务必须包含：
+
+- `TaskId`：稳定任务编号，例如 `MM-001`。
+- `DependsOn`：前置任务列表，无依赖写 `[]`。
+- `Branch`：建议分支名，格式 `feature/<任务名>`。
+- `OwnedPaths`：允许修改的主要路径，避免并行任务互相覆盖。
+- `AcceptanceCriteria`：用户可验证的完成条件。
+- `VerifyCommands`：operator 必须运行的验证命令；没有合适命令时写明原因。
+- `CodexPrompt`：完整 one-shot prompt，可直接喂给 `codex exec`。
+
+`CodexPrompt` 必须注入项目约束：遵守 `AGENTS.md`，使用纯 C++ 驱动，不要求编辑器手动配置，公开 API 写中文 `///` Doxygen 注释，如新增引擎模块依赖必须同步更新 `Source/MM/MM.Build.cs`。
+
+### operator 输出
+
+每个子任务完成后必须汇报：
+
+- 任务分支和 worktree 路径。
+- commit hash 和 commit message。
+- 关键 diff 摘要。
+- 实际运行的验证命令和结果。
+- 未解决风险、跳过的验证以及原因。
+
+### techlead 输出
+
+审核结论必须是以下之一：
+
+- `approve`：可进入用户确认合并阶段。
+- `request-changes`：必须列出阻塞问题、涉及文件/行号、建议修复方向。
+
+techlead 必须复核实现是否遵守 `AGENTS.md`，尤其是纯 C++ 驱动、Build.cs 依赖、公开 API 注释和不依赖蓝图/编辑器手工配置。
+
 ## Codex 执行策略

- 使用 `codex exec --full-auto` one-shot 模式
- 每个子任务一个 git worktree 隔离（`/tmp/mm-task-N/`）
+- 使用 `codex exec` one-shot 模式，不使用当前 CLI 不支持的 `--full-auto`
+- 推荐命令：
+
+  ```bash
+  codex exec -C "$WORKTREE" --sandbox workspace-write --ask-for-approval never -
+  ```
+
+  其中 prompt 从 stdin 传入，`$WORKTREE` 为当前子任务 worktree。
+
+- 每个子任务一个 git worktree 隔离（`/tmp/mm-task-N/` 或 operator 指定的唯一目录）
 - operator 用 `process(action="wait")` 阻塞等待 codex 完成
 - terminal timeout 上限 600 秒，任务粒度需控制在 10 分钟内
- 可并行执行无依赖的子任务
+- 可并行执行无依赖且 `OwnedPaths` 不重叠的子任务
+- 并行任务完成后按依赖顺序 rebase/merge 到目标任务分支；冲突由 operator 处理，不能自动解决时升级给用户

 ## 审核打回机制

 - techlead 打回时必须附带具体修改意见
- game-main 拿到意见后调整 prompt 重新生成
+- game-main 拿到意见后调整 task spec 和 prompt 重新生成
 - 单个子任务最大重试 3 次
 - 超过 3 次报给用户决策
+- 同类问题连续出现、验证命令缺失、验证失败无法定位、合并冲突无法自动解决时，立即升级给用户

 ## Git 策略

 - 主分支：`main`
 - 功能分支：`feature/<任务名>`
- operator 负责：创建分支 → 提交代码 → 合并到 main → 推送远程
+- operator 负责：创建分支 → 提交代码 → 推送任务分支
+- techlead 通过后，大总管汇报分支、commit、验证结果和审核结论
+- 用户确认后，operator 才能合并到 `main` 并推送远程
 - 每个 codex 任务对应一次 commit，commit message 格式：`feat: <简述>`
+- 多个并行任务合并时按依赖顺序处理；每次合并前必须确认 `main` 已更新到远程最新状态

 ## xie（独立）

--- a/3
+++ b/3
@@ -5,7 +5,7 @@ PROJECT_NAME           = "MM"
 PROJECT_NUMBER         = 
 PROJECT_BRIEF          = "API Documentation"
 PROJECT_LOGO           =
-OUTPUT_DIRECTORY       = docs
+OUTPUT_DIRECTORY       = Docs

 # 输入源
 INPUT                  = Source/ \
@@ -30,7 +30,6 @@ GENERATE_LATEX         = NO
 GENERATE_XML           = NO

 # Markdown 支持
-USE_MARKDOWN_TITLE     = YES
 MARKDOWN_SUPPORT       = YES
 TOC_INCLUDE_HEADINGS   = 5