Game Boy emulator written in Python

Overview

If you have any questions, or just want to chat, join us on Discord.

It is highly recommended to read the report to get a light introduction to Game Boy emulation. But do be aware, that the Python implementation has changed a lot. The report is relevant, eventhough you want to contribute to another emulator, or create your own.

If you've read the report and want more explicit details, have a look at the Pan Docs.

If you are looking to make a bot or AI, you can find all the external components in the PyBoy Documentation. There is also a short example on our Wiki page Scripts, AI and Bots as well as in the examples directory. If more features are needed, or if you find a bug, don't hesitate to make an issue here on GitHub, or write on our Discord channel.


Installation

The instructions are simple, if you already have a functioning Python environment on your machine.

  1. Install SDL2 through your package manager:

    • Ubuntu: sudo apt install libsdl2-dev
    • Fedora: sudo dnf install SDL2-devel
    • macOS: brew install sdl2
  2. Install PyBoy using pip install pyboy (add --user if your system asks)

Now you're ready! Either use PyBoy directly from the terminal $ pyboy file.rom or use it in your Python scripts:

from pyboy import PyBoy
pyboy = PyBoy('ROMs/gamerom.gb')
while not pyboy.tick():
    pass

When the emulator is running, you can easily access PyBoy's API:

from pyboy import WindowEvent

pyboy.send_input(WindowEvent.PRESS_ARROW_DOWN)
pyboy.tick() # Process one frame to let the game register the input
pyboy.send_input(WindowEvent.RELEASE_ARROW_DOWN)

pil_image = pyboy.screen_image()
pil_image.save('screenshot.png')

If you need more details, or if you need to compile from source, check out the detailed installation instructions. We support: macOS, Raspberry Pi (Raspbian), Linux (Ubuntu), and Windows 10.

At the Wiki page, you will also find out how to interface with PyBoy from your own project: Wiki.

Contributors

Thanks to all the people, who have contributed to the project!

Original Developers

GitHub Collaborators

Student Projects

  • Rewind Time: Jacob Olsen - JacobO1
  • Link Cable: Jonas Flach-Jensen - thejomas
  • Game Boy Color: Christian Marslev and Jonas Grønborg - CKuke and kaff3

Contribute

Any contribution is appreciated. The currently known errors are registered in the Issues tab. Feel free to take a swing at any one of them.

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:

  • Color
  • Link Cable
  • (Experimental) AI - use the botsupport or game wrappers to train a neural network
  • (Experimental) 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.

Comments
  • Implement Random RAM

    Implement Random RAM

    If the random flag is set, iterate through the existing RAM arrays and randomize the values.

    While there are no specific RAM unit tests, I played through some of the ROMs I have locally and the games seemed to be running fine.

    opened by naclander 19
  • WIP: Use scaled size for mouse events in debug windows

    WIP: Use scaled size for mouse events in debug windows

    The tile management in debug windows (hovering and clicking on squares) was not working correctly after the window was scaled. The logic for determining the tile index was relying on the original scaling of the window, resulting in the incorrect tile being targetted.

    By listening for SDL window resize events, we can keep the scaling value up-to-date. We also need to change the one-dimensional scaling value to separate horizontal/vertical scaling due to how the resizing allows the aspect ratio to change.

    Checklist for pull-requests

    1. The project is licensed under LGPL (see LICENSE.md). When merged, your code will be under the same license. So make sure you have read and understand it.
    2. Please coordinate with one of the core developers before making a big pull-request. It's a shame to make something big that doesn't fit the project.
    3. Remember to make a separate branch on your fork. This makes it a lot easier for the core developers to help getting your pull-request ready.
    4. Install pip install pre-commit. This takes care of the formatting rules when you commit your code.
    5. Add tests. We need good pytests for your code. This will help us keep the project stable.
    6. Please don't change the code style, unless it's specifically asked for.

    -->

    opened by JonathanMurray 18
  • Reworked input handling

    Reworked input handling

    I have reworked the input handling completely, in preparation for loadable scripts.

    Performance has worsened with this new input handler, hence the "WIP"-tag.

    opened by thomafred 14
  • Can't run Pokemon Red...

    Can't run Pokemon Red...

    I try to run Pokemon Red, but when I arrive in the screen to create a game, it says:

    1771008  pyboy                          ERROR    Unexpected write to 0x6000, value: 0x01
    1771009  pyboy                          ERROR    Unexpected write to 0x6000, value: 0x00
    

    I don't know why, and how to resolve it... ~~My ROM~~ [REMOVED] If you could help me...

    opened by arthur-fontaine 9
  • Implemented v1 of the Debugger's Memory Window

    Implemented v1 of the Debugger's Memory Window

    • Implemented the MemoryWindow class in pyboy/plugins/debug.py
    • Added the necessary attributes in pyboy/utils.py & pyboy/plugins/window_sdl2.py
    • Added the new memory window hot keys to the main.py output
      • J - next 0x100 bytes
      • K - back 0x100 bytes
      • Left Shift - forward 0x1000 bytes
      • Right Shift - back 0x1000 bytes
    • Added pyboy/plugins/assets/Mono_Hack_Font.ttf as the default font to use with SDL2_ttf
    • Updated the README with the package manager install instructions for each OS.
    opened by kr1tzy 9
  • Feature/gymboy

    Feature/gymboy

    Following issue #124 this is a first version to create a Gym environement from a PyBoy object There is still some tests to do ! But it's a working start !

    opened by MathisFederico 9
  • Tetris wrapper's reset_game() doesn't seem to work.

    Tetris wrapper's reset_game() doesn't seem to work.

    quiet = False 
    filename  = './roms/Tetris.gb' 
    pyboy = PyBoy(filename, window_type="headless" if quiet else "SDL2", window_scale=3, debug=True, game_wrapper=True) 
    pyboy.set_emulation_speed(0) 
    tetris = pyboy.game_wrapper() 
    tetris.start_game() 
    

    After this, calling reset_game() does nothing. Even after sending a few WindowEvents and tick().

    opened by ogabrielluiz 9
  • Running on RaspberryPi 4B error

    Running on RaspberryPi 4B error

    [email protected]:~/PyBoy $ python3 -m pyboy ../mario.nes
    1399     __main__                       INFO
    The Game Boy controls are as follows:
    
    | Keyboard key | GameBoy equivalant |
    | ---          | ---                |
    | Up           | Up                 |
    | Down         | Down               |
    | Left         | Left               |
    | Right        | Right              |
    | A            | A                  |
    | S            | B                  |
    | Return       | Start              |
    | Backspace    | Select             |
    
    The other controls for the emulator:
    
    | Keyboard key | Emulator function       |
    | ---          | ---                     |
    | Escape       | Quit                    |
    | D            | Debug                   |
    | Space        | Unlimited FPS           |
    | Z            | Save state              |
    | X            | Load state              |
    | I            | Toggle screen recording |
    | ,            | Rewind backwards        |
    | .            | Rewind forward          |
    
    See "pyboy --help" for how to enable rewind and other awesome features!
    
    Segmentation fault
    

    [email protected]:~/PyBoy $ pip3 list
    Package           Version
    ----------------- -----------
    appdirs           1.4.3
    asn1crypto        0.24.0
    astroid           2.1.0
    asttokens         1.1.13
    automationhat     0.2.0
    beautifulsoup4    4.7.1
    blinker           1.4
    blinkt            0.1.2
    buttonshim        0.0.2
    Cap1xxx           0.1.3
    certifi           2018.8.24
    chardet           3.0.4
    Click             7.0
    colorama          0.3.7
    colorzero         1.1
    cookies           2.2.1
    cryptography      2.6.1
    cycler            0.10.0
    Cython            0.29.16
    decorator         4.3.0
    docutils          0.14
    drumhat           0.1.0
    ecdsa             0.13
    entrypoints       0.3
    envirophat        1.0.0
    ExplorerHAT       0.4.2
    Flask             1.0.2
    fourletterphat    0.1.0
    gpiozero          1.5.1
    guizero           0.6.0
    html5lib          1.0.1
    idna              2.6
    ipykernel         4.9.0
    ipython           5.8.0
    ipython-genutils  0.2.0
    isort             4.3.4
    itsdangerous      0.24
    jedi              0.13.2
    Jinja2            2.10
    jupyter-client    5.2.3
    jupyter-core      4.4.0
    keyring           17.1.1
    keyrings.alt      3.1.1
    kiwisolver        1.0.1
    lazy-object-proxy 1.3.1
    logilab-common    1.4.2
    lxml              4.3.2
    MarkupSafe        1.1.0
    matplotlib        3.0.2
    mccabe            0.6.1
    microdotphat      0.2.1
    mote              0.0.4
    motephat          0.0.3
    mypy              0.670
    mypy-extensions   0.4.1
    nudatus           0.0.4
    numpy             1.16.2
    oauthlib          2.1.0
    olefile           0.46
    pantilthat        0.0.7
    parso             0.3.1
    pathlib           1.0.1
    pexpect           4.6.0
    pgzero            1.2
    phatbeat          0.1.1
    pianohat          0.1.0
    picamera          1.13
    pickleshare       0.7.5
    picraft           1.0
    piglow            1.2.5
    pigpio            1.44
    Pillow            5.4.1
    pip               20.0.2
    prompt-toolkit    1.0.15
    psutil            5.5.1
    pyaes             1.6.1
    pyboy             1.0.0
    pycairo           1.16.2
    pycodestyle       2.4.0
    pycrypto          2.6.1
    pyflakes          2.0.0
    pygame            1.9.4.post1
    Pygments          2.3.1
    PyGObject         3.30.4
    pyinotify         0.9.6
    PyJWT             1.7.0
    pylint            2.2.2
    pyOpenSSL         19.0.0
    pyparsing         2.2.0
    PySDL2            0.9.7
    pyserial          3.4
    python-apt        1.8.4.1
    python-dateutil   2.7.3
    pyudev            0.22.0
    pyxdg             0.25
    pyzmq             17.1.2
    qtconsole         4.3.1
    rainbowhat        0.1.0
    requests          2.21.0
    requests-oauthlib 1.0.0
    responses         0.9.0
    roman             2.0.0
    RPi.GPIO          0.7.0
    rshell            0.0.27
    RTIMULib          7.2.1
    scrollphat        0.0.7
    scrollphathd      1.2.1
    SecretStorage     2.3.1
    semver            2.0.1
    Send2Trash        1.5.0
    sense-emu         1.1
    sense-hat         2.2.0
    setuptools        40.8.0
    simplegeneric     0.8.1
    simplejson        3.16.0
    six               1.12.0
    skywriter         0.0.7
    sn3218            1.2.7
    soupsieve         1.8
    spidev            3.4
    ssh-import-id     5.7
    thonny            3.2.6
    tornado           5.1.1
    touchphat         0.0.1
    traitlets         4.3.2
    twython           3.7.0
    typed-ast         1.3.1
    uflash            1.2.4
    unicornhathd      0.0.4
    urllib3           1.24.1
    wcwidth           0.1.7
    webencodings      0.5.1
    websockets        8.1
    Werkzeug          0.14.1
    wheel             0.32.3
    wrapt             1.10.11
    

    [email protected]:~/PyBoy $ python3 -V
    Python 3.7.3
    [email protected]:~/PyBoy $ uname  -a
    Linux raspberrypi 4.19.97-v7l+ #1294 SMP Thu Jan 30 13:21:14 GMT 2020 armv7l GNU/Linux
    [email protected]:~/PyBoy $
    [email protected]:~/PyBoy $ lsb_release -a
    No LSB modules are available.
    Distributor ID: Raspbian
    Description:    Raspbian GNU/Linux 10 (buster)
    Release:        10
    Codename:       buster
    [email protected]:~/PyBoy $
    [email protected]:~/PyBoy $ free -m
                  total        used        free      shared  buff/cache   available
    Mem:           1939         137        1018          34         783        1677
    Swap:            99           0          99
    [email protected]:~/PyBoy $
    

    Compile from your repository, and running with an nintendo game rom called : mario.nes Dose it support Nintendo or just fit for gameboy?(GB) ?

    opened by yoyojacky 8
  • Add get_scanline_parameters method

    Add get_scanline_parameters method

    Hi,

    Not sure if this is generally useful -- this PR adds a method to retrieve the _scanlineparameters from the window object. It's implemented only for the SDLWindow and children, and returns a list of lists, one per scanline, with the position(s) in the tilemap used for each scanline per frame.

    From experimentation, this seems to work well. There's a comment on get_screen_position with a TODO about retrieving the scanline parameters instead -- not sure if this meets that requirement.

    Happy to flesh this out a bit to get it up to scratch!

    opened by marginalhours 8
  • Openai interface

    Openai interface

    Hi Mads,

    As we talked on LinkedIn, I would like to push the openai interface to this repo! To test it, you can try it from Source/main_openai.py(https://github.com/Rowing0914/PyBoy/blob/openai_interface/Source/main_openai.py)!!

    Thanks

    opened by Rowing0914 7
  • About TileViews

    About TileViews

    First, thanks for answering me before. Now, this is more a doubt than an issue... When I use the tileview I get two windows, one for the "current map without the player" and other for the HUD (the remaining time bar, power, and such). At the moment I can retreive the "on screen" sprites but I cant get the sprites in the tileviews and I need to get the sprites near the racer (in the tileview but not on screen). How should I proceed? This is what I see: https://i.imgur.com/3yrvuSg.png

    opened by ccokee 7
  • Modular Plugin Manager

    Modular Plugin Manager

    Allows for modularly adding plugins (game wrappers) to PyBoy. This is helpful so users can create their own game wrappers and add them without them having to be officially supported.

    There are still some Cython type definition things missing as that's not my specialty, but besides that, I'd like to hear your thoughts.

    P.S. my code formatter accidentally added some spaces between plus signs, so if you have an auto code formatter, you might want to run it on this branch.

    opened by hexiro 3
  • Add easy way to add plugins (game wrappers) to Plugin Manager

    Add easy way to add plugins (game wrappers) to Plugin Manager

    Hello! I've been attempted to add the WIP Pokemon Red Plugin to my local project, but I'm finding it's quite difficult due to the way the PyBoy and PluginManager classes are structured. Would you be willing to accept a PR that makes the design more modular, and allows the user to something like the following?

    game = pyboy.PyBoy(PATH, game_wrapper=True)
    game.plugin_manager.add_plugin(PLUGIN)
    

    Additionally, inside the plugin manager, there is a lot of .enabled() calls from plugins, but it appears as though that function will return the same result everytime. This can be seen by the fact that the PluginManager class has extra attributes to cache the result for all of them.

    # example:
    self.window_sdl2 = WindowSDL2(pyboy, mb, pyboy_argv)
    self.window_sdl2_enabled = self.window_sdl2.enabled()
    self.window_open_gl = WindowOpenGL(pyboy, mb, pyboy_argv)
    self.window_open_gl_enabled = self.window_open_gl.enabled()
    

    I personally think this would be structured better if the enabled function in each plugin was changed into a _enabled helper function that is called in the initializer and set to an enabled attribute, so the attribute .enabled would be available and these extra (plugin name)_enabled attributes wouldn't be needed.

    If there's conflicts with evaluating enabled state before hand, that's okay as that doesn't impact the user at the end of the day. What does though, is the ability to add custom plugins, so let me know what you think about these suggestions! :)

    opened by hexiro 11
  • Make API to extract sound stream

    Make API to extract sound stream

    We don't current have a way to get the sound output through the API. This could for example be in the form of a buffer to copy at every frame.

    This might also require some work to separate the sound implementation from SDL2.

    enhancement good first issue 
    opened by Baekalfen 4
Releases(v1.5.3)
Owner
Mads Ynddal
Bæk-alfen ― M.Sc. Computer Science, University of Copenhagen
Mads Ynddal
A simple hangman game for beginners trying to learn python

Hangman Game This is a simple hangman game for beginners trying to learn python. I have tried to keep it as simply as possible. Sample output Here is

1 Oct 13, 2021
Online battleships game on python and JS

Battleships Online battleships game Using websockets to connect to the client. SQLite database for storing account data and game logs (for players top

5 Nov 11, 2021
This is a python interactive story game that I made to show off what I've learnt in python coding for a month

Purpose The files in this repository are for that of a story game created with python version 3.8.5 The purpose of this project was to get familiar wi

0 Dec 30, 2021
Snake Game in Python

Snake game is one of the most popular arcade games of all time. In this game, the main objective of the player is to catch the maximum number of fruits without hitting the wall or itself.

Pavan Ananth Sharma 4 Jul 05, 2022
A Pygame Hangman Game coded in Python 3. Run Hangman.py in a terminal if you have Python 3

Hangman A Pygame Hangman Game coded in Python 3. Run python3 Hangman.py in a terminal if you have Python 3.

1 Dec 24, 2022
Crazy fast kahoot game flooder with a GUI and multi OS support.

kahoot flooder Crazy fast kahoot game flooder with a GUI and multi OS support. Made in python using tkinter and KahootPY with toast notifications. Req

Ben Tettmar 1 Apr 09, 2022
A puzzle game coded entirely in Python.

Pyzzle A puzzle game coded entirely in Python. This is a school project created by me, Mohit Singh. The .exe file, created from the main.py script, is

Mohit Singh 1 Mar 19, 2022
SnailJumper - A game that is developed as an assignment for Computer Intelligence course

Snail jumper Neuroevolution game assignment. Fall 2021 - Computer Intelligence.

Soroush Mehraban 22 Aug 22, 2022
Flappy bird using Pygames

flappy-bird Esse é um jogo que eu fiz utilizando a biblioteca de jogos do Python

Leandro Henrique 2 Jan 05, 2022
Snake game made in python with the pygame library.

Pygame snake Snake game made in python with the pygame library. Requirements pip pygame Pygame Installation On the command line, type: pip install pyg

Ayza 3 Oct 02, 2022
Minesweeper clone with 3 modes of difficulty, UI scaling and custom games feature.

Insect Sweeper Minesweeper clone with 3 modes of difficulty, UI scaling and custom games feature. Mines are replaced with random insects that a player

Piotr Data 1 Nov 05, 2021
Launch any Heroic-Games-Launcher game using bash scripts without having to open Heroic.

HeroicBashLauncher Ever wanted to launch your EGS games installed through Heroic Games Launcher directly from the terminal, Lutris or any other fronte

288 Dec 27, 2022
Abandoned plan for a clone of the old Flash game Star Relic

space-grid When I was in middle school, I was a fan of the Flash game Star Relic (no longer playable in modern browsers, but it works alright in Flash

Radon Rosborough 3 Aug 23, 2021
Implementation of the Spider-Man Game

Projeto FPRO FPRO/LEIC, 2021/22 Francisco Campos (up202108735) 1LEIC08 Objetivo Criar um clone do clássico Spider-Man em Pygame... Repositório de códi

1 Dec 24, 2021
I automated the lumberjack game on telegram, by recognising pixels and using pyautogui module

Lumberjack Automated: @gamebot According to the official documentation, @gamebot is a demo bot for the Telegram Gaming Platform.` It provides some sam

Yew Chong 1 Dec 07, 2021
Among Us Editor written in Python, for newer versions of the game

Among Us Editor Remake Among Us Editor written in Python, for newer versions of the game. Credits GUI Code by Vresod Data dumping and some GUI code by

Vresod 7 Nov 18, 2022
We tried to recreate this classic game using python physics libraries.

We tried to recreate this classic game using python physics libraries. The result is certainly hilarious but enjoyable. One of my very first physics application.

Delwys Glokpor 2 Dec 12, 2021
This a Chess PGN saver which allows you to save your game pgns, in a .pgn file

PGN Saver This a Chess PGN saver which allows you to save your game pgns, in a .pgn file This can be a very useful tool for the people using chessbase

3 Jan 06, 2022
N-Queens game made using pygame library

N-Queens N-Queens game using pygame for AIML201 Testing: 1. git clone https://github.com/python-game-dev/N-Queens.git 2. cd N-Queens 3. python main.py

1 Sep 24, 2021
Tictactoe py tkinter canvas - Tic Tac Toe written in Python 3 with tkinter mainly using canvas

Python 3 Tic Tac Toe with tkinter This is a tkinter version of my Tic Tac Toe ga

Bojan Adzic 1 Jan 09, 2022