GB Programming: Difference between revisions

Welcome to this tutorial ! The purpose of this page is to allow everyone to program anything on a Game Boy. This can sound complex, but the Game Boy is a very well-documented system, and programming for it can be learned quite easily.

Let's get started !

If you don't understand something later on, read this part again, and chances are, you'll understand it.

This paragraph is some trivia about why computers use binary instead of decimal. You can skip it if you will. So, why binary ? Because we need computers to be efficient. So we need to store information using electricity. The easiest variable to manipulate is "Is power running ?". The answer is either 0 (it doesn't) or 1 (it does). And there you got it ! Why do computers count in binary ? To keep them at reasonable prices !

To differentiate decimal numbers from binary numbers, binary numbers will be prepended with a % symbol. So, 10 is decimal, and %10 is binary. Got it ? Okay.

Why using hexadecimal ? Well, writing binary numbers is quite tedious. Take both examples together : we have 149 = %10010101 = $95. Now, consider the digits individually :

For the rest of this tutorial, we will mostly be using hexadecimal, but always remember the binary lying down below !

==A dip into technicals==

There are 8 different registers, which can be actually paired up. These are A, B, C, D, E, F, H and L. These are NOT hex digits, so beware !

* C is also used as a 8-bit counter, but also for port access. We'll see that wayy later.

* F holds the CPU's '''Flags'''. It is very special, as you cannot use it as a general-purpose register. You can't even directly access it ! We'll see how to use it later.

Did I mention that nothing is case-sensitive ?

Note that ''ld a, -1'' is valid, but actually, the "-1" wraps. Storing -1 will truly store 255 in a 8-bit register, and 65535 in a 16-bit register. Why ? Coming soon.

Time to confess : I've lied to you. Actually, 8-bit and 16-bit registers can hold negative numbers.

I've told you, "individual registers can hold unsigned 8-bit values, and pairs unsigned 16-bit values". However, these aren't true : these values can be signed. How does that work ?

What we will be doing is cutting our number range in half, and telling one half is composed of negative numbers. But how to distinguish positive and negative numbers ? Well, we tell the MSB is no longer meaning the symbol in front of 2^7, but it will give away the sign of the number (0 = positive, 1 = negative). So, instead of having values in ranges 0 - 255 and 0 - 65535, we will have values in ranges -128 - 127 and -32768 - 32767. Neat !

How to multiply by -1 ? Easy ! You can either :

So, uh, -(-128) = -128 ? Oops. You cannot negate -128 with only 8 bits. Try with 16 bits, and you'll see it works ! However, with 16 bits, you can't negate -32768 for the same reason.

Now, let's see how the CPU handles the difference between unsigned and signed values. Surprise, it doesn't ! Why ? Because making the same operations using signed or unsigned values give the same result !

And, you just saw why I told you to consider 0 the same as 256 : they are similar ! As 256 uses 8 zero bits preceded by a 1... but the 1 is discarded.

Finally ! So what is "memory", you ask ? It's a stream of bytes. A stream of numbers. And guess what ? Everything is a stream of numbers. From numbers to this cute kitten video, everything is numbers. Including programs. That's why [[Arbitrary code execution]] happens. Remember this sentence : ''Data is whatever you define it to be.''

Ever wondered why you could open a JPEG in Word ? Now you know.

How is every byte differentiated from its neighbors ? Well, everyone gets a 16-bit unsigned integer called their "address" (thus ranging from $0000 to $FFFF). To access a byte, use its address, just like to reach your friend, you use his e-mail address.

So, how does running a program works ? What happens is that a special register is incremented (its value is raised by one), then the processor fetches the byte located at the address held by that register, and processes it as an opcode ; when done, everyting is repeated. Instructions can be one to three opcodes (bytes) large, so this cycle may repeat for a single instruction.

So now, how to access memory ? With parentheses ! To access memory address $CD38, you just have to use ($CD38). Yay !

To access the memory location pointed to by HL, just do... (hl) ! It's the same with BC and DE.

Obviously, ''ld ($6511), a'' will overwrite the previous value stored here. But ''ld ($6511), hl'' will store a 16-bit value, which is a word long, that is two bytes long ! So, not only will ($6511) be overwritten, but ($6512) too ! Always be very careful about the memory you're touching. Otherwise, stuff like the [[ZZAZZ Glitch]] happen.

Remember that "special" F register ? Well, each of its bits is called a "flag", and holds information about (usually) the accumulator. A flag is dubbed "set" if it equals 1, and "reset" otherwise.

Both "-" are unsued flags. They behavior is very complicated, and isn't "official". Treat them as random.

===Instructions get !===

Q : Hey, but where's MULT ?

A : Nowhere :D To multiply, you must write your own routines ! However, a nice lil' trick : to do A <- A*2, simply ''add a, a'' ! To do A <- A*3, do ''ld b, a'', ''add a, a'', ''add a, b'' (you can swap B with any other register, of course). I'll leave you A <- A*4, A*5, A*6 and A*7 as an exercise.

What value will hold A ? The naive guess would be 322, or %101000010. However, this is 9 bits large, and won't fit in A. The way it works is that the eight rightmost bits are kept in the register, the rest being discarded. Because a non-zero value is dicarded, the C flag is set.

Let's say you run a ld hl, $D361. $D361 is put into HL, but since it is registers H and L paired up, what happen to them ?

Here is an exercise : what values will ($C000) to ($C00F) contain after this code is ran ?

===A stack ? Can you eat that ?===

No it's not. It's a data structure that has the cool property of not being fixed-length. How does it work ? Just like a stack of plates. Imagine you're washing some plates in the back of a restaurant. Next to you is a pile of plates you need to wash. Waiters come and place ("push") plates on top of the stack and when finished washing a plate, you take ("pop") the topmost one. This way of working is called LIFO (Last In First Out).

Let's say we have our stack pointer saved at memory address $C000 (because it is a 16-bit value, it also uses memory address $C001 !!).

Okay, coding a stack is cool, but... isn't there a faster way of doing it ? Of course ! Because the Game Boy's CPU has a stack by itself ! Meet

You cannot PUSH / POP with 8-bit registers. Instead, to save register B, you '''must''' ''push bc''. You don't have to push and pop to the same register ! For example :

Beware with the stack, even more when you're not coding your own game : everyone uses the stack ; even the CPU ! (We're about to see how) The best practice to have is to leave the stack identical before and after your code. Otherwise, expect some crashes, yay !

...at the speed of sound ! (I'M SO SORRY)

Up until now, we've seen only programs that begin somewhere and that are ran top to bottom, in that order. However, this never happens in a more complex context. So, let's see how to manipulate code flow !

What's the difference ?

And this brings us to the next part !

JP and JR can be executed in unconditional ways, meaning the jump will always occur. This can be useful, but sometimes we don't want that. And that's where flags come in handy ! Because we are able to trigger jumps depending on the status of the flags.

===Instructions get !===

Notice here that doing ''sub a, b'' actually increased A's value !