Metadata-Version: 2.4
Name: pyboy
Version: 2.8.0
Summary: Game Boy emulator written in Python
Author-email: Mads Ynddal <mads@ynddal.dk>
License-Expression: LGPL-3.0-only
Project-URL: Homepage, https://github.com/Baekalfen/PyBoy
Project-URL: Documentation, https://docs.pyboy.dk/index.html
Project-URL: Repository, https://github.com/Baekalfen/PyBoy.git
Keywords: gameboy,game boy,emulator,cython,pypy
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy
Requires-Dist: pysdl2
Requires-Dist: pysdl2-dll
Provides-Extra: all
Requires-Dist: pyopengl; extra == "all"
Requires-Dist: glfw; extra == "all"
Requires-Dist: PyOpenAL; extra == "all"
Requires-Dist: markdown<3.10; extra == "all"
Requires-Dist: gym; extra == "all"
Provides-Extra: docs
Requires-Dist: sphinx>=8; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

<p align="center">
<img src="extras/README/pyboy10.svg" width="800">
</p>

<p align="center"><strong>If you have any questions, or just want to chat, <a href="https://discord.gg/wUbag3KNqQ">join us on Discord</a>.</strong></p>

<p align="center">
<a href="https://trendshift.io/repositories/3811?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-3811" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/3811" alt="Baekalfen%2FPyBoy | Trendshift" width="250" height="55"/></a>
</p>


<!---
Generate GIF with the layout and captions
-->
<table>
  <tbody>
    <tr>
      <td colspan=2 align="center"><a href=https://github.com/PWhiddy/PokemonRedExperiments>Train RL agents to play Pokemon Red</a>
      </td>
      <td align="center"><a href=https://docs.pyboy.dk/plugins/index.html#rewind-time>Rewind any game</a><br>
      </td>
    </tr>
    <tr>
      <td colspan=2 align="center">
        <div align="center">
        <a href="http://www.youtube.com/watch?feature=player_embedded&v=DcYLT37ImBY" target="_blank">
        <img src="http://img.youtube.com/vi/DcYLT37ImBY/maxresdefault.jpg" alt="Watch the video" width="500" border="10" />
        <!-- <img src="http://img.youtube.com/vi/DcYLT37ImBY/hqdefault.jpg" alt="Watch the video" width="500" border="10" /> -->
        </a>
        <!-- https://www.youtube.com/watch?v=DcYLT37ImBY -->
        <!-- <img src="extras/README/8.gif" width="400"><br> -->
        </div>
      </td>
      <td align="center">
        <img src="extras/README/5.gif" width="250">
      </td>
    </tr>
    <tr>
      <td align="center">Play the classics<br>
      </td>
      <td align="center"><a href=https://github.com/NicoleFaye/PokemonPinballRL>Create your own AI</a><br>
      </td>
      <td align="center"><a href=https://github.com/Baekalfen/PyBrosAI>Teach Mario to win</a><br>
      </td>
    </tr>
    <tr>
      <td align="center">
        <img src="extras/README/1.gif" width="250">
      </td>
      <td align="center">
        <img src="extras/README/pinball.gif" width="250">
      </td>
      <td align="center">
        <img src="extras/README/pybrosai.gif" width="250">
      </td>
    </tr>
  </tbody>
</table>

Getting Started
===============
The instructions are simple:

```sh
$ pip install pyboy
```

For platform-specific instructions, see the
[installation guide](https://docs.pyboy.dk/wiki/development/index.html).

Now you're ready! Either use PyBoy directly from the terminal
```sh
$ pyboy game_rom.gb
```

Or use it in your Python scripts:
```python
from pyboy import PyBoy
pyboy = PyBoy('game_rom.gb')
while pyboy.tick():
    pass
pyboy.stop()
```

<!-- Or using the context manager:
```python
from pyboy import PyBoy
with PyBoy('game_rom.gb') as pyboy:
    while pyboy.tick():
        pass
``` -->


The API
=======

If you are looking to make a bot or AI, then these resources are a good place to start:
 * [PyBoy API Documentation](https://docs.pyboy.dk/api/index.html)
 * [Using PyBoy with Gym](https://docs.pyboy.dk/wiki/using-pyboy-with-gym.html)
 * [Example: Kirby](https://docs.pyboy.dk/wiki/examples/kirby.html)
 * [Example: Tetris](https://docs.pyboy.dk/wiki/examples/tetris.html)
 * [Example: Super Mario Land](https://docs.pyboy.dk/wiki/examples/super-mario-land.html)
 * [Code Examples](https://github.com/Baekalfen/PyBoy/tree/master/extras/examples)
 * [Discord](https://discord.gg/wUbag3KNqQ)


When the emulator is running, you can easily access [PyBoy's API](https://docs.pyboy.dk/api/index.html):
```python
pyboy.set_emulation_speed(0) # No speed limit
pyboy.button('down')
pyboy.button('a')
pyboy.tick() # Process at least one frame to let the game register the input
value_of_interest = pyboy.memory[0xC345]

pil_image = pyboy.screen.image
pil_image.save('screenshot.png')
```

The [documentation homepage](https://docs.pyboy.dk/) shows how to interface with PyBoy from your own project.

Performance
===========

Performance is a priority for PyBoy, to make your AI training and scripts as fast as possible.

The easiest way to improve your performance, is to skip rendering of unnecessary frames. If you know your
character takes X frames to move, or the game doesn't take input every frame, you can skip those to potentially triple
your performance. All game logic etc. will still process.

Here is a simple comparison of rendering every frame, rendering every 15th frame, and not rendering any frames (higher is better). See [`pyboy.tick`](https://docs.pyboy.dk/#pyboy.PyBoy.tick) for how it works. Your performance will depend on the game.

<table>
  <tbody>
    <tr>
      <td align="center">
        Full rendering
      </td>
      <td align="center">
        Frame-skip 15
      </td>
      <td align="center">
        No rendering
      </td>
    </tr>
    <tr>
      <td>
      x124 realtime
      </td>
      <td>
      x344 realtime
      </td>
      <td>
      x395 realtime
      </td>
    </tr>
<tr> <!-- Markdown/HTML broken after this -->
<td>

```python
for _ in range(target):
    pyboy.tick()

```
</td>
<td >

```python
for _ in range(target//15):
    pyboy.tick(15)

```
</td>
<td >

```python
pyboy.tick(target, False)

```
</td>
</tr>
  </tbody>
</table>

The Game Boy was originally running at 60 frames per second, so a speed-up of 100x realtime is 6,000 frames per
second. And trivially from the table above, simulating 395 hours of gameplay can be done in 1 hour with no rendering.

It's also recommended to be running multiple instances of PyBoy in parallel. On an 8-core machine, you could potentially
do 3160 hours of gameplay in 1 hour.

Contributing
============
For development setup, testing, and pull request guidance, see the
[Contributing guide](https://docs.pyboy.dk/wiki/development/contributing.html).
You can browse [open issues](https://github.com/Baekalfen/PyBoy/issues) or
discuss larger proposals on the [PyBoy Discord](https://discord.gg/wUbag3KNqQ).
