PyGBA

A Python wrapper around the Game Boy Advance emulator mGBA with built-in support for gymnasium environments.

Usage

PyGBA is designed to be used by bots/AI agents. It provides an easy-to-use interface to interact with the emulator as well as a gymnasium environment for reinforcement learning.

While any GBA ROM can be run out-of-the box, if you want to do reward-based reinforcement learning, you might want to use a game-specific wrapper that provides a reward function. Currently, only a wrapper for Pokemon Emerald is provided, but more will be added in the future.

A gym environment can be created as follows:

from pygba import PyGBA, PyGBAEnv, PokemonEmerald

rom_path = "path/to/pokemon_emerald.gba"
gba = PyGBA.load(rom_path, autoload_save=True)  # if autoload_save is True, a save file will be loaded if one exists next to the ROM

game_wrapper = PokemonEmerald()  # optionally customize the reward function by passing additional arguments
env = PyGBAEnv(gba, game_wrapper)

Installation

Install PyGBA with pip using:

pip install pygba

You'll also need to install mGBA with Python bindings. By default, mGBA is installed without Python bindings, so until the situation is improved, you'll need to build mGBA from source.

Installing mGBA

MGBA PACKAGE IS CURRENTLY BROKEN (help wanted)

For Python >= 3.10 on Linux and macOS, you can use the pre-built wheels from here:

pip install mgba

For Windows and older Python versions, you'll need to build mGBA from source. See the the next section for instructions.

Building mGBA from source

Official installation instructions can be found here, but here's a quick summary. The important detail is that Python bindings have to be enabled by passing -DBUILD_PYTHON=ON to CMake.

First, clone the mGBA repository:

git clone https://github.com/mgba-emu/mgba.git
cd mgba

• Unix: On Unix-based systems, run the following commands:

  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr -DBUILD_PYTHON=ON ..
  make
  sudo make install
  

• macOS: On macOS, additional dependencies are required:

  brew install cmake ffmpeg libzip qt5 sdl2 libedit lua pkg-config
  mkdir build
  cd build
  cmake -DCMAKE_PREFIX_PATH=`brew --prefix qt5` -DBUILD_PYTHON=ON ..
  make
  sudo make install
  

  Note: If both qt and qt5 are installed you might run into issues. If that's the case, try uninstalling qt.

• Windows: Please follow the official instructions here.

After compiling mGBA, the Python bindings should be built at build/python/lib.{platform}-{architecture}-cpython-{version}/mgba. To use it in your Python code, you'll need to add it to your PYTHONPATH environment variable.

You can check if the bindings were built and installed correctly by running python -c "import mgba" (should output nothing).