Lesson 14: Share Your Game (pygbag + zip)

🌍 Ways to Share a Game

Right now, playing Space Salvage means installing Python, installing pygame-ce and running a .py file. That is fine for a programmer and a wall for everyone else. There are three common ways past it, each for a different audience:

This lesson does the first two in full, because together they reach almost everyone: a link anyone can click, and a zip other coders can learn from. The desktop app gets a short optional section at the end of Share the Source.

Where can a web build live? Any site that serves static files can host it: itch.io (made for indie games, with a built-in way to play HTML games on a game page), GitHub Pages, or Netlify. This lesson uses itch.io, because it is free to publish, it puts your game on a page with a description and screenshots, and pygbag's documentation walks through it.

🧩 How pygbag Runs Python in a Browser

Browsers don't run Python. They do run WebAssembly, a compact program format that many languages can be compiled to. The pygbag project provides a copy of CPython and pygame-ce compiled to WebAssembly. pygbag, the tool you install with pip, packs your main.py and assets into a web page that downloads that runtime and runs your game on a <canvas>.

There is one catch. A web page shares a single line of work with the browser. While your code runs, the browser can't draw the canvas, read the keyboard or play sound. A desktop while running: loop never stops, so in a browser it would freeze the tab. The fix is to make the loop pause briefly once per frame and hand control back to the browser, then carry on. Python's built-in asyncio module is designed exactly for code that pauses and resumes like this, so pygbag uses it.

You don't need to learn asyncio in depth for this. Three keywords are enough: async def marks a function that can pause, await is where it pauses, and asyncio.run() starts it.

✏️ Three Changes for the Web

pygbag's quick-start guide lists what it needs, and your Part 2 game already follows most of it: one game loop inside main(), assets loaded once at the start, every file inside the game folder. What is left: name the file main.py (pygbag looks for that exact name), then make three changes:

1. Add import asyncio at the top.
2. Make the loop's function async def main():, and put await asyncio.sleep(0) inside the loop, once per frame. Right after pygame.display.flip() is a good place. Keep the number 0: it means "pause just long enough for the browser to catch up".
3. Start the game with asyncio.run(main()) at the end of the file, and add nothing after it.

Here are the changed lines of Space Salvage. Everything else stays exactly as it was:

import asyncio                             # change 1
import random
from pathlib import Path

import pygame


async def main():                          # change 2: async def
    # ... set up the window, fonts, assets and sounds exactly as before ...
    while running:
        # ... events, update and draw exactly as before ...
        pygame.display.flip()
        await asyncio.sleep(0)             # change 2: hand control to the browser (keep it 0)

    pygame.quit()


if __name__ == "__main__":
    asyncio.run(main())                    # change 3: start the async main()

The async version still runs on your desktop with python main.py, so you keep one file for both. Here is a complete, short program with the same shape that you can run anywhere. It moves a circle for about five seconds and stops:

import asyncio

import pygame

pygame.init()
screen = pygame.display.set_mode((640, 360))
pygame.display.set_caption("Async loop test")
clock = pygame.time.Clock()
font = pygame.font.Font(None, 48)


async def main():
    x = 0.0
    frames = 0
    running = True
    while running and frames < 300:          # about 5 seconds, then it stops
        dt = clock.tick(60) / 1000
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False
        x = (x + 200 * dt) % 640
        frames += 1
        screen.fill((20, 24, 36))
        pygame.draw.circle(screen, (255, 200, 80), (x, 180), 30)
        screen.blit(font.render(f"frame {frames}", True, (230, 230, 230)), (20, 20))
        pygame.display.flip()
        await asyncio.sleep(0)               # let the browser draw and read input
    pygame.quit()
    print(f"Ran {frames} frames.")


asyncio.run(main())

🧪 Build and Test Locally

Set up a folder that holds only the game. The folder name becomes the game's name in pygbag:

space_salvage/
├── main.py              the async game
├── assets/              images and .ogg sounds
├── CREDITS.md           where the art and sound came from
├── requirements.txt     for the source zip (next section)
└── README.txt           for the source zip

Install pygbag once, then, from the folder that contains space_salvage, run it on the game folder:

python -m pip install pygbag          # once (py -m pip on Windows)
python -m pygbag space_salvage        # build, then serve it on your computer

pygbag builds the web version into space_salvage/build/web/ and starts a small test server. Open http://localhost:8000 in your browser. The first load is slow, because the browser downloads the Python and pygame-ce runtime from pygbag's servers; later loads use a cache. When the loading bar finishes, click the page if the game waits for you: browsers don't let a page play sound until the player has interacted with it. Stop the server with Ctrl + C in the terminal.

Changed your code? Run the same command again: pygbag rebuilds the package every time.

To read errors from the web version, open http://localhost:8000?-i for pygbag's debug console, or open your browser's developer tools (F12) and look at the Console tab. A Python traceback shows up there just as it would in a terminal.

🕹️ Publish on itch.io

The local server only works on your computer. To let anyone play, upload the build to itch.io. First, have pygbag make a zip of the web build:

python -m pygbag --archive space_salvage

This writes space_salvage/build/web.zip, containing index.html, the packed game and an icon. Then, on itch.io (following the steps in pygbag's own itch.io guide):

1. Create a free account, then choose Upload new project.
2. Give it a title and set Kind of project to HTML.
3. Upload web.zip and tick This file will be played in the browser.
4. In the embed options, set the viewport to your window size, 960 × 540, and turn on the fullscreen button if you like.
5. Write a short description: your pitch from the design doc, the controls, and a credits line (for example "Art and sound: Kenney, kenney.nl, CC0").
6. Save it as a draft first and play it from its page. When it works, set visibility to Public (or restricted, if you only want people with the link) and share the URL.

Each time you improve the game, rebuild with --archive and upload the new web.zip. itch.io also has a command-line upload tool, butler, for people who update often; the web page is all you need for now.

📦 Share the Source

Other learners will want to see how you did it. A good source zip holds everything needed to run the game and nothing else:

• main.py and the assets folder;
• requirements.txt, the file pip reads to install dependencies. For this game it is one line:

  pygame-ce>=2.5

• README.txt: what the game is, the controls, how to run it (python -m pip install -r requirements.txt, then python main.py), and the credits;
• CREDITS.md, so the asset licenses travel with the files.

Leave out the build folder (pygbag's output, which can be rebuilt), __pycache__ folders and old zips. Zipping by hand makes it easy to forget one, so the lab includes a short script, make_source_zip.py, that uses Python's built-in zipfile module. Put it next to the game folder (not inside it) and run:

python make_source_zip.py space_salvage

It walks the folder with Path.rglob("*"), skips anything inside a skipped folder or with a skipped extension, and writes space_salvage_source.zip beside the folder. The heart of it is one small decision function:

SKIP_FOLDERS = {"build", "dist", "__pycache__", ".git", ".venv", "venv"}
SKIP_SUFFIXES = {".pyc", ".zip"}


def should_skip(relative_path):
    """True for files a friend does not need: build output, caches, old zips."""
    if any(part in SKIP_FOLDERS for part in relative_path.parts):
        return True
    return relative_path.suffix in SKIP_SUFFIXES

Before you send it, test it the way a friend would: unzip it into a new folder, install the requirements, and run python main.py. If it runs there, it will run for them.

python -m pip install pyinstaller
python -m PyInstaller --onefile --windowed --name SpaceSalvage --add-data "assets:assets" main.py

🏋️ Practice Exercise: Space Salvage Goes Live

"""Make a source zip of your game folder: Intro Lesson 14 (solution).

Put this file NEXT TO your game folder (not inside it) and run:
    python make_source_zip.py space_salvage
It writes space_salvage_source.zip beside the folder, with your code,
assets, requirements.txt and README.txt, and leaves out pygbag's build
folder and Python's cache files.
"""
import sys
import zipfile
from pathlib import Path

SKIP_FOLDERS = {"build", "dist", "__pycache__", ".git", ".venv", "venv"}
SKIP_SUFFIXES = {".pyc", ".zip"}


def should_skip(relative_path):
    """True for files a friend does not need: build output, caches, old zips."""
    if any(part in SKIP_FOLDERS for part in relative_path.parts):
        return True
    return relative_path.suffix in SKIP_SUFFIXES


def make_source_zip(game_folder):
    """Zip game_folder into <name>_source.zip next to it. Returns (zip path, names)."""
    game_folder = Path(game_folder)
    zip_path = game_folder.parent / f"{game_folder.name}_source.zip"
    names = []
    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as archive:
        for path in sorted(game_folder.rglob("*")):
            relative = path.relative_to(game_folder)
            if path.is_file() and not should_skip(relative):
                name = (Path(game_folder.name) / relative).as_posix()
                archive.write(path, name)
                names.append(name)
    return zip_path, names


def main():
    if len(sys.argv) < 2:
        print("Usage: python make_source_zip.py GAME_FOLDER")
        return
    game_folder = Path(sys.argv[1])
    if not (game_folder / "main.py").exists():
        print(f"{game_folder} has no main.py. Is that your game folder?")
        return
    missing = [n for n in ("requirements.txt", "README.txt") if not (game_folder / n).exists()]
    if missing:
        print("Warning: add these before you share:", ", ".join(missing))
    zip_path, names = make_source_zip(game_folder)
    for name in names:
        print("  added", name)
    print(f"Wrote {zip_path} ({len(names)} files).")


if __name__ == "__main__":
    main()

📓 Learning Journal

📝 Summary

You took your capstone from "runs on my computer" to "anyone can play it". pygbag runs Python and pygame-ce in the browser through WebAssembly, and because a browser tab can't be held by a never-ending loop, the game hands control back once per frame with await asyncio.sleep(0) inside an async main() started by asyncio.run(). You built and tested the web version locally, uploaded pygbag's web.zip to itch.io as an HTML game, and packaged a clean source zip with requirements.txt, a README and credits, checked by unzipping and running it the way a friend would. Congratulations: you have designed, built, polished, playtested and shipped a game.

🔭 Looking Ahead

This is the last lesson of Game Dev I: Intro. Game Dev II: Intermediate builds on everything here, starting with Groups, Layers & Masks and working up to a tower-defense capstone and real desktop builds.

❓ Common Questions

🎯 Quick Quiz

🌟 Going Further

• Make it look good on its page: take two screenshots and a short description for your itch.io page, and add a 32 × 32 favicon.png to the game folder; pygbag uses it as the web page's icon.
• Detect the browser: sys.platform == "emscripten" is true when running under pygbag. Use it to skip the Esc-to-quit key on the web, where quitting just leaves a blank canvas.
• Read the docs: pygbag's guide, its itch.io publishing page, and itch.io's HTML5 games documentation.
• Thanks: Space Salvage's art and sound come from Kenney's Space Shooter Extension and Sci-Fi Sounds packs (CC0). Credit isn't required, but it is a kind thing to do on your game page.
• Coming up in Game Dev II: Intermediate: Building Executables covers PyInstaller properly (spec files, where to save settings, macOS apps), and Launch & Live Ops covers store pages, butler uploads and updates.