Gameboy project week 7: A ROM for showing custom graphics

February 19th, 2013

As per usual, this week’s project is fashionably late. This week’s project is an image viewer ROM which you can use to show custom graphics on the screen. This is for example useful for modders who want to display a logo on the screen when doing a photoshoot. I’ve been making these ROMs for people on request, but even so, I have been limited to using an old DOS utility (yes, DOS, not just command line) called PCX2GB. However, this application is slow and buggy, and with the advent of 64-bit operating systems, DOS applications can no longer run natively. So for every one of those ROMs I’ve made, I’ve had to start DOSBox, then include the files that PCX2GB output into the project and recompile the ROM.

This project sets out to change that. The project consists of two parts. A Gameboy ROM which can be patched with one or more images, and Python script that converts the image to the Gameboy tile format and does the appropriate patching. The result is a Gameboy ROM you can use to show the images.


The patcher is a Python script, which means you need to install Python to run it. You should install the 32-bit version of Python 2.7 — the one marked x86 instead of x86-64. Sorry to those who prefer 3.x.
Additionally, you need PIL, or Python Image Library which is used to load the image files.

How to use the patcher

To use the patcher you need to prepare as many images as you want, which are exactly 160*144 pixels and color reduced to contain a palette of exactly 4 colors/shades of gray. The actual color depth of the file can be anything, as long as the image contains exactly 4 unique colors. The image can be in any format that PIL can load, which is almost any format. Avoid using JPEG images however. Use PNG, GIF or BMP.

When you have correctly installed Python 2.7 and PIL, you can use the patcher by giving the following command, with sample output:

python image1.png image2.png image3.png
===Processing image1.png
Optimized image to 127 tiles.
===Processing image2.png
Could not optimize image to below 256 tiles. Image stored as 360 tile image.
===Processing image3.png
Warning! Image has only 2 unique colors (instead of exactly 4.) Color table will
Optimized image to 5 tiles.
===Processing image4.png
Could not optimize image to below 256 tiles. Image stored as 360 tile image.
===Processing image5.png
Could not optimize image to below 256 tiles. Image stored as 360 tile image.

The first agument, is the name of the GB file to be produced. This is then followed by any number of image file names (up to potentially 256 images.) The output tries to be informative about what the patcher is doing.


imagerom.gbbase is the actual viewer code. This is used as the base ROM for the finished product, thus the different file extension. If you run this standalone (which there is no point in doing) you will see an X shape and hear two dissonant tones, as a warning message.

The Gameboy software

The Gameboy software is dead simple. Press left or right to scroll through the pictures or press A to invert the palette

Note on the inner workings of the patcher and ROM

The Gamboy graphics hardware is working with tiles, which are addressable 8*8 pixel blocks. If an image has repeated instances of the same 8*8 pixel area, those can be addressed as the same tile. The patcher tries, if possible, to “compress” an image this by removing redundant tiles. However, if an image contains more than 256 unique tiles, it instead displays the image with no repeated tiles, for a total of 360 tiles being displayed on the visible area of the DMG screen.


The download also comes with a cople of image that you can play around with until you make your own image.

11 Responses to “Gameboy project week 7: A ROM for showing custom graphics”

  1. Eduardo Sánchez says:

    Should I be running this script from the python command line or the windows command prompt? Python gives me an invalid syntax error; I try to cd into the folder with the files and it gives me the same error.

  2. nitro2k01 says:

    From the command prompt, and with all files in the same directory if you want to simplify things. But did you folllow the instructions, in particular the part in bold?

  3. radian says:

    Works like a charm.

  4. Eduardo Sánchez says:

    Yeah, I was doing everything right; it worked when I used this command:

    “ image.png”

    … apparently the “python” command was irrelevant in my setup.

  5. Tyler Barnes says:

    Took a great deal of effort to get PIL built on my PPC mac but I finally got there. Your script works very well.

  6. kevster15 says:

    Works great!
    Nitro, how can I animate these roms? I know in a previous article you mention animating frames to achieve more s
    ’shades’? I’m a novice but I’m learning fast, thank you!

  7. Clay Morrow says:

    Hello Nitro,

    I was just reading about your custom graphics ROM and was wondering if you would consider making me a cart with my own custom image on it? I would of course pay for the cart and your time + any shipping and handling. Please let me know if you are interested.

    Thanks for reading.

  8. Douglas Mendenhall says:

    I tried this, and keep getting syntax errors. where am i supposed to extract to?

  9. mistery says:

    I can’t :(

  10. James says:

    The Python Image Library is a mess of unmaintained code these days but thankfully pillow is a drop in replacement. a simple pip install pillow and your good to go

  11. jyushimatsu says:

    Beautiful gameboy graphix

Leave a Reply

If you'd rather contact me directly, please use the following e-mail address: It appears that you have Javascript disabled. Please enable it to see my e-mail address.