Metroid ii wrapper

.github/workflows/pr-test.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
-        python-version: [3.8, 3.9, "3.10", 3.11, 3.12, 3.13]
+        python-version: [3.9, "3.10", 3.11, 3.12, 3.13]
 
     steps:
     - uses: actions/checkout@v3
@@ -50,6 +50,13 @@ jobs:
         TEST_NO_UI: 1
       run: |
         python -m pytest tests/ -n auto -v
+    - name: Run PyTest Benchmark
+      env:
+        PYTEST_SECRETS_KEY: ${{ secrets.PYTEST_SECRETS_KEY }}
+        TEST_VERBOSE_IMAGES: 0
+        TEST_NO_UI: 1
+      run: |
+        python -m pytest tests/test_benchmark.py --benchmark-enable --benchmark-min-rounds=10
     - name: Build wheel
       run: |
         echo "Building wheel"
@@ -122,7 +129,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['cp38-cp38', 'cp39-cp39', 'cp310-cp310', 'cp311-cp311', 'cp312-cp312', 'cp313-cp313']
+        python-version: ['cp39-cp39', 'cp310-cp310', 'cp311-cp311', 'cp312-cp312', 'cp313-cp313']
         manylinux-version: ['manylinux_2_28_x86_64', 'musllinux_1_2_x86_64'] # GHA doesn't support manylinux_2_24_aarch64
 
     steps:
@@ -170,10 +177,10 @@ jobs:
           echo "Dists built:"
           ls -lah dist/
 
-    - name: Set up Python 3.8 (just for PyPi upload)
+    - name: Set up Python 3.11 (just for PyPi upload)
       uses: actions/setup-python@v3
       with:
-        python-version: 3.8
+        python-version: 3.11
     - name: Upload wheel
       if: ${{ github.event_name == 'release' && github.event.action == 'published' && !github.event.release.prerelease }}
       run: |

Makefile

@@ -1,5 +1,5 @@
 
-.PHONY: build clean run install test
+.PHONY: build clean run install test benchmark docs
 
 all: build
 
@@ -65,7 +65,7 @@ uninstall:
 	${PY} -m pip uninstall pyboy
 
 test: export DEBUG=1
-test: clean test_pypy test_cpython_doctest build test_cython
+test: clean test_pypy test_cpython_doctest build test_cython benchmark
 
 test_cpython_doctest:
 	${PY} -m pytest pyboy/ ${PYTEST_ARGS}
@@ -78,9 +78,13 @@ test_pypy:
 
 test_all: test
 
+benchmark:
+	${PY} -m pytest -m benchmark tests/test_benchmark.py --benchmark-enable --benchmark-min-rounds=10
+
 docs: clean
-	bash -O extglob -c 'rm -rf -- ${ROOT_DIR}/docs/!(templates|CNAME)'
+	find ./docs -type f ! -path "./docs/templates/*" ! -path "./docs/CNAME" ! -name "*.png" -exec rm -rf {} +
 	mkdir -p ${ROOT_DIR}/docs/templates
+	cd ${ROOT_DIR}/pyboy/plugins && ${PY} manager_gen.py
 	pdoc --html --force -c latex_math=True -c sort_identifiers=False -c show_type_annotations=True --template-dir docs/templates pyboy
 	cp -r html/pyboy/ ${ROOT_DIR}/docs/
 	rm -rf html

README.md

@@ -2,9 +2,9 @@
 <img src="extras/README/pyboy.svg" width="480">
 </p>
 
-__If you have any questions, or just want to chat, [join us on Discord](https://discord.gg/Zrf2nyH).__
+__If you have any questions, or just want to chat, [join us on Discord](https://discord.gg/wUbag3KNqQ).__
 
-[![Discord](https://img.shields.io/discord/584149554132418570?style=for-the-badge&logo=Discord&label=PyBoy)](https://discord.gg/Zrf2nyH)
+[![Discord](https://img.shields.io/discord/584149554132418570?style=for-the-badge&logo=Discord&label=PyBoy)](https://discord.gg/wUbag3KNqQ)
 
 <!---
 Generate GIF with the layout and captions
@@ -98,7 +98,7 @@ If you are looking to make a bot or AI, then these resources are a good place to
    * [Example: Tetris](https://github.com/Baekalfen/PyBoy/wiki/Example-Tetris)
    * [Example: Super Mario Land](https://github.com/Baekalfen/PyBoy/wiki/Example-Super-Mario-Land)
    * [Code Examples](https://github.com/Baekalfen/PyBoy/tree/master/extras/examples)
- * [Discord](https://discord.gg/Zrf2nyH)
+ * [Discord](https://discord.gg/wUbag3KNqQ)
 
 
 When the emulator is running, you can easily access [PyBoy's API](https://baekalfen.github.io/PyBoy/index.html):
@@ -186,9 +186,9 @@ do 3160 hours of gameplay in 1 hour.
 
 Contributing
 ============
-Any contribution is appreciated. The currently known problems are tracked in [the Issues tab](https://github.com/Baekalfen/PyBoy/issues). Feel free to take a swing at any one of them. If you have something original in mind, come and [discuss it on on Discord](https://discord.gg/Zrf2nyH).
+Any contribution is appreciated. The currently known problems are tracked in [the Issues tab](https://github.com/Baekalfen/PyBoy/issues). Feel free to take a swing at any one of them. If you have something original in mind, come and [discuss it on on Discord](https://discord.gg/wUbag3KNqQ).
 
-[![Discord](https://img.shields.io/discord/584149554132418570?style=for-the-badge&logo=Discord&label=PyBoy)](https://discord.gg/Zrf2nyH)
+[![Discord](https://img.shields.io/discord/584149554132418570?style=for-the-badge&logo=Discord&label=PyBoy)](https://discord.gg/wUbag3KNqQ)
 
 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):
 * Hacking games

extras/bootrom/bootrom_common.asm

@@ -74,13 +74,13 @@ main:
 
     ; Sound Setup
     ld A, $80
-    ldh [$26], A ; Enable sound - NR52
-    ldh [$11], A ; Use 50% duty cycle - NR11
+    ldh [$FF00+$26], A ; Enable sound - NR52
+    ldh [$FF00+$11], A ; Use 50% duty cycle - NR11
     ld A, $F3
-    ldh [$12], A
-    ldh [$25], A
+    ldh [$FF00+$12], A
+    ldh [$FF00+$25], A
     ld A, $77
-    ldh [$24], A
+    ldh [$FF00+$24], A
 
     ; #########################
     ; Graphics effect and wait
@@ -123,24 +123,24 @@ main:
 .play_sound
     ; Adjust frequency sweep
     ld A, %0010011
-    ldh [$10], A
+    ldh [$FF00+$10], A
 
     ld A, $48
-    ldh [$13], A
+    ldh [$FF00+$13], A
 
     ; Trigger
     ld A, $81
-    ldh [$14], A
+    ldh [$FF00+$14], A
     ret
 
 .adj_sound
     ; Adjust frequency sweep
     ld A, %0011001
-    ldh [$10], A
+    ldh [$FF00+$10], A
 
     ; Trigger
     ld A, $81
-    ldh [$14], A
+    ldh [$FF00+$14], A
     ret
 
 

extras/default_rom/default_rom.asm

@@ -99,7 +99,7 @@ Main:
 	ld a, [rWY]
 	cp a, 90
 	jr c, .loop
-
+.inner_loop ; Used in test
 	ldh a, [rDIV]
 	cp a, 255
 	jp z, .move

extras/default_rom/default_rom.sym

@@ -9,6 +9,7 @@
 00:0187 Main.readTilemap
 00:01a0 Main.clearOAM
 00:01ab Main.loop
+00:01b2 Main.inner_loop
 00:01bb Main.sync
 00:01c2 Main.move
 00:01cd Tileset

extras/default_rom/default_rom_cgb.sym

@@ -9,6 +9,7 @@
 00:0187 Main.readTilemap
 00:01a0 Main.clearOAM
 00:01ab Main.loop
+00:01b2 Main.inner_loop
 00:01bb Main.sync
 00:01c2 Main.move
 00:01cd Tileset

extras/examples/gamewrapper_kirby.py

@@ -10,8 +10,8 @@
 file_path = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, file_path + "/../..")
 
-from pyboy import PyBoy  # isort:skip
-from pyboy.utils import WindowEvent  # isort:skip
+from pyboy import PyBoy  # noqa
+from pyboy.utils import WindowEvent  # noqa
 
 # Check if the ROM is given through argv
 if len(sys.argv) > 1:

extras/examples/gamewrapper_mario.py

@@ -10,8 +10,8 @@
 file_path = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, file_path + "/../..")
 
-from pyboy import PyBoy  # isort:skip
-from pyboy.utils import WindowEvent  # isort:skip
+from pyboy import PyBoy  # noqa
+from pyboy.utils import WindowEvent  # noqa
 
 # Check if the ROM is given through argv
 if len(sys.argv) > 1:

extras/examples/gamewrapper_tetris.py

@@ -10,8 +10,8 @@
 file_path = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, file_path + "/../..")
 
-from pyboy import PyBoy  # isort:skip
-from pyboy.utils import WindowEvent  # isort:skip
+from pyboy import PyBoy  # noqa
+from pyboy.utils import WindowEvent  # noqa
 
 # Check if the ROM is given through argv
 if len(sys.argv) > 1:

pyboy/__main__.py

@@ -9,9 +9,10 @@
 import os
 
 import pyboy
-from pyboy import PyBoy, core, utils
+from pyboy import PyBoy
 from pyboy.plugins.manager import parser_arguments
 from pyboy.pyboy import defaults
+from pyboy.utils import PyBoyInvalidInputException
 
 logger = pyboy.logging.get_logger(__name__)
 
@@ -20,13 +21,15 @@
 
 def color_tuple(string):
     color_palette = [int(c.strip(), 16) for c in string.split(",")]
-    assert len(color_palette) == 4, f"Not the correct amount of colors! Expected four, got {len(color_palette)}"
+    if not (len(color_palette) == 4):
+        raise PyBoyInvalidInputException(f"Not the correct amount of colors! Expected four, got {len(color_palette)}")
     return color_palette
 
 
 def cgb_color_tuple(string):
     color_palette = [int(c.strip(), 16) for c in string.split(",")]
-    assert len(color_palette) == 12, f"Not the correct amount of colors! Expected twelve, got {len(color_palette)}"
+    if not (len(color_palette) == 12):
+        raise PyBoyInvalidInputException(f"Not the correct amount of colors! Expected twelve, got {len(color_palette)}")
     return [color_palette[0:4], color_palette[4:8], color_palette[8:12]]
 
 
@@ -43,6 +46,7 @@ def valid_file_path(path):
 )
 parser.add_argument("ROM", type=valid_file_path, help="Path to a Game Boy compatible ROM file")
 parser.add_argument("-b", "--bootrom", dest="bootrom", type=valid_file_path, help="Path to a boot-ROM file")
+parser.add_argument("--no-input", action="store_true", help="Disable all user-input (mostly for autonomous testing)")
 parser.add_argument(
     "--log-level",
     default=defaults["log_level"],
@@ -168,7 +172,6 @@ def main():
         with open(state_path, "rb") as f:
             pyboy.load_state(f)
 
-    render = not argv.no_renderer
     while pyboy.tick():
         pass
 

pyboy/api/__init__.py

@@ -17,4 +17,11 @@
 #     "constants": False,
 #     "manager": False,
 # }
-# __all__ = ["API"]
+__all__ = [
+    constants,
+    GameShark,
+    Screen,
+    Sprite,
+    Tile,
+    TileMap,
+]

pyboy/api/gameshark.pxd

@@ -17,8 +17,8 @@ cdef class GameShark:
 
     cdef uint8_t _get_value(self, int, int) noexcept
     cdef void _set_value(self, int, int, int) noexcept
-    cdef tuple _convert_cheat(self, str code) noexcept
+    cdef tuple _convert_cheat(self, str code)
     cpdef void add(self, str code) noexcept
     cpdef void remove(self, str code, bint restore_value=*) noexcept
     cpdef void clear_all(self, bint restore_value=*) noexcept
-    cdef void tick(self) noexcept
+    cdef void tick(self) noexcept with gil

pyboy/api/gameshark.py

@@ -121,7 +121,7 @@ def remove(self, code, restore_value=True):
             restore_value (bool): True to restore original value at address, otherwise don't restore
         """
 
-        if not code in self.cheats:
+        if code not in self.cheats:
             raise ValueError("GameShark code cannot be removed. Hasn't been applied.")
 
         original_value, (_type, _, address) = self.cheats.pop(code)

pyboy/api/memory_scanner.pxd

@@ -7,5 +7,5 @@ cdef class MemoryScanner:
     cdef int _memory_cache_byte_width
 
     cpdef list rescan_memory(self, object new_value=*, dynamic_comparison_type=*, byteorder=*)
-    cpdef list scan_memory(self, object target_value=*, int start_addr=*, int end_addr=*, standard_comparison_type=*, value_type=*, int byte_width=*, byteorder=*) noexcept
+    cpdef list scan_memory(self, object target_value=*, int start_addr=*, int end_addr=*, standard_comparison_type=*, value_type=*, int byte_width=*, byteorder=*)
     cpdef bint _check_value(self, uint64_t, uint64_t, int)noexcept

pyboy/api/memory_scanner.py

@@ -142,7 +142,7 @@ def rescan_memory(
                 else:
                     self._memory_cache[addr] = current_value
             elif dynamic_comparison_type == DynamicComparisonType.MATCH:
-                if new_value == None:
+                if new_value is None:
                     raise ValueError("new_value must be specified when using DynamicComparisonType.MATCH")
                 if current_value != new_value:
                     self._memory_cache.pop(addr)

pyboy/api/screen.pxd

@@ -11,13 +11,12 @@ from pyboy.core.mb cimport Motherboard
 
 cdef class Screen:
     cdef Motherboard mb
-    cpdef ((int, int), (int, int)) get_tilemap_position(self)
+    cpdef ((int, int), (int, int)) get_tilemap_position(self) noexcept
     # cdef readonly list tilemap_position_list
     # cdef readonly uint8_t[:,:] tilemap_position_list
     cdef readonly uint32_t[:,:] raw_buffer
     cdef readonly (int, int) raw_buffer_dims
     cdef readonly str raw_buffer_format
-    # cdef readonly uint8_t[144][160][4] memoryview
-    # cpdef np.ndarray[np.uint8_t, ndim=3] get_ndarray(self)
+
     cdef readonly object ndarray
     cdef readonly object image

pyboy/api/screen.py

@@ -54,8 +54,8 @@ def __init__(self, mb):
 
         Returns
         -------
-        bytes:
-            92160 bytes of screen data in a `bytes` object.
+        memoryview:
+            92160 bytes memoryview of screen data.
         """
         self.raw_buffer_dims = self.mb.lcd.renderer.buffer_dims
         """
@@ -121,6 +121,7 @@ def __init__(self, mb):
         """
         if not Image:
             logger.warning('Cannot generate screen image. Missing dependency "Pillow".')
+            self.image = utils.PillowImportError()
         else:
             self._set_image()
 
@@ -173,7 +174,7 @@ def _set_image(self):
     @property
     def tilemap_position_list(self):
         """
-        This function provides the screen (SCX, SCY) and window (WX. WY) position for each horizontal line in the
+        This function provides the screen (SCX, SCY) and window (WX, WY) position for each horizontal line in the
         screen buffer. These parameters are often used for visual effects, and some games will reset the registers at
         the end of each call to `pyboy.PyBoy.tick()`.
 
@@ -206,7 +207,7 @@ def tilemap_position_list(self):
         """
 
         if self.mb.lcd._LCDC.lcd_enable:
-            return [[line[0], line[1], line[2], line[3]] for line in self.mb.lcd._scanlineparameters]
+            return [[line[0], line[1], line[2] - 7, line[3]] for line in self.mb.lcd._scanlineparameters]
         else:
             return [[0, 0, 0, 0] for line in range(144)]
 

pyboy/api/sprite.py

@@ -7,6 +7,7 @@
 """
 
 from pyboy.core.lcd import LCDCRegister
+from pyboy.utils import PyBoyOutOfBoundsException
 
 from .constants import LCDC_OFFSET, OAM_OFFSET, SPRITES
 from .tile import Tile
@@ -30,7 +31,8 @@ def __init__(self, mb, sprite_index):
         By knowing the tile identifiers of players, enemies, power-ups and so on, you'll be able to search for them
         using `pyboy.sprite_by_tile_identifier` and feed it to your bot or AI.
         """
-        assert 0 <= sprite_index < SPRITES, f"Sprite index of {sprite_index} is out of range (0-{SPRITES})"
+        if not (0 <= sprite_index < SPRITES):
+            raise PyBoyOutOfBoundsException(f"Sprite index of {sprite_index} is out of range (0-{SPRITES})")
         self.mb = mb
         self._offset = sprite_index * 4
 

pyboy/api/tile.pxd

@@ -21,8 +21,8 @@ cdef class Tile:
     cdef readonly int tile_identifier
     cdef readonly int data_address
     cdef readonly tuple shape
-    cpdef object image(self) noexcept
-    cpdef object ndarray(self) noexcept
+    cpdef object image(self)
+    cpdef object ndarray(self)
 
     cdef uint32_t[:,:] data # TODO: Add to locals instead
     @cython.locals(byte1=uint8_t, byte2=uint8_t, colorcode=uint64_t)