Metadata-Version: 2.4
Name: pyboy
Version: 2.9.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: description
Dynamic: description-content-type
Dynamic: license-file

<p align="center">
<img src="https://raw.githubusercontent.com/Baekalfen/PyBoy/v2.9.0/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="https://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="https://raw.githubusercontent.com/Baekalfen/PyBoy/v2.9.0/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="https://raw.githubusercontent.com/Baekalfen/PyBoy/v2.9.0/extras/README/1.gif" width="250">
      </td>
      <td align="center">
        <img src="https://raw.githubusercontent.com/Baekalfen/PyBoy/v2.9.0/extras/README/pinball.gif" width="250">
      </td>
      <td align="center">
        <img src="https://raw.githubusercontent.com/Baekalfen/PyBoy/v2.9.0/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. Use the fast-mode to allow less accurate emulation, in exchange for performance: `p = PyBoy(..., fast_mode=True)`.

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 25th 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 25
      </td>
      <td align="center">
        No rendering
      </td>
    </tr>
    <tr>
      <td>
      x625 realtime
      </td>
      <td>
      x970 realtime
      </td>
      <td>
      x1014 realtime
      </td>
    </tr>
<tr> <!-- Markdown/HTML broken after this -->
<td>

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

```
</td>
<td >

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

```
</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 1,014 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 8,112 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).
