# b2d **Repository Path**: haart/b2d ## Basic Information - **Project Name**: b2d - **Description**: 使用C++编写的2D游戏引擎 - **Primary Language**: C++ - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-19 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # B2D C++ B2D 1.0 是使用 C++17 实现的 2D 像素游戏引擎,通过 [b2d.h](include/b2d.h) 提供 C 接口;公开头文件仍支持 C99/C++14。 Demo1、推箱子 Demo2、星际射击 Demo3、打砖块 Demo4 和扫雷 Demo5 使用过程式 C99:初始化、运行一个节拍主循环,最后关闭引擎。 `B2D_API_VERSION` 为 1。 另提供 [Python 扫雷与原生二进制模块](demos/python/README.md),通过 `b2d.pyd` 调用现有引擎 DLL。 引擎提供 640×480 索引色画面、四层背景、精灵与动画、持续动作与可选连发的触发输入、游戏计时、矩形碰撞、 MML 与 WAV/MP3 播放、ZIP/目录资源包和存档。Windows 后端可运行游戏;Linux 的 POSIX 后端目前为占位实现。 ## Demo 截图 以下为 640×480 原始游戏画面,PNG 文件位于 [screenshot/](screenshot/),操作说明见 [Demo 玩法](demos/gameplay.md)。 ### Demo1:背景绘制与移动 ![Demo1:背景图案与移动标记](screenshot/demo1.png) ### Demo2:推箱子 | 开始页面 | 选关页面 | 第 20 关 | | --- | --- | --- | | ![Demo2 开始页面](screenshot/demo2_title.png) | ![Demo2 选关页面](screenshot/demo2_selection.png) | ![Demo2 第 20 关](screenshot/demo2_level_20.png) | ### Demo3:星际射击 | 机炮射击 | 敌机俯冲 | | --- | --- | | ![Demo3 机炮射击](screenshot/demo3_shooting.png) | ![Demo3 敌机俯冲](screenshot/demo3_diving.png) | ### Demo4:打砖块 | 开始页面 | 选关页面 | | --- | --- | | ![Demo4 开始页面](screenshot/demo4_title.png) | ![Demo4 选关页面](screenshot/demo4_selection.png) | | 游戏画面 | 多球与宝物 | | --- | --- | | ![Demo4 游戏画面](screenshot/demo4_gameplay.png) | ![Demo4 多球与宝物](screenshot/demo4_powers.png) | ### Demo5:扫雷 | 开始页面 | 标准难度 | 专家难度 | | --- | --- | --- | | ![Demo5 开始页面](screenshot/demo5_title.png) | ![Demo5 标准难度](screenshot/demo5_gameplay.png) | ![Demo5 专家难度](screenshot/demo5_expert.png) | ## 编译 Windows 目标工具链为 **32 位 MinGW-w64 GCC 8.1.0,POSIX threads + DWARF**,最低要求 **CMake 3.31**。 需要与目标架构匹配的 zlib 头文件和静态库;呈现要求为 OpenGL 3.3 Core、最大纹理尺寸至少 640。 配置项目还需要匹配工具链的 Qt 5.12 或更新的 Qt 5 Widgets,用于资源编辑器 `b2deditor` 和存档工具 `b2dsave`。 当前开发和发布使用 Qt 5.15.2。 Qt 不在默认搜索位置时,给配置命令添加 `-DCMAKE_PREFIX_PATH=Qt安装目录`;引擎和 Demo 不链接 Qt。 开发环境应已能直接运行 `cmake`、`gcc`、`g++` 和 `mingw32-make`。 支持目标为 **Windows 7 或更新系统 + OpenGL 3.3**。 构建定义 `_WIN32_WINNT=0x0601`,运行时检测 OpenGL 3.3 Core; 索引底色与 GPU 调色板查表的使用约定见[使用指南](docs/usage.md#内置调色板)。 合成音频使用 waveOut;Win7 的最终运行库、驱动和媒体组件仍须实际验证。 CPU 按七层顺序更新索引帧,以 16×16 屏幕脏格缩小局部合成范围;大面积或碎片变化改为整帧合成。 GPU 通过着色器查询调色板,最近邻放大。 合成、纹理上传和截图共用一张 300 KiB 索引画面,以锁保护读写;绘制和交换缓冲不占用画面锁。 截图可保存为含调色板的 8 位 BMP,或复制到 Windows 剪贴板,无需先展开为 RGB。 呈现落后时保留最新画面,不维护快照队列或逐帧复制索引。 640×480 的 R8UI 索引纹理与 256×1 的 RGB8 调色板纹理分别按内容变化上传,名义容量合计约 301 KiB。 纹理不随窗口倍率增大,实际显存占用还取决于驱动对齐与分配。 2× 窗口的 1280×960 前后缓冲若各按 32 位分配,合计约 9.375 MiB,另有纹理及驱动开销; 这是窗口尺寸、所选像素格式和驱动分配共同决定的,不能把纹理放大参数当成免除帧缓冲的方式。 在项目根目录运行: ```powershell .\configure.cmd mingw32-make -C build -j4 .\build\demo1.exe .\build\demo2.exe .\build\demo3.exe .\build\demo4.exe .\build\demo5.exe ``` `configure.cmd` 只生成 MinGW Makefiles,默认 **Debug + 动态链接**;附加参数原样传给 CMake。 zlib 自动查找包含当前 MinGW 的搜索目录,不会下载依赖。自定义安装位置可传 `-DZLIB_ROOT=目录`, 或分别指定 `-DZLIB_INCLUDE_DIR=目录 -DZLIB_LIBRARY=静态库路径`。 构建不会运行测试,`add_test` 只注册命令。修改后按影响范围选择测试,见 [测试指南](TESTING.md); 不要每次构建都运行全量冒烟。 ### 构建目标 不指定目标等同于 `all`,也可单独构建下列目标及其依赖: | 目标 | 内容 | | --- | --- | | `all` | 引擎、工具、Demo、当前平台的测试程序及手册示例编译、链接检查 | | `sdk` | 引擎、三个工具和通用资源包,不包含 Demo 或测试程序 | | `b2d` | 单独的引擎库 | | `dll` | 引擎 DLL 与导入库,仅 Windows 动态构建提供 | | `b2dpack` / `b2dsave` | 资源配置编译工具 / 存档工具 | | `b2deditor` | 资源编辑器 | | `demo1` / `demo2` / `demo3` / `demo4` / `demo5` | 指定 Demo 及其依赖 | | `b2d_manual_examples` | 严格 C99 编译并链接全部手册示例和素材生成器,不运行 | 例如 `mingw32-make -C build sdk -j4`。 Windows 的 `sdk`、`demo2`、`demo3`、`demo4`、`demo5` 和内嵌资源测试目标会按依赖生成所需 ZIP;输入不变时不重复打包。 生成的 `*-resources.zip` 不提交到 Git,源素材、资源配置和授权保留在仓库中,见 [通用资源](asset/README.md)。 ### 资源工具 桌面资源工具 `b2deditor` 提供资源包属性、图集与图组编辑、瓦片编号浏览、动画及配色预览、音频试听、 四层地图编辑(各维最大 1024 格)、256 色调色板文件编辑及 ZIP 导出。 GUI 编译和 ZIP 导出调用同目录的 `b2dpack`;命令行及 CMake 使用相同入口。 调色板和瓦片查表图在编辑器中导出。 打开配置即可预览,编辑后自动刷新;缺失素材分项提示,导出时完整校验。 三个工具统一由根目录配置,均属于 `all` / `sdk`;可执行文件统一输出到当前构建根目录 (如 `build/` 或 `build_static/`),共用 Qt DLL 和平台插件。工具源码仍按职责分目录, 引擎和游戏不链接 Qt。 构建与操作步骤见 [资源工具](docs/resource-editor.md)。 ### 工具截图 资源工具可直接浏览和编辑素材;存档查看器可按类型查看和修改存档值。 详细操作与更多截图见 [资源工具](docs/resource-editor.md#界面示例)和[存档查看器](docs/save-viewer.md#界面示例)。 | 资源工具:瓦片浏览 | 存档查看器:章节与键值 | | --- | --- | | ![资源工具瓦片浏览](screenshot/b2deditor_tiles.png) | ![存档查看器](screenshot/b2dsave.png) | ### Debug / Release 与链接模式 | 配置 | 配置命令 | | --- | --- | | Debug + 动态(默认) | `.\configure.cmd` | | Release + 动态 | `.\configure.cmd -DCMAKE_BUILD_TYPE=Release` | | Debug + 静态 | `.\configure.cmd -B build_static -DB2D_STATIC_BUILD=ON` | | Release + 静态 | `.\configure.cmd -B build_static -DCMAKE_BUILD_TYPE=Release -DB2D_STATIC_BUILD=ON` | 动态构建使用 `mingw32-make -C build`,静态构建使用 `mingw32-make -C build_static`。 每次调用配置脚本都提供 Debug、动态链接默认值,需要其它组合时显式覆盖。 直接运行 CMake 时应自行指定 `-DCMAKE_BUILD_TYPE=Debug` 或 `Release`。 动态模式生成 `b2d.dll` 和 `libb2d.dll.a`,程序还需同一工具链的 `libgcc_s_dw2-1.dll`、`libstdc++-6.dll`、`libwinpthread-1.dll`(按实际依赖分发)。 静态模式生成 `libb2d.a`,引擎和 GCC 运行库链接进 EXE。 Demo2~Demo5 在两种模式下都内嵌资源;**静态 Demo2~Demo5 各可仅分发一个 EXE**,Windows 系统及 OpenGL DLL 仍然必需。 Windows Release Demo 使用 GUI 子系统,启动时不创建控制台;Debug Demo 保留控制台。 `b2dpack` 为控制台工具。`b2dsave` 无参数打开独立存档查看器,不创建控制台; `verify` / `info` 连接已有控制台或使用重定向,输出和退出码不变。 其 Qt DLL 与平台插件需随程序部署,即使引擎选择静态构建也一样;可运行 `windeployqt --no-translations build/b2dsave.exe`,该工具由匹配版本的 Qt 提供。 界面、默认存档目录和使用方式见 [存档查看器](docs/save-viewer.md)。 临时构建文件和测试产物仅放在 `build/`、`build_static/`,两者均可删除后重新生成。 它们共用源码树中的生成资源包,不能同时执行资源打包。 C++ 统一使用 `-fno-exceptions -fno-rtti`;编码、类型与命名规则见 [AGENTS.md](AGENTS.md)。 ### 平台自动选择与 Linux 占位构建 CMake 自动选择 Windows 或 POSIX 实现,不需要后端参数。Linux 需要 GCC/G++、CMake 3.31、Qt 5 Widgets、 Make 和 zlib 开发包(如 Debian/Ubuntu 的 `zlib1g-dev`): ```sh cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build --target b2d -j4 ``` Linux 可以编译原生库和程序,但 POSIX 的窗口、图形、音频、文件及图片后端尚未实现, 初始化游戏会报告失败;不能把编译成功理解为可运行游戏。主程序内嵌资源发现和纯内存格式处理已有实现。 Linux 构建 `demo2`~`demo5` 前,需先从 Windows 构建复制对应的 `demos/data/demo2-resources.zip`、`demos/data/demo3-resources.zip`、`demos/data/demo4-resources.zip` 或 `demos/data/demo5-resources.zip` 到同一路径;构建 `all` 需要四个 Demo 包,构建 `sdk` 还需要 `asset/b2d-resources.zip`。 单独构建引擎、工具或 Demo1 不需要这些包。Linux 的 `B2D_STATIC_BUILD=ON` 仅选择静态引擎, 不保证运行库与 zlib 全静态链接。不要跨系统复用构建目录。 Demo 测试不按平台隐藏,POSIX 后端未实现时正常运行用例应失败,见 [非 Windows 测试](TESTING.md#非-windows-平台)。 ## C 游戏接入 最小主循环保留初始化检查,并在关闭前保存取节拍失败的错误码: ```c #include "b2d.h" #include int main(int argc, char** argv) { b2d_init("My game", NULL, argc, argv); if (b2d_last_error() != B2D_ERR_NONE) { return 1; } while (b2d_next_tick()) { /* 在这里查询动作、更新游戏状态并绘制场景。 */ } const b2d_int error = b2d_last_error(); b2d_shutdown(); return error == B2D_ERR_NONE ? 0 : 1; } ``` `b2d_next_tick()` 每次推进一拍,固定步长由公开常量 `B2D_TICK_MS` 定义为 16.67 ms。 引擎逐拍更新自动移动、动画和画面;手动移动和碰撞由循环体负责。 简单移动可以保存 float 位置,每拍增加 `速度 * B2D_TICK_MS / 1000`,显示时取整。 有限追赶不保证实际阻塞相同的墙钟时间;暂停及中断规则见 [使用指南](docs/usage.md)。 动态链接示例:`gcc -std=c99 game.c -I include build/libb2d.dll.a -o build/game.exe`。 仅表示成功/失败的接口返回 `void`;资源、存档等可能失败的操作应立即读取最近错误, 后续 API 调用会覆盖它,`next_tick` 不汇总此前的 I/O 错误。 静态链接方法和完整约定见 [使用指南](docs/usage.md)。 ## 文档与目录 | 内容 | 位置 | | --- | --- | | 接口签名与中文参数注释 | [include/b2d.h](include/b2d.h) | | 逐函数讲解、参数与结构体字段、调用片段 | [C API 手册](docs/api-manual.md) | | 可独立编译运行的 C99 小程序与素材生成 | [手册示例](examples/README.md) | | 接入、输入、计时、资源、存档与调试输出 | [使用指南](docs/usage.md) | | 五个 C Demo 的运行、资源和关卡格式 | [Demo 指南](demos/README.md) | | Demo 操作、游戏规则和进度保存 | [Demo 玩法](demos/gameplay.md) | | Demo 模块、主循环和状态组织 | [Demo 代码结构](demos/code-structure.md) | | 测试内容、选择原则和运行方式 | [测试指南](TESTING.md) | | 通用素材、授权和资源包生成 | [asset/README.md](asset/README.md) | | 资源配置、瓦片、图组和动画的桌面编辑 | [资源工具](docs/resource-editor.md) | | 开发方向及待实施边界 | [开发决策](docs/development-decisions.md) | | 碰撞、游戏时间与节拍决策 | [gameplay-decisions.md](docs/gameplay-decisions.md) | | 资源对象与解压决策 | [resource-decisions.md](docs/resource-decisions.md) | | 存档格式与兼容性决策 | [save-decisions.md](docs/save-decisions.md) | | Windows 音频与兼容性决策 | [audio-decisions.md](docs/audio-decisions.md) | | 实现与协作规范 | [AGENTS.md](AGENTS.md) | 引擎实现位于 `src/`,公开头文件位于 `include/`;Windows 导出表位于 `src/platform/windows/b2d.def`。引擎测试在 `tests/`,工具及其测试在 `tools/`、 `tools/tests/`,Demo 及其专项测试在 `demos/`、`demos/tests/`。 内部实现按职责组织:`scene.cpp` 负责场景与合成,`input.cpp` 负责输入快照、动作与触发, `tick.cpp` 负责节拍推进;`config.cpp`、`screenshot.cpp`、`system_commands.cpp` 分别负责 配置持久化、截图和标准菜单命令。`save_format.cpp` 实现存档格式,`api_save.cpp` 提供公开存档接口; `builtin_data.hpp` 保存内置调色板和字形。`embedded_pack.cpp` 及平台同名文件负责内嵌包发现, Linux 主程序通过 `src/platform/posix/embedded_pack_entry.c` 提供资源访问入口。 `src/api_types.hpp` 集中定义 `b2d_res`、`b2d_timer` 等不透明句柄的内部结构; 公开头文件 `include/b2d.h` 只提供这些类型的前向声明。