Game Boy Tracker

From rv6502
Revision as of 07:38, 20 July 2014 by Rv6502 (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Game Boy Tracker 2.6.1 on Raspberry Pi

This is the export-enabled public release my Game Boy Tracker originally written in 1999, and the replay routines for Game Boy which were used in games such as Project S-11, Shantae, ESPN National Hockey Night, and Who Wants to Be A Millionaire.

Quick Start

If you unpack the whole archive (for the correct operating system, with directories) the executable should run and pressing CTRL+R will let you select and open a music file, F5 to play the music, F8 to stop, CTRL+Q to quit, ALT+ENTER will toggle fullscreen mode.

For the built-in help press the F1 key or you can read the documentation files in the doc/ directory.

The application uses relative paths and should run off a USB key just fine.


Yes you can.

  1. Load your .MGB song
  2. Go to the Order & Options Page (F11 or CTRL + SHIFT + Minus)
  3. Go to the "Music export file (without ext.)" text box
  4. Type the file name to export to (for example "potatoes" without the quotes) in the text box. NOTE: you must use a valid assembly name because it is used to generate data labels in the source code (no spaces, A to Z, a to z, 0 to 9 and underscores only).
  5. Save the mgb file (optional, but this will save the export settings for next time)
  6. Go to the pattern page (F2 or CTRL + SHIFT + 2)
  7. Press CTRL+E, this will export the music and instrument data to the files export/potatoes.z80 and export/
  8. Use those files to compile a ROM using the example projects (see next sections)

Get RGBDS Tools

This is for Windows, there is a version of those tools for Linux now and they probably are portable to OSX but I haven't tried them, I'll look into it if people show enough interest.

  1. Google for RGBDS (Rednex Gameboy Development System) or go to
  2. put the files RGBASM.EXE, RGBFIX.EXE, and XLINK.EXE into the bin/ sub-directory of where you unzipped the tracker (there's a file that is called "put_rgbds_executables_here.txt")
  3. now you can go into the player/one_bank and-or player/multibnk and run make.bat to build a test ROM
  4. if all goes well it will output a file that should be identical to (This ROM is there for reference)


Compile Single-Bank ROM (Limit 12KB approx total)

(Assuming you named the file "potatoes" without the quotes)

  1. Go into the directory player/one_bank
  2. Open the file music.def in a text editor
  3. Change include "..\\..\\export\\" and include "..\\..\\export\\music.z80" to match the name of your exported file (for example include "..\\..\\export\\" and include "..\\..\\export\\" , do not forget the quotes, you need them here)
  4. Replace dw Inst_music and dw Music_music with dw Inst_potatoes and dw Music_potatoes
  5. Remove the lines with music2 or change those to match the 2nd song you want to put into the same ROM (keep in mind the single-bank player supports only about 12KB total)
  6. You can add more songs (if they fit)
  7. Run the make.bat batch file if all goes well it will generate a 32KB ROM file named (if the rom is larger than 32KB that means the music data is too large for single-bank and it will crash on GameBoy)
  8. Flash to a cartridge and enjoy your tunes on hardware

Compile Multi-Bank ROM (Unlimited Size *)

  • Max 16KB Instrument Data PER SONG
  • No other limit, go nuts.
  1. Go into the directory player/multibnk
  2. Open the file music.def in a text editor
  3. Change include "..\\..\\export\\" and include "..\\..\\export\\s11space.z80" to match the name of your exported file (for example include "..\\..\\export\\" and include "..\\..\\export\\" , do not forget the quotes, you need them here)
  4. Search and Replace Inst_s11space and Music_s11space with Inst_potatoes and Music_potatoes (there's two of each)
  5. Remove the lines with music or change those to match the 2nd song you want to put into the same ROM
  6. You can add more songs, just follow the same pattern. There is no limit to the total size other than what the MBC5 can handle.
  7. Run the make.bat batch file if all goes well it will generate a ROM file named
  8. Flash to a cartridge and enjoy your tunes on hardware

Easy Hacks For Coders

The player could easily be abused to run multiple songs at the same time on Game Boy Color if you run the player using different memory banks, you can also edit the code to run multiple songs without switching banks and share the same instruments. have fun.

The songs will each ideally need to use different channels but its not necessary (it'll just fight over audio registers, could be interesting).

Every pattern is exported individually in its own section and its own label so its fairly easy to hack the player to jump around songs and play multiple patterns at the same time.

Download links (2.6.1)

Supported Platforms

I was able to test on

  • WinXP SP2 (32 bits)
  • Win7 (32 & 64 bits)
  • Mac mini Core 2 Duo, OSX 10.6.8 32 & 64 bits (See notes)
  • Various popular Linux distros, x86 32 and 64 bits, ALSA and PulseAudio.
    • Mint 17
    • Slacko 5.7.0
    • Open SUSE 13.1
    • Fedora 20.1
    • Ubuntu 14.04
    • Xubuntu 12.04
    • OpenPandora Release 1.55 Super Zaxxon, Kernel 3.2 (See notes)
    • Raspberry Pi 2011, Raspbian (See issues)

With AMD/ATI, nVidia, and Intel Atom (PowerVR 545) cards on Windows & Linux, Intel GMA 950 on the Mac.

Minimum specs originally was AMD K6-300Mhz under MS-DOS, anything fairly recent should not have a problem as long as the GPU is doing the scaling or no scaling is used.

PC Graphic Driver Issues

If the tracker window is all garbled or nothing shows up you can try one of these command line options:

  • --force-power-of-two-textures
  • --no-gpu

On windows you'll have to make a shortcut to the executable to pass the option, launching from the command line crashes the application on windows (I'll look into it as soon as I find some time).


Normally OSX grabs most the F1 to F12 for its own uses so as a work around you can use CTRL+SHIFT+1 to CTRL+SHIFT+= instead to switch pages in the tracker.

To resize the window you can drag the lower-right corner (there's no /// graphic but it works, I'll try to find time to fix that).

I only have an Intel Mac mini with OSX 10.6.8 installed, I was able to test the 32 and 64bits builds.

I don't remember setting a minimum OS version so it might work on older versions of OSX as long as the libraries are compatible.

No clue if it'll work on PowerPC, in theory its compiled for a G4 processor and the code should be independant of endianness but the tracker was never tested, I'll see if I can find a cheap G4 or G5 Mac with OSX for fun (people tend to charge stupidly high amounts of money for their old PPC macs).


OpenPandora - GameBoy tracking on the BMW of handhelds

When toggling fullscreen mode the application loses focus, you must click on the window (tap the screen) to set focus for keyboard inputs to work again.

Instead of F1 to F10 you can use CTRL+SHIFT+1 to CTRL+SHIFT+0 to switch pages (Left & Right shoulder buttons + number keys) so you don't have to press the Fn Key first.

No PND yet, for now you'll have to unpack the archive to an ext2 partition or work some magic.


There's a glitch with the dispmanx (or the way I use it) which often makes the whole X11 framebuffer go black. To work around this you can run the tracker without OpenGL by launching it with the command line option --no-gpu or if you want GPU scaling switch to the console and back to X11, this fixes the black screen (CTRL+ALT+F1 followed by ALT+F7).

If anyone knows how to fix this you're very welcome to contact me with the info. I've also tried making the layer only shows up over RGB color key 0xFF00FF so that other windows could cover the OpenGL display but I haven't found the magic voodoo settings yet.

I haven't had much time to spend on that particular port but it's working well enough that its worth releasing even with the display glitch.


If you want to contact me regarding the tracker or replay routine:

GBTracker addr.png

Or see the Support And Donation Page