Can someone help me understand some Assembly language?

Question

I'm sorry is this isn't the right place, but I'm trying desperately to understand what's happening in this Assembly script (I'm assuming that's what it is, based on the hours of googling I've done.) It's a rom for Pokemon Yellow version, and I understand some but not all. I figure if I can get some help understanding what this one paragraph is doing, I can figure the rest out. The code looks like this:

PalletTownScript:
    CheckEvent EVENT_GOT_POKEBALLS_FROM_OAK
    jr z, .next
    SetEvent EVENT_PALLET_AFTER_GETTING_POKEBALLS
.next
    call EnableAutoTextBoxDrawing
    ld hl, PalletTownScriptPointers
    ld a, [wPalletTownCurScript]
    jp JumpTable

My understanding is that the first line just puts the rest of it into a label called "PalletTownScript", just a name that's referenced later. The second line checks that a certain event has happened, detailed in another file. All that's fine so far. The third line is where it gets complicated for me. I determined that "jr" jumps to another section of the script, and then returns back here? I think? But, from what I've seen, every single example only has one argument, and this line has two. Is it jumping to z? What is z? I've searched the rest of this file, and there's no section called z. Is z another function? The other argument is .next, which is, from what I can tell, a subsection of the PalletTownScript section. So it makes sense that it's jumping there (but why bother jumping? If it's right there, wouldn't it just do it anyway?) But I still don't know what "z" is doing there. In .next, it's calling some stuff and loading some other stuff, that's all fine, but at the end, it jumps to JumpTable, which is in another file (I'm assuming that doesn't matter after it's all compiled, so I'm not concerned about that), but is it still Jumped to the .next, and then again to JumpTable? When does it go back to do that SetEvent? Where does it go after that?

I have never dealt with Assembly before, and it's all very confusing for me, so if someone could give me some help with this, I would really appreciate it. Thanks!

Answer 1

jr z, .next is a conditional relative jump. The jump will only be taken if the Zero flag is set (in the F register).

If the event EVENT_GOT_POKEBALLS_FROM_OAK has already happened, the event EVENT_PALLET_AFTER_GETTING_POKEBALLS becomes set.

If it didn't, the SetEvent EVENT_PALLET_AFTER_GETTING_POKEBALLS is skipped.

The CheckEvent and SetEvent macros are defined here: https://github.com/pret/pokered/blob/master/macros/scripts/events.asm

Answer 2

Assembler program should be read line by line. Each line can be

1. a comment (ignored by CPU),
2. a label (symbolic name of this place in the program),
3. machine instruction (order for CPU to perform some action),
4. macro (symbolic name of a bunch of machine instructions which are defined somewhere else in the source file or in some other source file included into the main source)

Visualize each statement mentally as a blackbox which does something. In order to understand each statement it should have documented its input, what it does, what is the output, whether there are any collateral damages (clobbered registers or flags, unbalanced stack, exceptions). CPU seems to be Zilog Z80, mnemonic shortcuts of its machine instructions are listed in http://nemesis.lonestar.org/computers/tandy/software/apps/m4/qd/opcodes.html together with brief explanation. In your snippet we can recognize machine instructions jr, call, ld, jp. Z80 has 8bit registers a, b, c, d, e, h, l, some of them may be joined to form a 16bit pair: bc, de, hl. It also has 1bit "registers" z, c, p called flags which can be set or reset by some instructions and thus they remmber the outcome of previous statement. Processor can branch its further execution according to flags, using conditional jumps, such as jr z, .next. If the previous statement has set the z flag to true, jr jumps to .next, otherwise jr is ignored. There's no magic in labels, its just an assembler's way to point your finger to a particular place in the program flow.

If you want to know whether z was set or reset by previous statement
CheckEvent EVENT_GOT_POKEBALLS_FROM_OAK, you would have to grep for CheckEvent in included source files and hope that the macro definition was provided with its documentation. Labels, symbols and macro names in Pokemon ROM are talkative (which isn't always the case in asm programs, unfortunately), so it easy to guess that the macro will reset z flag when the EVENT_GOT_POKEBALLS_FROM_OAK (whatever it means) occured, otherwise the following conditional jump orders CPU to skip the macroinstruction
SetEvent EVENT_PALLET_AFTER_GETTING_POKEBALLS and continune at the label .next.

.

Answer 3

The other answers explained it well, but you have a misconception regarding jumps.

I determined that "jr" jumps to another section of the script, and then returns back here? I think?

Jump (jr and jp) does not return, it just changes the program counter, it's C equivalent would be goto. call (and rst) is what comes back like a function, it stores the current pc on stack, changes pc and then restores pc from stack when it reaches ret/reti.

Where does it go after that?

It just goes to JumpTable and never comes back.

---

PokeRed uses RGBDS, which is well documented.

Descriptions of the instructions: https://rgbds.gbdev.io/docs/v0.5.0/gbz80.7

Descriptions of other syntax like macros: https://rgbds.gbdev.io/docs/v0.5.0/rgbasm.5