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
Meu primeiro jogo desenvolvido em Python, usado o módulo do Pygame

📖 Sobre Esse repositório é dedicado ao meu primeiro jogo feito em Python, utilizando o módulo do pygame. O jogo foi desenvolvido seguindo o tutorial

Michael Douglas 0 May 06, 2022
MinMax Algo , Python

Write a PYTHON program to play the game of TIC-TAC-TOE on a 3×3 board with alternate inputs from user and computer.

Naman Anand 1 Nov 26, 2021
Simple python program to simulate Conway's game of life with custom variables.

ConwaysGameOfLife Simple python program to simulate Conway's game of life with custom variables. Custom Variables Grid-size : Change the size of the p

davidgasinski 1 Oct 28, 2021
This is a 2D Link to the Past-esque game made using Python 3.2.5 and pygame 1.9.2

Queen-s-Demise Queen's Demise This is a 2D Link to the Past-esque game made using Python 3.2.5 and pygame 1.9.2 I made this for a game development cla

Zoey 1 Dec 15, 2021
PyCharge is an open-source computational electrodynamics Python simulator

PyCharge PyCharge is an open-source computational electrodynamics Python simulator that can calculate the electromagnetic fields and potentials genera

Matthew Filipovich 28 Jan 03, 2023
XO game with server, client and visualizer for AI bots.

XO game with server, client and visualizer for AI bots.

Ali 4 Jul 14, 2022
Simulate a Monopoly game to generate the probabilities of landing on each square.

Monopoly-Probabilities Simulate a Monopoly game to generate the probabilities of landing on each square. While this project originally was inspired by

George Waters 2 Jan 04, 2023
uses Entropy to find the best next guess for Wordle, given the color clues

WordleSolver uses Entropy to find the best next guess for Wordle, given the color clues use player.py and enter in the string for the suggested clue w

Steve Earth 1 Jan 26, 2022
A minecraft bedrock server software written in python (3.X)

Podrum README also available in: English 🇺🇸 Français 🇫🇷 Deutsch 🇩🇪 Español 🇪🇸 Tiếng Việt 🇻🇳 Italiana 🇮🇹 Русский 🇷🇺 中文 🇨🇳 Is a Minecraf

Podrum 53 Nov 11, 2022
You can play TicTacToe with the engine running UI.py with python3

TicTacToe An "Engine" for TicTacToe You can play TicTacToe with the engine running UI.py with python3. The file engine.py is designed so you can make

Ahnaf Syndeed 3 Feb 20, 2022
Launcherpi - Minecraft Launcher for Raspberry Pi computers

launcherpi Minecraft Launcher for Raspberry Pi computers. ASLO BIG THANKS TO KLO

8 Sep 24, 2022
An environment to run atari-like games in VGDL.

vgdl An environment to run atari-like games in VGDL. Requirements python = 3.6 Installation pip install -r requirements.txt Usage # Create an enviro

Sergio Arnaud Gomez 1 Dec 24, 2021
Dota2 AI bot - Last Order Dota2 Solo AI

Last Order Dota2 Solo AI 该库提供一个由强化学习训练出的Dota2影魔solo智能体。该智能体通过自我对战的训练方式训练,从随机动作开始学习复杂的策略。玩家可以与该智能体进行影魔solo对战。 对战规则 1.物品方面不可以出凝魂之露,灵魂之戒,魔瓶,真眼。 2.不可以吃符,或

bilibili 365 Jan 05, 2023
Arcade-like space shooter game written entirely in python

E.T.-Attack Arcade-like space shooter game written entirely in python Project description A space shooter game - inspired by the legendary game Space

Sven Eschlbeck 2 Dec 17, 2022
Wordlebot - A simple Wordle puzzle solver in python

WordleBot A simple search-based puzzle solver for Wordle, built in Python. Inspi

Rob Kimball 2 Jan 27, 2022
An ongoing process to make a physics engine using python.

Simple_Physics_Engine An ongoing process to make a physics engine using python. I am using this goal as a way to learn python in and out. I am trying

Jon Sherrick 1 Jan 18, 2022
Automatic game data translator for RPGMaker-MV

RPGMaker-MV Translator 🕹️ 🎮 Use AI to translate all the dialogs and texts of your RPGMaker automatically. 👊 You worked hard to make your game, now

Davide Liu 11 Dec 26, 2022
A Simple 2048 Game Built Using Python

Game 2048_Python Dựa trên trò chơi nổi tiếng 2048 của Gabriele Cirulli. Mục tiêu của trò chơi là trượt các khối được đánh số trên một lưới để kết hợp

Le Phuong Anh 3 Dec 13, 2021
A fully automated system that transforms Twitch clips into gaming compilations

A fully automated system that transforms Twitch clips into gaming compilations Authors: Christian C., Moritz M., Luca S. Related Projects: Neural Netw

215 Dec 27, 2022
Made to help you create UI using pygame in python, gonna add way more to this project

Pygame visualizer Made to help you create UI using pygame in python, gonna add way more to this project. As of now, this is only hours worth of work.

Ayza 2 Feb 08, 2022