Generating Gameboy Assembler
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

GGBASM (Generating Gameboy Assembler)

Build Status dependency status Docs

A gameboy assembler as a rust crate library. Being a library instead of command line application, allows for an elegant combination of:

  • raw bytes and instructions generated from rust code
  • instructions read from *.asm files.


The RomBuilder is the core rust api of GGBASM.

    // Starts off in the first rom bank
    // A simple example doesnt need to deal with interrupts and jumps, so generate a dummy

    // generate a header from data in the passed header struct

    // Add game code via an asm file

    // Add an image to the second rom bank
    .advance_address(1, 0)?
    .add_image("tiles.png", "GraphicsBinary", &colors_map)?

    // Consume the RomBuilder and write the rom to disk


Check out the examples folder and heartacheGB.

Comparison with RGBDS

  • RGBDS requires only *.asm files, while GGBASM requires *.asm, and an entire rust crate.
  • RGBDS needs to run RGBDS -o main.obj src/main.asm; rgblink -m -n game.sym -o main.obj; rgbfix -p 0 -v to build the rom, while GGBASM uses cargo run to build the rom
  • RGBDS uses includes inside the *.asm files, while GGBASM uses rust to insert instructions and raw bytes at the correct location in the rom.
  • GGBASM has helper functions for generating bytes such as: png_to_gb_sprite
  • RGBDS has its own intel-like syntax, GGBASM syntax uses RGBDS syntax with a few additions. Changes from RGBDS are:
    • hexadecimal can be represented as 0x2a as well as $2a
    • uses advance_address 0xYYYY instead of section "FOO",$HOME[$YY]