Experimental GDB support

.gitignore

@@ -1,3 +1,6 @@
+# macOS
+.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -38,11 +41,6 @@ docs/_build/
 # PyBuilder
 target/
 
-.DS_Store
-Report/*.pdf
-Report/*.aux
-Report/*.log
-
 # Don't want to see any ROMs being uploaded
 # This project is not for pirating games!
 *.gb
@@ -64,6 +62,7 @@ test_data.encrypted
 tetris/
 PyBoy-RL/
 
+# Cython
 /pyboy/**/*.c
 /pyboy/**/*.h
 /pyboy/**/*.html
@@ -80,29 +79,22 @@ PyBoy-RL/
 /site-packages
 /share
 
-# LaTeX files
-Projects/Projects.aux
-Projects/Projects.bbl
-Projects/Projects.blg
-Projects/Projects.out
-Projects/Projects.log
-
-bootrom/bootrom*.map
-bootrom/bootrom*.obj
-bootrom/bootrom*.sym
-bootrom/bootrom*.gb
-bootrom/logo.asm
-bootrom/pyboy.png
-bootrom/PYBOY_ROM.bin
+# Bootrom
+extras/bootrom/bootrom*.map
+extras/bootrom/bootrom*.obj
+extras/bootrom/bootrom*.sym
+extras/bootrom/bootrom*.gb
+extras/bootrom/logo.asm
 
-default_rom/default_rom.map
-default_rom/default_rom.obj
-default_rom/default_rom.sym
+extras/default_rom/default_rom.map
+extras/default_rom/default_rom.obj
+extras/default_rom/default_rom.sym
 !default_rom.gb
 
 test.replay
 
 /mooneye/
 /blargg/
 /GB Tests/
-/SameSuite/
+/SameSuite/
+.vscode/

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-exclude: opcodes.py
+exclude: (opcodes.py|manager.py|manager.pxd)
 repos:
 - repo: https://github.com/myint/unify
   rev: v0.5

CONTRIBUTING.md

@@ -3,7 +3,7 @@ Any contribution is appreciated. The currently known errors are registered in th
 For the more major features, there are the following that you can give a try. They are also described in more detail in the [project list](https://github.com/Baekalfen/PyBoy/raw/master/extras/Projects/Projects.pdf):
 * Color
 * Link Cable
-* _(Experimental)_ AI - use the `botsupport` or game wrappers to train a neural network
+* _(Experimental)_ AI - use the API or game wrappers to train a neural network
 * _(Experimental)_ Game Wrappers - make wrappers for popular games
 
 If you want to implement something which is not on the list, feel free to do so anyway. If you want to merge it into our repo, then just send a pull request and we will have a look at it.

README.md

@@ -4,48 +4,97 @@
 
 __If you have any questions, or just want to chat, [join us on Discord](https://discord.gg/Zrf2nyH).__
 
-
-It is highly recommended to read the [report](https://github.com/Baekalfen/PyBoy/raw/master/extras/PyBoy.pdf) to get a light introduction to Game Boy emulation. _But do be aware, that the Python implementation has changed a lot_. The report is relevant, eventhough you want to contribute to another emulator, or create your own.
-
-If you've read the report and want more explicit details, have a look at the [Pan Docs](http://bgb.bircd.org/pandocs.htm).
-
-__If you are looking to make a bot or AI__, you can find all the external components in the [PyBoy Documentation](https://baekalfen.github.io/PyBoy/index.html). There is also a short example on our Wiki page [Scripts, AI and Bots](https://github.com/Baekalfen/PyBoy/wiki/Scripts,-AI-and-Bots) as well as in the [examples directory](https://github.com/Baekalfen/PyBoy/tree/master/extras/examples). If more features are needed, or if you find a bug, don't hesitate to make an issue here on GitHub, or post on our [Discord channel](https://discord.gg/Zrf2nyH).
-
+Sources for making AI and bots
+==============================
+If you are looking to make a bot or AI, then these resources is a good place to start:
+ * [PyBoy API Documentation](https://baekalfen.github.io/PyBoy/index.html)
+ * [Wiki Pages](https://github.com/Baekalfen/PyBoy/wiki/)
+   * [Using the Gym](https://github.com/Baekalfen/PyBoy/wiki/Scripts,-AI-and-Bots)
+   * [Generic scripts and bots](https://github.com/Baekalfen/PyBoy/wiki/Scripts,-AI-and-Bots)
+ * [Examples](https://github.com/Baekalfen/PyBoy/tree/master/examples)
+ * [Discord](https://discord.gg/Zrf2nyH)
 
 <!---
 Generate GIF with the layout and captions
 -->
 <table>
   <tbody>
     <tr>
-      <td colspan="3">
-<div align="center">
-<img src="extras/README/1.gif" width="400"><br>
-</div>
+      <td colspan=2 align="center"><a href=https://github.com/PWhiddy/PokemonRedExperiments>Train RL agents to play Pokemon Red</a>
       </td>
     </tr>
     <tr>
-      <td align="center">Rewind any game<br>
+      <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/mqdefault.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"><a href=https://github.com/uiucanh/tetris>Beat world records</a><br>
+    </tr>
+    <tr>
+      <td align="center"><a href=https://github.com/Baekalfen/PyBoy/wiki/Experimental-and-optional-features#rewind-time>Rewind any game</a><br>
       </td>
-      <td align="center"><a href=https://github.com/lixado/PyBoy-RL>Train with Reinforcement Learning</a><br>
+      <td align="center"><a href=https://github.com/uiucanh/tetris>Beat world records with AI</a><br>
       </td>
     </tr>
     <tr>
       <td align="center">
-        <img src="extras/README/5.gif" width="200">
+        <img src="extras/README/5.gif" width="250">
+      </td>
+      <td align="center">
+        <img src="extras/README/7.gif" width="250">
+      </td>
+    </tr>
+    <tr>
+      <td align="center">Play the classics<br>
+      </td>
+      <td align="center"><a href=https://github.com/lixado/PyBoy-RL>Train your own AI</a><br>
       </td>
+    </tr>
+    <tr>
       <td align="center">
-        <img src="extras/README/7.gif" width="200">
+        <img src="extras/README/1.gif" width="250">
       </td>
       <td align="center">
-        <img src="extras/README/6.gif" width="200">
+        <img src="extras/README/6.gif" width="250">
       </td>
     </tr>
   </tbody>
 </table>
 
+Performance
+===========
+<table>
+  <tbody>
+    <tr>
+      <td align="center">
+        `pyboy.screen()` in null mode
+      </td>
+      <td align="center">
+        `pyboy.game_area()` in null mode
+      </td>
+    </tr>
+    <tr>
+      <td>
+      x59 realtime
+      </td>
+      <td>
+      x282 realtime
+      </td>
+    </tr>
+    <tr>
+      <td align="center">
+        <img src="README/screen.png" width="200">
+      </td>
+      <td align="center">
+        <img src="README/game_area.png" width="200">
+      </td>
+    </tr>
+  </tbody>
+</table>
 
 Installation
 ============
@@ -54,34 +103,33 @@ The instructions are simple if you already have a functioning Python environment
  1. Install PyBoy using __`pip install pyboy`__ (add __` --user`__ if your system asks)
  2. If your system isn't supported by [pysdl2-dll](https://pypi.org/project/pysdl2-dll/), you'll need to install SDL2 from your package manager.
 
-If you need more details, or if you need to compile from source, check out the detailed [installation instructions](https://github.com/Baekalfen/PyBoy/wiki/Installation). We support: macOS, Raspberry Pi (Raspbian), Linux (Ubuntu), and Windows 10.
+For details, see [installation instructions](https://github.com/Baekalfen/PyBoy/wiki/Installation).
 
 Now you're ready! Either use PyBoy directly from the terminal __`$ pyboy file.rom`__ or use it in your Python scripts:
 ```python
 from pyboy import PyBoy
 pyboy = PyBoy('ROMs/gamerom.gb')
-while not pyboy.tick():
+while pyboy.tick():
     pass
 pyboy.stop()
 ```
 
-Or using the context manager:
+<!-- Or using the context manager:
 ```python
 from pyboy import PyBoy
 with PyBoy('ROMs/gamerom.gb') as pyboy:
-    while not pyboy.tick():
+    while pyboy.tick():
         pass
-```
+``` -->
 
 When the emulator is running, you can easily access [PyBoy's API](https://baekalfen.github.io/PyBoy/index.html):
 ```python
-from pyboy import WindowEvent
-
-pyboy.send_input(WindowEvent.PRESS_ARROW_DOWN)
+pyboy.button('down')
+pyboy.button('a')
 pyboy.tick() # Process one frame to let the game register the input
-pyboy.send_input(WindowEvent.RELEASE_ARROW_DOWN)
+value_of_interest = pyboy.memory[0xC345]
 
-pil_image = pyboy.screen_image()
+pil_image = pyboy.screen.image
 pil_image.save('screenshot.png')
 ```
 
@@ -118,7 +166,7 @@ Any contribution is appreciated. The currently known problems are tracked in the
 
 For the more major features, there are the following that you can give a try. They are also described in more detail in the [project list in the Wiki](https://github.com/Baekalfen/PyBoy/wiki/Student-Projects):
 * Link Cable
-* _(Experimental)_ AI - use the `botsupport` or game wrappers to train a neural network
+* _(Experimental)_ AI - use the `api` or game wrappers to train a neural network
 * _(Experimental)_ Game Wrappers - make wrappers for popular games
 
 If you want to implement something which is not on the list, feel free to do so anyway. If you want to merge it into our repo, then just send a pull request and we will have a look at it.

docs/api/constants.html

@@ -0,0 +1,80 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
+<meta name="generator" content="pdoc 0.10.0" />
+<title>pyboy.api.constants API documentation</title>
+<meta name="description" content="Memory constants used internally to calculate tile and tile map addresses." />
+<link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css' rel='stylesheet'>
+<link href='https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/8.0.0/sanitize.min.css' rel='stylesheet'>
+<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">
+<style>.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{font-weight:bold}#index h4 + ul{margin-bottom:.6em}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary,.git-link-div{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase}.source summary > *{white-space:nowrap;cursor:pointer}.git-link{color:inherit;margin-left:1em}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
+<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:0.8em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
+<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
+<script async src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS_CHTML'></script>
+</head>
+<body>
+<main>
+<article id="content">
+<header>
+<h1 class="title">Module <code>pyboy.api.constants</code></h1>
+</header>
+<section id="section-intro">
+<p>Memory constants used internally to calculate tile and tile map addresses.</p>
+<details class="source">
+<summary>
+<span>Expand source code</span>
+</summary>
+<pre><code class="python">#
+# License: See LICENSE.md file
+# GitHub: https://github.com/Baekalfen/PyBoy
+#
+&#34;&#34;&#34;
+Memory constants used internally to calculate tile and tile map addresses.
+&#34;&#34;&#34;
+
+VRAM_OFFSET = 0x8000
+LCDC_OFFSET = 0xFF40
+OAM_OFFSET = 0xFE00
+LOW_TILEMAP = 0x1800 + VRAM_OFFSET
+HIGH_TILEMAP = 0x1C00 + VRAM_OFFSET
+LOW_TILEDATA = VRAM_OFFSET
+LOW_TILEDATA_NTILES = 0x100
+HIGH_TILEDATA = 0x800 + VRAM_OFFSET
+TILES = 384
+TILES_CGB = 768
+SPRITES = 40
+ROWS, COLS = 144, 160</code></pre>
+</details>
+</section>
+<section>
+</section>
+<section>
+</section>
+<section>
+</section>
+<section>
+</section>
+</article>
+<nav id="sidebar">
+<h1>Index</h1>
+<div class="toc">
+<ul></ul>
+</div>
+<ul id="index">
+<li><h3>Super-module</h3>
+<ul>
+<li><code><a title="pyboy.api" href="index.html">pyboy.api</a></code></li>
+</ul>
+</li>
+</ul>
+</nav>
+</main>
+<footer id="footer">
+<p>Generated by <a href="https://pdoc3.github.io/pdoc"><cite>pdoc</cite> 0.10.0</a>.</p>
+</footer>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
+<script>hljs.initHighlightingOnLoad()</script>
+</body>
+</html>