# Tereis Tereis 是一个基于 C++、Win32 API、GDI/GDI+ 实现的桌面版俄罗斯方块课程大作业。 项目在经典俄罗斯方块玩法上扩展了 Rogue 模式，加入等级成长、强化选择、主动技能、特殊方块、视频复活、鼠标交互和视觉特效。程序不依赖游戏引擎，主要使用 Win32 消息循环和 GDI 绘图完成。 ## 快速运行 推荐在 Windows + PowerShell + MinGW-w64 环境下运行。 1. 确认 `g++.exe` 和 `windres.exe` 已加入 `PATH`，或安装在 `C:\mingw64\bin\`。 2. 在项目根目录执行构建并运行： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run ``` 3. 如只需构建，不启动程序： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 ``` 构建产物位于： ```text .vscode-build\mingw\Tetris.exe ``` 运行时请从项目根目录启动程序，确保 `assets/` 目录可被读取，否则背景图、音乐和复活视频可能无法加载。 ## 功能概览 ### 经典模式 - 标准俄罗斯方块规则 - 方块生成、移动、旋转、软降、硬降 - 方块落地固定、消行、计分和死亡判定 - 预测落点显示 - 暂停、重开、返回主菜单 ### Rogue 模式 Rogue 模式是本项目的主要扩展玩法。 - 消行获得分数和 EXP - EXP 满后进入强化选择界面 - 支持普通三选一强化 - 支持双重抉择，同屏选择两个强化 - 支持命运轮盘，同屏展示六个强化并选择两个 - 随时间提升危险等级，底部封锁区会压缩可用空间 - 支持多种强化联动和构筑方向 ### 强化与技能 项目中包含多类强化效果： - 基础成长：得分倍率、EXP 倍率、预览数量、下落速度调整 - 生存强化：最后一搏、时间缓流、稳定结构 - 主动技能：备用仓、清屏炸弹、黑洞奇点、空中换形 - 特殊方块：爆破核心、棱镜激光、十字方块、彩虹方块 - 进阶联动：连锁火花、连环炸弹、雷霆四消、雷霆棱镜 - 风险收益：高压悬赏、豪赌四消、极限玩家、赌徒契约 - 升级联动：双重抉择、命运轮盘、升级冲击波、进化冲击 具体效果可在游戏主菜单的 `帮助 -> 强化图鉴` 中查看。 ### 鼠标交互 除键盘操作外，项目也支持鼠标点击： - 主菜单项目可点击 - 帮助页项目可点击 - 升级卡片可点击选择 - 多选强化可点击标记 - 暂停和结算界面按钮可点击 - 非主菜单界面左上角有返回按钮，可点击回到主菜单 - 右下角音乐按钮可点击开关背景音乐 ### 视听与资源 - 自定义图标 - 背景图片 - 背景音乐 - 消行和技能清除特效 - 死亡后可播放本地视频复活一次 ## 操作说明 ### 通用键盘操作 | 按键 | 功能 | | --- | --- | | `← / A` | 左移 | | `→ / D` | 右移 | | `↑ / W` | 旋转 | | `↓ / S` | 软降 | | `Space` | 硬降 | | `P` | 暂停 / 继续 | | `R` | 重开当前对局 | | `M` | 返回主菜单 | ### Rogue 模式额外按键 | 按键 | 功能 | | --- | --- | | `C / Shift` | 备用仓 | | `Z` | 黑洞奇点 | | `X` | 清屏炸弹 | | `V` | 空中换形 | | 死亡后 `V` | 看视频复活一次 | ### 升级选择 - 普通升级：方向键 / WASD 切换，Enter 或 Space 确认 - 双重抉择 / 命运轮盘：Space 标记，Enter 确认已选强化 - 鼠标操作：直接点击升级卡片即可选择或标记 ## 运行说明 ### 方式一：PowerShell 一键运行 在项目根目录打开 PowerShell，执行： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run ``` 该命令会先编译项目，编译成功后自动启动游戏窗口。 ### 方式二：先构建再运行 先在项目根目录执行构建： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 ``` 构建成功后运行生成的程序： ```powershell .\.vscode-build\mingw\Tetris.exe ``` ### 方式三：VS Code 运行和调试 项目已经配置好 VS Code 任务： - 按 `Ctrl + Shift + B` 执行默认构建任务 `build Tetris MinGW` - 在任务列表中运行 `run Tetris MinGW` 可构建并启动游戏 - 在“运行和调试”中选择 `Debug Tetris MinGW` 可启动调试 调试需要系统能找到 `gdb.exe`。如果无法调试，请确认 MinGW 的 `bin` 目录已经加入 `PATH`。 ### 方式四：Visual Studio 中运行 本项目没有提供 Visual Studio 的 `.sln` 或 `.vcxproj` 工程文件，推荐在 Visual Studio 中打开项目文件夹，然后通过终端调用已有构建脚本运行。 操作步骤： 1. 打开 Visual Studio。 2. 选择 `文件 -> 打开 -> 文件夹`，打开项目根目录 `Tereis`。 3. 打开 Visual Studio 内置终端，或在项目根目录单独打开 PowerShell。 4. 确认 MinGW-w64 已安装，并且 `g++.exe`、`windres.exe` 可以被系统找到。 5. 在终端中执行： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run ``` 如果只想编译，不立即运行： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 ``` 编译成功后，程序位置为： ```text .vscode-build\mingw\Tetris.exe ``` 也可以在 Visual Studio 的终端中运行： ```powershell .\.vscode-build\mingw\Tetris.exe ``` 注意：不要直接把 `src` 目录中的单个 `.cpp` 文件当作独立程序运行。本项目由多个源文件、资源文件和 `assets/` 资源目录共同组成，必须通过项目根目录下的 `build-mingw.ps1` 构建。 ### 运行注意事项 - 推荐始终从项目根目录启动程序。 - 不建议直接双击 `.vscode-build\mingw\Tetris.exe`，因为工作目录可能不正确，导致 `assets/` 资源加载失败。 - 如果重新构建时提示 `Tetris.exe: Permission denied`，请先关闭正在运行的游戏窗口。 - 程序使用 Win32 桌面窗口运行，不会显示控制台窗口。 ## 项目结构 ```text Tereis/ ├─ src/ │ ├─ include/ 头文件 │ ├─ source/ 源文件 │ │ ├─ Tetris.cpp 程序入口、窗口和消息框架 │ │ ├─ TetrisLogic.cpp 基础俄罗斯方块逻辑框架 │ │ ├─ TetrisRender.cpp 基础绘制框架 │ │ ├─ common/ 资源路径、文件检查等通用工具 │ │ ├─ app/ 媒体播放、布局命中、输入和定时器处理 │ │ ├─ extensions/ 框架外通用扩展、界面状态和视觉效果 │ │ ├─ logic/ 特殊方块落地效果等逻辑扩展 │ │ ├─ render/ 图片加载等渲染内部支持 │ │ └─ rogue/ Rogue 模式、强化和技能系统 │ └─ resources/ Windows 资源脚本 ├─ assets/ │ ├─ audio/ 背景音乐 │ ├─ icons/ 程序图标 │ ├─ images/ 背景图片 │ └─ video/ 复活视频 ├─ report/ 报告相关材料 ├─ .vscode/ VS Code 配置 ├─ .vscode-build/ 本地构建输出目录 ├─ build-mingw.ps1 MinGW 构建脚本 ├─ README.md 项目说明 └─ AGENTS.md 项目协作和代码生成约束 ``` ## 构建环境 推荐环境： - Windows - PowerShell - MinGW-w64 - `g++.exe` - `windres.exe` - 如需调试：`gdb.exe` 构建脚本会优先使用系统 `PATH` 中的 MinGW。如果没有加入 `PATH`，脚本也会尝试使用： ```text C:\mingw64\bin\ ``` 构建脚本会递归收集 `src/source` 下的 `.cpp` 文件。新增功能代码可以放入功能目录，不需要手动维护固定源码列表。 ## 构建与运行 在项目根目录执行： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 ``` 构建成功后生成： ```text .vscode-build\mingw\Tetris.exe ``` 构建后直接运行： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run ``` 也可以直接运行已生成的程序： ```powershell .\.vscode-build\mingw\Tetris.exe ``` 如果使用 VS Code： - `Ctrl + Shift + B` 执行默认构建任务 `build Tetris MinGW` - 运行任务 `run Tetris MinGW` 可构建并启动游戏 - 调试配置 `Debug Tetris MinGW` 会先构建，再使用 `gdb.exe` 启动调试 注意：直接双击 `.vscode-build\mingw\Tetris.exe` 时，当前工作目录可能不是项目根目录，资源文件可能无法正常读取。推荐从项目根目录通过脚本或 VS Code 任务启动。 ## 常见问题 ### 1. 提示 `Tetris.exe: Permission denied` 说明游戏程序仍在运行，链接器无法覆盖旧文件。 处理方式： - 关闭正在运行的游戏窗口 - 重新执行构建命令 ### 2. 没有背景图、音乐或视频 请确认运行时保留了 `assets/` 目录。项目会从资源目录读取背景、音乐和复活视频。 ### 3. 视频复活播放失败 项目会优先查找： - `assets/video/video.avi` - `assets/video/video.mp4` 如果系统不支持对应格式，可能会播放失败。建议保留项目中已提供的视频文件。 ### 4. 鼠标点击不生效 请确认运行的是最新构建结果。若构建时 `Tetris.exe` 被占用，实际运行的可能仍是旧版本。 ## 课程展示建议 建议按以下顺序展示： 1. 主菜单、帮助页和鼠标点击 2. 经典模式基础玩法 3. Rogue 模式升级选择 4. 双重抉择或命运轮盘的多选界面 5. 主动技能：黑洞、炸弹、换形、备用仓 6. 特殊方块和消除特效 7. 死亡后视频复活 ## 实现说明 本项目以过程式 C++ 写法为主，核心逻辑分布如下： - `src/source/Tetris.cpp`：Win32 程序入口、窗口创建和消息分发主干 - `src/source/TetrisLogic.cpp`：基础方块逻辑、消行和状态重置 - `src/source/TetrisRender.cpp`：界面绘制、面板、动画和特效 - `src/source/common/TetrisAssets.cpp`：资源路径拼接和文件存在判断 - `src/source/app/`：背景音乐、复活视频、窗口布局命中、鼠标键盘和定时器处理 - `src/source/logic/TetrisPieceEffects.cpp`：彩虹、爆破、激光、十字和稳定结构等落地效果 - `src/source/extensions/TetrisGameExtensions.cpp`：框架外通用状态切换、复活、说明页、视觉效果等扩展支持 - `src/source/render/TetrisRenderAssets.cpp`：背景图、致谢页图片等 GDI+ 图片资源加载 - `src/source/rogue/TetrisRogue.cpp`：Rogue 模式、强化、技能和成长系统 - `src/include/Tetris.h`：主要结构体、全局状态和函数声明 - `src/include/TetrisAppInternal.h`、`src/include/TetrisRenderInternal.h`、`src/include/TetrisAssets.h`：窗口层、渲染层和资源工具的内部声明 项目适合作为程序设计课程大作业展示，也便于在答辩时讲解窗口程序、游戏循环、碰撞检测、状态管理和功能扩展。 ## 开源协议与素材说明 本项目为程序设计课程大作业，仅供课程学习、课堂展示和个人技术交流使用，不用于商业发布。 - 源代码、构建脚本和原创文档内容采用 MIT License，详见 `LICENSE`。 - `assets/`、`report/images/` 和 `report/code-snippets/` 中的音频、图片、视频等非代码素材不包含在 MIT License 授权范围内。 - 音乐素材来自《千恋*万花》，仅作为课程大作业学习展示使用，版权归原权利方所有。 - 图片素材主要由 AI 生成或用于课程报告展示。 - 如需二次发布、公开分发可执行文件或用于课程以外场景，请先替换或移除未取得独立授权的素材。 更完整的素材来源和授权限制说明见 `NOTICE.md`。