本页目录

pygbag:把 pygame 游戏打包进浏览器的 Python WebAssembly 打包器

pygbag · pygame-web/pygbag

pygbag 是面向 pygame 的 Python WebAssembly 工具,由打包器、测试服务器与模拟器组成,目标是在现代浏览器(含移动端)中直接运行 Python 代码。项目要求应用目录内含 main.py,且主循环需 async 感知,例如在循环中调用 await asyncio...

其他 Pygame Python 渲染技术 中级
★ Stars 526 Forks 59 License MIT 更新 2026-11-19

国内开发环境适配

Windows
未知
Linux
未知
macOS
未知
引擎 / 框架:Pygame 暂无中文教程标记 未标记站长实测
pip 安装需访问 PyPI;首次运行会从默认 CDN(pygame-web.github.io/archives/ 下的版本目录)拉取 CPython 与 pygame-ce 预构建并写入本地缓存。国内访问 GitHub Pages 可能较慢或不稳定,可用 --cdn 指定可访问的缓存来源,但镜像可用性需自行核验。

中文项目介绍

pygbag 是 pygame-web 组织维护的 Python WebAssembly 打包工具,核心目标是把 pygame 应用带进现代浏览器,包括移动端浏览器。它并不是一款具体的游戏,而是一套由打包器、测试服务器与模拟器组成的开发工具链:开发者准备一个应用目录,pygbag 负责生成可在浏览器中加载的页面与资源,并启动本地测试服务器供调试。README 将其称为“Python WebAssembly for everyone”的第二集,并指出项目概念可追溯到 2016 年 Panda3D 社区基于 Python 2.7 与 asm.js 的实验。

需要注意的是,pygbag 明确只提供对 pygame-ce(pygame 社区版)的支持。它直接在现代浏览器中运行 Python 代码,社区文档位于 pygame-web.github.io。项目本身不承诺具体性能指标,实际帧率与兼容范围会受浏览器、设备与项目实现影响。

技术架构分析

构建与模块扩展

pygbag 不只是一个 Python 模块,它的 Python 运行时存放在线上,重建完整工具链可能相当困难。README 指向 python-wasm-sdk 用于构建 CPython(不是 pyodide),默认只构建 pygame,开发者可以 fork 后加入自己的模块。构建 pygame、C 加载器 pymain 以及将其链接到 libpython 的方式,可参考 pygbag 的 CI。自 0.6 起,模块加载默认使用 wasm 动态库;静态/动态模块的添加方式见 package.d 目录与 vendor/vendor.sh,各 vendor 的具体支持说明位于对应 README。

补充说明

快速开始与异步主循环

使用 pygbag 的前提是应用目录中包含 main.py,并且主循环必须“async aware”。README 给出的最小结构包括:在文件顶部尽量一次性声明全局变量,尽早完成初始化与资源加载,以减少运行时的卡顿或网络错误;将主逻辑放入 async def main(),在循环中执行渲染,并在 pygame.display.update() 之后调用 await asyncio.sleep(0)。这个 sleep 的数值应保持为 0,README 特别强调其重要性。

主循环并不是传统意义上的无限循环:渲染逻辑只在 VSYNC 触发时执行,桌面端通常为每秒 60 次或更高,部分移动设备可能更低。程序入口使用 asyncio.run(main()),并且不要在入口之后继续添加代码,尤其不要添加 sys.exit 或 pygame.quit,因为 asyncio.run 在 pygame-wasm 上是非阻塞的,后续代码可能在 main() 真正开始前就被执行。

安装与运行命令为:

  • pip3 install pygbag --user --upgrade
  • pygbag your.app.folder
  • pygbag --help your.app.folder

命令行与测试服务器

执行打包命令后,pygbag 会启动测试服务器,默认端口为 8000,浏览器访问 http://localhost:8000 即可查看。命令行提供多种选项,例如 --bind 指定绑定地址、--PYBUILD 指定 Python 版本、--app_name 设置应用名称、--ume_block 控制是否等待用户媒体交互后再运行、--can_close 控制关闭确认、--cache 指定缓存目录、--package 设置包名、--title 设置页面标题、--version 覆盖预构建版本路径。

构建相关选项包括 --build 仅构建而不启动测试服务器、--html 生成内嵌资源 HTML、--no_opt 关闭资源优化、--archive 生成可用于 itch.io 的 build/web.zip、--icon 指定图标、--cdn 指定本地缓存来源、--template 指定 index.html 模板、--ssl 启用 SSL、--port 指定端口,以及 --disable-sound-format-error 避免常见不支持音频格式直接抛异常。README 还列出未公开的开发者选项 --git 与 --dev。

URL 也可以像命令行一样传参:在 ? 之后、# 之前放置 Python 参数或 KEY=VALUE 环境变量,使用 & 分隔;在 # 之后放置程序名或程序参数,空格需按 HTML URL 规则编码为 %20。访问 http://localhost:8000?-i# 可以获得终端 REPL 与缩小画布。若使用 --html 且游戏目录名为 test,可访问 test.html。

浏览器与兼容性说明

README 建议优先使用基于 V8 的浏览器,例如 Chromium、Brave、Chrome 等,起步版本为 81.0.4044(Android 4.4),原因是这些浏览器对 WebAssembly 加载设有基线限制;在它们上面测试有助于保证其他浏览器中的运行效果。移动 Safari 方面,README 提醒不要在程序启动时播放声音,并建议添加 --ume_block 0;Safari/Chrome 移动版需要 iOS 15.x 及以上。项目在可能的情况下使用 BrowserStack 进行测试。

首次加载通常较慢,因为需要从 CDN 建立本地缓存,以避免反复传输 pygame 与 CPython 预构建文件。默认预构建由 GitHub Pages 上的版本化目录提供。代码、资源或模板发生较大变化后,需要重新运行 pygbag your.app.folder,但缓存不会被销毁以节省带宽;如需重置预构建缓存,可删除应用目录下的 build/web-cache。此外,pyodide wheels 属于非标准 wasm,不能开箱即用于 pygbag 运行时。

适用人群与学习建议

pygbag 更适合已经拥有 pygame/pygame-ce 项目、希望把作品发布到浏览器中的开发者,也适合想了解 Python WebAssembly 打包流程的技术学习者。上手前应先把主循环改为 async 结构,处理好全局变量、初始化与资源加载顺序;发布前则应在目标浏览器与移动设备上实际验证音频、输入与性能表现。由于 README 未给出统一性能基准,不建议仅凭工具链描述推断所有游戏的兼容性。

开源许可证与版权说明

许可证标识:MIT。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目