GameBoy Development Setup

• This page gives complete instructions for setting up a an editor, assembler, linker, and emulator for the GameBoy on any Windows system (98 through Vista).

• An environment for OSX and Linux is possible but is not currently supported for class.

  • If somebody wants to volunteer instructions for setting up an environment on one of those two platforms, they are welcome to add them to this page

• All software referenced on this page is available and maintained on the class software page. Open it in a new tab or window.

• All software is free

---

Windows OS (all)

basic environment

• If you have a USB flash drive, keep the complete development environment on this drive
  • The complete development environment has a small footprint
  • By putting the environment on the flash drive, you are portable
  • none of the development tools require installation scripts
• You can save your developer tools in any directories you want

  • for simplicity, I will assume you are installing on f:\gameboy and I will assume a directory structure that makes sense to me. You are welcome to change this as you see fit.

emulator

run gameboy ROMs on a standard PC

setup

• download nocash gameboy emulator/debugger for dos/windows

  • choose the standard Windows 32bit version

  • extract all files to f:\gameboy\no$gmb

test

• get a GameBoy ROM, such as Pacman

• save the ROM to f:\gameboy\no$gmb\SLOT

• open f:\gameboy\no$gmb with Windows Explorer and click on GMB.BAT to run the emulator

• On first run, you will see 2 initial flash screens
  • disable the first flash screen with the check box in that screen

  • disable the second flash screen (emulator is older than 6 months) by going to options --> emulation setup --> other and unchecking the box labelled Warn if older than 6 months after the emulator loads

• once the emulator loads, from the file menu choose Cartridge Menu (FileName). Navigate to find the GameBoy ROM you downloaded and open it.

• controls can be changed in options --> Controls Setup

assembler and linker

build GameBoy assembly code

setup

• download RGBDS

  • extract all files to f:\gameboy\rgbds

  • extract examples.zip inside the rgbds.zip file to f:\gameboy\rgbds\examples

  • extract docs.zip inside the rgbds.zip file to f:\gameboy\rgbds\docs

• download assemble.bat and makelnk.bat and put them f:\gameboy\rgbds

test

build "Hello World" program

• download hello-world.asm, gbhw.inc, ibmpc1.inc, and memory.asm, and save all of them in f:\gameboy\rgbds

  • instead of hello-world.asm you can download hello-world-with-comments.asm to read tutorial comments in the code. The actual code is the same with both files.

• go to the command prompt (cmd) and change to directory f:\gameboy\rgbds

• type assemble hello-world

• hopefully you will see something like:

  assembling...
  Output filename hello-world.obj
  Assembling hello-world.asm
  Pass 1...
  Pass 2...
  Success! 3471 lines in 0.15 seconds (1335000 lin
  linking...
  fixing...
  Validating header:
          Nintendo Character Area is OK
          ROM size byte is OK
          Cartridge type byte is OK
          Checksum changed from 0x0000 to 0xF268
          CompChecksum changed from 0x00 to 0xA7 

• if the build was successful, you will find hello-world.gb in f:\gameboy\rgbds

  • hello-world.gb is a GameBoy ROM. Load it in the emulator to confirm that it works.

editor

edit assembly code

• I recommend SciTE as your editor

  • provides line numbers, which you will reference when tracking down errors reported by the assembler
  • nice color coding
  • very small footprint
  • open-source

  • Recommended version of SciTE: single file executable called Sc1 (510K)

  • save it anywhere you want (f:\gameboy, perhaps)

  • open hello-world.asm with it and see how it feels.

OS X

OS X support is available for the assembler and linker, and is referenced on the class software page. If you have specifics on how to get this to work, please add them here.

Linux

Linux support is available for the assembler and linker, and is referenced on the class software page. If you have specifics on how to get this to work, please add them here.