hgbasm

A JavaScript-based compiler for RGBDS GameBoy assembly syntax variants.

If you're looking to use the compiler directly from the command line, see hgbasm-cli. A Visual Studio Code extension is also available.

Note that this project is not a perfect port of the RGBDS suite and is not guaranteed to accept every valid assembly file or generate binary-compatible output. However, issues related to compatibility will be addressed as they are reported, especially if there is no suitably trivial workaround available. Pull requests welcome.

Features

HGBASM normally runs in an RGBDS-compatible mode with no new features enabled. To enable full HGBASM mode, add this directive to the top of your source file:

#mode hgbasm

In addition to normal RGBDS functionality, the following HGBASM-specific features are available:

Additional Predefined Symbols

Name	Type	Value
__HGBASM_MAJOR__	EQU	Current HGBASM major version number
__HGBASM_MINOR__	EQU	Current HGBASM minor version number
__HGBASM_PATCH__	EQU	Current HGBASM patch version number
TRUE	EQU	1
FALSE	EQU	0
true	EQU	1
false	EQU	0

String/Integer Conversion Functions

• INT(str) converts a string to an integer. The base is determined by the prefix ($ for hexadecimal, & for octal, % for binary, and no prefix for decimal).
• DEC(num) converts a number to its decimal string representation.
• HEX(num) converts a number to its hexadecimal string representation, without a prefix symbol.
• OCT(num) converts a number to its octal string representation, without a prefix symbol.
• BIN(num) converts a number to its binary string representation, without a prefix symbol.

Additional String Functions

• STRRPL(source, pattern, replacement) finds all occurances of the string pattern within source and replaces them with the string replacement.
• STRPAD(source, pad, length) prepends the character pad to the string source until the length is equal to the absolute value of length. If length is negative, pad is appended instead of prepended.

Random Number Generation

• RANDINT(min, max) returns a random integer from min (inclusive) to max (inclusive).
• RANDBYTE() returns a random value from $00 to $FF.
• RANDWORD() returns a random value from $0000 to $FFFF.
• RANDLONG() returns a random value from $00000000 to $FFFFFFFF.
• RESEED seed is a keyword that resets the random number generator and sets its initial seed to the number or string seed.

Size-Of Function

• SIZEOF(@) returns the size in bytes of the current section. Cannot be used in constant expressions.
• SIZEOF("section name") returns the size in bytes of the named section. Cannot be used in constant expressions.
• SIZEOF(global_label) returns the number of bytes from the specified global label until the next defined global label. Cannot be used in constant expressions.
• SIZEOF(.local_label) returns the number of bytes from the specified local label until the next defined local or global label. Cannot be used in constant expressions.
• SIZEOF(number) returns the smallest number of bytes needed to fit the number.
• SIZEOF(register) returns the size of the specified register (1 for a, b, c, d, e, h, l; 2 for af, bc, de, hl, sp).

Status

• Assembler (RGBASM equivalent)
• Linker (RGBLINK equivalent)
• Fixer (RGBFIX equivalent)
• JS API (subject to change)
• Command-line API for Node environments
• Visual Studio Code extension
• Monaco web editor plugin

Installation

npm install --save hgbasm

Usage

Proper documentation will be added once the API is stable. The source code of hgbasm-cli shows basic usage of each of the main compiler components.

Contribution

All feature requests, issues, and code contributions are welcome. Just clone the repo, make any changes to the TypeScript code in the src/ directory, and submit a pull request.

Credits

Thanks to the various contributors to the RGBDS suite; Donald Hays, creator of the existing RGBDS GBZ80 VSCode plugin; Beware, creator of the emulator BGB; and special thanks to the members of the gbdev Discord server, particularly ISSOtm and PinoBatch, for helping teach Game Boy development.

License

MIT