<p align="center">
  <img src="https://raw.githubusercontent.com/williamckha/PyBoyAdvance/master/assets/pyboy_advance.svg" alt="PyBoy Advance" width="240">
</p>

---

PyBoy Advance is a Game Boy Advance emulator written in Python, with [Cython](https://cython.org/) declarations for compiling to C.

>[!WARNING]
> This is experimental software and under development. Some GBA hardware features are not yet implemented and games may not function properly. 

## Getting started

Install PyBoy Advance with `pip`:

```bash
$ pip install pyboy-advance
```

You will need to provide a Game Boy Advance BIOS. Normatt's open source BIOS is supported and
available [here](https://github.com/Nebuleon/ReGBA/blob/master/bios/gba_bios.bin).

Launch PyBoy Advance from the terminal:

```bash
$ pyboy_advance --bios /path/to/bios.bin game_rom.gba
```

Or import and use it in your Python scripts:

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance(rom="game_rom.gba", bios="/path/to/bios.bin")
emulator.run()
```

## Performance

PyBoy Advance is written in "pure" Python and can technically be run with [PyPy](https://pypy.org/) or even CPython (though games 
will be virtually unplayable with the latter). To achieve practical performance, we use [Cython](https://cython.org/) 
to statically type our Python code and generate efficient C code from it. This allows us to build PyBoy Advance as a 
Python C extension module, significantly improving execution speed.

## Screenshots

<p align="center">
  <img src="https://raw.githubusercontent.com/williamckha/PyBoyAdvance/master/assets/screenshot_kirby.png" alt="Screenshot of PyBoy Advance running Kirby: Nightmare in Dream Land" width="400">
</p>

## Acknowledgements

- [Cython](https://cython.org/) compiler for Python. Thanks to the [development team and contributors](https://cython.org/#community)!
- [GBATEK](https://problemkaputt.de/gbatek.htm) by Martin Korth, the king of GBA hardware documentation
- [ARM7TDMI Technical Reference Manual](https://developer.arm.com/documentation/ddi0210/c/)
- [CowBite Virtual Hardware Specifications](https://www.cs.rit.edu/~tjh8300/CowBite/CowBiteSpec.htm) by Tom Happ
- [Tonc](https://www.coranac.com/tonc/text/toc.htm) by Jasper Vijn
- Excellent reference GBA emulators:
    - [mGBA](https://mgba.io/) by Vicki Pfau (endrift)
    - [NanoBoyAdvance](https://github.com/nba-emu/NanoBoyAdvance) by Fleroviux
    - [Hades](https://github.com/hades-emu/Hades) by Arignir
    - [RustBoyAdvance-NG](https://github.com/michelhe/rustboyadvance-ng/) by Michel Heily
- [PyBoy](https://github.com/Baekalfen/PyBoy) by Mads Ynddal (Baekalfen), the original inspiration for this project!
