TheTangestFive/Tereis
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

添加完善说明

Browse Source
This commit is contained in:
Qi-huanye
2026-04-26 15:20:50 +08:00
parent ea10e6ef12
commit a117b12981
3 changed files with 274 additions and 212 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Dev-C++运行说明.md
+89 -58
View File
@@ -1,38 +1,36 @@
# Dev-C++ 运行说明
本说明适用于需要在 `Dev-C++` 环境下编译本项目的情况。
结论先说：
- 可以运行
- 但不如 VS Code + 脚本方式稳定
- 如果只是为了交作业或课堂展示，优先推荐使用项目自带的 MinGW 脚本
## 1. 适用环境
本说明适用于 Windows 下的 Dev-C++ + MinGW 环境。
- Windows
- Dev-C++
- MinGW-w64
如果 Dev-C++ 自带的是较旧版本 MinGW，也可以尝试使用，但更建议使用支持 C++17 和 `windres` 的 MinGW。
建议 Dev-C++ 所使用的编译器支持：
## 2. 当前工程结构
- `C++17`
- `windres`
- `-municode`
项目已按工程方式整理：
## 2. 建议工程类型
```text
src/
├─ include/ 头文件
├─ source/ 源文件
└─ resources/ Windows 资源脚本
assets/
├─ icons/ 图标资源
├─ images/ 图片资源
└─ audio/ 音频资源
```
## 3. 建议的工程类型
在 Dev-C++ 中新建工程时，建议选择：
新建工程时请选择：
```text
Windows Application
```
不要选控制台程序，否则窗口程序的入口和链接方式会不匹配。
不要选择控制台程序。
## 4. 需要加入工程的文件
## 3. 需要加入工程的文件
### 源文件
@@ -42,27 +40,29 @@ Windows Application
- `src/source/Tetris.cpp`
- `src/source/TetrisLogic.cpp`
- `src/source/TetrisRender.cpp`
- `src/source/TetrisRogue.cpp`
### 头文件
头文件通常不需要全部加入编译列表，但建议加入工程树便于查看：
头文件不一定要加入编译列表，但建议加入工程树，便于浏览：
- `src/include/stdafx.h`
- `src/include/Tetris.h`
- `src/include/TetrisLogicInternal.h`
- `src/include/targetver.h`
- `src/include/resource.h`
### 资源文件
如果 Dev-C++ 当前环境支持资源编译，再把下面文件加入工程：
如果当前 Dev-C++ 环境支持资源编译，可以再加入：
- `src/resources/Tetris.rc`
## 5. 需要配置的选项
## 4. 需要配置的选项
### 头文件搜索路径
把下面目录加入 include path：
加入：
```text
src/include
@@ -70,15 +70,18 @@ src/include
### 链接库
确保工程链接以下 Windows 库：
确保链接以下库：
- `winmm`
- `gdi32`
- `user32`
- `comdlg32`
- `ole32`
- `gdiplus`
### 编译标准
建议使用：
建议设置为：
```text
C++17
@@ -92,59 +95,87 @@ C++17
- `_UNICODE`
- `_WINDOWS`
### 工程类型相关参数
### 建议参数
如果需要手动补参数，建议与当前脚本保持一致：
如果需要手动补充：
- `-mwindows`
- `-municode`
## 6. 关于资源文件
## 5. 资源文件注意事项
这里是 Dev-C++ 环境下最可能出问题的地方。
Dev-C++ 下最容易出问题的是资源编译。
`src/resources/Tetris.rc` 原始编码是 UTF-16，而有些 MinGW / Dev-C++ 组合下的 `windres` 不能直接编译它。
本项目资源包括：
同时，资源脚本中引用的图标名是：
- 图标
- 菜单
- 关于框
- `Tetris.ico`
- `small.ico`
资源脚本为：
而实际文件位于：
```text
src/resources/Tetris.rc
```
- `assets/icons/Tetris.ico`
- `assets/icons/small.ico`
如果 Dev-C++ 对该资源文件编译不稳定，最稳妥的做法有两种。
## 7. 推荐做法
### 做法一：不编译资源文件
### 做法一：先不编资源文件
最省事的方式是先不要把 `Tetris.rc` 加入 Dev-C++ 工程，只编译 C++ 源文件。
先只编译 C++ 源文件。
这样：
- 程序主体通常可以编译运行
- 但图标、菜单、关于框资源可能缺失
- 程序主体通常能正常运行
- 但窗口图标、菜单等资源可能缺失
### 做法二：单独处理资源文件后再加入工程
### 做法二：优先使用脚本构建
如果你希望在 Dev-C++ 中也带资源运行，建议先做这两步：
先在项目根目录执行：
1. 将 `Tetris.rc` 另存为 UTF-8 或 ANSI
2. 把资源中的图标路径改成实际可访问路径
例如改为：
```text
"assets/icons/Tetris.ico"
"assets/icons/small.ico"
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
```
这样更容易在 Dev-C++ 中直接通过资源编译。
确认脚本方式可构建后，再视需要把 Dev-C++ 作为备用方案。
## 8. 运行结果
## 6. 资源目录不要遗漏
如果配置正确，编译后应该能得到一个 Windows 图形界面的 `exe`，并正常弹出游戏窗口。
无论你用哪种方式运行，下面这些目录都不要删：
如果只是为了开发和调试，建议优先使用本项目现成的 VS Code 配置，因为当前目录结构、构建脚本和资源处理逻辑已经和 VS Code 对齐。 Dev-C++ 更适合作为兼容运行方案。
- `assets/icons/`
- `assets/images/`
- `assets/audio/`
- `assets/video/`
否则会影响：
- 图标显示
- 背景图片
- 背景音乐
- 视频复活
## 7. 常见问题
### 1）能编译但没有图标或菜单
通常是资源文件没有正确编译进程序。
### 2）编译时报 `gdiplus` 或 `winmm` 未定义引用
说明缺少链接库，请检查工程链接设置。
### 3）运行时没有背景图 / 音乐 / 视频
说明程序找不到 `assets/` 目录，通常是工作目录不对，或者运行时只复制了 `exe` 没带资源。
## 8. 建议
如果你的目标是：
- 交作业
- 本地演示
- 快速稳定运行
请优先使用本项目已经配好的 `build-mingw.ps1` 和 VS Code 配置。
Dev-C++ 更适合作为兼容环境，而不是主开发环境。
README.md
+104 -69
View File
@@ -1,19 +1,63 @@
# Tereis
基于 C++ 与 Windows API 实现的俄罗斯方块课程项目。
基于 C++、Win32 API 和 GDI/GDI+ 实现的俄罗斯方块课程大作业。
本项目使用 MinGW 进行构建，当前已完成基础窗口框架、方块逻辑、绘图显示与资源编译接入，适合作为《大学计算》程序设计大作业使用。
项目提供两种主要玩法：
## 项目简介
- `经典模式`：标准俄罗斯方块，强调移动、旋转、消行和生存。
- `Rogue 模式`：在标准玩法基础上加入升级、强化、主动技能、危险等级和局内构筑。
项目目标是实现一个可运行的桌面版俄罗斯方块程序，包含以下核心内容：
当前工程可直接在 Windows 下编译运行，适合作为课程展示、实验报告和源码答辩使用。
- 创建 Windows 游戏窗口
- 实现方块生成、移动、旋转与下落
- 实现碰撞检测、方块固定与游戏结束判定
- 实现消行逻辑与基础分数系统
- 实现界面绘制与部分资源显示
- 提供 MinGW 构建脚本和 VS Code 调试配置
## 项目特点
- Win32 图形界面程序，不依赖第三方游戏引擎
- 支持键盘操作、暂停、重开和返回主菜单
- 支持主菜单、帮助页、升级选择界面和结算反馈
- Rogue 模式包含强化系统、主动技能和特殊方块机制
- 支持背景图、图标、背景音乐和视频复活功能
- 提供 MinGW 构建脚本，以及 VS Code / Dev-C++ 运行说明
## 当前已实现内容
### 1. 基础玩法
- 方块生成、移动、旋转、软降、硬降
- 碰撞检测、落地固定、消行、游戏结束判定
- 预测落点显示
- 重新开始、暂停、返回菜单
### 2. 界面与资源
- 自定义窗口界面
- 图标资源
- 背景图片
- 背景音乐
- 帮助页与强化图鉴
### 3. Rogue 模式
- EXP 与等级系统
- 三选一 / 六选二强化系统
- 升级后强化选择
- 危险等级和底部封锁区
- 主动技能：
- `C / Shift` 备用仓
- `Z` 黑洞奇点
- `X` 清屏炸弹
- `V` 空中换形
- 特殊方块与连锁效果：
- 爆破核心
- 棱镜激光
- 十字方块
- 彩虹方块
- 方块改造
### 4. 额外功能
- 死亡后看本地视频复活一次
- 消除与技能清除特效
- 升级冲击波 / 进化冲击等升级联动效果
## 目录结构
@@ -22,47 +66,33 @@ Tereis/
├─ src/
│ ├─ include/ 头文件
│ ├─ source/ 源文件
│ └─ resources/ Windows 资源脚本
│ └─ resources/ Windows 资源文件
├─ assets/
│ ├─ audio/ 音频资源
│ ├─ icons/ 图标资源
│ ├─ images/ 图片资源
│ └─ audio/ 音频资源
│ └─ video/ 复活视频资源
├─ report/ 报告与整理材料
├─ .vscode/ VS Code 配置
├─ .vscode-build/ 本地构建输出目录
├─ report/ 实验报告材料与草稿
├─ build-mingw.ps1 MinGW 构建脚本
├─ list.md 项目阶段划分
├─ VSCode运行说明.md VS Code 使用说明
└─ README.md 项目说明
├─ README.md 项目总说明
├─ VSCode运行说明.md VS Code 运行说明
└─ Dev-C++运行说明.md Dev-C++ 运行说明
```
## 开发阶段划分
整个程序按 6 个阶段拆分实现：
1. 窗口创建与程序框架搭建
2. 游戏区域与方块数据结构设计
3. 方块生成、移动与旋转功能
4. 碰撞检测与方块固定逻辑
5. 消除逻辑与分数系统
6. 界面完善与创新功能扩展
详细内容见 [list.md](./list.md)。
## 构建与运行
### 环境要求
## 环境要求
- Windows
- MinGW
- `g++.exe`
- `gdb.exe`
- `windres.exe`
- PowerShell
- MinGW-w64
- `g++.exe`
- `windres.exe`
- 如需调试：`gdb.exe`
脚本会优先使用系统 `PATH` 中的工具；如果未加入 `PATH`，也兼容 `C:\mingw64\bin\` 下的 MinGW。
脚本会优先使用系统 `PATH` 中的 MinGW；如果没有加入 `PATH`，也兼容常见安装路径 `C:\mingw64\bin\`。
### 使用脚本构建
## 构建与运行
在项目根目录执行：
@@ -70,58 +100,63 @@ Tereis/
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
```
构建完成后会生成：
构建成功后，生成文件位于：
```text
.vscode-build\mingw\Tetris.exe
```
### 构建并直接运行
如果希望构建后直接运行：
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run
```
### 使用 VS Code
注意：
项目已提供：
- 如果提示 `Tetris.exe: Permission denied`，通常是程序还在运行，先关闭游戏窗口再重新构建。
- 项目依赖 `assets/` 下的图标、图片、音频和视频资源，提交或运行时不要删掉这些文件。
- 构建任务 `build Tetris MinGW`
- 运行任务 `run Tetris MinGW`
- 调试配置 `Debug Tetris MinGW`
## 操作说明
详见 [VSCode运行说明.md](./VSCode运行说明.md)。
### 通用操作
## 资源文件说明
- `← / A`：左移
- `→ / D`：右移
- `↑ / W`：旋转
- `↓ / S`：软降
- `Space`：硬降
- `P`：暂停 / 继续
- `R`：重开当前对局
- `M`：返回主菜单
项目包含 Windows 资源文件 `src/resources/Tetris.rc`，其中定义了图标、菜单、快捷键和关于框等内容。
### Rogue 模式附加操作
由于原始 `Tetris.rc` 为 UTF-16 编码，当前构建脚本会在编译时临时转换资源文件编码，并将 `assets/icons/` 中的图标文件一起编译进最终程序，因此资源不再被跳过。
- `C / Shift`：备用仓
- `Z`：黑洞奇点
- `X`：清屏炸弹
- `V`：空中换形
## 报告目录
### 复活
实验报告相关材料已整理到 [report/](./report/)：
- 死亡后按 `V` 播放本地视频，可复活一次
- `report.md`：报告正文草稿
- `outline.md`：章节提纲
- `notes.md`：待补充内容
- `images/`：截图和流程图
- `code-snippets/`：报告中准备引用的代码
- `submission/`：最终提交版文档
## 文档说明
## 当前状态
- [VSCode运行说明.md](./VSCode运行说明.md)：适合直接在 VS Code 中构建、运行和调试
- [Dev-C++运行说明.md](./Dev-C++运行说明.md)：适合作为备用运行方案
- [report/list.md](./report/list.md)：项目阶段清单
当前项目已完成的工作：
## 课程展示建议
- 修复项目迁移后的路径配置问题
- 补充 `.gitignore`
- 接入资源文件编译流程
- 整理项目阶段清单
- 建立实验报告目录结构
如果用于课堂演示，建议优先展示以下内容：
后续可以继续完善的方向：
1. 主菜单与帮助页
2. 经典模式基础玩法
3. Rogue 模式升级界面
4. 特殊方块与主动技能
5. 视频复活功能
- 优化界面表现
- 完善分数与状态提示
- 增加创新功能
- 补充测试截图和实验分析
## 说明
本项目为课程设计 / 大作业用途，代码风格以过程式实现为主，便于和课程内容对照理解，不以复杂架构设计为目标。
VSCode运行说明.md
+74 -78
View File
@@ -1,71 +1,45 @@
# VS Code 运行说明
## 1. 适用环境
本说明适用于 `Windows + VS Code + MinGW-w64` 环境。
本项目适用于 Windows + VS Code + MinGW 环境。
## 1. 推荐环境
建议已安装：
- VS Code
- C/C++ 扩展（Microsoft）
- Microsoft C/C++ 扩展
- PowerShell
- MinGW，且可用 `g++.exe`、`gdb.exe`、`windres.exe`
- MinGW-w64
- `g++.exe`
- `gdb.exe`
- `windres.exe`
脚本会优先使用系统 `PATH` 中的工具；如果未加入 `PATH`，也兼容 `C:\mingw64\bin\` 下的 MinGW。
## 2. 正确打开方式
## 2. 项目结构
当前工程目录结构如下：
```text
src/
├─ include/ 头文件
├─ source/ 源文件
└─ resources/ Windows 资源脚本
assets/
├─ icons/ 图标资源
├─ images/ 图片资源
└─ audio/ 音频资源
```
其中：
- 头文件检索路径为 `src/include`
- 编译的源文件位于 `src/source`
- 资源脚本为 `src/resources/Tetris.rc`
- 图标资源为 `assets/icons/Tetris.ico` 和 `assets/icons/small.ico`
## 3. 打开方式
用 VS Code 打开项目根目录，也就是包含以下文件的目录：
请直接用 VS Code 打开项目根目录，也就是包含以下内容的目录：
- `build-mingw.ps1`
- `.vscode/`
- `src/`
- `assets/`
不要只打开 `src/` 子目录，否则任务和调试配置会失效。
不要只打开 `src/` 子目录，否则：
## 4. 构建方式
- 构建任务不可用
- 调试配置不可用
- 路径和资源引用可能失效
### 方法一：快捷键构建
## 3. 构建方法
按 `Ctrl+Shift+B`，默认会执行：
### 方法一：快捷键
```text
build Tetris MinGW
```
按 `Ctrl + Shift + B`
它会调用：
默认会执行项目中的 MinGW 构建任务。
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
```
### 方法二：运行任务
### 方法二：命令面板运行任务
在命令面板中执行：
打开命令面板，执行：
```text
Tasks: Run Task
@@ -76,7 +50,7 @@ Tasks: Run Task
- `build Tetris MinGW`
- `run Tetris MinGW`
## 5. 调试方式
## 4. 调试方法
按 `F5`，选择：
@@ -84,69 +58,91 @@ Tasks: Run Task
Debug Tetris MinGW
```
调试配置会先执行构建任务，然后启动：
该配置会先构建，再启动：
```text
.vscode-build\mingw\Tetris.exe
```
当前工作目录为项目根目录。
## 5. 输出位置
## 6. 构建输出
成功构建后，输出文件位于：
构建成功后，程序位于：
```text
.vscode-build\mingw\Tetris.exe
```
同时在资源编译阶段，脚本还会临时生成：
中间产物位于同一目录下，例如：
- `.vscode-build\mingw\Tetris.utf8.rc`
- `.vscode-build\mingw\Tetris.res.o`
- `Tetris.utf8.rc`
- `Tetris.res.o`
这些都属于中间产物，不需要手动维护。
## 6. 推荐命令
## 7. 资源文件说明
在 VS Code 终端中，也可以直接执行：
原始 `Tetris.rc` 是 UTF-16 编码，MinGW 的 `windres` 不能直接稳定编译该文件。
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
```
当前脚本的处理方式是：
如果构建后要立即运行：
1. 读取 `src/resources/Tetris.rc`
2. 临时转换为 UTF-8
3. 将图标路径替换为 `assets/icons/` 下的实际文件
4. 使用 `windres` 编译资源
5. 将资源对象与 C++ 源文件一起链接
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run
```
因此在 VS Code 环境下，图标和菜单资源是会参与构建的。
## 7. 常见问题
## 8. 常见问题
### 1）提示找不到 `g++.exe`
### 找不到 `g++.exe`
说明 MinGW 没有正确安装，或者没有加入系统 `PATH`。
说明 MinGW 没加入系统 `PATH`，或者未安装在 `C:\mingw64\bin\`。
处理方式：
- 把 MinGW 的 `bin` 目录加入 `PATH`
- 或安装到 `C:\mingw64\bin\`
### 找不到 `gdb.exe`
### 2）提示找不到 `windres.exe`
说明调试器不可用。
构建通常还能继续，但 `F5` 调试会失败。
说明资源文件无法编译进程序。
### 找不到 `windres.exe`
结果通常是：
程序主体仍可能编译通过，但资源文件无法编译进最终 `exe`。
- 主体代码可能还能编译
- 但图标、菜单等资源会出问题
### 打开的是 `src/` 而不是项目根目录
### 3）提示 `Tetris.exe: Permission denied`
会导致：
通常是因为游戏程序还在运行，导致链接器无法覆盖旧的 `exe`。
- VS Code 任务不可用
- 调试配置不可用
- include 路径不正确
处理方式：
应重新打开项目根目录。
- 先关闭正在运行的游戏窗口
- 再重新执行构建
### 4）按 `F5` 无法调试
一般是因为：
- 没安装 `gdb.exe`
- 打开的不是项目根目录
- VS Code 没有加载 `.vscode` 配置
## 8. 资源说明
项目运行依赖以下资源目录：
- `assets/icons/`
- `assets/images/`
- `assets/audio/`
- `assets/video/`
如果只是拷贝 `exe` 而不带资源目录，部分功能会缺失，例如：
- 背景图
- 背景音乐
- 复活视频
## 9. 适用场景
如果你主要在本机开发、调试和演示，VS Code 是本项目最推荐的运行方式。当前任务配置、构建脚本和资源处理流程都已经围绕 VS Code 配好。