Welcome to GBGuide

This is under construction. Please read Duo's ASMSchool until this guide is fully finished.

What is the GameBoy?

The Nintendo GameBoy, strictly speaking, is an 8-bit portable game platform released in 1989. You might ask, "why are you messing with a system that's like 13 years old man?" Well, that's pretty easy to answer. The GameBoy, flat out, is the most successful handheld video game system ever made. One of the best reasons for it's success was the long amount of time it could run on one set of batteries. The Sega GameGear, while a great game machine, required more batteries than the GameBoy and voraciously drained them in less than 1/4 of the time of a GameBoy. This was due to the backlit Color LCD the GameGear had. The GameBoy, on the other hand had a 4-greyscale non-backlit screen. There are advantages and disadvantages to both systems, but I won't go too far into those. The Turbo Express Portable system and the Atari Lynx game system were designed with similar battery killing LCD's and ended up sharing a similar fate of the GameGear.

Nintendo also created a device called the Super GameBoy, which is a Super Nintendo cartridge that has a GameBoy cartridge slot on top of it. You plug in a GameBoy game, turn the Super Nintendo on, and you could play GB games on your TV, with a few "colorized" features similar to how the GameBoy Color colorizes greyscale games. The colorizing wasn't really true colorizing like the GameBoy Color performs, its more like placing colored plastic wrap over a greyscale screen. In addition, a GameBoy game programmed to use the Super GameBoy could draw a 256-color border on the TV screen around the smaller GameBoy screen, and instruct the SGB to generate sounds through the Super Nintendo's sound CPU. There is also another function that is fairly unknown; a GameBoy program can upload small Super Nintendo programs into the Super Nintendo's RAM, and run them. Only one commercial GameBoy game, to my knowledge, ever used this feature: Space Invaders '94. When starting, the game would give you a choice between the original GameBoy version, and a Super Nintendo version that was very very simple, but full screen. The Super GameBoy cartridge is basically a GameBoy with no LCD, instead using a special chip to send the LCD data to the Super Nintendo to display. It's a pretty cool little toy, if nothing else.

After years of phenomenal market success, Nintendo took their little workhorse and threw it back into their workshop for an overhaul. With advances in Electronics and LCD technology, it was possible for Nintendo to redesign the GameBoy with a smaller case, higher contrast LCD, and lower power requirements. The result is the GameBoy Pocket, a system that's much easier to put in your pocket. =) The system eventually came in a small variety of case colors, whereas the original GameBoy was plain ol' Grey. Japan also saw the release of a lighted GameBoy Pocket, named the GameBoy Light. It featured the exact same hardware as the GameBoy Pocket, but with the addition of an "Indiglo" backlit screen. The screen glowed a green-ish blue color.

The GameBoy Pocket was also very well received, since it only required half as many batteries, and played all of the games that were available for the original GameBoy. But again, after advances in technology, Nintendo put their little machine back on the drawing board. This time, the goal was to make a more capable system based on the GameBoy, but with COLOR features and a few hardware enhancements that many programmers asked for. The new system had to be totally backwards compatible with the GameBoy and GameBoy Pocket, and had to be small, like the Pocket version. The end result was the GameBoy Color system. It sported a Color LCD that could display up to 56 colors at a time from a palette of 32,000 colors, had a CPU that could be set to run at 2x the speed of the original GameBoy, and an infrared port for sharing data without having a link cable (though the IR port isn't really intended for active link-play games, since it's short range). Also, there are a few more hardware goodies that programmers wanted. The GameBoy color plays all of the original games, as well as new GameBoy Color Only games that take advantage of the new hardware. The greyscale games can be "colorized" by pressing different key combinations on power-up. The colors don't really change the game to full color, they just change the original game's display to a color set for the Background and 2 color sets for the sprites (characters).

Many accessories were released for the GameBoy, including a monochrome digital camera, a thermal-transfer paper printer, various lights and magnifiers, battery packs, speaker additions, etc. The GameBoy Camera was a cartridge that went right into the gameboy. It would take small greyscale images, play some simple games and music, and print those images to the GameBoy Printer. The GameBoy Printer was powered by its own batteries, and connected to the GameBoy via the link port. Games that supported the Printer could do things like print images, high scores, bonus material, etc.

CPU Basics and moving data around

Welcome to GBGuide, a little attempt at helping people to learn how to code in assembly language on the GameBoy using RGBDS. These tutorials will hopefully be of use to quite a few people, both total newbies and more experienced coders. I am NOT going to just post some source code, give comments and have you cutting and pasting, that won't teach you very much of anything. Instead, I will be going to the lowest levels and explain everything in as much detail as I can so that you can understand "why does this do this" or "why can't I do that?". You will learn how the processor works and how to control it before I ever start writing lessons on how to display graphics or how to make sound. Lesson 1 will teach the student about the layout, structure, and general philosophy behind the GameBoy CPU, as well as basic data manipulation. This CPU is a derivative of the very popular 8-bit Zilog Z-80 CPU, and has many identical features, although the GameBoy's CPU includes memory handlers, I/O control, and other things not found in the Z80 on-chip. There are also a few things that the Z80 has that were taken out of the GameBoy, as they were deemed by Nintendo R&D as unnesecary. (either that or SHARP's custom chip didn't have those options available. who knows.)

Ok, so you're probably thinking, "where do I start?" or "how do I make a game?". Well, we are a LONG way from making a game. You have to learn the hardware and how to manipulate it way before you can even make anything worthwhile. I'm going to start here with the basic structure of the GameBoy's CPU, and then explain how you can make it do your evil bidding! MWA HA HA HA HA HA HA!!!.... uh hrm.. oh sorry. ;-) Well to do ANYTHING with a CPU, you have to MOVE and OPERATE on DATA! And how on earth are we going to do that? Well, with registers that's how. Registers in the CPU are where all data is handled and processed.


Working with and manipulating data with this processor is accomplished through the use of 8 registers inside the CPU. Each of these registers can hold 8-bits or 1 byte of data. The registers can also be paired up to form 16-bit registers for tasks such as addressing data. The names of these registers are A, F, B, C, D, E, H, and L. They can be grouped to form the 16-bit registers AF, BC, DE, and HL. There are also the 16-bit registers SP and PC. Each of these registers has it's own little part to play inside the CPU.

The A register is where almost all data being processed passes through. It is also known as the Accumulator (No, not because it's accumulating dust either!). This register, as well as B, C, D, E, H, L can have data loaded into it directly.(I purposely left out register F) By this I mean you can just say "I want the A register to contain 25!". You don't specifically have to load a value from memory somewhere. It is the only 8-bit register that can be shifted with a one-byte instruction (you'll find out about SHIFT instructions later). It is the only register that can be complemented, decimal adjusted, or negated with a single byte instruction. It is the source AND destination for all 8-bit arithmetic and logical instructions except for INC and DEC, which increment or decrement a register by 1. This means that when you want to perform a certian operation like ADDing two 8-bit registers together, the two numbers you'd want to add would be in A and some other 8-bit register, then the answer would be left in A after the operation was completed. Simple eh?

The F register (F for Flags) is a processor status register that can only be read from and not written to, with one exception. Four of the bits in this register indicate the outcome of generally the last operation performed. One bit indicates whether the last operation produced a zero or not, another bit indicates whether or not the last instruction generated a carry, yet another indicates whether or not the last instruction performed a subtract, and a half-carry flag in case a carry is generated between nybbles in a byte.

The B and C registers are generally used as counters during repetitive blocks of code such as moving data from one location to another.

Registers D and E are generally used together as a 16-bit register for holding a destination address in moving data from one address to another. They can be used for other operations though, as much as the instructions will permit.

The H and L registers are special due to the fact that they are extensively used for indirect addressing as register pair HL. Indirect Addressing is when instead of specifying an specific address for an operation, you could just use the 16-bit value in HL as an address. It's pretty handy for things like address calculations when you need to access an array of value for example. This is the ONLY register pair that can be used indirectly in the instructions ADC, ADD, AND, CP, DEC, INC, OR, SUB, and XOR.

The SP register is the Stack Pointer, where values from PUSH, POP, CALL, and RET instructions are placed or taken. These values are return addresses for subroutines and such. When the GameBoy is initlaized, this register contains the value $FFFE. On the GameBoy CPU, the Stack grows from TOP DOWN. The means that when you PUSH a 16-bit value to the stack, it hangs down the address space from the top like a stalactite (or is it stalagmite? I can never remember).

The PC is the Program Counter. This register tells the CPU the address that the next instruction is to be fetched from in memory. When the GameBoy starts up, this register contains the value $0100.

Well, those are the GameBoy's CPU registers. So now that you think you know those, we'll jump right on into the instructiuons that get to play with those registers. Can you hear it? Can you? Can you? I hear the sound of data screaming! We're coming to get you data! Cower in fear little data for a new ASM coder is born!!! MWA HA HA!!!

8 and 16-bit Loads

Well, when programming, your ultimate goal is to manipluate data, as simple as that might sound. Simple yes. Easy, not nessecarily. These instructions are what move data to and from registers, memory, and oblivion (in the case of directly loading a fixed value into a register).

Register to Register Transfers

The LD (load) instruction can transfer any 8-bit general-purpose register (A, B, C, D, E, H, or L) to any other 8-bit general purpose register. The F register can only be transferred to or from the stack, along with the accumulator as register pair AF (PUSH AF and POP AF).

The common transfer instructions are:

  • LD A, reg - Transfers the contents of reg into the accumulator
  • LD reg, A - Transfers the contents of the accumulator into reg
  • LD reg, (HL) - Load reg with the value at the address in HL
  • LD (HL), reg - stores reg at the address in HL

Note the the destination of the data comes first in the operand field of the LD instruction. The LD instruction changes ONLY the destination, the source stays intact. Rather than being a MOVE style of instruction, it is rather a COPY of the source contents to the destination contents.

Now you try...

  • LD A, B
  • LD C, A
  • LD A, (HL)
  • LD (HL), A

See? Was that really difficult? The first instruction loaded the contents of register B into register A. The next instruction loaded the contents of register A into register C. The third instruction load the memory contents located at the address contained in HL into register A. That might seem a bit wordy, but its just a way to use HL as an address place holder. The last instruction does just the opposite.

Direct Loading of Registers

The accumulator, register pairs BC, DE, or HL, and the Stack Pointer can be loaded from memory using Direct Addressing. Some examples of this are:

  1. LD A, ($3FFF) - This instruction loads the accumulator (register A) from memory location $3FFF.
  2. LD HL, ($A000) - This instruction loads register L from memory location $A000, and register H from memory location $A001. Note the practice of storing the Least Significant byte at the lower address. Oops! No wait! This instruction isn't viable on the GameBoy CPU! (just checking the experienced coders) You can't just load H and L from two memory locations with one instruction, you must load each one independently when load from memory. When loading a direct data value you CAN do that though.
  3. LD SP, ($4050) - This instruction loads the Stack Pointer from memory locations $4050 (least significant byte) and $4051 (most significant byte). All subsequent stack operations such as PUSH or POP will be located at that new address loaded from that loacation, EG.. if at $4050 the data was $00 and at $4051 was $C4, then the Stack Pointer will contain $C400 and all stack operations will happen there. Notice how the less significant byte of a 16-bit address is stored at the LOWER address.

Immediate Loading of Registers

Immediate addressing can be used to load any specific register or register pair with a specific fixed value. This also includes the Stack Pointer and the Program Counter, though you shouldn't directly load the Program Counter unless you really know what you're doing, since that is where the CPU get the address for the next instruction to execute. Some more examples follow.

  1. LD C, 3 - This instruction loads register C with the value 3. The 3 is an 8-bit data item, NOT a 16-bit address. Also, do not confuse the plain decimal 3 with $0003, even though they are relatively equal.
  2. LD DE, $FF80 - This instruction loads register pair DE with the value $FF80. This would be the same as loading register D with $FF and loading register E with $80.

Indirect Loading of Registers

The instruction LD reg, (HL) can load any 8-bit register from the address in register pair HL. The instruction LD A, (rp) can load the accumulator from the address in register pairs BC, DE, or HL. A is the only register that can use BC and DE with indirect addressing. Note that there is no instruction to load a register pair indirectly, so you CANNOT say something like LD DE,(HL) or LD HL,(A000h).


  1. LD D, (HL) - This instruction loads D with the byte located at the address in register pair HL.
  2. LD A, (BC) - This instruction loads the accumulator from the memory address in register pair BC. Note that you cannot load any register besides A using BC or DE indirectly.

Stack Loading of Registers

The instruction POP rp (rp is a register pair) loads a register pair from the top of the stack. Remember, that the stack in the GameBoy grows from top-down, so the top of the stack is the lowest address occupied by the stack, which is indexed by the Stack Pointer. Of course, POPping from the stack INCREMENTS the stack pointer by 2, to point to the new top-of-stack address. PUSH is how you store a register pair to the stack. These two instructions are great for temporarily saving registers if you need to use them for something else (since there's only a few registers).

Storing Registers in Memory

Well, we talked about loading registers from memory, I guess we should now talk about storing them TO memory. The concept is really easy now that you know how to LD a register. To store registers, you just turn the operands around in the previous examples I gave you. Remember in Z80 and GameBoy assembly code, the structure of an instruction is the OPERATION first, then the DESTINATION, then the SOURCE. Like this:

LD dest, source

All you gotta do to store a register is change the destination to a memory location instead of a register and make the source a register. Here's an example:

LD ($C000),A This just loads the contents of A into the memory location $C000. Note that there are brackets around the memory destination. This is to distinguish the address $C000 from the actual plain 16-bit data value of $C000. You can also do things like:

LD (HL),C This just moves the contents of C to the address contained in HL. Is that pretty simple or what? =)

Ok, well say you want to store a specific value in memory, like maybe.... $6F. Well how would we do that? You could do it a few ways. Let's start out by loading HL with the destination memory address. Then we have to use that address in HL as a destination in memory to load a register to: LD HL, address (eg: $8000)

LD (HL), A <-loads contents of register A into memory location at HL or LD HL, address LD (HL), $6F <-loads value $6F into memory location at HL

Now those weren't too hard right? For all the specific limitations and abilities when using the LD opcode, see the instruction set reference guide.