355 lines
17 KiB
Markdown
355 lines
17 KiB
Markdown
# Tereis 实验报告与项目整理 TODO
|
||
|
||
> 依据：实验报告模板 `大学计算-程序设计大作业-实验报告模板.docx`、课堂报告要求截图、当前 `src` 源码目录。
|
||
> 说明：`report/` 文件夹按废弃资料处理，不作为本 TODO 的依据。
|
||
|
||
## 0. 当前项目审查结论
|
||
|
||
- [ ] 确认最终报告只引用 `src/`、`assets/`、`README.md`、构建脚本和重新整理的截图材料。
|
||
- [ ] 清点当前源码模块：
|
||
- `src/source/Tetris.cpp`：Win32 程序入口、窗口注册、消息循环、主窗口消息处理。
|
||
- `src/source/TetrisLogic.cpp`：基础俄罗斯方块移动、旋转、落地、消行、重开等核心逻辑。
|
||
- `src/source/logic/`：生成下一方块、固定方块、特殊落地效果、棋盘辅助逻辑。
|
||
- `src/source/app/`：定时器、键盘鼠标输入、窗口布局、背景音乐和复活视频。
|
||
- `src/source/render/` 与 `TetrisRender.cpp`：界面绘制、背景图片、GDI/GDI+ 资源加载。
|
||
- `src/source/extensions/`：菜单、反馈提示、视觉特效、复活、页面切换等扩展状态。
|
||
- `src/source/rogue/`：Rogue 模式、升级选项、主动技能、特殊方块、难度成长。
|
||
- [ ] 记录项目规模：多源文件 C++ Win32 桌面程序，主要采用全局变量、结构体、函数的过程式组织。
|
||
- [ ] 检查课程限制风险：
|
||
- 当前代码没有自定义 `class`、继承、多态。
|
||
- 但存在 `std::wstring`、`std::vector` 未发现、`auto` lambda、GDI+ `Image` 对象、`new/delete`、`constexpr`、C++17 构建参数等超出“仅基础语法”的风险点。
|
||
- 报告中需要说明：核心游戏逻辑坚持数组、循环、分支、函数、结构体；Win32/GDI+ 属于界面和资源接口调用。
|
||
|
||
## 1. 阶段一：窗口创建与程序框架
|
||
|
||
- [ ] 功能设计文档：说明为什么先搭建窗口、消息循环和菜单状态。
|
||
- [ ] 关键代码整理：
|
||
- `_tWinMain`：`src/source/Tetris.cpp`
|
||
- `MyRegisterClass`：`src/source/Tetris.cpp`
|
||
- `InitInstance`：`src/source/Tetris.cpp`
|
||
- `WndProc`：`src/source/Tetris.cpp`
|
||
- `About`：`src/source/Tetris.cpp`
|
||
- [ ] 代码说明重点：
|
||
- Win32 程序入口如何创建主窗口。
|
||
- 消息循环如何把键盘、鼠标、定时器、绘制消息分发给游戏。
|
||
- 为什么用全局状态变量保存当前界面和游戏状态。
|
||
- [ ] 截图补充：
|
||
- 程序启动主菜单。
|
||
- 帮助/说明页面。
|
||
- [ ] 编译运行记录：
|
||
- 执行 `.\build-mingw.ps1`。
|
||
- 记录是否成功生成 `.vscode-build\mingw\Tetris.exe`。
|
||
- [ ] AI 对话记录整理：
|
||
- 提示词主题：搭建 Win32 窗口框架。
|
||
- 人工审查点：入口函数、窗口大小、消息处理是否能正常运行。
|
||
|
||
## 2. 阶段二：基础方块移动与碰撞检测
|
||
|
||
- [ ] 功能设计文档：说明棋盘数组、活动方块坐标、边界判断和碰撞判断。
|
||
- [ ] 关键代码整理：
|
||
- `CanMoveDown`：`src/source/TetrisLogic.cpp`
|
||
- `CanMoveLeft`：`src/source/TetrisLogic.cpp`
|
||
- `CanMoveRight`：`src/source/TetrisLogic.cpp`
|
||
- `MoveDown`：`src/source/TetrisLogic.cpp`
|
||
- `MoveLeft`：`src/source/TetrisLogic.cpp`
|
||
- `MoveRight`：`src/source/TetrisLogic.cpp`
|
||
- `Rotate`：`src/source/TetrisLogic.cpp`
|
||
- `DropDown`：`src/source/TetrisLogic.cpp`
|
||
- [ ] 代码说明重点：
|
||
- `workRegion[20][10]` 如何表示固定方块。
|
||
- `bricks[7][4][4][4]` 如何表示 7 类方块和旋转状态。
|
||
- 移动前先检测，检测通过再修改坐标。
|
||
- 旋转失败时保持原状态，避免方块穿墙或重叠。
|
||
- [ ] 截图补充：
|
||
- 方块左移、右移、旋转、硬降后的游戏画面。
|
||
- [ ] 测试记录：
|
||
- 左右边界不能越界。
|
||
- 方块落到已有方块上方时停止。
|
||
- 旋转时不能覆盖已有方块。
|
||
- [ ] AI 对话记录整理：
|
||
- 提示词主题：补全移动和碰撞检测函数。
|
||
- 人工审查点：数组下标是否越界、边界条件是否完整。
|
||
|
||
## 3. 阶段三：方块固定、消行、得分和游戏状态
|
||
|
||
- [ ] 功能设计文档：说明方块落地后的固定流程、消行流程、分数变化和结束判断。
|
||
- [ ] 关键代码整理：
|
||
- `Fixing`：`src/source/TetrisLogic.cpp`
|
||
- `DeleteOneLine`：`src/source/TetrisLogic.cpp`
|
||
- `DeleteLines`：`src/source/TetrisLogic.cpp`
|
||
- `GameOver`：`src/source/TetrisLogic.cpp`
|
||
- `ComputeTarget`：`src/source/TetrisLogic.cpp`
|
||
- `Restart`：`src/source/TetrisLogic.cpp`
|
||
- `SpawnNextFallingPiece`：`src/source/logic/TetrisCoreHelpers.cpp`
|
||
- `ScanAndDeleteFullLines`：`src/source/logic/TetrisCoreHelpers.cpp`
|
||
- `ApplyLineClearResult`：`src/source/rogue/TetrisRogue.cpp`
|
||
- [ ] 代码说明重点：
|
||
- 活动方块如何写入棋盘数组。
|
||
- 满行检测从下到上扫描的原因。
|
||
- 消行后上方方块整体下移。
|
||
- `ComputeTarget` 如何得到预览落点。
|
||
- `Restart` 如何重置棋盘、分数、方块状态和视觉状态。
|
||
- [ ] 截图补充：
|
||
- 消除一行或多行。
|
||
- 分数变化。
|
||
- 游戏结束或重新开始。
|
||
- [ ] 测试记录：
|
||
- 单行消除。
|
||
- 多行消除。
|
||
- 顶部堆满后的游戏结束。
|
||
- 重新开始后棋盘清空。
|
||
- [ ] Bug 记录模板：
|
||
- 问题：消行后上方方块没有正确下落。
|
||
- 原因：删除行后未正确复制上一行数据。
|
||
- 修复：从被删行开始向上逐行覆盖，并清空第一行。
|
||
|
||
## 4. 阶段四：界面绘制、资源加载与交互
|
||
|
||
- [ ] 功能设计文档：说明游戏区、侧边栏、菜单、帮助页、按钮和背景资源。
|
||
- [ ] 关键代码整理：
|
||
- `TDrawScreen`：`src/source/TetrisRender.cpp`
|
||
- `RenderFullScreen`：`src/source/render/TetrisRenderMain.cpp`
|
||
- `LoadBackgroundImage`：`src/source/render/TetrisRenderAssets.cpp`
|
||
- `FileExists`：`src/source/common/TetrisAssets.cpp`
|
||
- `GetMenuOptionRect`：`src/source/app/TetrisLayout.cpp`
|
||
- `GetUpgradeCardRect`：`src/source/app/TetrisLayout.cpp`
|
||
- `HandleMouseClick`：`src/source/app/TetrisInput.cpp`
|
||
- `HandleMouseWheel`：`src/source/app/TetrisInput.cpp`
|
||
- `HandleKeyDown`：`src/source/app/TetrisInput.cpp`
|
||
- `StartBackgroundMusic`：`src/source/app/TetrisMedia.cpp`
|
||
- `ToggleBackgroundMusic`：`src/source/app/TetrisMedia.cpp`
|
||
- `PlayReviveVideo`：`src/source/app/TetrisMedia.cpp`
|
||
- [ ] 代码说明重点：
|
||
- 界面绘制与游戏逻辑分离。
|
||
- 鼠标点击通过矩形区域判断菜单和按钮。
|
||
- 键盘输入对应移动、旋转、暂停、重开、技能。
|
||
- 背景图、图标、音乐、视频统一放在 `assets/`。
|
||
- [ ] 截图补充：
|
||
- 主菜单。
|
||
- 经典模式游戏界面。
|
||
- 帮助页。
|
||
- 音乐按钮或返回按钮。
|
||
- [ ] 测试记录：
|
||
- 键盘控制有效。
|
||
- 鼠标点击菜单有效。
|
||
- 背景音乐开关有效。
|
||
- 从根目录运行时资源能正常加载。
|
||
- [ ] 风险处理：
|
||
- 报告中不要把 GDI+ 对象作为课程核心语法重点，重点讲过程式游戏逻辑和数组状态。
|
||
|
||
## 5. 阶段五：Rogue 创新模式与强化系统
|
||
|
||
- [ ] 功能设计文档：说明创新点来源、玩法目标和与经典模式的区别。
|
||
- [ ] 关键代码整理：
|
||
- `StartGameWithMode`：`src/source/extensions/TetrisGameExtensions.cpp`
|
||
- `ResetPlayerStats`：`src/source/extensions/TetrisGameExtensions.cpp`
|
||
- `OpenUpgradeMenu`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `ConfirmUpgradeSelection`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `CheckRogueLevelProgress`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `AwardRogueSkillClearRewards`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `AdvanceRogueDifficulty`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `GetRogueFallInterval`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `GetRogueLockedRows`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `GetUpgradeSynthesisPath`：`src/source/rogue/TetrisRogue.cpp`
|
||
- [ ] 代码说明重点：
|
||
- Rogue 模式如何用 `PlayerStats` 结构体保存等级、经验、强化、技能次数。
|
||
- 消行如何获得经验并触发升级选择。
|
||
- 强化选项如何随机生成、选择并影响后续游戏。
|
||
- 难度如何随时间推进。
|
||
- [ ] 截图补充：
|
||
- Rogue 模式游戏界面。
|
||
- 升级三选一。
|
||
- 双重选择或命运轮盘。
|
||
- 难度提升/底部封锁效果。
|
||
- [ ] 测试记录：
|
||
- 消行获得 EXP。
|
||
- EXP 满后进入升级界面。
|
||
- 选择强化后返回游戏。
|
||
- 难度等级会随时间变化。
|
||
- [ ] AI 对话记录整理：
|
||
- 提示词主题：设计俄罗斯方块 Rogue 强化系统。
|
||
- 人工审查点：强化是否真的改变游戏状态，升级界面是否能返回主流程。
|
||
|
||
## 6. 阶段六：主动技能、特殊方块和视觉特效
|
||
|
||
- [ ] 功能设计文档：说明主动技能和特殊方块是创新功能，不影响基础玩法可运行。
|
||
- [ ] 关键代码整理：
|
||
- `HoldCurrentPiece`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `UseScreenBomb`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `UseBlackHole`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `UseAirReshape`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `RollCurrentPieceSpecialFlags`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `ApplySpecialLandingEffects`：`src/source/logic/TetrisPieceEffects.cpp`
|
||
- `ApplyRainbowLandingEffect`：`src/source/logic/TetrisPieceEffects.cpp`
|
||
- `TriggerScreenBomb`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `TriggerMiniBlackHole`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `ClearExplosiveAreaAt`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `ClearColumnAt`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `ClearRowAt`：`src/source/rogue/TetrisRogue.cpp`
|
||
- `TriggerLineClearEffect`：`src/source/extensions/TetrisGameExtensions.cpp`
|
||
- `TickVisualEffects`：`src/source/extensions/TetrisGameExtensions.cpp`
|
||
- [ ] 代码说明重点：
|
||
- 技能按键如何触发对应函数。
|
||
- 技能如何修改棋盘数组。
|
||
- 特殊方块落地后如何触发清除、变色、爆炸、激光等效果。
|
||
- 视觉特效只负责显示，不应破坏核心棋盘数据。
|
||
- [ ] 截图补充：
|
||
- 备用仓。
|
||
- 清屏炸弹。
|
||
- 黑洞奇点。
|
||
- 空中换形。
|
||
- 爆破/激光/彩虹等特殊方块效果。
|
||
- [ ] 测试记录：
|
||
- 技能次数不足时不能使用。
|
||
- 技能使用后棋盘变化正确。
|
||
- 特殊方块效果不会造成数组越界。
|
||
- 特效结束后游戏仍可继续。
|
||
|
||
## 7. 实验报告正文 TODO
|
||
|
||
- [ ] 封面信息：
|
||
- 项目名称：使用大模型辅助开发俄罗斯方块程序。
|
||
- 小组成员、学号、班级、日期。
|
||
- [ ] 摘要：
|
||
- 简述完成了经典俄罗斯方块和 Rogue 创新模式。
|
||
- 强调使用 C++、Win32 API、数组、结构体、函数组织。
|
||
- [ ] 需求功能设计：
|
||
- 按至少 6 个阶段写，每阶段包含目标、功能点、涉及文件。
|
||
- 每阶段最多聚焦一个主要功能主题。
|
||
- [ ] 功能实现：
|
||
- 每阶段放关键代码截图。
|
||
- 每阶段写代码说明。
|
||
- 每阶段放游戏运行截图。
|
||
- [ ] AI 辅助编程体验反思：
|
||
- 写明大模型做得好的地方：快速生成框架、补全重复逻辑、解释 Win32 消息流程、提供调试思路。
|
||
- 写明大模型表现不好的地方：容易生成过复杂代码、可能使用超出课程范围的语法、边界条件不完整、变量命名可能不符合原框架。
|
||
- 写明改进方法：拆小任务、明确限制语法、每次只让模型生成一个函数、人工检查数组下标、编译运行验证。
|
||
- 注意表述成“多轮 LLM 对话迭代生成”，不要写成一次性 vibe coding。
|
||
- [ ] 成员分工表：
|
||
- 提示词工程师：拆分需求、编写和迭代提示词。
|
||
- 代码审计员：检查语法限制、数组越界、全局状态和函数注释。
|
||
- 功能测试员：运行游戏、记录 bug、截图。
|
||
- 报告撰稿人：整理阶段文档、代码截图、反思和分工。
|
||
- 现场汇报人：演示程序并回答问题。
|
||
- [ ] Bug 记录：
|
||
- 至少整理 3 个 bug，每个包含“问题、原因、修复过程、验证结果”。
|
||
- [ ] 总结：
|
||
- 说明最终实现的功能。
|
||
- 说明仍可改进的地方，例如代码规模较大、部分界面资源依赖本地文件、复杂扩展功能需要更多测试。
|
||
|
||
## 8. 答辩准备 TODO
|
||
|
||
- [ ] 每位组员至少熟悉一个源码模块，不能只由一人理解。
|
||
- [ ] 准备 5 分钟演示路线：
|
||
- 主菜单。
|
||
- 经典模式移动、旋转、消行。
|
||
- Rogue 模式升级。
|
||
- 主动技能。
|
||
- 特殊方块或视频复活。
|
||
- [ ] 准备常见问题回答：
|
||
- 方块形状如何存储？
|
||
- 如何判断碰撞？
|
||
- 如何消行？
|
||
- 如何实现升级选择？
|
||
- 如何保证没有使用自定义 class？
|
||
- AI 生成代码后做了哪些人工审查？
|
||
- [ ] 准备现场编译：
|
||
- 命令：`.\build-mingw.ps1`
|
||
- 运行：`.\build-mingw.ps1 -Run`
|
||
- 如果提示 `Tetris.exe: Permission denied`，先关闭正在运行的游戏窗口。
|
||
|
||
## 9. 四人专项分工规划
|
||
|
||
> 原则：四个人各有一个主要专项，同时都要理解自己负责模块对应的代码和报告内容；现场答辩时不能只由一个人解释全部代码。
|
||
|
||
### 成员 A：需求拆分与报告主线负责人
|
||
|
||
- [ ] 专项任务：负责实验报告整体结构、阶段划分和文字主线。
|
||
- [ ] 负责内容：
|
||
- 将项目整理成 6 个阶段：窗口框架、基础移动、消行得分、界面交互、Rogue 强化、主动技能与特效。
|
||
- 编写每个阶段的“需求功能设计”。
|
||
- 整理摘要、项目背景、总体架构、总结与不足。
|
||
- 保证报告符合截图要求：不少于五个阶段、每阶段有功能设计文档。
|
||
- [ ] 重点熟悉代码：
|
||
- `src/source/Tetris.cpp`
|
||
- `src/include/Tetris.h`
|
||
- `src/source/TetrisLogic.cpp`
|
||
- [ ] 最终交付：
|
||
- 报告目录结构。
|
||
- 6 个阶段的功能设计文字。
|
||
- 项目总体介绍和总结。
|
||
|
||
### 成员 B：核心逻辑与代码说明负责人
|
||
|
||
- [ ] 专项任务：负责基础俄罗斯方块核心逻辑的代码审查和代码说明。
|
||
- [ ] 负责内容：
|
||
- 解释棋盘数组 `workRegion[20][10]`。
|
||
- 解释方块数组 `bricks[7][4][4][4]`。
|
||
- 整理移动、旋转、碰撞、固定、消行、得分、游戏结束的关键代码。
|
||
- 检查数组下标、边界判断、函数注释是否适合放进报告。
|
||
- [ ] 重点熟悉代码：
|
||
- `src/source/TetrisLogic.cpp`
|
||
- `src/source/logic/TetrisCoreHelpers.cpp`
|
||
- `src/source/logic/TetrisPieceEffects.cpp`
|
||
- [ ] 最终交付：
|
||
- 阶段二、阶段三的关键代码截图清单。
|
||
- 每段关键代码的说明文字。
|
||
- 至少 1 个核心逻辑 bug 的“问题、原因、修复、验证”记录。
|
||
|
||
### 成员 C：界面交互、资源与运行截图负责人
|
||
|
||
- [ ] 专项任务：负责程序运行、界面截图、资源加载和交互测试。
|
||
- [ ] 负责内容：
|
||
- 编译并运行项目，记录构建结果。
|
||
- 截取主菜单、经典模式、帮助页、Rogue 升级、主动技能、特殊方块等运行截图。
|
||
- 测试键盘输入、鼠标点击、音乐开关、返回按钮、视频复活。
|
||
- 整理运行环境和现场演示路线。
|
||
- [ ] 重点熟悉代码：
|
||
- `src/source/render/TetrisRenderMain.cpp`
|
||
- `src/source/render/TetrisRenderAssets.cpp`
|
||
- `src/source/app/TetrisInput.cpp`
|
||
- `src/source/app/TetrisLayout.cpp`
|
||
- `src/source/app/TetrisMedia.cpp`
|
||
- `src/source/app/TetrisTimers.cpp`
|
||
- [ ] 最终交付：
|
||
- 每个阶段至少 1 张游戏界面截图。
|
||
- 构建运行记录。
|
||
- 现场 5 分钟演示路线。
|
||
- 至少 1 个界面或资源加载 bug 记录。
|
||
|
||
### 成员 D：AI 对话、创新功能与答辩问答负责人
|
||
|
||
- [ ] 专项任务：负责 AI 辅助编程过程整理、Rogue 创新功能说明和答辩材料。
|
||
- [ ] 负责内容：
|
||
- 整理“提示词 -> 模型生成 -> 人工审查 -> 编译测试 -> 修复”的多轮迭代过程。
|
||
- 编写 AI 辅助编程体验反思，突出优点、不足和改进方法。
|
||
- 整理 Rogue 模式、升级系统、主动技能、特殊方块、视觉特效的创新点。
|
||
- 准备答辩常见问题回答。
|
||
- [ ] 重点熟悉代码：
|
||
- `src/source/rogue/TetrisRogue.cpp`
|
||
- `src/source/extensions/TetrisGameExtensions.cpp`
|
||
- `src/source/logic/TetrisPieceEffects.cpp`
|
||
- [ ] 最终交付：
|
||
- AI 对话迭代记录。
|
||
- AI 编程体验反思。
|
||
- Rogue 创新功能说明。
|
||
- 答辩问答表。
|
||
- 至少 1 个 AI 生成代码问题或边界条件 bug 记录。
|
||
|
||
### 协作检查点
|
||
|
||
- [ ] 第一次合并：成员 A 完成报告框架后，成员 B/C/D 将各自材料填入对应阶段。
|
||
- [ ] 第二次合并：成员 B 审查所有关键代码说明，确认不夸大、不漏掉核心逻辑。
|
||
- [ ] 第三次合并：成员 C 核对每个阶段是否都有运行截图和测试记录。
|
||
- [ ] 第四次合并：成员 D 检查报告中 AI 过程是否像“多轮 LLM 对话迭代生成”，避免写成一次性生成。
|
||
- [ ] 最终检查：四人各自用 2 分钟讲清自己负责模块，互相提问一次。
|
||
|
||
## 10. 下一步执行顺序
|
||
|
||
1. [ ] 重新编译项目，确认当前源码可运行。
|
||
2. [ ] 按 6 个阶段重新截取游戏界面截图，保存到新的报告素材目录，避免使用废弃 `report/`。
|
||
3. [ ] 为每个阶段截取 2-4 张关键代码截图。
|
||
4. [ ] 根据本 TODO 填写实验报告模板。
|
||
5. [ ] 补充 AI 对话过程记录，包装为“需求拆分 -> 模型生成 -> 人工审查 -> 编译测试 -> 修复”的迭代过程。
|
||
6. [ ] 最终通读报告，检查是否符合“至少五个阶段、每阶段有设计文档、代码说明、游戏截图、AI 反思、成员分工”的要求。
|