Hey there, welcome to the Pygbag Wiki!
This page covers installing Pygbag, using it to package your game, and uploading it to be played by anyone on the Internet.
If you have questions at any point, you can ask for help in Pygame’s Discord Server.
Pip is a tool used to install Python libraries, and it’s usually installed along with Python.
Execute the following command in the terminal:
pip install git+https://github.com/pygame-web/pygbag --user --upgrade
.
This would install/upgrade to the latest version of pygbag.
pip install pygbag --user --upgrade
also works.
When packaging, Pygbag sets up a local server which runs your game and provides debug information. This is only accessible from your own computer. If you do not need to debug your game, add --build
to the command line options.
Create a folder. This folder will include all your game files.
Now, create main.py
inside that folder and paste this code into it.
import asyncio
import pygame
pygame.init()
pygame.display.set_mode((320, 240))
clock = pygame.time.Clock()
async def main():
count = 60
while True:
print(f"{count}: Hello from Pygame")
pygame.display.update()
await asyncio.sleep(0) # You must include this statement in your main loop. Keep the argument at 0.
if not count:
pygame.quit()
return
count -= 1
clock.tick(60)
asyncio.run(main())
This is some test code to check if Pygbag is running correctly.
On the command line, navigate to the parent directory of your project. (that is, the directory which holds it)
Run this command: pygbag folder_name
(replace folder_name with the name that you gave your game folder)
If pygbag
isn’t recognised as a command, you can run python -m pygbag folder_name
as an alternative.
After running this command, navigate to localhost:8000#debug. The browser should show a page like this:
So, you might be wondering how players will play your game if your game window is so small and the debug console takes up so much space. The answer is that you can navigate to localhost:8000 instead to hide the debug console.
If you were able to complete this step, congratulations! You have successfully set up Pygbag and tested that your game runs in the browser!
You can change the page layout (and much more) using templates. They consist of HTML markup and Python/JavaScript code to contain your packaged game, plus some CSS to style it. To make your template better fit your game, you may want change it from the default one. Add --template [TEMPLATE NAME].tmpl
to Pygbag’s arguments when running it from the command line to set the template it uses.
This is recommended if you don’t want to edit HTML. Check /static in Pygbag’s repository for a list of available templates. Put the filename after --template
to make Pygbag use it.
Here you can find various templates available online. The simplest way to customise a template is to download one and edit them.
If you want to make Pygbag use a template on your computer, pass the full path of your template file instead of just the filename. Running Pygbag in this way will package your game with your desired template without erasing the cache.
With this approach, you can customize the template as you like, and test out changes before you publish your game.
Before editing templates, you should have a good knowledge of HTML. The code in templates is important to running the game properly, so edit them carefully. Remember to test that your game still packages correctly after switching/editing templates.
Assets are the images, fonts and sounds your game uses. If you aren’t using Pygbag, you can place the assets in any folder (although it’s good practice to put them in your project folder anyways). With Pygbag, you must place all your assets in your project folder, or they will not be packaged.
Most libraries can be used normally, but certain complex ones (e.g. numpy, matplotlib) need to be imported at the top of main.py
.
You won’t need to change much of your project’s code to make it compatiable with Pygbag:
import asyncio
to the script containing your game loop.main()
. It must be an asynchronous function (use async def
instead of def
).await asyncio.sleep(0)
in your game loop.asyncio.run(main())
at the end of the file. The game loop will be run here, so any additional lines will not be run.To let others play your game online, you must publish your game on a publicly accessible website. itch.io offers free hosting and allows you to customise your game page.
To host your game on itch.io, you need to zip the bundle created by Pygbag and upload it. Use the --archive
option if you want Pygbag to produce a ZIP file. This will be located at PROJECT_DIR/build/web.zip
Kind of project
to HTML
This file will be played in the browser
on the uploadMore information can be found here. After following these steps, if you view your game page, you would be able to see your game. If you update your games frequently, you can use butler, a command-line tool made by the developers of itch.
Congratulations for finishing this tutorial! Now you can go ahead and make all your Python games playable in the browser! Thank you for reading.