# 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`](https://github.com/Farama-Foundation/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](https://vimm.net/vault/5625) is provided, but more will be added in the future.
A gym environment can be created as follows:
```python
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:
```bash
pip install pygba
```
You'll also need to install [mGBA](https://mgba.io/) 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:
```bash
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](https://github.com/mgba-emu/mgba/#compiling), 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:
```bash
git clone https://github.com/mgba-emu/mgba.git
cd mgba
```
- **Unix**:
On Unix-based systems, run the following commands:
```bash
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr -DBUILD_PYTHON=ON ..
make
sudo make install
```
- **macOS**:
On macOS, additional dependencies are required:
```bash
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](https://github.com/mgba-emu/mgba/#windows-developer-building).
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).
Raw data
{
"_id": null,
"home_page": "",
"name": "pygba",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "gba,mgba,emulator,gymnasium,reinforcement-learning",
"author": "Dimitri von R\u00fctte",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# PyGBA\n\nA Python wrapper around the Game Boy Advance emulator mGBA with built-in support for gymnasium environments.\n\n\n## Usage\n\nPyGBA 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`](https://github.com/Farama-Foundation/Gymnasium) environment for reinforcement learning.\n\nWhile 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](https://vimm.net/vault/5625) is provided, but more will be added in the future.\n\nA gym environment can be created as follows:\n```python\nfrom pygba import PyGBA, PyGBAEnv, PokemonEmerald\n\nrom_path = \"path/to/pokemon_emerald.gba\"\ngba = 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\n\ngame_wrapper = PokemonEmerald() # optionally customize the reward function by passing additional arguments\nenv = PyGBAEnv(gba, game_wrapper)\n```\n\n\n## Installation\n\nInstall PyGBA with pip using:\n```bash\npip install pygba\n```\n\nYou'll also need to install [mGBA](https://mgba.io/) 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.\n\n\n### Installing mGBA\n\nMGBA PACKAGE IS CURRENTLY BROKEN (help wanted)\n\nFor Python >= 3.10 on Linux and macOS, you can use the pre-built wheels from here:\n```bash\npip install mgba\n```\n\nFor Windows and older Python versions, you'll need to build mGBA from source. See the the next section for instructions.\n\n### Building mGBA from source\n\nOfficial installation instructions can be found [here](https://github.com/mgba-emu/mgba/#compiling), but here's a quick summary.\nThe important detail is that Python bindings have to be enabled by passing `-DBUILD_PYTHON=ON` to CMake.\n\nFirst, clone the mGBA repository:\n```bash\ngit clone https://github.com/mgba-emu/mgba.git\ncd mgba\n```\n\n- **Unix**:\n On Unix-based systems, run the following commands:\n ```bash\n mkdir build\n cd build\n cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr -DBUILD_PYTHON=ON ..\n make\n sudo make install\n ```\n\n- **macOS**:\n On macOS, additional dependencies are required:\n ```bash\n brew install cmake ffmpeg libzip qt5 sdl2 libedit lua pkg-config\n mkdir build\n cd build\n cmake -DCMAKE_PREFIX_PATH=`brew --prefix qt5` -DBUILD_PYTHON=ON ..\n make\n sudo make install\n ```\n Note: If both `qt` and `qt5` are installed you might run into issues. If that's the case, try uninstalling `qt`.\n\n- **Windows**:\n Please follow the official instructions [here](https://github.com/mgba-emu/mgba/#windows-developer-building).\n\nAfter compiling mGBA, the Python bindings should be built at `build/python/lib.{platform}-{architecture}-cpython-{version}/mgba`.\nTo use it in your Python code, you'll need to add it to your `PYTHONPATH` environment variable.\n\nYou can check if the bindings were built and installed correctly by running `python -c \"import mgba\"` (should output nothing).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python wrapper around the Game Boy Advance emulator mGBA with built-in support for gymnasium environments.",
"version": "0.2.9",
"project_urls": {
"github": "https://github.com/dvruette/pygba"
},
"split_keywords": [
"gba",
"mgba",
"emulator",
"gymnasium",
"reinforcement-learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3a769fb73ebdc108ba19f1289fc5d4bf06eb500371f6e4ffc38b6477431814a",
"md5": "3c911d124b1b1bbdbaef24d1b1389298",
"sha256": "0ffaee06ac484b7785681ccc5d42f0aa5f9e9f59b3eb429797c8952c7df8c243"
},
"downloads": -1,
"filename": "pygba-0.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c911d124b1b1bbdbaef24d1b1389298",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16995,
"upload_time": "2023-11-14T10:16:23",
"upload_time_iso_8601": "2023-11-14T10:16:23.437743Z",
"url": "https://files.pythonhosted.org/packages/b3/a7/69fb73ebdc108ba19f1289fc5d4bf06eb500371f6e4ffc38b6477431814a/pygba-0.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-14 10:16:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dvruette",
"github_project": "pygba",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pygba"
}
JSON
