---

Compile Rust to Game Boy ROMs.

The Rust-GB Project

Everything needed to write a Game Boy program in Rust, and to build it into a ROM.

Rust libraries for writing Game Boy programs

• rust-gb: the hardware abstraction layer, and the crate to start from.
• gb-bank, gb-hram, gb-pak, gb-ram-fn: the pieces behind rust-gb
• gb-rt: the runtime. rrt0.s is the startup code a cartridge boots into.
• gbdk-sys: Rust bindings to GBDK-2020.

Host tools for building ROM

• cargo-gb, gb-header-fix, gb-bank-pack: turn a crate into a ROM.
• gb-image-fx: convert images into Game Boy tile data.

Example programs

• examples/: example Game Boy ROMs written in Rust.

Building Rust-GB also produced llvm-z80, rust-z80 and decolorize.

Building a ROM

Install the build tool once:

cargo install --path tools/cargo-gb

Then, in any example (or your own crate):

cargo gb build    # compiles and writes target/<name>.gb
cargo gb run      # build, then launch $EMULATOR (default: sameboy)

The rust-z80 toolchain bundles the SM83 linker and LLVM tools, so there is nothing else to configure.

How is this possible?

The Game Boy is not a Rust target (it is not even in Tier 3), and there has been no stable LLVM backend for its CPU.

Rust-GB uses a custom LLVM backend for Game Boy:

1. rust-z80, a fork of the Rust compiler, targets sm83 and emits LLVM-IR.
2. llvm-z80, an LLVM fork with a Z80/SM83 backend, lowers that IR to SM83 machine code.
3. The objects are linked against the runtime and built into a Game Boy ROM. cargo gb build (cargo-gb) drives the whole pipeline.

Why use Rust instead of C or ASM?

1. Rust provides a higher-level and better grammar than C.
2. Rust's memory stability and strict types help you avoid writing incorrect code (even on a small device).
3. Putting everything aside, it's fun!

Goal

This project's goal is to develop a Game Boy Development Kit that enables the creation of Game Boy games using Rust, including safe management APIs in Game Boy memory, abstracted functions, and more.

Support

If you like this project, you can always join our Discussion! Please feel free to share your opinions or ideas.

This project is in its very early stages, and we are still designing many things, so it would be nice to have a variety of ideas.

PRs are always welcome too!

Dependencies

• rust-z80 (nightly Rust fork)

Related & Similar projects

• GBDK-2020 : Provides the basic library for Game Boy.
• llvm-z80 : The LLVM fork providing the Z80/SM83 backend.
• z80_babel : Gave the idea of compiling Rust code into Z80 in the early stages of the rust-gb project.
• gba : Compiles Rust code for the Game Boy Advance. (Unlike DMG, GBA is Rust's Tier 3 target.)