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.

Gameboy project week 6: Can I have an A-MEN?

February 11th, 2013

Fixed the download link at the bottom of the post.

I’m tired. I need a break. What better choice than the amen? Probably a dozen, but nevermind that.

This week’s ROM is a sample masher that lets you apply live effects and rearrangement to a loop. As such, it’s using the wave channel. During the development of my sample playback routine, I accidentally discovered a solution to an old problem. The wave channel on the Gameboy has a buffer containing 32 samples, or 16 bytes which is normally used to store a repeating wave form such as a sawtooth wave, square wave or sine wave. However, if you continually reload the buffer with new data, you can play a sampled waveform. This is all well except that the channel needs to be stopped before the buffer can be reloaded. The problem is that this causes a small spike in the waveform. It is noticeable on a DMG, but completely abhorrent on a GBA, to the point of making kit instruments unusable. I found a solution to this problem which is simple and elegant, which is to simply turn off the channel in ff25, the sound routing register, while the buffer is being refilled.

With some swift work from Johan, this fix, which I call the antispike fix, is now included in the latest version of LSDj, 4.7.0. And kit instruments now sound eh-ok on GBA.

So, this week’s ROM is a simple, GUI-less ROM which lets you process a short loop, for example an Amen. This is another “failed” project in that it doesn’t have all the functionality I originally wanted to include. Here’s the functionality in this version of the ROM:

  • You can press start to start or stop playback of the loop.
  • The loop can be freely pitched by pressing select+up/down.
  • While the loop is playing, the ROM sends out an LSDj compatible sync signal on the link port.
  • You can press the D pad to rearrange the loop in 16th “slices”.
  • You can apply effects by holding either B or A, or both. B enables a granular/repeater effect. B+up/down controls the repeat size. A enables a stutter effect. A+left/right controls the stutter length.
  • Effect values can not be changed while one direction on the D pad is held down. While this might sound strange, the purpose of this is that you could be able to “roll” around on the D pad to mash the beat while an effect is triggered without changing the effect values.
  • Finally, you can press select+start to enable a “special” effect. When this effect is active, the pitch of the wave channel does not follow the general pitch of the loop. This causes a phasing type effect when adjuting the pitch.

Sound examples, some notes on the development process as well as information about how to replace the sample with your own sounds will follow shortly.

Fixed link: Download

Gameboy project week 5: LittleFM 0.5 (finally) released

February 4th, 2013

This week’s project is (again) slightly late, but hopefully worth the wait. This is the latest and greatest version of LittleFM, and alternative file manager for LSD. Here are the key features in this version:

Key features

  • LittleFM now comes with a Java based patcher application for easy application to any unpatched LSDj ROM, including (most probably) future versions. No more IPS patches that only work with a single version of LSDj.
  • LittleFM is fully Drag’n'derp compatible. This includes interfacing with the virtual “file system” of the Derp and making sure that any song data stored in flash will be copied back when you copy the GB file off of the cartridge.
  • LittleFM now supports song trading over a link cable. Currently only in the form of transfering a whole 128 kB sav at a time, but this may still be useful for backups and redundancy.
  • LittleFM now checks that the SRAM is ok, both in terms of hardware and corruption. If the SRAM is corrupt or uninitialized, LittleFM will offer you to initialize it, but also to leave it as is. If the SRAM is malfunctioning on the hardware level, the program will halt with an error message.
  • The stupid screen scroll bug is gone! You can now scroll to the bottom of the song list in SAVs with 32 songs, without problems.

I’ve also made a number of under the hood tweaks and small bug fixes.

Some notes on the features

ShitStrapOn, the patcher application

If you have Java installed, starting the application should be as simple double clicking the file. Should you need to execute it manually from the command line, you should be able to run it with something like java -jar ShitStrapOn.jar

The patcher will ask for three things, a clean LSDj ROM, the file, and a location where to sav the output. However, it will search for and not ask for it, if the program finds the file in the same directory as the .jar file. A clean LSDj ROM means one that has not been patched with LittleFM and does not contain any LittleFM save data in ROM. The ROM may still have ny number of kits, so long as there is one free slot where LittleFM can reside.

The name originally meant bootstrap for Shitwave. Since, then, however, the project has come to be used for patching LSDj ROMs with LittleFM. If you’re offended by the name, (or the subtext, a dirty dildo in LSDj’s ass,) too bad for you.

Link cable support

LittleFM sav trading
The link feature is a hardware feature, and any attempt to use it with any emulator is likely to end in missed bytes and tears. In my experience so far, it works perfectly both between a DMG and a DMG, and a GBC and a DMG. A GBC can send data about twice as fast DMG. (Well, it can transmit much faster than that, actually, but the *2 mode is what I’ve found to be safe for these transfers.)

LittleFM will show a progress bar as the transfer progresses. If all is well, both sides will move their progress bar in synch, and will both show OK on their respective side. If a transfer is stalled, it is safe to turn off the Gameboy, as long as no data is currently being actively transmitted or received.

You can use the Nanoloop MIDI adapter with, sort of. Sending data from the PC usually works ok-ish. However, make sure that the receving Gameboy shows ok at the end of the transfer, and that songs load correctly when the transfer is finished. Receiving data from the Gameboy to the PC can work but is extremely touchy. You may lose bytes in transit, with or without an error message. Be extremely wary of corruption, and make sure the received file is 131072 bytes big. Not a single byte less or more! Remember, unlike LSDj’s own file manager, LFM will give you an error on almost every kind of corruption, so use it to detect errors early.

Please also the previous post about LittleFM 0.4.The same basic precautions apply. Pressing erase flash in the Bleepbloop/Smartboy etc type flasher application will delete all songs stored in flash. Save project will overwrite whatever was in that flash slot before.

Have fun and be safe, and report any issue to me.

Download LittleFM.

And a quick plug: If you have an older flash cart (for example belonging to an older LPT port flasher) then I would like to borrow the cartridge for a while for science, to make it work well with LittleFM and other software I have in the pipeline.

Gameboy project week 4: A test/”welcome” ROM

January 28th, 2013

This week’s was supposed to be a MIDI controllable version of Shitwave, and while that’s done, I found out it was a bit less exciting than I was hoping for, so I want to try to come up with some new ideas for that. However, I found a new project to do over the weekend. beware, the author of BGB (Gameboy emulator and debugger) mentioned that he wanted to include a ROM with the emulator (not specifically mentioning me) that a new user of the emulator could use to test the emulator, without having to go to a different site to find a ROM. These are his criteria for this ROM:

  • Should show some form of graphics, and ideally show some form of animation.
  • Should play sounds.
  • Should show the user which buttons are currently pressed.

All these things are potentially useful in case the emulator (or the configuration of the emulator) is not working correctly for some reason.

For this week’s project I’m also including the source code. I pondered whether to do this or not for a couple of reasons. One reason is code vanity. When you release the source code for something, it lets other people judge the code. I would describe my programming style as casual and chaotic. This means that in a lot of cases I make things up as I go along. This means that sometimes I do things in ways that are “wrong”, or only works under certain circumstances, or are unnecessarily tedious. Another risk with releasing the source code is that people will invariably ask you for help in private communication. There’s not necessarily anything wrong with that per se (unless the question is stupid) and I try to answer questions I get in my inbox, but it may not be the most efficient way to get an answer. You may want to try my Gameboy development forum or perhaps more realistically if you want people to see your question, NESDev’s Gameboy subforum. Or #gbdev on EFNet if you use IRC.

The program

The program in its current form shows the BGB icon, BGB in a big font and the text “press buttons to test”.

There’s a starfield in the background with 24 indiidual stars, made up of sprites. The stars travel from right to left and can travel at three different speeds (1, 2 or 3 pixels per frame) and there are two types of stars. Their Y positions are determined by an LFSR random number generator.

When you press one or more buttons, an indication is shown on the screen. A note is also played. I wanted to get this function right. The scale used for the notes is a mixolydian scale (or, major scale with a flat 7th) because plain major scales are boring. The note are played duophonically by alternating between the two pulse channels, so you can play two note chords. And the program also alternates between playing the actual note and playing it slightly detuned. This gives a slightly phasey sound when playing the some note multiple times, which in my opinion sounds better.

There’s also a melody played on the wave channel, which pseudorandomly generated by the same random number generator which is used for the stars. It plays notes from the same scale, but if you want you can turn it off by pressing select+start, say if you want to actually use this ROM for playing melodies.

The ROM also has an easter egg, which you might be able to find.

The ROM currently says BGB, but if you want, I can customize it for you to show your own logo, if you want to use it as the standard ROM to come with cartridges you sell. (The usual suspects, you know who you are.)
Read on…

Gameboy project week 3: A simple MIDI ROM

January 20th, 2013

nitromidi1 is a very simple Gameboy MIDI ROM. It can be used with an Arduinoboy or Nanoloop USB MIDI adapter. It’s not meant to be all that practically useful atm. Rather, I created it to have all the plumbing in place for future MIDI software.

It currently responds to the following things:

  • MIDI channel 1 only.
  • Gameboy pulse channel 1 only.
  • Note ons. (But currently not note offs!)
  • The typical “panic” button. (Channel mode messages $7B, all notes off and $78, all sound off.)
  • The pitch wheel, currently with a fixed range of +/-7 semitones.
  • CC 71/$47 which controls the pulse width of the wave.
  • CC 72/$48 which is a combined attack/release control, ie. the second nibble of the envelope byte. The control scans from short decay to long decay to constant volume output to slow rise to fast rise. In other word, the following envelope values mapped onto a knob: 1-7,8,F-9.
    As noted above, it doesn’t respond to note offs, so be careful with rising envelopes!
  • It has no GUI except a lines pattern indicating CPU usage. This is literally
    made by changing the background palette when the CPU is busy.

Have fun, and report any bugs/anomalies/feature requests.

Download nitromidi1

Mystery ROM explanation

January 16th, 2013

^ The ROM in action.

So, what about the mystery ROM? If you try to run the ROM in an emulator, it will do nothing. If you try to run the ROM on actual hardware, preferably a DMG, you might hear the faint sound of the first couple of bars of the Super Mario Bros overworld theme if you hold up the speaker to your ear. But what is the relevance of this?
Read on…

Gameboy project week 2: Mystery ROM!

January 13th, 2013

This week’s project is a mystery ROM. It’s a ROM that does nothing. Or maybe it does something, but it’s so subtle that you may not be able to detect it. Or if you think you do, maybe it’s you imagination?

Download the mystery ROM and see if you can figure out anything about it…

Edit: Explanation of what the ROM does.

Gameboy project week 1: More than four shades of green

January 6th, 2013

I’m hereby announcing 2013 as the “one Gameboy project per week” year. This an idea I came up with during a discussion with Seb (little-scale) where I jokingly suggested it as an alternative to the usual “one song per week” type challenges. So, my challenge is to try to do some kind of Gameboy-related project each week. Some of them will be more practically useful projects, like music/noise making ROMs, while others, like this week, will be research projects that I’m doing out of my own curiosity. This week’s project was actually meant to be a different project, but I postponed doing it, and had to settle for a smaller project to have a finished project at the end of the week. (Off to a bad start already. :p )
There’s a big risk this whole project will fail somewhere along the way. If not for lack of motivation (most likely) then because of lack of ideas.

Read on…