Astatin Assembler

Heyo !! This is the assembler I use to create BunnyLand (Temporary name) on stream on Twitch

Get the assembler

If you’re on linux on x86_64 you can download an already compiled binary here.

If you can’t use this binary you will need to compile the binary by yourself:

Compiling

The assembler is made in golang, check if you have it on your system, If you do not:

# Arch
sudo pacman -S go

# Debian/Ubuntu
sudo apt install golang

# Windows:
# I don't know lol

Clone the assembler:

git clone https://github.com/AstatinChan/gameboy-asm.git
cd gameboy-asm

Compile the assembler:

go build .

Usage

To assemble gbasm files, call the assembler with the input file as the first parameter and the output file as the second

Example

When having the file zoom.gbasm in your current directory, this will compile to a usable rom file:

gbasm zoom.gbasm zoom.rom

Gameboy assembly

To even be able to start, gameboy roms need to contain some data to be validated by the boot rom. The minimal rom which starts, clear the screen and starts an infinite loop to hang is available in examples/minimal.gbasm

Labels

Labels are defined with alphanumerical strings followed by a colon at the start of a line and can be referenced by appending the alphanumerical string to a =.

Inside of .MACRODEF, labels must start with $ and cannot be referenced outside of the macro.

Parameters

The list of the parameters that could be passed to the opcodes:

Name	abbreviation	possible values	.DEFINE constants	Labels
8 bits registers	r8	`A`, `B`, `C`, `D`, `E`, `H`, `L`, `(HL)`	No	No
16 bits registers	r16	`BC`, `DE`, `HL`, `SP` (for PUSH and PULL `SP` is replaced by `AF`)	No	No
Raw 8 bits	8b	`0x00` to `0xff`, can also be written `$00` to `$ff`.	Yes	No
Raw 16 bits	16b	`0x0000` to `0xffff`, can also be written `$0000` to `$ffff`	Yes	Yes
register indirect	ri	`(BC)`, `(DE)`, `(HL+)`, `(HL-)`	No	No
Raw 8 indirect	8i	`(0x00)` to `(0xff)`, can also be written `($00)` to `($ff)`.	Yes	No
Raw 16 indirect	16i	`(0x0000)` to `(0xffff)`, can also be written `($0000)` to `($ffff)`.	Yes	No
Condition	cc	`NZ`, `Z`, `NC`, `C`	No	No
Bit ordinal	o	from `0` to `7`	No	No

Opcodes

The list of different possible opcodes:

Opcode	First parameter	Second parameter
LD	r8	r8
	r8	8b
	`A`	8i
	8i	`A`
	`A`	ri
	ri	`A`
	`A`	16i
	16i	`A`
	`A`	`(C)`
	`(C)`	`A`
	r16	16b
	16i	`SP`
	`SP`	`HL`
PUSH	r16
POP	r16
ADD	r8
	8b
	`SP`	8b
ADC	r8
	8b
SUB	r8
	8b
SBC	r8
	8b
CP	r8
	8b
AND	r8
	8b
OR	r8
	8b
XOR	r8
	8b
INC	r8
	r16
DEC	r8
	r16
CCF
SCF
DAA
CPL
JP	16b
	HL
	cc	16b
JR	8b
	cc	8b
	16b¹
	cc	16b²
CALL	16b
	cc	16b
RET
	cc
RETI
RST	o
DI
EI
NOP
HALT
STOP
RLCA
RLA
RRCA
RRA
BIT	o	r8
SET	o	r8
RES	o	r8
RLC	r8
RL	r8
RRC	r8
RR	r8
SLA	r8
SRA	r8
SWAP	r8
SRA	r8
SRL	r8
DBG³

MACROS

Name	Parameters	Explanation	Usable in .MACRODEF
.DB	Any number of 8b	Will insert the 8b in the ROM as is	Yes
.PADTO	16b	Will insert 0x00 in the ROM so that the next instruction is situated as the address provider	No
.INCLUDE	A file path in double quotes (example: `"./file-to-be-included.gbasm"`)	Will include all of the code inside the file provided in parameters	No
.DEFINE	A alphanumerical string as first parameter and a 8b, 16b, 8i or 16i to use as value	The alphanumerical string in parameter will be able to be used instead of the value	No
.MACRODEF	An alphanumeric string	Creates a new macro that will insert all of the code between this macro and the .END macro when called. The macro will be able to be called by calling the string provided in parameter prefixed by a `.`	No
.END		Ends a .MACRODEF block	N/A
User defined with .MACRODEF			Yes

This is only syntaxic sugar that will be converted to 8b relative to the instruction to allow the use of labels. If the address is too far away from the address of the instruction in rom to be converted to 8b, the assembly will fail with an error suggesting to use JP instead of JR.↩︎
This is only syntaxic sugar that will be converted to 8b relative to the instruction to allow the use of labels. If the address is too far away from the address of the instruction in rom to be converted to 8b, the assembly will fail with an error suggesting to use JP instead of JR.↩︎
This instruction is not standard and may cause error or crashes on both emulators and real hardware. In my gameboy emulator it is used to tell the emulator to dump the content of the registers.↩︎