TypePHP 编译器 https://swoole.com/aot/

5.0 KiB

Raw Blame History Unescape Escape

俄罗斯方块游戏 - 快速开始

🎮 项目简介

这是一个使用 PHP 和 C++ 混合编程实现的俄罗斯方块游戏示例，展示了：

PHP 编写高层游戏逻辑
C++ 提供底层图形 API 和游戏状态管理
通过 Box 机制在 PHP 和 C++ 之间传递对象

📦 编译步骤

前置条件

PHP 8.4+（路径：D:\workspace\php-8.4.20\php.exe）
MSVC 编译器
Windows 10/11 操作系统

编译命令

在项目根目录执行：

D:\workspace\php-8.4.20\php.exe bin\compiler.php examples/tetris

编译成功后会生成 tetris.exe 文件。

🚀 运行游戏

双击运行 tetris.exe 或在命令行中执行：

.\tetris.exe

🎯 游戏控制

按键	功能
← (左箭头)	向左移动方块
→ (右箭头)	向右移动方块
↑ (上箭头)	旋转方块
↓ (下箭头)	加速下落
空格键	直接落下（硬降）

📋 游戏规则

基本玩法
- 不同形状的方块从顶部随机出现
- 玩家可以移动和旋转方块
- 方块落地后固定，新方块继续出现
消除规则
- 当一行被完全填满时，该行消除
- 一次消除多行有额外奖励分数
计分系统
- 消除 1 行：100 分
- 消除 2 行：400 分（2×2×100）
- 消除 3 行：900 分（3×3×100）
- 消除 4 行：1600 分（4×4×100）
难度递增
- 初始下落间隔：500 毫秒
- 每获得 500 分，速度提升一级
- 最快下落间隔：100 毫秒
游戏结束
- 当新方块无法放置时，游戏结束
- 显示最终得分
- 可以选择重新开始或退出

🏗️ 技术架构

三层架构

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 类型接收和操作这个对象指针。

// C++ 实现
var php_tetris_new() {
    return {new TetrisBox()};
}

void php_tetris_move_down(Variant box) {
    auto tetris = box.toBox<TetrisBox>();
    // 操作游戏状态
}

// 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 和游戏状态管理）

🔧 扩展开发

可以进一步改进的方向：

✅ 添加完整的方块旋转逻辑
✅ 实现真实的方块碰撞检测
✅ 添加下一个方块预览
✅ 添加暂停功能
✅ 添加音效
✅ 保存最高分记录
✅ 添加幽灵方块（显示落点）
✅ 支持自定义难度级别

📚 参考示例

本项目参考了以下示例：

examples/win32-hello：Windows GUI 编程基础
examples/prime：Box 对象封装和传递

⚠️ 注意事项

类型匹配：Stub 文件中使用 mixed 类型对应 C++ 的 var/Variant 类型
编码问题：C++ 源文件必须使用 UTF-8 编码以支持中文
链接库：需要链接 user32.lib、gdi32.lib、kernel32.lib 等 Windows 系统库
Box 资源管理：Box 对象由 C++ 管理内存，PHP 层只需持有引用

🎓 学习价值

这个项目适合学习：

PHP 和 C++ 混合编程架构
Box 对象传递机制
Windows GUI 编程基础
游戏开发基本概念
跨语言类型映射

祝游戏愉快！ 🎮✨

5.0 KiB Raw Blame History Unescape Escape