Gameboy Assembler

Small assembler for Gameboy assembly programs written in Swift.
Assembly syntax mostly follows other assemblers, but is probably not compatible.
Takes an assembly file as input, produces a binary, which can be executed in a Gameboy emulator.
Is fairly feature complete, supports all of the instruction set. Still missing some nice-to-have features, see the todo below.

Example program

Here is a small example Gameboy program, which displays a smiley sprite on screen:

# Simple smiley
# Displays a smiley sprite in the upper left corner of the screen

bg_tile_map = 0x9800
bg_tile_data = 0x9000

[org(0x4000)] graphics: db 0x00, 0x24, 0x24, 0x00, 0x81, 0x7e, 0x00, 0x00
[org(0x100)] start: nop; jp main
[org(0x134)] game_title: db "SMILEY"

[org(0x150)] main:
	# Set LCDC (bit 7: operation on, bit 0: bg and win on)
	ld hl, 0xff40
	ld [hl], (1 | (1 << 7))

	# Set first bg tile
	ld h, (bg_tile_map >> 8)
	ld l, (bg_tile_map & 0xff)
	ld [hl], 1

	# Set the tile data
	ld h, (bg_tile_data >> 8)
	ld l, ((bg_tile_data & 0xff) + 16)
	ld b, 8
	ld de, 0x4000
	loop:
		ld a, [de]
		inc de
		ld [hl+], a
		ld [hl+], a
		dec b
		jp nz, loop

	# Set bg palette data
	ld hl, 0xff47
	ld [hl], 0xe4
	end: jp end

[org(0x7fff)] pad: db 0x00

This is how it looks:

There are more examples in the examples folder:

Smiley sprite | Hello world | Directional pad movement

Usage

Quick start:

git clone [email protected]:ulrikdamm/Assembler.git
cd Assembler
swift build -c release
./.build/release/Assembler input.asm

You can compile the app from the Xcode project or by running swift build (the executable will be in .build/debug/Assembler)
You compile source code with Assembler input.asm.
It also contains a dynamic framework which you can import into a macOS or iOS app.

Project status

The assembler is stable and able to produce working binaries. See below for which features are supported and which are yet to come.

New in version 1.2

🆕 Optional linker output showing all symbol locations (run with --output-symbols)
🆕 Relative jumps (jr)
🆕 Updated syntax (uses [] instead of () for direct memory access, as in ld a, [0xff46])
🆒 Example code showing gamepad input and DMA transfers
🆗 Fixed problems with loads between a and memory that wouldn’t assemble properly

New in version 1.1

🆕 Ability to use labels in expressions (e.g. ld a, (data_end - data))
🆕 Allows empty labels (useful for the first point)
🆕 Better command line interface, allows relative paths
🆒 Updated examples
🆗 Fixed loading of values between A and memory addresses (e.g. ld a, (0xff00 + 0x44))

Implemented features

✅ Assembly parsing
✅ Code generation
✅ Linking
✅ All of the Gameboy instruction set
✅ Error reporting with line numbers
✅ Command line interface
✅ Constant defines
✅ Build-time expressions
✅ Strings

Todo

➡️ Imports and file modules
➡️ Smart layout of disconnected blocks in linker
➡️ Support for variables though ds (define storage)

Wish list

💟 More awesome example programs
💟 Sprite importer (manually entering pixel hex codes suck. Maybe a way of defining sprites in ASCII art?)
💟 Graphical code editor

Contributing

Right now it’s still a personal project, and I might not be accepting pull requests for new features. Bug fixes and more tests are welcome though.

If you find a bug or a missing feature, feel free to submit an issue.