So, why learn Z80 assembly code, particularly for a very outdated handheld console?

  • It’s a fun way to learn assembly! Rather than programming for some random piece of hardware, you’re making a Gameboy game!
  • It’s inexpensive to purchase the actual hardware. An original Gameboy is $20-$30 on eBay (though Gameboy Colors will also play regular Gameboy games and are even cheaper/easier to find), and a cartridge you can write to via a USB cable is ~$45. With that you get the input, screen, processor, etc. all in one device!
  • Z80 assembly is pretty straightforward. What I mean is, there aren’t that many instructions to keep track of (it’s a CISC architecture), and it’s pretty easy to learn in my opinion.
  • The Gameboy’s variant of Z80 is designed to be used for games. Tile sets, sprites, etc. are handled by the system itself (i.e. it’s built in to the assembly language), so drawing graphics to the screen is fairly painless.
  • The appropriate tools (assembler, linker, etc.) are available on Windows, Linux, and Mac, so development is basically OS-independent. Caveat: Software for writing to some flash carts [writable cartridges] may not be available on every OS.

I recently posted on my personal blog that I’ve been teaching myself to program Z80 assembly for the Gameboy. I already have some assembly programming experience, so the process isn’t too difficult for me; however, others might not, so I figured I’d start up a series on learning assembly code (Gameboy style)! This post will mostly get you set up to get ready to rock, and provide you with a few links to get you going. Tutorials from me will come in future posts!

Note: If at any point you get stuck, feel free to ask me for help! My email is zachary.hoefler@gmail.com. I also recommend the IRC channel #gbdev on EFnet, though it might take a bit to get a reply.

First, you’ll want to set up a development environment. That link will more or less walk you through the process. Basically, you’ll just need to download the RGBDS tool chain and figure out what text editor and emulator you want to use. I highly recommend the BGB Gameboy emulator over nocash (no$gmb). Both will work fine, but BGB is my personal emulator of choice. Both BGB and nocash have debuggers built into them, so they’re really your primary choices for development. (Linux users: BGB also runs fine under Wine!)

At this point, make sure you can compile code properly. This is also covered in the link for setting up a development environment, thankfully! You’ll need to use the command line, but it’s nothing too horrible. In fact, Windows/Linux scripts are available online which will allow you to basically just type “assemble hello-world” and let it automate the assembling, linking, and fixing process. “Fixing” means, basically, that after compiling and linking, a program will run through the output .GB file and make sure a Gameboy will read it as a legitimate game by checking the headers, file size, etc.

Now, we’ve got a development environment set up! Diving in to coding assembly is… well, a bit rough at first. Take a look at this hello world example, with comments. There are a few things you’ll notice:

  • There’s boilerplate code. Every Gameboy ROM has a specific header it has to include in order for the system to read it, and that header goes right into your code. Thankfully, though, the header can be entered using a macro rather than having to enter it every time. Additionally, you have to define handlers for interrupts, start your code at a certain position in the ROM file (that’s what those SECTION assembler commands mean), etc. Try and understand what it’s doing, but don’t expect to memorize it all; you can just look it up later.
  • Each instruction is separated by line breaks. Semicolons denote comments, not the end of an instruction.
  • The instructions like “SECTION,” “INCLUDE,” “DB,” etc. are actually giving instructions to the assembler/linker; they aren’t actual code. These are sort of like C preprocessor commands.
  • There’s a mix of assembly instructions (nop, jp, ld, etc.) and macros (ROM_HEADER, chr_IBMPC1, etc.). The RGBDS assembly has a pretty powerful macro language which is covered very thoroughly in its documentation. They work… well, a lot like C macros. Basically, the code for a macro is inserted wherever the macro is invoked. Additionally, though, you can also do thinks like define a loop using the macro language which lets you have an unrolled loop inside of your code without copying and pasting a line repeatedly.
  • There are labels. These denote sections of code, and work pretty similarly to labels in C. You’ll also use labels to define locations in memory. For example, the ‘Title’ label in the Hello World is the memory address of the “Hello world!” string defined below it.

Sorry for that bombardment of information! However, that should be enough where you can start to identify what a line is when you see it, even if you don’t know exactly what the instruction/macro/etc. is doing just yet.

At this point, a great way to get the hang of programming in assembly is to start modifying code rather than trying to write whole programs from scratch. I recommend checking out these two assignments from Wichita State’s 2008 course on Gameboy assembly programming: Once Upon a Z80, and Hello Gameboy. The first assignment, “Once Upon a Z80,” basically points you to various sections of the Z80 User’s Manual that are worth reading. The second assignment is basically taking the Hello World program I linked above and changing it in some way.

Hopefully that’s enough to get you started! However, if you’re struggling to dive in, don’t worry! My next post is going to be a tutorial starting right at the basics.

Further Reading/Other Resources
http://cratel.wichita.edu/cratel/ECE238Spr08 – This page was from Wichita State’s 2008 course, Assembly Language Programming for Engineers. To make the course more entertaining (and so students could walk away with something cool!), they decided to teach the Gameboy’s Z80 assembly. You can find all of their assignments, downloads, etc. right on the web page. Not only that, all of the students have their work posted on a blog, and there’s a link to their Google Group they used for discussion. Definitely a good resource, particularly if you want a guideline on where to start, what to look up, etc.

Gameboy Dev’rs – Though some of the links are broken by now, GameBoy Dev’rs has a ton of resources on it.

Gameboy Z80 Cribsheet – A really fantastic cheat sheet for Gameboy assembly programming. It’s meant as a reference, so you won’t necessarily be able to learn a lot from it, but it keeps you from having to look stuff up. I highly recommend printing out a copy.

Gameboy Development Wiki – Documentation, tutorials, code examples, hardware information, information on tools like assemblers/compilers/emulators… you can get a lot from this page.

And, if you’re an IRC fan, check out #gbdev on EFnet.