[KDL2 Enthusiast]

I've been trying to figure out the BGB debugger for the past two days, sorry for the super late follow up. To be honest, I feel completely lost right now. In the main window, I can identify one segment that is obviously HEX, which seems to update in real time... then there's a segment that is definitely ASM, but I don't believe that updates as the game goes. I can't tell what anything on the far right is, aside from the z80 CPU register names.


I also found the VRAM viewer, which was pretty self explanatory. Background viewer, loaded tiles, palette info, and then the OAM viewer. I basically understand what all of this does, although I don't know how to properly apply the OAM viewer here. It tells me the x/y coordinates and everything else about the graphics on the screen, but I don't know if the OAM address is anything meaningful that could lead me to related code.


FAST wisely advised me to start simple, so I decided to go with something along the lines of the 1up idea he suggested (when you collect one star in the game, I'd have it give you two instead). However... I don't know how to track things in the game using these tools. There's a cheat searcher, which I used to compare save states before and after getting a star. There were basically no differences in the 16 bit values, and a good number of them in the 8 bit values. I couldn't find any that really went from 01 to 02, though. I'm not really sure how I could use the cheat searcher to modify gameplay elements that aren't simple number changes, either. How would I know what value Rick is demanding when he jumps?

For whatever reason, I was expecting to be able to pause the game and track the differences/what it's being fed frame by frame to determine what is what, but now I'm not quite sure. I don't know how one would even begin reverse engineering a game/ASM hacking like this.

[Psyklax]

I can see you're a bit confused, so let me try and help: I've used BGB before to hack a couple of GB games.

Let's look at the debugger window and help you understand what each of the four windows are. The bottom-left window is the address space. For the CPU to read and write what's going on in the computer/console (the RAM, the ROM, other things) it needs an address space. The GB uses a Z80 CPU, which has a 16-bit address space: this means the most it can address is 64 kilobytes, or from $0000 to $FFFF. This space is shared by different things, and if you want to know precisely where everything is, you can look at a memory map.

Helpfully, BGB tells you exactly what the memory is mapped to at any given moment: in your screenshot you can see ROM0:0000, which means that that part of the address space is what's in ROM bank 0. 64KB isn't a lot to work with, so the GB uses bank switching to have bigger games (the NES does the same thing).

You'll notice that from $0000 to $7FFF, there are two ROM banks, usually 0 and 1, but the game can switch these at will during play - sometimes even during a single frame. After that you have VRAM (where the video information is stored); SRAM (kept on cartridges that need to save games, or just have a bit of extra RAM); WRAM (work RAM, the main RAM used by the console to do general stuff during a game); ECH (echo RAM, just echoes what the work RAM does); OAM (object attribute memory - sprites, in other words); an unused area; I/O (all the hardware registers that control different things like player input); and HRAM (high RAM, often used for regular things because it's a bit quicker than the work RAM).

Phew! Anyway, the top-left window is the actual game code. This is what's being executed to run the game, and is generally stored in ROM (usually bank 0 because that never changes). From left to right: the address; the bytes (opcodes) that are used for this instruction; a disassembly of that instruction; and a bit that I'm not sure about - maybe just a comment on each line? I don't know what the numbers mean, but it doesn't matter.

Top-right you'll see the current state of the Z80's registers. These are small bits of memory that the CPU uses to do things. For example, if you kill a baddie and get 100 points, the game might find the points value in ROM, load it to BC, load your current points to AF, add the two together, then store AF back to RAM.

The bottom-right is the stack: this is a temporary RAM area that acts like, well, a stack. You put something on top of the stack, and you can pull stuff off the top, too. It's commonly used by games because it's very fast - you can pile a whole load of things on the stack before pulling them off in quick succession. Sometimes when you're hacking, you need to find stuff that is on the stack.

So now hopefully you at least understand what you see, though I'm sure there are plenty of things you still need to know. Let me help you figure out that first idea you mentioned: giving two for a star instead of one.

Yes, you need the cheat searcher, so here's how to use it. I've never played the game so forgive me if I don't understand something... Open the cheat searcher (it's a bad name, it should be a RAM searcher because it's not just for cheating), and search for an 8-bit value equal to 0 (because I guess you have zero stars at the beginning, right?). 8-bit values go up to 255, so I don't think you'll be needing to look for 16-bit values here.

Once you've done the search, you'll see a ton of RAM addresses with zero in them, so now go collect one star and now search for 1 instead of 0. See, what we've done is say "only show the addresses that had zero when I first clicked, and one when I clicked again", therefore severely limiting the possibilities. Go get one more star and search for 2. I'd be very surprised if you haven't narrowed it down to a single address, so assuming you have, right-click the address and go there in the debugger.

Remember that the Z80 is little-endian, so if you were to have more than 255, the larger byte would go second (i.e. 02 01 equals 258). Try changing the "02" you see to "09" or something, and see if the total in the game changes. If so, great! We know where the stars are stored in RAM, so now to change the code. This is the tricky bit, because you need to understand assembly, but it's not as hard as it sounds.

Right-click the address and "set access breakpoint", and add a breakpoint "on write" (because we want the game to stop when it writes to that address with the new star value). Now get another star and the game should freeze with the debugger on the instruction that's writing to the address.

Now, without actually doing it myself, I can't say what is going to happen. But I can say that, unfortunately, this may be where you encounter the problem with this kind of hack. See, there's an instruction on the Z80 that lets you add one to something, which is easier than saying specifically "add x amount to this". So changing 1 to 2 isn't easy, because you need a new instruction - and that instruction needs at least two bytes, unlike the INC command. Since you can't even move the code a single byte without crashing the game, you'll find it difficult to do this. There IS a way which involves jumping to an empty part of the ROM and putting the new code there, however, but I think this is enough for one day.

So, read what I said, play around a bit, and I hope you'll figure a few things out!

[Squall_FF8]

KDL2 Enthusiast, hold your horses 

As I told you earlier: "start small". Trying to do do many things, to grasp many concepts at the same times is the fastest way to burn out very easy!

As you said wisely: "assembly seems like the only way forward here". Start there, forget about everything else for the moment, and try to learn all of the z80 asm instructions. Just by reading the description of the asm commands or even memorizing them by heart will not lead to learning the language. As with real language: you know a language only when learn to talk.
In order to do so - find a good tutorial, not reference doc. A good tutorial group few instructions in a logical unit that is enough to be able to accomplish some tasks. This way you will learn the meaning of the used instruction AND you will be able to read a code that use them and even do some practical tasks! Doing things that way will produce long term practical knowledge!!!

[KDL2 Enthusiast]

I can see you're a bit confused, so let me try and help: I've used BGB before to hack a couple of GB games.

Let's look at the debugger window and help you understand what each of the four windows are. The bottom-left window is the address space. For the CPU to read and write what's going on in the computer/console (the RAM, the ROM, other things) it needs an address space. The GB uses a Z80 CPU, which has a 16-bit address space: this means the most it can address is 64 kilobytes, or from $0000 to $FFFF. This space is shared by different things, and if you want to know precisely where everything is, you can look at a memory map.

Helpfully, BGB tells you exactly what the memory is mapped to at any given moment: in your screenshot you can see ROM0:0000, which means that that part of the address space is what's in ROM bank 0. 64KB isn't a lot to work with, so the GB uses bank switching to have bigger games (the NES does the same thing).

You'll notice that from $0000 to $7FFF, there are two ROM banks, usually 0 and 1, but the game can switch these at will during play - sometimes even during a single frame. After that you have VRAM (where the video information is stored); SRAM (kept on cartridges that need to save games, or just have a bit of extra RAM); WRAM (work RAM, the main RAM used by the console to do general stuff during a game); ECH (echo RAM, just echoes what the work RAM does); OAM (object attribute memory - sprites, in other words); an unused area; I/O (all the hardware registers that control different things like player input); and HRAM (high RAM, often used for regular things because it's a bit quicker than the work RAM).

Phew! Anyway, the top-left window is the actual game code. This is what's being executed to run the game, and is generally stored in ROM (usually bank 0 because that never changes). From left to right: the address; the bytes (opcodes) that are used for this instruction; a disassembly of that instruction; and a bit that I'm not sure about - maybe just a comment on each line? I don't know what the numbers mean, but it doesn't matter.

Top-right you'll see the current state of the Z80's registers. These are small bits of memory that the CPU uses to do things. For example, if you kill a baddie and get 100 points, the game might find the points value in ROM, load it to BC, load your current points to AF, add the two together, then store AF back to RAM.

The bottom-right is the stack: this is a temporary RAM area that acts like, well, a stack. You put something on top of the stack, and you can pull stuff off the top, too. It's commonly used by games because it's very fast - you can pile a whole load of things on the stack before pulling them off in quick succession. Sometimes when you're hacking, you need to find stuff that is on the stack.

So now hopefully you at least understand what you see, though I'm sure there are plenty of things you still need to know. Let me help you figure out that first idea you mentioned: giving two for a star instead of one.

Yes, you need the cheat searcher, so here's how to use it. I've never played the game so forgive me if I don't understand something... Open the cheat searcher (it's a bad name, it should be a RAM searcher because it's not just for cheating), and search for an 8-bit value equal to 0 (because I guess you have zero stars at the beginning, right?). 8-bit values go up to 255, so I don't think you'll be needing to look for 16-bit values here.

Once you've done the search, you'll see a ton of RAM addresses with zero in them, so now go collect one star and now search for 1 instead of 0. See, what we've done is say "only show the addresses that had zero when I first clicked, and one when I clicked again", therefore severely limiting the possibilities. Go get one more star and search for 2. I'd be very surprised if you haven't narrowed it down to a single address, so assuming you have, right-click the address and go there in the debugger.

Remember that the Z80 is little-endian, so if you were to have more than 255, the larger byte would go second (i.e. 02 01 equals 258). Try changing the "02" you see to "09" or something, and see if the total in the game changes. If so, great! We know where the stars are stored in RAM, so now to change the code. This is the tricky bit, because you need to understand assembly, but it's not as hard as it sounds.

Right-click the address and "set access breakpoint", and add a breakpoint "on write" (because we want the game to stop when it writes to that address with the new star value). Now get another star and the game should freeze with the debugger on the instruction that's writing to the address.

Now, without actually doing it myself, I can't say what is going to happen. But I can say that, unfortunately, this may be where you encounter the problem with this kind of hack. See, there's an instruction on the Z80 that lets you add one to something, which is easier than saying specifically "add x amount to this". So changing 1 to 2 isn't easy, because you need a new instruction - and that instruction needs at least two bytes, unlike the INC command. Since you can't even move the code a single byte without crashing the game, you'll find it difficult to do this. There IS a way which involves jumping to an empty part of the ROM and putting the new code there, however, but I think this is enough for one day.

So, read what I said, play around a bit, and I hope you'll figure a few things out!

I'd like to start by thanking you for your in depth reply explaining everything about the debugger there, and what sections do what. Even after reading the pandocs page I wasn't too sure about the differences between say, RAM or SRAM.

I followed what you said with the cheat searcher and... it worked! I had to collect 4 stars and update it every time, but it eventually narrowed down to the point where I could find one value in the cheat searcher that was indeed a 4, and when I modified that to a 5 it properly updated on the next room switch! Following what you told me, I was even able to set a breakpoint on write successfully and find the code related to it. And, well, I don't think I can actually do what I had in mind, but I think this is progress still. Now I know how to properly search for changes in RAM, and how to break on write to find assembly code related to the thing I'm tracking. Thank you so much, again! I still have a long way to go, though. This was easy to track because it's a numeric value that I can see normally, but I'm not sure how to actually do things like find code related to Kirby's commands...

My next goal would to be to somehow track his forward walk speed and boost it, somehow. Before this I might need to go and study other source codes, and maybe see if I can get semi-functioning homebrew going.

KDL2 Enthusiast, hold your horses 

As I told you earlier: "start small". Trying to do do many things, to grasp many concepts at the same times is the fastest way to burn out very easy!

As you said wisely: "assembly seems like the only way forward here". Start there, forget about everything else for the moment, and try to learn all of the z80 asm instructions. Just by reading the description of the asm commands or even memorizing them by heart will not lead to learning the language. As with real language: you know a language only when learn to talk.
In order to do so - find a good tutorial, not reference doc. A good tutorial group few instructions in a logical unit that is enough to be able to accomplish some tasks. This way you will learn the meaning of the used instruction AND you will be able to read a code that use them and even do some practical tasks! Doing things that way will produce long term practical knowledge!!!

You're probably right, sorry if I came off a bit overwhelmed and frustrated there. I think I was just expecting too much and I jumped in without enough knowledge of how things work. I'm going to probably try my hand using the many gb-dev tutorials, and see if I can get basic homebrew running first. Do you think this would help me when it comes to reverse engineering existing games?

[Squall_FF8]

You're probably right, sorry if I came off a bit overwhelmed and frustrated there.

Yup, that is how things works. When you try to do/understand many thing at the same time (short period), the feeling of overwhelming will come, frustration will start and raise constantly to a point where you must take a decision to stop or burn out. Somehow every humans tend to slide in that cursed loop, regardless is it for work, games, hacks, ....

Anyway, lets focus on hacking.

I'm going to probably try my hand using the many gb-dev tutorials, and see if I can get basic homebrew running first. Do you think this would help me when it comes to reverse engineering existing games?

Positively! The asm instructions are like the alphabet of a spoken language. Only after you learn the alphabet you will learn to 'read'. Regardless how complicated a code is, it can be divided to a smaller pieces that convey standalone meaning. When you start with few instructions and combine them in what the task is, you will learn not just to read individual 'letters' but consequence of letters as a 'word', later on combing 'words' as a 'sentences' and so on. Same goes with the 'writing'.
But don't fool yourself, this doesn't happen in a moment, just by reading a reference doc. It require work, work and more work 
And with the risk to repeat myself, that's why a good tutorial is a crucial for your growth. A good one will 'shoot you high in the sky'. A bad one will just add more frustrations.

[KDL2 Enthusiast]

Yup, that is how things works. When you try to do/understand many thing at the same time (short period), the feeling of overwhelming will come, frustration will start and raise constantly to a point where you must take a decision to stop or burn out. Somehow every humans tend to slide in that cursed loop, regardless is it for work, games, hacks, ....

Anyway, lets focus on hacking.Positively! The asm instructions are like the alphabet of a spoken language. Only after you learn the alphabet you will learn to 'read'. Regardless how complicated a code is, it can be divided to a smaller pieces that convey standalone meaning. When you start with few instructions and combine them in what the task is, you will learn not just to read individual 'letters' but consequence of letters as a 'word', later on combing 'words' as a 'sentences' and so on. Same goes with the 'writing'.
But don't fool yourself, this doesn't happen in a moment, just by reading a reference doc. It require work, work and more work 
And with the risk to repeat myself, that's why a good tutorial is a crucial for your growth. A good one will 'shoot you high in the sky'. A bad one will just add more frustrations.

Yep. This is probably going to take me a long time to learn, but for now I am going to go through the resources on gb-dev and study the source codes for other existing GB hacks. It might take me a long time to fully grasp, but I promise I'll be back eventually! Should I post here if I need any help, or should I head on over into programming for that?