删除无用文件整理README等文件

2026-04-26 16:06:04 +08:00
parent 7db0bfadfc
commit 47ca7473ec
4 changed files with 290 additions and 293 deletions
@@ -1,26 +1,8 @@
 # Dev-C++ 运行说明
-本说明适用于需要在 `Dev-C++` 环境下编译本项目的情况。
+本项目可以尝试在 Dev-C++ 中运行，但更推荐使用 VS Code 和 `build-mingw.ps1` 脚本。Dev-C++ 对资源文件、Unicode 入口和链接库的处理更容易出现环境差异。
-结论先说：
+## 1. 工程类型
 - 可以运行
 - 但不如 VS Code + 脚本方式稳定
 - 如果只是为了交作业或课堂展示，优先推荐使用项目自带的 MinGW 脚本
 ## 1. 适用环境
 - Windows
 - Dev-C++
 - MinGW-w64
 建议 Dev-C++ 所使用的编译器支持：
 - `C++17`
 - `windres`
 - `-municode`
 ## 2. 建议工程类型
 新建工程时请选择：
@@ -30,152 +12,127 @@ Windows Application
 不要选择控制台程序。
-## 3. 需要加入工程的文件
+## 2. 需要加入工程的源码
-### 源文件
+源文件：
-把以下文件加入工程：
+```text
 src/source/stdafx.cpp
 src/source/Tetris.cpp
 src/source/TetrisLogic.cpp
 src/source/TetrisRender.cpp
 src/source/TetrisRogue.cpp
 ```
- `src/source/stdafx.cpp`
+头文件目录：
 - `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++ 环境支持资源编译，可以再加入：
 - `src/resources/Tetris.rc`
 ## 4. 需要配置的选项
 ### 头文件搜索路径
 加入：
 ```text
 src/include
 ```
-### 链接库
+建议把以下头文件加入工程树，便于查看：
 确保链接以下库：
 - `winmm`
 - `gdi32`
 - `user32`
 - `comdlg32`
 - `ole32`
 - `gdiplus`
 ### 编译标准
 建议设置为：
 ```text
-C++17
+src/include/stdafx.h
 src/include/Tetris.h
 src/include/TetrisLogicInternal.h
 src/include/targetver.h
 src/include/resource.h
 ```
-### 预处理宏
+## 3. 资源文件
-建议定义：
+资源文件为：
 - `UNICODE`
 - `_UNICODE`
 - `_WINDOWS`
 ### 建议参数
 如果需要手动补充：
 - `-mwindows`
 - `-municode`
 ## 5. 资源文件注意事项
 Dev-C++ 下最容易出问题的是资源编译。
 本项目资源包括：
 - 图标
 - 菜单
 - 关于框
 资源脚本为：
 ```text
 src/resources/Tetris.rc
 ```
-如果 Dev-C++ 对该资源文件编译不稳定，最稳妥的做法有两种。
+如果 Dev-C++ 能正常编译资源，可以加入该文件。  
 如果资源编译失败，可以先不加入资源文件，只编译 C++ 源码。这样程序主体仍可运行，但图标、菜单等资源可能不完整。
-### 做法一：不编译资源文件
+## 4. 编译设置
-先只编译 C++ 源文件。
+建议：
-这样：
+- C++ 标准：`C++17`
 - 工程类型：Windows 程序
 - 字符集：Unicode
- 程序主体通常能正常运行
+建议预处理宏：
 - 但窗口图标、菜单等资源可能缺失
-### 做法二：优先使用脚本构建
+```text
-
+UNICODE
-先在项目根目录执行：
+_UNICODE
-
+_WINDOWS
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
 ```
-确认脚本方式可构建后，再视需要把 Dev-C++ 作为备用方案。
+建议编译 / 链接参数：
-## 6. 资源目录不要遗漏
+```text
 -mwindows
 -municode
 ```
-无论你用哪种方式运行，下面这些目录都不要删：
+## 5. 链接库
- `assets/icons/`
+需要链接以下库：
 - `assets/images/`
 - `assets/audio/`
 - `assets/video/`
-否则会影响：
+```text
 winmm
 gdi32
 user32
 comdlg32
 ole32
 gdiplus
 shell32
 ```
- 图标显示
+如果出现 `undefined reference`，优先检查这些库是否正确加入。
 ## 6. 资源目录
 运行时请保留：
 ```text
 assets/icons/
 assets/images/
 assets/audio/
 assets/video/
 ```
 这些资源用于：
 - 程序图标
 - 背景图片
 - 背景音乐
 - 视频复活
 如果工作目录设置不正确，程序可能找不到这些资源。
 ## 7. 常见问题
-### 1）能编译但没有图标或菜单
+### 资源文件编译失败
-通常是资源文件没有正确编译进程序。
+Dev-C++ 的 `windres` 对资源文件编码和路径比较敏感。可以先不加入 `Tetris.rc`，或者改用项目自带脚本构建。
-### 2）编译时报 `gdiplus` 或 `winmm` 未定义引用
+### 无法识别 `_tWinMain`
-说明缺少链接库，请检查工程链接设置。
+说明工程类型或 Unicode 参数不正确。请确认使用 Windows Application，并启用 Unicode 相关宏和 `-municode`。
-### 3）运行时没有背景图 / 音乐 / 视频
+### 背景、音乐或视频缺失
-说明程序找不到 `assets/` 目录，通常是工作目录不对，或者运行时只复制了 `exe` 没带资源。
+说明运行目录找不到 `assets/`。建议从项目根目录运行，或保持 exe 与资源目录的相对位置。
 ### 链接失败
 检查是否加入了 `winmm`、`gdiplus`、`shell32` 等库。
 ## 8. 建议
-如果你的目标是：
+Dev-C++ 适合作为备用运行方式。  
 如果要稳定构建、调试和课堂展示，建议优先使用：
- 交作业
+```powershell
- 本地演示
+powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
- 快速稳定运行
+```
 请优先使用本项目已经配好的 `build-mingw.ps1` 和 VS Code 配置。  
 Dev-C++ 更适合作为兼容环境，而不是主开发环境。
@@ -1,87 +1,121 @@
 # Tereis
-基于 C++、Win32 API 和 GDI/GDI+ 实现的俄罗斯方块课程大作业。
+Tereis 是一个基于 C++、Win32 API、GDI/GDI+ 实现的桌面版俄罗斯方块课程大作业。
-项目提供两种主要玩法：
+项目在经典俄罗斯方块玩法上扩展了 Rogue 模式，加入等级成长、强化选择、主动技能、特殊方块、视频复活、鼠标交互和视觉特效。程序不依赖游戏引擎，主要使用 Win32 消息循环和 GDI 绘图完成。
- `经典模式`：标准俄罗斯方块，强调移动、旋转、消行和生存。
+## 功能概览
 - `Rogue 模式`：在标准玩法基础上加入升级、强化、主动技能、危险等级和局内构筑。
-当前工程可直接在 Windows 下编译运行，适合作为课程展示、实验报告和源码答辩使用。
+### 经典模式
 ## 项目特点
 - Win32 图形界面程序，不依赖第三方游戏引擎
 - 支持键盘操作、暂停、重开和返回主菜单
 - 支持主菜单、帮助页、升级选择界面和结算反馈
 - Rogue 模式包含强化系统、主动技能和特殊方块机制
 - 支持背景图、图标、背景音乐和视频复活功能
 - 提供 MinGW 构建脚本，以及 VS Code / Dev-C++ 运行说明
 ## 当前已实现内容
 ### 1. 基础玩法
 - 标准俄罗斯方块规则
 - 方块生成、移动、旋转、软降、硬降
- 碰撞检测、落地固定、消行、游戏结束判定
+- 方块落地固定、消行、计分和死亡判定
 - 预测落点显示
- 重新开始、暂停、返回菜单
+- 暂停、重开、返回主菜单
-### 2. 界面与资源
+### Rogue 模式
- 自定义窗口界面
+Rogue 模式是本项目的主要扩展玩法。
- 图标资源
+
 - 消行获得分数和 EXP
 - EXP 满后进入强化选择界面
 - 支持普通三选一强化
 - 支持双重抉择，同屏选择两个强化
 - 支持命运轮盘，同屏展示六个强化并选择两个
 - 随时间提升危险等级，底部封锁区会压缩可用空间
 - 支持多种强化联动和构筑方向
 ### 强化与技能
 项目中包含多类强化效果：
 - 基础成长：得分倍率、EXP 倍率、预览数量、下落速度调整
 - 生存强化：最后一搏、时间缓流、稳定结构
 - 主动技能：备用仓、清屏炸弹、黑洞奇点、空中换形
 - 特殊方块：爆破核心、棱镜激光、十字方块、彩虹方块
 - 进阶联动：连锁火花、连环炸弹、雷霆四消、雷霆棱镜
 - 风险收益：高压悬赏、豪赌四消、极限玩家、赌徒契约
 - 升级联动：双重抉择、命运轮盘、升级冲击波、进化冲击
 具体效果可在游戏主菜单的 `帮助 -> 强化图鉴` 中查看。
 ### 鼠标交互
 除键盘操作外，项目也支持鼠标点击：
 - 主菜单项目可点击
 - 帮助页项目可点击
 - 升级卡片可点击选择
 - 多选强化可点击标记
 - 暂停和结算界面按钮可点击
 - 非主菜单界面左上角有返回按钮，可点击回到主菜单
 - 右下角音乐按钮可点击开关背景音乐
 ### 视听与资源
 - 自定义图标
 - 背景图片
 - 背景音乐
- 帮助页与强化图鉴
+- 消行和技能清除特效
 - 死亡后可播放本地视频复活一次
-### 3. Rogue 模式
+## 操作说明
- EXP 与等级系统
+### 通用键盘操作
 - 三选一 / 六选二强化系统
 - 升级后强化选择
 - 危险等级和底部封锁区
 - 主动技能：
  - `C / Shift` 备用仓
  - `Z` 黑洞奇点
  - `X` 清屏炸弹
  - `V` 空中换形
 - 特殊方块与连锁效果：
  - 爆破核心
  - 棱镜激光
  - 十字方块
  - 彩虹方块
  - 方块改造
-### 4. 额外功能
+| 按键 | 功能 |
 | --- | --- |
 | `← / A` | 左移 |
 | `→ / D` | 右移 |
 | `↑ / W` | 旋转 |
 | `↓ / S` | 软降 |
 | `Space` | 硬降 |
 | `P` | 暂停 / 继续 |
 | `R` | 重开当前对局 |
 | `M` | 返回主菜单 |
- 死亡后看本地视频复活一次
+### Rogue 模式额外按键
 - 消除与技能清除特效
 - 升级冲击波 / 进化冲击等升级联动效果
-## 目录结构
+| 按键 | 功能 |
 | --- | --- |
 | `C / Shift` | 备用仓 |
 | `Z` | 黑洞奇点 |
 | `X` | 清屏炸弹 |
 | `V` | 空中换形 |
 | 死亡后 `V` | 看视频复活一次 |
 ### 升级选择
 - 普通升级：方向键 / WASD 切换，Enter 或 Space 确认
 - 双重抉择 / 命运轮盘：Space 标记，Enter 确认已选强化
 - 鼠标操作：直接点击升级卡片即可选择或标记
 ## 项目结构
 ```text
 Tereis/
 ├─ src/
 │  ├─ include/                 头文件
 │  ├─ source/                  源文件
-│  └─ resources/               Windows 资源文件
+│  └─ resources/               Windows 资源脚本
 ├─ assets/
-│  ├─ audio/                   音频资源
+│  ├─ audio/                   背景音乐
-│  ├─ icons/                   图标资源
+│  ├─ icons/                   程序图标
-│  ├─ images/                  图片资源
+│  ├─ images/                  背景图片
-│  └─ video/                   复活视频资源
+│  └─ video/                   复活视频
-├─ report/                     报告与整理材料
+├─ report/                     报告相关材料
 ├─ .vscode/                    VS Code 配置
 ├─ .vscode-build/              本地构建输出目录
 ├─ build-mingw.ps1             MinGW 构建脚本
-├─ README.md                   项目总说明
+├─ README.md                   项目说明
-├─ VSCode运行说明.md           VS Code 运行说明
+├─ VSCode运行说明.md           VS Code 构建运行说明
-└─ Dev-C++运行说明.md          Dev-C++ 运行说明
+└─ Dev-C++运行说明.md          Dev-C++ 兼容运行说明
 ```
-## 环境要求
+## 构建环境
 推荐环境：
 - Windows
 - PowerShell
@@ -90,7 +124,11 @@ Tereis/
 - `windres.exe`
 - 如需调试：`gdb.exe`
-脚本会优先使用系统 `PATH` 中的 MinGW；如果没有加入 `PATH`，也兼容常见安装路径 `C:\mingw64\bin\`。
+构建脚本会优先使用系统 `PATH` 中的 MinGW。如果没有加入 `PATH`，脚本也会尝试使用：
 ```text
 C:\mingw64\bin\
 ```
 ## 构建与运行
@@ -100,63 +138,66 @@ 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
 ```
-注意：
+## 常见问题
- 如果提示 `Tetris.exe: Permission denied`，通常是程序还在运行，先关闭游戏窗口再重新构建。
+### 1. 提示 `Tetris.exe: Permission denied`
 - 项目依赖 `assets/` 下的图标、图片、音频和视频资源，提交或运行时不要删掉这些文件。
-## 操作说明
+说明游戏程序仍在运行，链接器无法覆盖旧文件。
-### 通用操作
+处理方式：
- `← / A`：左移
+- 关闭正在运行的游戏窗口
- `→ / D`：右移
+- 重新执行构建命令
 - `↑ / W`：旋转
 - `↓ / S`：软降
 - `Space`：硬降
 - `P`：暂停 / 继续
 - `R`：重开当前对局
 - `M`：返回主菜单
-### Rogue 模式附加操作
+### 2. 没有背景图、音乐或视频
- `C / Shift`：备用仓
+请确认运行时保留了 `assets/` 目录。项目会从资源目录读取背景、音乐和复活视频。
 - `Z`：黑洞奇点
 - `X`：清屏炸弹
 - `V`：空中换形
-### 复活
+### 3. 视频复活播放失败
- 死亡后按 `V` 播放本地视频，可复活一次
+项目会优先查找：
-## 文档说明
+- `assets/video/video.avi`
 - `assets/video/video.mp4`
- [VSCode运行说明.md](./VSCode运行说明.md)：适合直接在 VS Code 中构建、运行和调试
+如果系统不支持对应格式，可能会播放失败。建议保留项目中已提供的视频文件。
- [Dev-C++运行说明.md](./Dev-C++运行说明.md)：适合作为备用运行方案
+
- [report/list.md](./report/list.md)：项目阶段清单
+### 4. 鼠标点击不生效
 请确认运行的是最新构建结果。若构建时 `Tetris.exe` 被占用，实际运行的可能仍是旧版本。
 ## 课程展示建议
-如果用于课堂演示，建议优先展示以下内容：
+建议按以下顺序展示：
-1. 主菜单与帮助页
+1. 主菜单、帮助页和鼠标点击
 2. 经典模式基础玩法
-3. Rogue 模式升级界面
+3. Rogue 模式升级选择
-4. 特殊方块与主动技能
+4. 双重抉择或命运轮盘的多选界面
-5. 视频复活功能
+5. 主动技能：黑洞、炸弹、换形、备用仓
 6. 特殊方块和消除特效
 7. 死亡后视频复活
-## 说明
+## 实现说明
-本项目为课程设计 / 大作业用途，代码风格以过程式实现为主，便于和课程内容对照理解，不以复杂架构设计为目标。
+本项目以过程式 C++ 写法为主，核心逻辑分布如下：
 - `src/source/Tetris.cpp`：窗口、消息循环、输入和鼠标交互
 - `src/source/TetrisLogic.cpp`：基础方块逻辑、消行和状态重置
 - `src/source/TetrisRogue.cpp`：Rogue 模式、强化、技能和成长系统
 - `src/source/TetrisRender.cpp`：界面绘制、面板、动画和特效
 - `src/include/Tetris.h`：主要结构体、全局状态和函数声明
 项目适合作为程序设计课程大作业展示，也便于在答辩时讲解窗口程序、游戏循环、碰撞检测、状态管理和功能扩展。
@@ -1,56 +1,72 @@
 # VS Code 运行说明
-本说明适用于 `Windows + VS Code + MinGW-w64` 环境。
+本项目推荐使用 `VS Code + MinGW-w64 + PowerShell` 构建和调试。
-## 1. 推荐环境
+## 1. 环境准备
-建议已安装：
+需要安装：
- VS Code
+- Visual Studio Code
 - Microsoft C/C++ 扩展
 - PowerShell
 - MinGW-w64
 - PowerShell
 MinGW 中至少需要：
 - `g++.exe`
 - `gdb.exe`
 - `windres.exe`
 - `gdb.exe`，仅调试时需要
-## 2. 正确打开方式
+## 2. 打开项目
-请直接用 VS Code 打开项目根目录，也就是包含以下内容的目录：
+请在 VS Code 中打开项目根目录，也就是包含以下文件和目录的位置：
- `build-mingw.ps1`
+```text
- `.vscode/`
+build-mingw.ps1
- `src/`
+src/
- `assets/`
+assets/
 .vscode/
 README.md
 ```
-不要只打开 `src/` 子目录，否则：
+不要只打开 `src/` 子目录，否则 VS Code 任务和调试配置无法正常工作。
- 构建任务不可用
+## 3. 使用 VS Code 任务构建
 - 调试配置不可用
 - 路径和资源引用可能失效
-## 3. 构建方法
+按：
-### 方法一：快捷键
+```text
-
+Ctrl + Shift + B
-按 `Ctrl + Shift + B`
+```
 默认会执行项目中的 MinGW 构建任务。
-### 方法二：运行任务
+也可以打开命令面板，选择：
 打开命令面板，执行：
 ```text
 Tasks: Run Task
 ```
-然后选择：
+然后运行：
 - `build Tetris MinGW`
 - `run Tetris MinGW`
-## 4. 调试方法
+## 4. 使用命令行构建
 在 VS Code 终端中进入项目根目录，执行：
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
 ```
 构建后直接运行：
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run
 ```
 ## 5. 调试
 按 `F5`，选择：
@@ -58,91 +74,74 @@ Tasks: Run Task
 Debug Tetris MinGW
 ```
-该配置会先构建，再启动：
+调试配置会先构建项目，再启动：
 ```text
 .vscode-build\mingw\Tetris.exe
 ```
-## 5. 输出位置
+如果提示找不到 `gdb.exe`，说明 MinGW 的调试器没有安装或没有加入 `PATH`。
-构建成功后，程序位于：
+## 6. 构建输出
 最终程序：
 ```text
 .vscode-build\mingw\Tetris.exe
 ```
-中间产物位于同一目录下，例如：
+构建中间文件：
- `Tetris.utf8.rc`
+```text
- `Tetris.res.o`
+.vscode-build\mingw\Tetris.utf8.rc
-
+.vscode-build\mingw\Tetris.res.o
 ## 6. 推荐命令
 在 VS Code 终端中，也可以直接执行：
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
 ```
-如果构建后要立即运行：
+这些中间文件不需要手动维护。
-```powershell
+## 7. 资源文件
-powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run
+
 项目运行依赖：
 ```text
 assets/icons/
 assets/images/
 assets/audio/
 assets/video/
 ```
-## 7. 常见问题
+如果只移动 `Tetris.exe` 而不带 `assets/`，会影响背景图、音乐和视频复活功能。
-### 1）提示找不到 `g++.exe`
+## 8. 常见问题
-说明 MinGW 没有正确安装，或者没有加入系统 `PATH`。
+### 找不到 `g++.exe`
 处理方式：
- 把 MinGW 的 `bin` 目录加入 `PATH`
+- 将 MinGW 的 `bin` 目录加入系统 `PATH`
- 或安装到 `C:\mingw64\bin\`
+- 或将 MinGW 安装到 `C:\mingw64\bin\`
-### 2）提示找不到 `windres.exe`
+### 找不到 `windres.exe`
-说明资源文件无法编译进程序。
+资源文件无法编译，图标和菜单资源可能缺失。请检查 MinGW 安装是否完整。
-结果通常是：
+### `Tetris.exe: Permission denied`
- 主体代码可能还能编译
+说明程序正在运行，构建时无法覆盖旧 exe。
 - 但图标、菜单等资源会出问题
 ### 3）提示 `Tetris.exe: Permission denied`
 通常是因为游戏程序还在运行，导致链接器无法覆盖旧的 `exe`。
 处理方式：
- 先关闭正在运行的游戏窗口
+1. 关闭游戏窗口
- 再重新执行构建
+2. 重新构建
-### 4）按 `F5` 无法调试
+### 鼠标点击、按钮或界面不是最新版
-一般是因为：
+通常是因为构建失败后仍在运行旧 exe。请确认构建命令成功完成。
- 没安装 `gdb.exe`
+## 9. 推荐运行流程
 - 打开的不是项目根目录
 - VS Code 没有加载 `.vscode` 配置
-## 8. 资源说明
+1. 打开项目根目录
-
+2. 关闭旧的游戏窗口
-项目运行依赖以下资源目录：
+3. 执行构建
-
+4. 运行 `.vscode-build\mingw\Tetris.exe`
- `assets/icons/`
+5. 如果要调试，按 `F5`
 - `assets/images/`
 - `assets/audio/`
 - `assets/video/`
 如果只是拷贝 `exe` 而不带资源目录，部分功能会缺失，例如：
 - 背景图
 - 背景音乐
 - 复活视频
 ## 9. 适用场景
 如果你主要在本机开发、调试和演示，VS Code 是本项目最推荐的运行方式。当前任务配置、构建脚本和资源处理流程都已经围绕 VS Code 配好。