You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: wiki/README.md
+3-103Lines changed: 3 additions & 103 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,108 +1,8 @@
1
1
Check out some [demos](#demos-on-itchio) before you start!
2
2
3
-
## Important points
4
-
5
-
Read Pygbag's [project description](https://pypi.org/project/pygbag/) for a more detailed overview. A full packaging guide can be found [here](/wiki/pygbag/).
6
-
7
-
**<ins>Also, read the page on [making your code compatible with browser game loop](/wiki/python-wasm). You will probably have to change some of your code.</ins>**
8
-
9
-
### All operating systems
10
-
11
-
- Name your main game script `main.py` and put it in the root folder of your game.
12
-
- Make your main loop async-aware and use `asyncio.sleep(0)` every iteration to give control back to the main thread.
13
-
- Add `--template noctx.tmpl` to pygbag command line if using 3D/WebGL.
14
-
- Put the import statements of complex packages in order (but numpy first) at the top of `main.py`.
15
-
- 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](https://pypi.org/project/pygame_gui) works on top of [pygame-ce](https://pyga.me), [Panda3D](https://www.panda3d.org/) provides [directgui](https://docs.panda3d.org/1.10/python/programming/gui/directgui/index) and Harfang3D provides imgui. They are all cross-platform.
16
-
- You can add a square image file named `favicon.png` in your game's root folder to make Pygbag use it as the web package's favicon.
17
-
- Make sure all audio files are in OGG format, and all files are compressed. (that is, not in WAV/AIFF)
18
-
- Avoid raw formats like BMP for your image assets, they are too big for web use; use PNG/WEBP or JPG instead.
19
-
20
-
- Do not use filenames like `*-pygbag.*` that pattern is reserved for pygbag internal use (optimizing pass).
21
-
22
-
Before packaging, adapt your code this way if you still want WAV/MP3 format on desktop:
23
-
```py
24
-
if sys.platform =="emscripten":
25
-
snd = pygame.mixer.Sound("sound.ogg")
26
-
else:
27
-
snd = pygame.mixer.Sound("sound.wav") # or .WAV, .mp3, .MP3, etc.
28
-
```
29
-
30
-
if you have heightmaps in your assets use `--no_opt` to prevent png recompression.
31
-
32
-
if you want to keep pixelated look whatever the device screen size is use:
- Use Python that was downloaded from python.org rather than the Windows Store. You can check installed version(s) with the `py --list` command.
42
-
- Use `/` instead of `\` as a path separator (e.g. `img/my_image.png` instead of `img\my_image.png`). The path should still be valid on newer Windows versions.
43
-
44
-
### MacOS
45
-
46
-
- If you get a SSL error, use the file `Install Certificates.command` in `Applications/Python 3.XX`.
47
-
48
-
### Linux
49
-
50
-
- When using webusb ftdi serial emulation, use `sudo rmmod ftdi_sio` after plugging devices.
51
-
52
-
## Template
53
-
54
-
There is actually none, because Python-WASM is just a web-friendly version of CPython REPL with [some added facilities](https://discuss.python.org/t/status-of-wasm-in-cpythons-main-branch/15542/12?u=pmp-p). Most desktop code will run (and continue to run) with only a few changes.
55
-
56
-
Basic structure of a game (available [here](https://github.com/pygame-web/pygbag/tree/main/test)):
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](https://peps.python.org/pep-0723/), for example:
91
-
```
92
-
# /// script
93
-
# dependencies = [
94
-
# "six",
95
-
# "bs4",
96
-
# "markdown-it-py",
97
-
# "pygments",
98
-
# "rich",
99
-
# "mdurl",
100
-
# "textual",
101
-
# ]
102
-
# ///
103
-
```
104
-
105
-
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)
3
+
## Using Pygbag
4
+
- Visit [this page](/wiki/pygbag/) on how to use Pygbag to make web games with Python.
5
+
- Visit [this page](/wiki/pygbag-code/) for useful Pygbag code snippets and a Pygbag FAQ.
This would install/upgrade to the latest version of pygbag.
14
12
15
13
`pip install pygbag --user --upgrade` also works.
16
14
17
-
## Web Testing
18
-
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.
19
-
20
-
### Creating a project
21
-
Create a folder. This folder will include all your game files.
15
+
## Quick Start Guide
16
+
### Code
17
+
You won't need to change much of your project's code to make it compatible with Pygbag:
22
18
23
-
Now, create `main.py` inside that folder and paste this code into it.
19
+
1. Name the file with your game loop `main.py`.
20
+
1. Add `import asyncio` to the script containing your game loop.
21
+
2. Encapsulate your variable declarations (other than the window, as other functions might use it too)
22
+
3. Put the game loop inside `main()`. It must be an asynchronous function (use `async def` instead of `def`).
23
+
3. Put `await asyncio.sleep(0)` anywhere in your game loop. Right after your `clock.tick()` is fine.
24
+
4. Put `asyncio.run(main())` at the end of the file. The game loop will be run here, so any additional lines will not be run.
24
25
26
+
Here's a working example for what `main.py` might look like.
25
27
```py
26
28
import asyncio
27
29
import pygame
@@ -48,29 +50,39 @@ async def main():
48
50
49
51
asyncio.run(main())
50
52
```
51
-
This is some test code to check if Pygbag is running correctly.
53
+
<!-- ### Web Testing
54
+
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. -->
55
+
56
+
52
57
53
-
### Running your packaged project in your own browser
58
+
### Running your project in your own browser
54
59
On the command line, navigate to the parent directory of your project. (that is, the directory which holds it)
55
60
56
-
Run this command: `pygbag folder_name` (replace folder_name with the name that you gave your game folder)
61
+
Run this command: `pygbag folder_name` (replace `folder_name` with the name that you gave your game folder)
57
62
58
63
If `pygbag` isn't recognised as a command, you can run `python -m pygbag folder_name` as an alternative.
59
64
60
-
After running this command, navigate to [localhost:8000#debug](https://localhost:8000#debug). The browser should show a page like this:
After running this command, navigate to [localhost:8000](https://localhost:8000). Pygbag will take a while to load. As of writing, this phase shows a blank cyan page. This may take a long time the first load, but will speed up on later reloads.
66
+
67
+
Once Pygbag has loaded, it will load your game. Once the loading bar completes, you should be able to click the screen to start.
68
+
69
+
If you were able to complete these step, congratulations! You have successfully set up Pygbag and tested that your game runs in the browser! We will continue with some next steps you may consider.
62
70
63
-
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](https://localhost:8000/) instead to hide the debug console.
71
+
If you were not able to, scroll down to the [documentation](#detailed-documentation)to troubleshoot.
64
72
65
-
If you were able to complete this step, congratulations! You have successfully set up Pygbag and tested that your game runs in the browser!
73
+
### Debugging
74
+
If you need to debug your game going forward, you may consider reading the page on [debugging](/wiki/pygbag-debug/) with Pygbag.
66
75
67
-
## Templates
76
+
### Publishing
77
+
To let others play your game online, you must publish your game on a publicly accessible website. We provide documentation for publishing [via itch.io](/wiki/publishing/itch.io/) and [via Github Pages](/wiki/publishing/github.io/).
78
+
79
+
### Templates
68
80
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.
69
81
70
-
### Using built-in templates
82
+
####Using built-in templates
71
83
This is recommended if you don't want to edit HTML. Check [/static](https://github.com/pygame-web/pygbag/tree/main/static) in Pygbag's repository for a list of available templates. Put the filename after `--template` to make Pygbag use it. <!--Not sure where the templates are hosted exactly, made my best guess. Correct me if I'm wrong.-->
72
84
73
-
### Downloading a template and customising it
85
+
####Downloading a template and customising it
74
86
[Here](https://github.com/pygame-web/pygbag/tree/main/static) you can find various templates available online. The simplest way to customise a template is to download one and edit them.
75
87
76
88
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.
@@ -79,25 +91,112 @@ With this approach, you can customize the template as you like, and test out cha
79
91
80
92
> 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.
81
93
82
-
## Project Structure
94
+
## Detailed Documentation
83
95
84
-
### Assets
96
+
### Asset location
85
97
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.
86
98
87
-
### Other libraries
88
-
Most libraries can be used normally, but certain complex ones (e.g. numpy, matplotlib) need to be imported at the top of `main.py`.
99
+
Your project folder, `my-game`, might look like this:
100
+
```
101
+
my-game
102
+
├── img
103
+
│ ├── pygc.bmp
104
+
│ ├── pygc.png
105
+
│ └── tiger.svg
106
+
├── main.py
107
+
└── sfx
108
+
└── beep.ogg
109
+
```
89
110
90
-
### Code
91
-
You won't need to change much of your project's code to make it compatiable with Pygbag:
111
+
Make sure you're not pulling assets from outside your folder, like this!
112
+
```
113
+
.
114
+
├── my-game/
115
+
│ ├── main.py
116
+
│ └── sfx/
117
+
│ └── beep.ogg
118
+
└── img/
119
+
├── pygc.bmp
120
+
├── pygc.png
121
+
└── tiger.svg
122
+
```
92
123
93
-
1. Add `import asyncio` to the script containing your game loop.
94
-
2. Encapsulate your variable declarations (other than the window, as other functions might use it too)
95
-
3. Put the game loop inside `main()`. It must be an asynchronous function (use `async def` instead of `def`).
96
-
3. Put `await asyncio.sleep(0)` in your game loop.
97
-
4. Put `asyncio.run(main())` at the end of the file. The game loop will be run here, so any additional lines will not be run.
98
124
99
-
## Publishing (Optional)
100
-
To let others play your game online, you must publish your game on a publicly accessible website. We provide documentation for publishing [via itch.io](/wiki/publishing/itch.io/) and [via Github Pages](/wiki/publishing/github.io/).
125
+
126
+
### Complex Packages
127
+
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](https://peps.python.org/pep-0723/), for example:
128
+
```
129
+
# /// script
130
+
# dependencies = [
131
+
# "six",
132
+
# "bs4",
133
+
# "markdown-it-py",
134
+
# "pygments",
135
+
# "rich",
136
+
# "mdurl",
137
+
# "textual",
138
+
# ]
139
+
# ///
140
+
```
141
+
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)
142
+
143
+
### Useful .gitignore additions
144
+
```
145
+
*.wav
146
+
*.mp3
147
+
*.pyc
148
+
*.egg-info
149
+
*-pygbag.???
150
+
/build
151
+
/dist
152
+
```
153
+
### Using 3D/WebGL?
154
+
Add `--template noctx.tmpl` to pygbag command line if using 3D/WebGL.
155
+
156
+
### Using heightmaps?
157
+
You can use `--no_opt` to prevent png recompression.
158
+
159
+
### File formats and names
160
+
- You can add a square image file named `favicon.png` in your game's root folder to make Pygbag use it as the web package's favicon.
161
+
- Make sure all audio files are in OGG format, and all files are compressed. (that is, not in WAV/AIFF)
162
+
- Avoid raw formats like BMP for your image assets, they are too big for web use; use PNG/WEBP or JPG instead.
163
+
164
+
- Do not use filenames like `*-pygbag.*` that pattern is reserved for pygbag internal use (optimizing pass).
165
+
166
+
Before packaging, adapt your code this way if you still want WAV/MP3 format on desktop:
167
+
```py
168
+
if sys.platform =="emscripten":
169
+
snd = pygame.mixer.Sound("sound.ogg")
170
+
else:
171
+
snd = pygame.mixer.Sound("sound.wav") # or .WAV, .mp3, .MP3, etc.
172
+
```
173
+
174
+
### Keep pixellated style?
175
+
If you want to keep pixelated look whatever the device screen size is use:
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](https://pypi.org/project/pygame_gui) works on top of [pygame-ce](https://pyga.me), [Panda3D](https://www.panda3d.org/) provides [directgui](https://docs.panda3d.org/1.10/python/programming/gui/directgui/index) and Harfang3D provides imgui. They are all cross-platform.
184
+
185
+
### Windows
186
+
- Use Python that was downloaded from python.org rather than the Windows Store. You can check installed version(s) with the `py --list` command.
187
+
- Use `/` instead of `\` as a path separator (e.g. `img/my_image.png` instead of `img\my_image.png`). The path should still be valid on newer Windows versions.
188
+
189
+
### MacOS
190
+
- If you get a SSL error, use the file `Install Certificates.command` in `Applications/Python 3.XX`.
191
+
192
+
### Linux
193
+
- When using webusb ftdi serial emulation, use `sudo rmmod ftdi_sio` after plugging devices.
194
+
195
+
### Pypi
196
+
Pygbag's project description on pypi exists here: [https://pypi.org/project/pygbag/](https://pypi.org/project/pygbag/)
197
+
198
+
### Boilerplate code
199
+
There is very little because Python-WASM is just a web-friendly version of CPython REPL with [some added facilities](https://discuss.python.org/t/status-of-wasm-in-cpythons-main-branch/15542/12?u=pmp-p). Most desktop code will run (and continue to run) with only a few changes.
101
200
102
201
## Conclusion
103
202
Congratulations for finishing this tutorial! Now you can go ahead and make all your Python games playable in the browser! Thank you for reading.
0 commit comments