This is the CDN root used by Pygbag (Source code/Old runtimes) and the site of its wiki.
Pygbag does not track usage at all, not even for statistical purposes. If you like it, please star the repository!
Check out some demos before you start!
Read Pygbag's project description for a more detailed overview. A full packaging guide can be found here.
Also, read the page on making your code compatible with browser game loop. You will probably have to change some of your code.
-
Name your main game script
main.pyand put it in the root folder of your game. -
Make your main loop async-aware and use
asyncio.sleep(0)every iteration to give control back to the main thread. -
Add
--template noctx.tmplto pygbag command line if using 3D/WebGL. -
Put the import statements of complex packages in order (but numpy first) at the top of
main.py. -
Avoid using CPython's standard library for web operations, GUI (like tkinter), or I/O as it is very synchronous/platform-specific and will probably stay that way. In terms of GUI alternatives, pygame_gui works on top of pygame-ce, Panda3D provides directgui and Harfang3D provides imgui. They are all cross-platform.
-
You can add a square image file named
favicon.pngin your game's root folder to make Pygbag use it as the web package's favicon. -
Make sure all audio files are in OGG format, and all files are compressed. (that is, not in WAV/AIFF)
-
Avoid raw formats like BMP for your image assets, they are too big for web use; use PNG/WEBP or JPG instead.
-
Do not use filenames like
*-pygbag.*that pattern is reserved for pygbag internal use (optimizing pass).
Before packaging, adapt your code this way if you still want WAV/MP3 format on desktop:
if sys.platform == "emscripten":
snd = pygame.mixer.Sound("sound.ogg")
else:
snd = pygame.mixer.Sound("sound.wav") # or .WAV, .mp3, .MP3, etc.if you have heightmaps in your assets use --no_opt to prevent png recompression.
if you want to keep pixelated look whatever the device screen size is use:
import sys, platform
if sys.platform == "emscripten":
platform.window.canvas.style.imageRendering = "pixelated"- Use Python that was downloaded from python.org rather than the Windows Store. You can check installed version(s) with the
py --listcommand. - Use
/instead of\as a path separator (e.g.img/my_image.pnginstead ofimg\my_image.png). The path should still be valid on newer Windows versions.
- If you get a SSL error, use the file
Install Certificates.commandinApplications/Python 3.XX.
- When using webusb ftdi serial emulation, use
sudo rmmod ftdi_sioafter plugging devices.
There is actually none, because Python-WASM is just a web-friendly version of CPython REPL with some added facilities. Most desktop code will run (and continue to run) with only a few changes.
Basic structure of a game (available here):
test
├── img
│ ├── pygc.bmp
│ ├── pygc.png
│ └── tiger.svg
├── main.py
└── sfx
└── beep.ogg
Useful .gitignore additions:
*.wav
*.mp3
*.pyc
*.egg-info
*-pygbag.???
/build
/dist
When importing complex packages (for example, numpy or matplotlib), you must put their import statements at top of main.py. You should also add a metadata header as specified by PEP 723, for example:
# /// script
# dependencies = [
# "six",
# "bs4",
# "markdown-it-py",
# "pygments",
# "rich",
# "mdurl",
# "textual",
# ]
# ///
If using pygame-zero (mostly untested), put #!pgzrun near the top of main.py. (2nd line is perfect if the file already has a shebang)
- How to enter debug mode
- While working, you can access the simulator of the web loop by replacing
import asynciobyimport pygbag.aio as asyncioat top of main.py and run the program from the folder containing it. - TODO: Android remote debugging via chromium browsers series.
- TODO: Universal remote debugging via IRC Client or websocket using pygbag.net.
- Pygbag-script (WIP)
- REPL
- CPython test suite (WIP)
- Games using Python-WASM (Expected to be stable)
- Panda3D demos (Experimental)
These are provided for testing purposes only, and might not always work since they use development versions of Pygbag.
Source code for these games can be found here. You can tag your Github repositories with [pygame-wasm].
The code is read-only, so you should right-click then open in a new window.
- Initial discussion
- Discussion at pygame-ce repo
- Python-WASM explained by core dev Christian Heimes (video)
Python WebAssembly at PyCon FR 2023 (in French): Pour quoi, pour qui et comment
- Pyodide/Pyscript ( py3.12+ not suitable for heavy games, music or 3D )
- Micropython/Pyscript ( py3.4, no pygame, but pysdl2/javascript libraries possible )
- PocketPy, not any Python spec compliant but sometimes close. Can make Terminal/raylib based games.
Thanks for reading and supporting pygame-ce and pygbag. These tools could not have existed without your support.
Work in progress, pull requests welcomed. Feel free to propose links to games or tutorials. Please contribute!!!