a technical blog

Gameboy Development on Mac OS X

with 2 comments



357294As I have gone more and more low-level over the past month, I was searching for a platform that is well understood/documented, not too fancy and thus allows me to use it for learning on different topics at once in a fun way. I.e. micro-processors/electrical-engineering, emulators, dev-tools.

Well, I found the old Gameboy to match that category:

  • Electrical Engineering: Building own game cartridges/ROMs, ROM-readers/writers and play around with other interfacing possibilities. As it happens, I still have my old Gameboy lying around… somewhere…
  • Emulators: Write a simple emulator for the Gameboy’s Z80 processor. Compared to others, the instruction of the Z80 is “quiet” small. Except for the CHIP-8 language, there are not many other processor that are this popular and have an as small instruction set.
  • Dev-Tools: Understanding how compiler and linker for this platform work and tinkering with it. As one of the most popular tool-chains (Rednex Gameboy Development System358295) is open-source and a comparably small project, this is hopefully not a month-long endeavor.

And I like doing game-development for fun anyway. With a quiet old and restricted platform like the Gameboy, this is a nice thing to do in with limited time and good results. Building only a simple game for PC or any of the latest Mobile-platforms (iOS, Android) can take month when you also have some sense for art and style. With a four-color 160×144 pixel display, you are so restricted on itself, that doing the graphics yourself is quiet easy; even for someone that is not a great artist. I was surprised what can be achieved on a 14 hour flight. Maybe I will even enter the next Ludum Dare359296 with a Gameboy game.

The first step required to dive into the world of Gameboy development is to set up the development tools, emulator and some more useful tools like tile-editors on your Mac. The main purpose of this post is to describe the steps I have taken. And as it was more then just click-click-finish at some stages, I hope this will also be helpful to others.

Development Kit

RGBDS360297 seems to be a popular set of developer tools for the original Gameboy. It contains four command-line tool for which two are the assembler and the linker. Unfortunately, there is no binary available for Mac OS. Fortunately, it is open source. With minor modifications I was able to compile the tools for Mac OS X Lion. You can find the compiled binaries (rgbds.tar361298) and the Makefile I used in my github repository362299.


Next thing I needed for development was an emulator with an embeded deugger. Who writes a working game with closed eyes, loads it onto a gameboy cartidge and it works? Well, at least not me.

The emulators I found to be the best matches are no$gmb363300 and bgb364301. Both are similar feature wise; bgb seems to have been implemented based on no$gmb, so both interfaces look alike and also shortcuts in the debugger are mostly the same. bgb is still actively developed and you can also get tips by the developer in the EFNet #gbdev IRC channel.

Both emulators are for windows originally and they are not open source. So, using Wine was the only real option. If you don’t have Wine yet installed, you might want to download MacPorts365302. It is a package manager for Mac OS and also allows to easily install said software. As you also need to have the X11 window server installed for Wine to work properly, best is to follow these instructions366303 for the whole installation.

The Installation of wine itself is straightforward: After the installing MacPorts type “sudo port” in the to start the MacPorts package manager. Supply your user’s password and the prompt of the package manager should appear. Type “install wine” and do something else for the next half hour. This will download all dependencies (a lot) and install Wine on your system. I got an error like

:info:build Assembler messages:
:info:build Fatal error: invalid listing option `r'
:info:build winebuild: /opt/local/bin/gas -arch i386 failed with status 256

while installing Wine because it seemed to interfere with other packages I have already had installed. If you also encounter this problem, follow the workaround at the bottom of this bug-ticket367304:

sudo port clean wine
sudo port -f deactivate binutils
sudo port install wine
sudo port activate binutils

Once you have installed wine successfully, you can start the emulator. I was not able to get bgb running yet but no$gmb works just fine. Get the 32-bit Windows version from here368305 and start it with “wine NO$GMB.EXE” from the commandline.


As said before, a quiet restricted platform like the Gameboy allows also a developer without a hand for art to create nice games. Still, you might want some tools to assist in the process. The Gameboy Tile Designer369306 and the Gameboy Map Builder370307 are two such tools. Easily generate tiles and maps and directly export them into an assembler-file containing the required data to directly work with the tiles/maps. These tools are again windows-only but work just fine with wine.

Unfortunately, as of this writing, the host for these tools seems to be shutting down its operation completely, so I hope the owner of these tools will find another host soon.

Getting Started

That’s about what you need if you want to get into Gameboy development and have some retro-fun. To point you in the right direction for getting started I can recommend the notes of the Wichita State University’s 2008 Z80 Assembler Programming lecture371308. Luckily, the exact same tools we just installed on our system are used 🙂

Written by 38leinad

March 3, 2012 at 1:57 pm

Posted in gameboy, macos

2 Responses

Subscribe to comments with RSS.

  1. Hey thanks for the concise instructions. I found this very useful. I’ve managed to get the emulator running after installing wine. I am having difficulty however assembling the hello-world.asm that is supplied in the Wichita University notes.

    Would you be able to elaborate a little more on your Development Tools section. I’ve downloaded the files that you kindly made available on your git repository but I don’t understand the line “With minor modifications I was able to compile the tools”. What do you mean by compile the tools? At what point do I run the make file and when do I use the patch? I can’t really understand the make file and whenever I run it I get “mkdir: rgbds: File exists”. Is this supposed to be used when I want to compile my code?

    Sorry if these questions are little stupid. Thank you!


    September 6, 2014 at 5:34 pm

  2. I Sorry for the spam, but I just realised (I think) that I was supposed to unzip the file and run the make file while those extracted files were in the same directory. When I did this I seem to get more progress in the command line but still errors. It would appear that I’m missing a lot of stuff? See below :

    mkdir rgbds
    cd LINK; \
    gcc -x c -o link -IINCLUDE -I../ *.C; \
    mv link ../rgbds
    /bin/sh: line 0: cd: LINK: Not a directory
    clang: error: no such file or directory: ‘*.C’
    clang: error: no input files
    cd RGBFIX; \
    gcc -x c -o rgbfix -I../ MAIN.C; \
    mv rgbfix ../rgbds
    /bin/sh: line 0: cd: RGBFIX: Not a directory
    clang: error: no such file or directory: ‘MAIN.C’
    clang: error: no input files
    cd LIB; \
    gcc -x c -o lib -I../ -IINCLUDE *.C; \
    mv lib ../rgbds
    /bin/sh: line 0: cd: LIB: Not a directory
    clang: error: no such file or directory: ‘*.C’
    clang: error: no input files
    cd ASM; \
    cat YACCPRT1.Y > ASMY.Y; \
    cat YACCPRT3.Y >> ASMY.Y; \
    bison -d -o GAMEBOY/ASMY.C ASMY.Y; \
    patch INCLUDE/OUTPUT.H ../patch; \
    mv asm ../rgbds
    /bin/sh: line 0: cd: ASM: Not a directory
    cat: YACCPRT1.Y: No such file or directory
    cat: GAMEBOY/YACCPRT2.Y: No such file or directory
    cat: YACCPRT3.Y: No such file or directory
    cat: GAMEBOY/YACCPRT4.Y: No such file or directory
    ASMY.Y:1.1: error: syntax error, unexpected end of file
    patch: **** Can’t open patch file ../patch : No such file or directory
    clang: error: no such file or directory: ‘GAMEBOY/asmy.c’
    clang: error: no such file or directory: ‘MAIN.C’
    clang: error: no such file or directory: ‘FSTACK.C’
    clang: error: no such file or directory: ‘GLOBLEX.C’
    clang: error: no such file or directory: ‘LEXER.C’
    clang: error: no such file or directory: ‘MATH.C’
    clang: error: no such file or directory: ‘OUTPUT.C’
    clang: error: no such file or directory: ‘RPN.C’
    clang: error: no such file or directory: ‘SYMBOL.C’
    clang: error: no such file or directory: ‘GAMEBOY/LOCALLEX.C’
    clang: error: no input files
    chmod u+x rgbds/*
    chmod: rgbds/*: No such file or directory
    make: *** [all] Error 1


    September 6, 2014 at 5:47 pm

Any thoughts?

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: