WLA-DX

WLA-DX
Author(s)	Ville Helin
Links Source

WLA-DX is the assembler used by the disassembly. It supports numerous different architectures, but the one we're interested in is the gameboy assembler, wla-gb.

Handy features

High and low bytes

One can use > or < to get the high and low bytes of a value, respectively.

For example, >$1234 = $12, and <$1234 = $34.

Child labels

Labels prefixed with @ are considered "child" labels; they will fall out of scope when a new "parent" label is specified. This allows one to use short and sweet label names for a specific context.

As an example, here, two labels named @loop are used, which don't conflict because they have different parents:

parentLabel1:
    ld b,4
@loop:
    dec b
    jr nz,@loop
    ret

parentLabel2:
    ld b,8
@loop:
    dec b
    jr nz,@loop
    ret

One can jump directly to a child label by prefixing the parent name, ie. jp parentLabel1@loop. This should be used sparingly, since it is useful to assume that child labels are not jumped to by external sources (this makes reasoning about a function easier).

Anonymous labels

Before child labels, there were anonymous labels. These are labels named +, ++, +++, or -, --, ---, etc...

+ labels are ones that only work with forward jumps, while - labels only work with backward jumps. These should generally only be used for very short jumps (the destination should be visible on the screen without scrolling).

One can also use __ (two underscores) as an anonymous label; then, _f works as a forward reference to this label, and _b works as a backward reference to it. This syntax is not used in the disassembly due to being a bit cryptic.

Local labels

Local labels are prefixed with an underscore (_). These labels are not visible outside of the section they are defined in.

While these were previously used extensively in the codebase, they were seen as more of an annoyance than anything else as it was somewhat arbitrary what labels were deemed "local" or not. Now, they are only used in bank 0.

Quirks and Workarounds

Argument separation

When passing arguments to macros or assembler directives, arguments can be separated by spaces or commas, ie, these two lines are equivalent:

.db $01 $02
.db $01, $02

There are rare cases where WLA gets confused by the space-separators. For instance, this line in the disassembly caused issues:

.db <wObtainedTreasureFlags    (1<<TREASURE_PUNCH) | (1<<TREASURE_SWORD)

This is fixed by using comma-separators instead.

.db <wObtainedTreasureFlags,   (1<<TREASURE_PUNCH) | (1<<TREASURE_SWORD)

Comma separators are generally preferred for anything mildly complex.

More information

See the wla-dx documentation.