Tuesday Tooling: PyBoy - Python Gameboy emulator

With a fresh set of AA batteries and my trusty Gameboy I could game for hours in the car!

This weeks #TuesdayTooling was sent in by a tweet from Brian Linuxing Thanks Brian!

So what is it?

A Nintendo Gameboy emulator written in Python, yup you read that right!

No seriously why?

This project was created as part of a report on emulating computer hardware by Troels Ynddal, Mads Ynddal and Asger Lund Hansen at the University of Copenhagen

The project page for PyBoy is https://github.com/Baekalfen/PyBoy

The emulator is not just a means to play games, it also provides a programmatic interface to interact with the Gameboy. Yes we can control and learn more about a game using Python.

Hi reader!

I never put my blog posts behind paywall or pop ups because quite frankly that is annoying and prevents anyone from accessing the content. I will always keep my blog content free of charge. But I do ask that if you are able and willing, that you buy me a "coffee" as it helps me to pay for hosting this blog, and to buy stuff to hack from Poundshops / Dollar Stores / Aliexpress which are used in free projects and reviews on this blog. It is You dear reader who make this possible, and I am immensely grateful for your support.
Thanks!

So how do I install it?

Linux
I installed PyBoy on Ubuntu 20.04.
First I had to install Simple DirectMedia Layer, which provides low level access to keyboard and graphics hardware. In a terminal I typed.

sudo apt install libsdl2-dev

Then I installed PyBoy using pip3.

pip3 install pyboy

Mac osX
You will need to have brew installed before continuing. and then update brew and install python3 and Simple DirectMedia Layer.

brew update
brew install python3 sdl2

Then update pip3 and install PyBoy.

python3 -m pip install --upgrade pip
python3 -m pip install pyboy

Windows and Raspberry Pi
Windows 10 and Raspberry Pi users will need to refer to the official installation instructions

So how do I use it?

PyBoy can be used in two different ways.
First we can run pyboy from the terminal / command line and pass a few arguments. But at the most basic level we call pyboy and then give it the filename of the game that we wish to play.

pyboy coolgame.gb

Hey! Where can I get games from?
Ok here is the legal bit. Game ROMs (data dumps of cartridges) are under copyright despite being old. Where to find ROMs is up to you and your search engine. If you get into trouble, then it is not my fault.

So how do I use it with Python 3?

Open your favourite Python 3 editor and create a new file called pyboy-test.py then enter this code.

from pyboy import PyBoy, WindowEvent
pyboy = PyBoy("/path/to/your/game.gb")
while not pyboy.tick():
    pass

Running this code will start the game.

Can I integrate this into my Python code?

Sure!
Here is a really simple piece of code. It asks the user if they would like to play a game, if they answer y then the game plays. Answer with anything else, and the program exits.

from pyboy import PyBoy, WindowEvent
choice = input("Would you like to play Zelda? Answer y or n: ")
if choice == "y":
    pyboy = PyBoy("/home/les/Games/zelda.gb")
    while not pyboy.tick():
        pass
else:
    print("Ok bye bye")

So how do I play a game?

The controls are

Arrow keys for movement.
Enter = Start (Pause)
Backspace = Select
A = A
S = B
Spacebar = Unlock the FPS (makes games run CRAZY FAST)

But! There is no sound! This is will be added in a future release.

So is there anything else?

Of course! We can use PyBoy to create bots to play our games and we can dig into the game and learn more about how it works. Full details are here.

Happy Hacking!