Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/baekalfen/pyboy
Game Boy emulator written in Python
https://github.com/baekalfen/pyboy
cython emulator gameboy gameboy-emulator gameboy-emulator-library pypy python
Last synced: 14 days ago
JSON representation
Game Boy emulator written in Python
- Host: GitHub
- URL: https://github.com/baekalfen/pyboy
- Owner: Baekalfen
- License: other
- Created: 2015-05-29T11:58:11.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-05-22T06:59:08.000Z (6 months ago)
- Last Synced: 2024-05-22T07:51:41.026Z (6 months ago)
- Topics: cython, emulator, gameboy, gameboy-emulator, gameboy-emulator-library, pypy, python
- Language: Python
- Homepage:
- Size: 43.2 MB
- Stars: 4,466
- Watchers: 75
- Forks: 468
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
__If you have any questions, or just want to chat, [join us on Discord](https://discord.gg/Zrf2nyH).__
[](https://discord.gg/Zrf2nyH)
Train RL agents to play Pokemon Red
Rewind any game
Play the classics
Create your own AI
Beat world records with AI
Getting Started
===============
The instructions are simple:
```sh
$ pip install pyboy
```
For details, see [installation instructions](https://github.com/Baekalfen/PyBoy/wiki/Installation).
Now you're ready! Either use PyBoy directly from the terminal
```sh
$ pyboy game_rom.gb
```
Or use it in your Python scripts:
```python
from pyboy import PyBoy
pyboy = PyBoy('game_rom.gb')
while pyboy.tick():
pass
pyboy.stop()
```
The API
=======
If you are looking to make a bot or AI, then these resources are a good place to start:
* [PyBoy API Documentation](https://baekalfen.github.io/PyBoy/index.html)
* [Wiki Pages](https://github.com/Baekalfen/PyBoy/wiki/)
* [Using PyBoy with Gym](https://github.com/Baekalfen/PyBoy/wiki/Using-PyBoy-with-Gym)
* [Example: Kirby](https://github.com/Baekalfen/PyBoy/wiki/Example-Kirby)
* [Example: Tetris](https://github.com/Baekalfen/PyBoy/wiki/Example-Tetris)
* [Example: Super Mario Land](https://github.com/Baekalfen/PyBoy/wiki/Example-Super-Mario-Land)
* [Code Examples](https://github.com/Baekalfen/PyBoy/tree/master/extras/examples)
* [Discord](https://discord.gg/Zrf2nyH)
When the emulator is running, you can easily access [PyBoy's API](https://baekalfen.github.io/PyBoy/index.html):
```python
pyboy.set_emulation_speed(0) # No speed limit
pyboy.button('down')
pyboy.button('a')
pyboy.tick() # Process at least one frame to let the game register the input
value_of_interest = pyboy.memory[0xC345]
pil_image = pyboy.screen.image
pil_image.save('screenshot.png')
```
The [Wiki](https://github.com/Baekalfen/PyBoy/wiki) shows how to interface with PyBoy from your own project.
Performance
===========
Performance is a priority for PyBoy, to make your AI training and scripts as fast as possible.
The easiest way to improve your performance, is to skip rendering of unnecessary frames. If you know your
character takes X frames to move, or the game doesn't take input every frame, you can skip those to potentially triple
your performance. All game logic etc. will still process.
Here is a simple comparison of rendering every frame, rendering every 15th frame, and not rendering any frames (higher is better). See [`pyboy.tick`](https://docs.pyboy.dk/#pyboy.PyBoy.tick) for how it works. Your performance will depend on the game.
Full rendering
Frame-skip 15
No rendering
x124 realtime
x344 realtime
x395 realtime
```python
for _ in range(target):
pyboy.tick()
```
```python
for _ in range(target//15):
pyboy.tick(15)
```
```python
pyboy.tick(target, False)
```
The Game Boy was originally running at 60 frames per second, so a speed-up of 100x realtime is 6,000 frames per
second. And trivially from the table above, simulating 395 hours of gameplay can be done in 1 hour with no rendering.
It's also recommended to be running multiple instances of PyBoy in parallel. On an 8-core machine, you could potentially
do 3160 hours of gameplay in 1 hour.
Contributing
============
Any contribution is appreciated. The currently known problems are tracked in [the Issues tab](https://github.com/Baekalfen/PyBoy/issues). Feel free to take a swing at any one of them. If you have something original in mind, come and [discuss it on on Discord](https://discord.gg/Zrf2nyH).
[](https://discord.gg/Zrf2nyH)
For the more major features, there are the following that you can give a try. They are also described in more detail in the [project list in the Wiki](https://github.com/Baekalfen/PyBoy/wiki/Student-Projects):
* Hacking games
* Link Cable
* Debugger (VSCode, GDB, terminal or otherwise)
* AI - [use the `api`](https://baekalfen.github.io/PyBoy/index.html) or game wrappers to train a neural network
* Game Wrappers - make wrappers for popular games
If you want to implement something which is not on the list, feel free to do so anyway. If you want to merge it into our repo, then just send a pull request and we will have a look at it.