0

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!

5
  • 1
    Pokémon Yellow runs on a Gameboy which uses a pretty specific processor. I am not familiar with it, but reading the instruction set reference for it might tell you what jr does. I suppose CheckEvent and SetEvent are macros defined elsewhere. Note that a label is just like a bookmark to give a place in the code a symbolic name instead of having to remember its address. You can't store something “into a label” because labels do not exist at runtime.
    – fuz
    May 9, 2020 at 1:16
  • 2
    Note further that likely nobody is going to be able to tell from just this tiny bit of code what it does as it references a lot of external symbols and macros whose function I can only speculate about. Your best bet is to read the instruction set reference and learn some assembly programming. Then dig through the code base yourself. I know this is a lot of work, but it's the same work I would have to do to understand how this works.
    – fuz
    May 9, 2020 at 1:18
  • how will understanding this high level assembly enable you to understand all of assembly language for the whole program, its a couple few macros which arent the asm they are like #defines in C you have to go look at the actual asm there, then a function call then prepping a jump table, pretty obvious stuff for any programmer, but being so far out of context doesnt mean much and cant teach you anything of real value as is.
    – old_timer
    May 9, 2020 at 1:22
  • jr z almost certainly is a conditional branch. It jumps if something is zero, and doesn’t jump if it is non-zero. So the effect is to skip over SetEvent if CheckEvent returned zero.
    – prl
    May 9, 2020 at 1:26
  • It doesn’t come back to this code after it jumps to JumpTable.
    – prl
    May 9, 2020 at 1:35

3 Answers 3

5

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

1
  • This makes a lot of sense. Thank you!
    – MisterRed
    May 10, 2020 at 3:12
1

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.

.

2
  • 4
    FYI, the gameboy processor isn’t exactly a Z-80, but it is similar.
    – prl
    May 9, 2020 at 9:34
  • This is very informative. I can't get that link to load right now, but I'll try it later. Thank you for the help!
    – MisterRed
    May 10, 2020 at 3:12
1

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.