General improvements

.github/ISSUE_TEMPLATE/issue-template.md

@@ -7,10 +7,15 @@ assignees: ''
 
 ---
 
-Describe in detail how to reproduce the bug you're reporting. Preferably with a short code example to reproduce the bug.
+Describe in detail how to reproduce the bug you're reporting. Preferably with a short code example to reproduce the bug like this:
+```python
+>>> from pyboy import PyBoy
+>>> p = PyBoy(..., window="SDL2")
+>>> p.memory[0,0x1234] # Example: I expected an int, but it throws exception
+```
 
 Please make sure you've already checked the documentation: https://docs.pyboy.dk
 
-If you're seeking help for a project, then Discord is a better place to go https://discord.gg/wUbag3KNqQ
+If this is not a bug report, and you're seeking help for a project, then Discord is a better place to go https://discord.gg/wUbag3KNqQ
 
 If you used ChatGPT to produce 6 pages of word soup, your issue will be closed without an answer.

.github/workflows/pr-test.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest, ubuntu-24.04-arm]
-        python-version: [3.9, "3.10", 3.11, 3.12, 3.13]
+        python-version: ["3.10", 3.11, 3.12, 3.13, 3.14]
 
     steps:
     - uses: actions/checkout@v4
@@ -151,7 +151,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, ubuntu-24.04-arm]
-        python-version: ['cp39-cp39', 'cp310-cp310', 'cp311-cp311', 'cp312-cp312', 'cp313-cp313']
+        python-version: ['cp310-cp310', 'cp311-cp311', 'cp312-cp312', 'cp313-cp313', 'cp314-cp314']
         manylinux-version: ['manylinux_2_28_x86_64', 'musllinux_1_2_x86_64', 'manylinux_2_28_aarch64', 'musllinux_1_2_aarch64']
         exclude:
           - os: ubuntu-24.04-arm

extras/bootrom/bootrom_cgb.sym

@@ -10,8 +10,8 @@
 00:0087 main.wave_table
 00:0097 main.effect
 00:00a5 main.exit_vblank
-00:00bb main.logo
 00:00bb main.P1
+00:00bb main.logo
 00:00c3 main.P2
 00:00cb main.Y1
 00:00d3 main.B2

extras/bootrom/bootrom_dmg.sym

@@ -10,8 +10,8 @@
 00:0087 main.wave_table
 00:0097 main.effect
 00:00a5 main.exit_vblank
-00:00bb main.logo
 00:00bb main.P1
+00:00bb main.logo
 00:00c3 main.P2
 00:00cb main.Y1
 00:00d3 main.B2

pyboy/api/tile.py

@@ -120,7 +120,8 @@ def image(self):
             utils.PillowImportError()._raise_import_error()
 
         if utils.cython_compiled:
-            return Image.fromarray(self._image_data().base, mode=self.raw_buffer_format)
+            # Image.fromarray(..., mode=...) is now deprecated. No good alternative.
+            return Image.fromarray(self._image_data().base).convert(self.raw_buffer_format)
         else:
             return Image.frombytes(self.raw_buffer_format, (8, 8), self._image_data())
 

pyboy/core/bootrom.pxd

@@ -13,4 +13,4 @@ cdef Logger logger
 cdef class BootROM:
     cdef uint8_t[:] bootrom
     cdef bint cgb
-    cdef uint8_t getitem(self, uint16_t) noexcept nogil
+    # cdef uint8_t getitem(self, uint16_t) noexcept nogil

pyboy/core/bootrom.py

@@ -21,5 +21,5 @@ def __init__(self, bootrom_file, cartridge_cgb):
         self.bootrom = array.array("B", struct.unpack("%iB" % len(rom), rom))
         self.cgb = len(rom) > 0x100
 
-    def getitem(self, addr):
-        return self.bootrom[addr]
+    # def getitem(self, addr):
+    #     return

pyboy/core/cartridge/base_mbc.pxd

@@ -13,7 +13,6 @@ from pyboy.utils cimport IntIOInterface
 cdef Logger logger
 
 cdef class BaseMBC:
-    cdef str filename
     cdef str gamename
     cdef uint8_t[:, :] rombanks
     cdef uint8_t[:,:] rambanks
@@ -31,6 +30,7 @@ cdef class BaseMBC:
     cdef uint16_t rombank_selected_low
     cdef bint cgb
 
+    cdef void stop(self, object, object) noexcept
     cdef int save_state(self, IntIOInterface) except -1
     cdef int load_state(self, IntIOInterface, int) except -1
     cdef int save_ram(self, IntIOInterface) except -1

pyboy/core/cartridge/base_mbc.py

@@ -4,7 +4,6 @@
 #
 
 import array
-import os
 
 import pyboy
 from pyboy.utils import IntIOWrapper, PyBoyException, PyBoyInvalidInputException
@@ -15,16 +14,15 @@
 
 
 class BaseMBC:
-    def __init__(self, filename, rombanks, external_ram_count, carttype, sram, battery, rtc_enabled):
-        self.filename = filename + ".ram"
+    def __init__(self, rombanks, ram_file, rtc_file, external_ram_count, carttype, sram, battery, rtc_enabled):
         self.rombanks = rombanks
         self.carttype = carttype
 
         self.battery = battery
         self.rtc_enabled = rtc_enabled
 
         if self.rtc_enabled:
-            self.rtc = RTC(filename)
+            self.rtc = RTC(rtc_file)
         else:
             self.rtc = None
 
@@ -43,18 +41,17 @@ def __init__(self, filename, rombanks, external_ram_count, carttype, sram, batte
         self.rombank_selected = 1
         self.rombank_selected_low = 0
 
-        if not os.path.exists(self.filename):
-            logger.debug("No RAM file found. Skipping.")
+        if ram_file is not None and self.battery:
+            self.load_ram(IntIOWrapper(ram_file))
         else:
-            with open(self.filename, "rb") as f:
-                self.load_ram(IntIOWrapper(f))
+            logger.debug("No RAM file found. Skipping.")
 
-    def stop(self):
-        with open(self.filename, "wb") as f:
-            self.save_ram(IntIOWrapper(f))
+    def stop(self, ram_file, rtc_file):
+        if ram_file is not None and self.battery:
+            self.save_ram(IntIOWrapper(ram_file))
 
         if self.rtc_enabled:
-            self.rtc.stop()
+            self.rtc.stop(rtc_file)
 
     def save_state(self, f):
         f.write(self.rombank_selected)
@@ -147,7 +144,6 @@ def __repr__(self):
         return "\n".join(
             [
                 "MBC class: %s" % self.__class__.__name__,
-                "Filename: %s" % self.filename,
                 "Game name: %s" % self.gamename,
                 "GB Color: %s" % str(self.rombanks[0, 0x143] == 0x80),
                 "Cartridge type: %s" % hex(self.carttype),

pyboy/core/cartridge/cartridge.pxd

@@ -16,11 +16,11 @@ from .base_mbc cimport BaseMBC
 cdef Logger logger
 
 @cython.locals(carttype=uint8_t, cart_name=basestring, cart_line=basestring)
-cpdef BaseMBC load_cartridge(str)
+cpdef BaseMBC load_cartridge(object, object, object)
 cdef bint validate_checksum(uint8_t[:,:]) noexcept
 
 @cython.locals(romdata=array, banksize=int)
-cdef uint8_t[:, :] load_romfile(str) noexcept
+cdef uint8_t[:, :] load_romfile(object) noexcept
 
 cdef dict CARTRIDGE_TABLE
 cdef dict EXTERNAL_RAM_TABLE

pyboy/core/cartridge/cartridge.py

@@ -17,8 +17,8 @@
 logger = pyboy.logging.get_logger(__name__)
 
 
-def load_cartridge(filename):
-    rombanks = load_romfile(filename)
+def load_cartridge(gamerom_file, ram_file, rtc_file):
+    rombanks = load_romfile(gamerom_file)
     if not validate_checksum(rombanks):
         raise PyBoyException("Cartridge header checksum mismatch!")
 
@@ -36,7 +36,7 @@ def load_cartridge(filename):
     logger.debug("Cartridge size: %d ROM banks of 16KB, %s RAM banks of 8KB", len(rombanks), external_ram_count)
     cartmeta = CARTRIDGE_TABLE[carttype]
 
-    return cartmeta[0](filename, rombanks, external_ram_count, carttype, *cartmeta[1:])
+    return cartmeta[0](rombanks, ram_file, rtc_file, external_ram_count, carttype, *cartmeta[1:])
 
 
 def validate_checksum(rombanks):
@@ -47,9 +47,8 @@ def validate_checksum(rombanks):
     return rombanks[0, 0x14D] == x
 
 
-def load_romfile(filename):
-    with open(filename, "rb") as romfile:
-        romdata = array("B", romfile.read())
+def load_romfile(gamerom_file):
+    romdata = array("B", gamerom_file.read())
 
     logger.debug("Loading ROM file: %d bytes", len(romdata))
     if len(romdata) == 0:

pyboy/core/cartridge/rtc.pxd

@@ -16,7 +16,6 @@ from pyboy.utils cimport IntIOInterface
 cdef Logger logger
 
 cdef class RTC:
-    cdef str filename
     cdef bint latch_enabled
     cdef cython.double timezero
     cdef bint timelock
@@ -28,7 +27,7 @@ cdef class RTC:
     cdef uint64_t day_carry
     cdef uint64_t halt
 
-    cdef void stop(self) noexcept
+    cdef void stop(self, object) noexcept
     cdef int save_state(self, IntIOInterface) except -1
     cdef int load_state(self, IntIOInterface, int) except -1
     @cython.locals(days=uint64_t)

pyboy/core/cartridge/rtc.py

@@ -2,7 +2,6 @@
 # License: See LICENSE.md file
 # GitHub: https://github.com/Baekalfen/PyBoy
 
-import os
 import struct
 import time
 
@@ -13,30 +12,27 @@
 
 
 class RTC:
-    def __init__(self, filename):
-        self.filename = filename + ".rtc"
-
+    def __init__(self, rtc_file):
         self.timezero = time.time()
         self.timelock = False
         self.day_carry = 0
         self.halt = 0
 
-        if not os.path.exists(self.filename):
-            logger.info("No RTC file found. Skipping.")
-        else:
-            with open(self.filename, "rb") as f:
-                self.load_state(IntIOWrapper(f), STATE_VERSION)
-
         self.latch_enabled = False
         self.sec_latch = 0
         self.min_latch = 0
         self.hour_latch = 0
         self.day_latch_low = 0
         self.day_latch_high = 0
 
-    def stop(self):
-        with open(self.filename, "wb") as f:
-            self.save_state(IntIOWrapper(f))
+        if rtc_file is not None:
+            self.load_state(IntIOWrapper(rtc_file), STATE_VERSION)
+        else:
+            logger.info("No RTC file found. Skipping.")
+
+    def stop(self, rtc_file):
+        if rtc_file is not None:
+            self.save_state(IntIOWrapper(rtc_file))
 
     def save_state(self, f):
         for b in struct.pack("d", self.timezero):

pyboy/core/cpu.pxd

@@ -36,7 +36,7 @@ cdef class CPU:
     cdef void set_interruptflag(self, int) noexcept nogil
     cdef bint handle_interrupt(self, uint8_t, uint16_t) noexcept nogil
 
-    @cython.locals(opcode=uint16_t)
+    @cython.locals(pc1=uint16_t,pc2=uint16_t,pc3=uint16_t, opcode=uint16_t, v=cython.int, a=cython.int, b=cython.int)
     cdef inline uint8_t fetch_and_execute(self) noexcept nogil
     @cython.locals(_cycles0=int64_t)
     cdef int tick(self, int64_t) noexcept nogil

pyboy/core/cpu.py

@@ -178,12 +178,44 @@ def handle_interrupt(self, flag, addr):
         self.SP &= 0xFFFF
 
         self.PC = addr
+
+        # https://gbdev.io/pandocs/Interrupts.html#interrupt-handling
+        # "The entire process lasts 5 M-cycles."
+        self.cycles += 20
+
         self.interrupt_master_enable = False
 
     def fetch_and_execute(self):
-        opcode = self.mb.getitem(self.PC)
+        # HACK: Shortcut the mb.getitem() calls
+        if (not self.mb.bootrom_enabled) and self.PC + 2 < 0x4000:
+            pc1 = self.mb.cartridge.rombanks[self.mb.cartridge.rombank_selected_low, self.PC]
+            pc2 = self.mb.cartridge.rombanks[self.mb.cartridge.rombank_selected_low, self.PC + 1]
+            pc3 = self.mb.cartridge.rombanks[self.mb.cartridge.rombank_selected_low, self.PC + 2]
+        elif (not self.mb.bootrom_enabled) and self.PC + 2 < 0x8000:  # 16kB switchable ROM bank
+            pc1 = self.mb.cartridge.rombanks[self.mb.cartridge.rombank_selected, self.PC - 0x4000]
+            pc2 = self.mb.cartridge.rombanks[self.mb.cartridge.rombank_selected, self.PC + 1 - 0x4000]
+            pc3 = self.mb.cartridge.rombanks[self.mb.cartridge.rombank_selected, self.PC + 2 - 0x4000]
+        else:
+            pc1 = self.mb.getitem(self.PC)
+            pc2 = self.mb.getitem((self.PC + 1) & 0xFFFF)
+            pc3 = self.mb.getitem((self.PC + 2) & 0xFFFF)
+
+        v = 0
+        opcode = pc1
         if opcode == 0xCB:  # Extension code
-            opcode = self.mb.getitem(self.PC + 1)
+            opcode = pc2
             opcode += 0x100  # Internally shifting look-up table
-
-        return opcodes.execute_opcode(self, opcode)
+        else:
+            # CB opcodes do not have immediates
+            oplen = opcodes.OPCODE_LENGTHS[opcode]
+            if oplen == 2:
+                # 8-bit immediate
+                v = pc2
+            elif oplen == 3:
+                # 16-bit immediate
+                # Flips order of values due to big-endian
+                a = pc3
+                b = pc2
+                v = (a << 8) + b
+
+        return opcodes.execute_opcode(self, opcode, v)