|
|
# 俄罗斯方块游戏 - 快速开始
|
|
|
|
|
|
## 🎮 项目简介
|
|
|
|
|
|
这是一个使用 PHP 和 C++ 混合编程实现的俄罗斯方块游戏示例，展示了：
|
|
|
- PHP 编写高层游戏逻辑
|
|
|
- C++ 提供底层图形 API 和游戏状态管理
|
|
|
- 通过 Box 机制在 PHP 和 C++ 之间传递对象
|
|
|
|
|
|
## 📦 编译步骤
|
|
|
|
|
|
### 前置条件
|
|
|
- PHP 8.4+（路径：`D:\workspace\php-8.4.20\php.exe`）
|
|
|
- MSVC 编译器
|
|
|
- Windows 10/11 操作系统
|
|
|
|
|
|
### 编译命令
|
|
|
|
|
|
在项目根目录执行：
|
|
|
|
|
|
```bash
|
|
|
D:\workspace\php-8.4.20\php.exe bin\compiler.php examples/tetris
|
|
|
```
|
|
|
|
|
|
编译成功后会生成 `tetris.exe` 文件。
|
|
|
|
|
|
## 🚀 运行游戏
|
|
|
|
|
|
双击运行 `tetris.exe` 或在命令行中执行：
|
|
|
|
|
|
```bash
|
|
|
.\tetris.exe
|
|
|
```
|
|
|
|
|
|
## 🎯 游戏控制
|
|
|
|
|
|
| 按键 | 功能 |
|
|
|
|------|------|
|
|
|
| ← (左箭头) | 向左移动方块 |
|
|
|
| → (右箭头) | 向右移动方块 |
|
|
|
| ↑ (上箭头) | 旋转方块 |
|
|
|
| ↓ (下箭头) | 加速下落 |
|
|
|
| 空格键 | 直接落下（硬降） |
|
|
|
|
|
|
## 📋 游戏规则
|
|
|
|
|
|
1. **基本玩法**
|
|
|
- 不同形状的方块从顶部随机出现
|
|
|
- 玩家可以移动和旋转方块
|
|
|
- 方块落地后固定，新方块继续出现
|
|
|
|
|
|
2. **消除规则**
|
|
|
- 当一行被完全填满时，该行消除
|
|
|
- 一次消除多行有额外奖励分数
|
|
|
|
|
|
3. **计分系统**
|
|
|
- 消除 1 行：100 分
|
|
|
- 消除 2 行：400 分（2×2×100）
|
|
|
- 消除 3 行：900 分（3×3×100）
|
|
|
- 消除 4 行：1600 分（4×4×100）
|
|
|
|
|
|
4. **难度递增**
|
|
|
- 初始下落间隔：500 毫秒
|
|
|
- 每获得 500 分，速度提升一级
|
|
|
- 最快下落间隔：100 毫秒
|
|
|
|
|
|
5. **游戏结束**
|
|
|
- 当新方块无法放置时，游戏结束
|
|
|
- 显示最终得分
|
|
|
- 可以选择重新开始或退出
|
|
|
|
|
|
## 🏗️ 技术架构
|
|
|
|
|
|
### 三层架构
|
|
|
|
|
|
#### 1. C++ 层 (`cpp-src/tetris.cc`)
|
|
|
- **TetrisBox 类**：继承自 `Box`，封装游戏状态
|
|
|
- 游戏面板数据（10x20）
|
|
|
- 当前方块信息（形状、位置、类型）
|
|
|
- 分数和游戏状态
|
|
|
- 方块移动、旋转、消除等核心算法
|
|
|
|
|
|
- **Windows API 封装**：
|
|
|
- 窗口创建和管理
|
|
|
- GDI 图形渲染（绘制方块、网格）
|
|
|
- 键盘输入处理
|
|
|
- UTF-8 中文支持
|
|
|
|
|
|
#### 2. Stub 层 (`php-src/tetris.stub.php`)
|
|
|
- 声明所有 C++ 函数供 PHP 调用
|
|
|
- 定义函数签名和返回类型
|
|
|
- 使用 `mixed` 类型表示 Box 对象
|
|
|
|
|
|
#### 3. PHP 层 (`main.php`)
|
|
|
- **TetrisGame 类**：游戏主控制器
|
|
|
- 游戏循环管理
|
|
|
- 消息处理（键盘输入、窗口事件）
|
|
|
- 自动下落逻辑
|
|
|
- 速度递增机制
|
|
|
- 游戏结束处理
|
|
|
|
|
|
## 🔑 关键技术点
|
|
|
|
|
|
### Box 对象传递
|
|
|
|
|
|
C++ 的 `TetrisBox` 类继承自 `Box`，通过 `{new TetrisBox()}` 返回给 PHP 层，PHP 使用 `mixed` 类型接收和操作这个对象指针。
|
|
|
|
|
|
```cpp
|
|
|
// C++ 实现
|
|
|
var php_tetris_new() {
|
|
|
return {new TetrisBox()};
|
|
|
}
|
|
|
|
|
|
void php_tetris_move_down(Variant box) {
|
|
|
auto tetris = box.toBox<TetrisBox>();
|
|
|
// 操作游戏状态
|
|
|
}
|
|
|
```
|
|
|
|
|
|
```php
|
|
|
// PHP 调用
|
|
|
$game = tetris_new(); // 接收 mixed 类型
|
|
|
tetris_move_down($game); // 传递给 C++ 函数
|
|
|
```
|
|
|
|
|
|
### 函数命名规范
|
|
|
|
|
|
所有 C++ 函数必须以 `php_` 前缀命名，这样编译器才能识别并在 PHP 层调用。
|
|
|
|
|
|
### Windows GUI 编程
|
|
|
|
|
|
- 使用 Win32 API 创建窗口和处理消息循环
|
|
|
- GDI 绘图 API 进行图形渲染
|
|
|
- 支持 UTF-8 编码的中文显示（通过 `MultiByteToWideChar` 转换）
|
|
|
|
|
|
### 性能优化
|
|
|
|
|
|
- C++ 层处理所有计算密集型操作（碰撞检测、消除判断等）
|
|
|
- PHP 层负责高层逻辑和流程控制
|
|
|
- 使用 PeekMessage 实现非阻塞消息处理
|
|
|
- 帧率控制在约 60 FPS
|
|
|
|
|
|
## 📁 项目结构
|
|
|
|
|
|
```
|
|
|
tetris/
|
|
|
├── main.php # PHP 主程序（游戏逻辑）
|
|
|
├── project.yml # 项目配置文件
|
|
|
├── README.md # 项目说明
|
|
|
├── QUICKSTART.md # 本快速开始指南
|
|
|
├── php-src/
|
|
|
│ └── tetris.stub.php # C++ 函数的 PHP 声明（stub）
|
|
|
└── cpp-src/
|
|
|
└── tetris.cc # C++ 实现（图形 API 和游戏状态管理）
|
|
|
```
|
|
|
|
|
|
## 🔧 扩展开发
|
|
|
|
|
|
可以进一步改进的方向：
|
|
|
1. ✅ 添加完整的方块旋转逻辑
|
|
|
2. ✅ 实现真实的方块碰撞检测
|
|
|
3. ✅ 添加下一个方块预览
|
|
|
4. ✅ 添加暂停功能
|
|
|
5. ✅ 添加音效
|
|
|
6. ✅ 保存最高分记录
|
|
|
7. ✅ 添加幽灵方块（显示落点）
|
|
|
8. ✅ 支持自定义难度级别
|
|
|
|
|
|
## 📚 参考示例
|
|
|
|
|
|
本项目参考了以下示例：
|
|
|
- `examples/win32-hello`：Windows GUI 编程基础
|
|
|
- `examples/prime`：Box 对象封装和传递
|
|
|
|
|
|
## ⚠️ 注意事项
|
|
|
|
|
|
1. **类型匹配**：Stub 文件中使用 `mixed` 类型对应 C++ 的 `var`/`Variant` 类型
|
|
|
2. **编码问题**：C++ 源文件必须使用 UTF-8 编码以支持中文
|
|
|
3. **链接库**：需要链接 `user32.lib`、`gdi32.lib`、`kernel32.lib` 等 Windows 系统库
|
|
|
4. **Box 资源管理**：Box 对象由 C++ 管理内存，PHP 层只需持有引用
|
|
|
|
|
|
## 🎓 学习价值
|
|
|
|
|
|
这个项目适合学习：
|
|
|
- PHP 和 C++ 混合编程架构
|
|
|
- Box 对象传递机制
|
|
|
- Windows GUI 编程基础
|
|
|
- 游戏开发基本概念
|
|
|
- 跨语言类型映射
|
|
|
|
|
|
---
|
|
|
|
|
|
**祝游戏愉快！** 🎮✨
|
|
|
|
