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 -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run

3. 如只需构建，不启动程序：

powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1

构建产物位于：

.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 -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run

该命令会先编译项目，编译成功后自动启动游戏窗口。

方式二：先构建再运行

先在项目根目录执行构建：

powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1

构建成功后运行生成的程序：

.\.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 -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run

如果只想编译，不立即运行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1

编译成功后，程序位置为：

.vscode-build\mingw\Tetris.exe

也可以在 Visual Studio 的终端中运行：

.\.vscode-build\mingw\Tetris.exe

注意：不要直接把 src 目录中的单个 .cpp 文件当作独立程序运行。本项目由多个源文件、资源文件和 assets/ 资源目录共同组成，必须通过项目根目录下的 build-mingw.ps1 构建。

运行注意事项

• 推荐始终从项目根目录启动程序。
• 不建议直接双击 .vscode-build\mingw\Tetris.exe，因为工作目录可能不正确，导致 assets/ 资源加载失败。
• 如果重新构建时提示 Tetris.exe: Permission denied，请先关闭正在运行的游戏窗口。
• 程序使用 Win32 桌面窗口运行，不会显示控制台窗口。

项目结构

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，脚本也会尝试使用：

C:\mingw64\bin\

构建脚本会递归收集 src/source 下的 .cpp 文件。新增功能代码可以放入功能目录，不需要手动维护固定源码列表。

构建与运行

在项目根目录执行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1

构建成功后生成：

.vscode-build\mingw\Tetris.exe

构建后直接运行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run

也可以直接运行已生成的程序：

.\.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。