Let’s Write a Game Boy Emulator in Python

What’s an Emulator?

Let’s briefly talk about what an emulator is. In our case, the Game Boy emulator we’ll write will mimic as many of the components that make up the Game Boy as we need to, to make it work. But, there’s a lot of obscured context to that statement: what does it mean to mimic something? How do you simulate the intricacies of an LCD — and do you even try or just settle for drawing stuff to your screen? What about the CPU, the RAM and the physical buttons? What about the cartridges that hold the games?

The determination of what is a good or bad emulator comes down to careful trade-offs. It’s not always feasible (or useful) to perfectly render unto your host system every hardware quirk or software foible the source system has. There are also other considerations such as whether the host system is even capable of accurately emulating it in the first place.

So the job of an emulator writer is picking your battles and conceding that some things (certain games, in our case) cannot be made to work without a disproportionate amount of work versus what the return on that investment is. The intricacies of how the different pieces of hardware interacted with each other, and the extreme lengths the programmers went through to eke out every cycle of performance, means there’s an awful lot of obscure behavior that you must implement if you truly want a cycle-accurate emulator. Now, I will not be striving for that level of emulation as the educational “return on investment” drops sharply.

But saying that, how these intricate components interact is absolutely something we’ll encounter: there are many edge cases and design quirks where we’ll have to weigh the benefits of trying to accurately mirror what the real system does, in lieu of simply proclaiming it “good enough” and moving on.

As this is an educational course the main focus is teaching the concepts that result in a passable emulator capable of running some Game Boy cartridges. So even if you are not prima facie interested in the Game Boy, the lessons you’ll learn from following the course will leave with a deep understanding of software and systems programming nonetheless.

Intended Audience

You don’t need to be an expert in Python nor systems programming to have a go at this. The entirety of the course is designed to gently introduce each concept that you’ll work on. That does not mean you’ll sit down and knock this out in a weekend even if you are; it’s a pretty large undertaking, but thankfully one where the payout is the experience of building the emulator.

What You’ll Learn

CPU Design and CPU Architecture

The Z80-style CPU is very similar to the foundational 8080 CPU design that modern Intel CPUs can trace their lineage back to. Although the Z80 is similar to the CPU in the Game Boy, it is not entirely the same: it’s most likely an Intel 8080-style Sharp CPU called LR35902, but I will instead use the term Z80 even though it’s not 100% truthful. The reason for that is there’s scant documentation for the Sharp CPU on the internet except references to just the Game Boy. The Z80 – even though it is different in a number of ways from the Sharp – is reasonably similar and has a very large body of documentation online.

Modern CPUs are, of course, fantastically complex; but the old Z80 is not, which makes it perfect for understanding the fundaments of how a CPU actually works.

You’ll write a full-fledged “CPU” in Python with registers, flags, memory controller, instruction execution, and much more.

Assembly Language Programming

You’ll walk away with a good understanding of Z80 assembly language (and by extension general concepts still in use today) and how it underpins literally everything we do today. A register-based CPU is most likely what powers the computer that you are reading this on, and knowing enough about assembly language to cogently reason about how machine code is decoded and executed by the CPU will serve you well.

How to write a Disassembler

If an assembler turns assembly language into machine code that a CPU can understand, the disassembler does the reverse: it turns machine code back into assembly. As part of your work on the emulator, you’ll need to do this as you methodically work your way through the CPU specification or to debug issues that will crop up during its development.

Interrupt Handling

Ask yourself what happens when you press the key on the Game Boy’s game pad? How does a physical button press manifest itself as something actionable for the CPU that is busy executing the code that makes up a computer game? The answer to that (and many other events) is the interrupt handler, another core part of systems programming that allow for event handling in a CPU that is otherwise entirely bereft of concurrency.

Interactive Debugger

You’ll write an interactive debugger capable of stepping through each machine code instruction; evaluate simple expressions like viewing memory or registers; place breakpoints when certain parts of the code is reached; and more.

Bit manipulation (or “bit twiddling”)

Ask yourself how a computer that only understands 0s and 1s can comprehend the number 2? How does it add another number to that number, and what does it mean that a CPU can only operate on 8-bit or 16-bit numbers? At the end of the course you’ll have a solid understanding of binary numbers; how CPUs add, subtract and represent both signed and unsigned numbers; how to “bit manipulate” binary numbers to do things like set or reset flags in bitfields; and the perplexing etymology of Gulliver’s Travels and CPU endianness.

Vertical Blanking, Blitting, Scrolling and Sprites

Drawing stuff to a screen is a carefully choreographed ballet between the CPU, the memory and the display and its display controller. Get it wrong on real hardware and you’ll print only garbage or even damage it! Luckily that is no concern in an emulator, and yet you’ll still have to understand screen blanking; blitting to a screen; and how the Game Boy scrolls the screen and displays moving graphics.

Performance Profiling and Code Optimization

Python is… not fast. And you would be surprised to hear that even semi-accurately simulating a humble 4.19 MHz CPU will take its toll on yours! So once it’s all said and done, you’ll learn some tricks of the trade to speed things up a bit.

Python

I would be remiss if I did not include this. Throughout the course I intend to show you how I would develop key parts of the emulator with testability and good design in mind. I will use Python 3.10’s match-case pattern matching as it has a number of tantalizing use cases, and there’s a lot to be said here for separation of concerns — a critical concept when you have to develop a complex web of components that must nevertheless be written and tested independently.

Goals & Non-Goals

Let’s talk about goals and also non-goals. The end goal is a functioning Game Boy emulator and a debug suite to aid in developing it further; but it’s the journey more-so than the destination. There’s a lot of really cool concepts and techniques you’ll learn along the way. Finishing a project feels good, but this is an undertaking where every percentage point of incrementation beyond 70-80% complete will take more and more time as you’ll have to get a lot of complex timings and design quirks right to progress. The end goal for me, then, is to take us as far as we can go and still extract fun and learning out of it, which falls well short of cycle-accuracy. But that should not discourage you: once you have a good understanding of how the mechanics of Game Boy emulation works, you should have the tools and knowledge needed to take things further yourself.

So, in short:

Emphasis on Readability over Performance

The code I write will emphasize readability and not performance. It’s far too easy to get caught up in needless performance optimizations when you do not yet understand where or what the bottlenecks are likely to be.

Course Plan

There’s fair bit of required reading if you want to write a Game Boy emulator, but the prevailing documentation on the subject – although very good – does assume a level of fluency in systems programming that I will of course explain first.

So the plan is, roughly, as follows:

1. Introduction (that’s what you’re reading right now)

   1. What is a Game Boy and what is an Emulator

   2. Recommended and Required Resources

   3. Reading Opcodes from the Opcode JSON

2. Understanding Opcodes and Operands

   1. How to read and implement opcodes and operands

   2. Writing a basic disassembler (and our future decoder)

   3. What’s a Cartridge ROM?

   4. Reading the metadata from a Cartridge

3. Writing the Python skeleton of a Z-80 CPU

   1. The Program Counter

   2. Registers and Flags

   3. Basics of Bit Twiddling

4. The Memory Banks and Memory Controller

5. Writing an Interactive Debugger

6. Implementing some of the basic CPU opcodes

7. Bit Twiddling and manipulating Numbers

8. The ALU and arithmetic opcodes

9. Interrupt Handling

10. Graphics, tile maps, backgrounds and the display

11. Joypad and Memory Bank Switching

12. Performance Optimizations

13. Sound

Recommended and Required Resources

You cannot write a Game Boy emulator in a vacuum. This course stands on the shoulders of giants. There’s a large body of enthusiast-made documentation for all the various incarnations of the Game Boy. The Game Boy has been painstakingly reverse-engineered over many, many years into a collection of documentation and resources that we can draw on.

There are also many other Game Boy emulators and there is no shame in having a peek at how they do things if you are stuck. And you will get stuck. Once you’re further along you’ll have no problems divining how these other emulator implementations work and you can quickly check if your understanding is correct.

I will include code samples that roughly match the level of progress at each stage we progress to, but with the caveat that like all half-finished things, it will of course never be a 100% correct reference implementation – you only really reach that stage at the end – but it should serve well as a reference or starting point for you. Each incrementation brings changes, fixes, and changes as we collectively grow our understanding of the Game Boy and its internals.

Reading and Parsing Opcodes and Operands

>>> def add(a, b):
        return a + b
>>> import dis
>>> dis.dis(add)
  2           0 LOAD_FAST                0 (a)
              2 LOAD_FAST                1 (b)
              4 BINARY_ADD
              6 RETURN_VALUE
                ^--- Mnemonic            ^^^^^ Argument
              ^--- Offset

>>> add.__code__.co_code
b'|\x00|\x01\x17\x00S\x00'

<addr> <opcode> <mnemonic> [<operand> ...] [; commentary ]

"0xFF": {
          "flags": {
              "C": "-",
              "H": "-",
              "N": "-",
              "Z": "-"
          },
          "immediate": true,
          "operands": [
              {
                  "immediate": true,
                  "name": "38H"
              }
          ],
          "cycles": [
              16
          ],
          "bytes": 1,
          "mnemonic": "RST"
}

from dataclasses import dataclass
from typing import Literal

@dataclass(frozen=True)
class Operand:

    immediate: bool
    name: str
    bytes: int
    value: int | None
    adjust: Literal["+", "-"] | None

    def create(self, value):
        return Operand(immediate=self.immediate,
                       name=self.name,
                       bytes=self.bytes,
                       value=value,
                       adjust=self.adjust)

@dataclass
class Instruction:

    opcode: int
    immediate: bool
    operands: list[Operand]
    cycles: list[int]
    bytes: int
    mnemonic: str
    comment: str = ""

    def create(self, operands):
        return Instruction(opcode=self.opcode,
                           immediate=self.immediate,
                           operands=operands,
                           cycles=self.cycles,
                           bytes=self.bytes,
                           mnemonic=self.mnemonic)

>>> 0xFF
255
>>> 0b1111_1111
255
>>> hex(255)
'0xff'
>>> bin(255)
'0b11111111'

>>> 0b0000_1111
15
>>> hex(15)
'0xf'
>>> 0xF
15

>>> int("0xFF", base=16)
255

>>> int("0b0110111", base=2)
55

>>> instructions[0xFF]
Instruction(opcode=255, immediate=True, operands=[
    Operand(immediate=True, name='38H', bytes=None, value=None, adjust=None)
    ], cycles=[16], bytes=1, mnemonic='RST', comment='')

>>> {inst.mnemonic for inst in instructions.values()}
{'ADC',
 'ADD',
 'AND',
 'CALL',
 # ... etc ...
 'SUB',
 'XOR'}

Conclusion and Next Steps

Opcodes and operands is the machine code that powers your computer

We’ve briefly covered what a CPU is and what it does – with far more to come – and what role opcodes and operands have. It’s the programming language for your CPU. But as I’ve shown, high-level languages like Python with its interpreted language; the bytecode that it emits when it’s compiled; and virtual machine it uses to run the bytecode, is not all that different from the role of a CPU.

Hexadecimals, Binary and Numbers writ large

Hexadecimals are a programmer aid. They have little to do with computing except to aid us in reasoning about binary numbers, a topic I’ve not yet covered at all, as it deserves a thorough deep dive to truly understand them. Binary numbers are the lifeblood, so to speak, of the CPU.

Emulation is the act of replicating the conditions that allow code to run unmodified on a different host

But with the caveat that not everything is so easily replicated! Getting things just right is as much a science as it is an art. It’s our goal to write a Game Boy emulator but with trade-offs around cycle-accuracy and performance.

The Game Boy CPU is a hybrid of multiple different CPU types

I will refer to it as Z80 as it hews reasonably close to that CPU, but it’s not entirely the same. It’s a Sharp LR35902 and it’s definitely inspired by the Intel 8080 and the Z80. But there is no official reference documentation available online for that model, and most documentation you can find leads you back to Game Boy emulators.

If you want to read up on the Z80, remember that the Sharp has a different instruction set (but with a lot of overlap); and it’s missing a number of registers and flags.