CS/ENGR 101: Gameboy Session
Fall 2006 – Day 1


Setting up VisualHam

We will store the Gameboy programs on the network drive (I:). You probably will want to store your Gameboy programs in a separate folder. If so, browse to the I: drive, then create a new folder (e.g., cs101).


We will be writing Gameboy programs using VisualHam, a cross-compiler and emulator. (A cross-compiler is a compiler that generates machine code for a processor other than the one it is running on. An emulator is a program that will run this machine code as if it were running on the actual processor.) VisualHam (VH) is launched by going to the Start menu, then Programs, then CS, then VisualHam, then VisualHam. You should maximize the window if it is not full size.


To start writing a new program in VisualHam, you do the following steps:


  1. Click on the File menu and choose New, then Project. This gives you the dialog box to create one.

  2. In the new project dialog box, select [C] Empty, type in a project name (e.g. day1, the name cannot have any spaces), and type the folder name of where you want the project to go (e.g., I:\cs101\day1). Click OK.

  3. In the left panel, there is a tree representation of the project. The code you write goes in the main.c file. Double-clicking on the entry will bring up the file in the main edit window. VH creates a skeleton program containing the minimum code necessary for a Gameboy program.


Writing a Gameboy program

Here is a C program that draws two lines as an X on the Gameboy screen. Note that all but 3 lines were already present in the program file.


#include <mygba.h>   /* Gameboy libraries */

int main(void)
{
   ham_Init();

   /* These three lines were added */
   ham_SetBgMode(3);
   ham_PutLine(0,0,239,159, COLOR_RED);
   ham_PutLine(239,0,0,159, COLOR_GREEN);

   while(TRUE)
   {
       
   }

   return 0;
}

Type this program into the edit window. Note that this editor automatically indents the code and uses different colors for some of the constructs in C. E.g., the comments are in green and the reserve words are in blue.


When you are done typing in the program, save it. (File|Save or type Ctrl-s or click the floppy icon on the toolbar.) For longer programs, you want to do this fairly frequently, and always before you try to compile your program.


Building a Gameboy program

To build the program, go to the Project menu, select Execute Target, then choose Build (or press the F5 key). This will compile and link all of the files in the project into an executable program. A window at the bottom of the screen should report on the progress being made during the build.


If you have any syntax errors, the progress window will contain a list of errors and the line numbers. (You may have to scroll up to see them.) Double-clicking on an error message should highlight the line in error and cause the cursor in the source edit window to be put at that line. Correct any errors and build the project again.


If the compilation phase is successful, the system will link your program with the library routines to create an executable program.


Emulating a Gameboy program

VH allows us to run the program in the VisualBoyAdvance emulator so that we can see what the program does without downloading it into the Gameboy. Go to the Project menu, select Execute Target, then choose Build+VBA (or press the F7 key). This will both compile the program and then run it in the emulator.


The emulator will execute your program. A window exactly the size of the Gameboy display will pop up and will display exactly what your program will do on the actual Gameboy hardware.


To end the program and close the emulator window, type ESC. (The normal close window button does not work for this program.)


Downloading a Gameboy program

The final step in Gameboy program development is downloading the program into the Gameboy hardware. We will be using the Flash2Advance F2A PowerWriter program to do this. F2A PowerWriter is launched by going to the Start menu, then Programs, then CS, then Flash2Advance, then F2A PowerWriter.


To download the program, you do the following steps:


  1. Connect the download cable from the Gameboy to the computer. Turn up the volume on the Gameboy.

  2. Click on the Add button. Browse to your project folder and choose the file with the .gba extension. Click Open.

  3. Click on the Write F2A button. As the instructions say, turn on the Gameboy and simultaneously press the Select and Start buttons until the download begins. (The Gameboy will make a distinctive sound when this happens.) Information on the download will be displayed on both the Gameboy and the computer.


  1. Disconnect the download cable. Restart the Gameboy by turning the power off and on. It should now be running the program that you wrote.


Exercise

Write a program to draw something interesting. Use at least three colors.

09/15/2006 3