# 俄罗斯方块游戏 - PHP 编译器示例

这是一个使用 PHP 编写主要逻辑、C++ 提供底层图形 API 的俄罗斯方块游戏示例。

## 项目结构

```
tetris/
├── main.php              # PHP 主程序（游戏逻辑）
├── project.yml           # 项目配置文件
├── php-src/
│   └── tetris.stub.php  # C++ 函数的 PHP 声明（stub）
└── cpp-src/
    └── tetris.cc        # C++ 实现（图形 API 和游戏状态管理）
```

## 设计架构

### C++ 层 (cpp-src/tetris.cc)
- **TetrisBox 类**：继承自 `Box`，封装游戏状态
  - 游戏面板数据（10x20）
  - 当前方块信息（形状、位置、类型）
  - 分数和游戏状态
  - 方块移动、旋转、消除等核心算法
  
- **Windows API 封装**：
  - 窗口创建和管理
  - 图形渲染（绘制方块、网格）
  - 键盘输入处理
  - UTF-8 中文支持

### PHP 层 (main.php)
- **TetrisGame 类**：游戏主控制类
  - 游戏循环管理
  - 消息处理（键盘输入、窗口事件）
  - 自动下落逻辑
  - 速度递增机制
  - 游戏结束处理

### Stub 层 (php-src/tetris.stub.php)
- 声明所有 C++ 函数供 PHP 调用
- 定义函数签名和返回类型

## 编译和运行

### 编译
```bash
cd examples/tetris
php ../../bin/compiler.php build
```

或在项目根目录：
```bash
php bin/compiler.php build examples/tetris
```

### 运行
编译后生成的可执行文件位于 `build/tetris.exe`，双击运行即可。

## 游戏控制

- **← →** ：左右移动方块
- **↑** ：旋转方块
- **↓** ：加速下落
- **空格** ：直接落下（硬降）

## 游戏规则

1. 不同形状的方块从顶部随机出现
2. 玩家可以移动和旋转方块
3. 当一行被完全填满时，该行消除并得分
4. 一次消除多行有额外奖励分数
5. 随着分数增加，方块下落速度会逐渐加快
6. 当方块堆叠到顶部无法放置新方块时，游戏结束

## 技术要点

### Box 对象传递
C++ 的 `TetrisBox` 类继承自 `Box`，通过 `{new TetrisBox()}` 返回给 PHP 层，PHP 使用 `mixed` 类型接收和操作这个对象指针。

### 函数命名规范
所有 C++ 函数必须以 `php_` 前缀命名，这样编译器才能识别并在 PHP 层调用。

### Windows GUI 编程
- 使用 Win32 API 创建窗口和处理消息循环
- GDI 绘图 API 进行图形渲染
- 支持 UTF-8 编码的中文显示

### 性能优化
- C++ 层处理所有计算密集型操作（碰撞检测、消除判断等）
- PHP 层负责高层逻辑和流程控制
- 使用 PeekMessage 实现非阻塞消息处理

## 扩展建议

可以进一步改进的方向：
1. 添加下一个方块预览
2. 添加暂停功能
3. 添加音效
4. 保存最高分记录
5. 添加幽灵方块（显示落点）
6. 支持自定义难度级别

## 参考示例

本项目参考了以下示例：
- `examples/win32-hello`：Windows GUI 编程基础
- `examples/prime`：Box 对象封装和传递