basic-introduction.md

The Process

1. Disassembly

The first step was to transform the machine code from the original ROM into assembly language, readable by humans. This step was done with the help of the Emulicious emulator which has this functionality. About 26k lines of code were generated. Below is an routine from this file.

Machine code

061e 2100 c3cd 8d27 2310 fac9

Assembly:

_LABEL_9D9_:
    ld b, $1E
    ld hl, _RAM_C300_
-:
    call _LABEL_278D_
    inc hl
    djnz -
    ret

2. Name labels

When the game was compiled back in 1986, all variable and routine names were discarded as they are not needed at runtime. That's why the disassembler has to give generic names to these labels like _LABEL_9D9_ and _RAM_C300_.

This second step is to understand what a routine does and rename the labels so they make sense. There are several ways to do this: using a emulator with an debugger, looking for online documentation or analyzing other routines called from or to this part of the code.

See the result below.

clearEntities:
    ld b, $1E
    ld hl, entities
@loop:
    call clearEntity
    inc hl
    djnz @loop
    ret

When done, you must compile the game to make sure that your changes will output exactly the same bytes as before. The build script does this check automatically.

3. Document

This is an optional step, but it can help other people to understand particularly complex snippets without having to analyze assembly code.

Below we see the same excerpt above written in pseudo-code.

clearEntities() {
    for (i = 0x1E; i > 0; i--) {
        clearEntity(i)
    }
 
    return
}