AGBRS

Rust for the Game Boy Advance

This is a library for making games on the Game Boy Advance using the Rust programming language. It attempts to be a high level abstraction over the internal workings of the Game Boy Advance whilst still being high performance and memory efficient.

AGBRS provides the following features:

Simple build process with minimal dependencies
Built in importing of sprites, backgrounds, music and sound effects
High performance audio mixer
Simple sprite and tiled background usage
Global allocator allowing for use of both core and alloc

The documentation for the latest release can be found on docs.rs.

Getting started

The best way to get started with agb is to use the template, either within the template directory in this repository or cloning the template repository.

Once you have done this, you will find further instructions within the README in the template.

There is an (in progress) tutorial which you can find on the project website.

Help / Support

If you need any help, the discussions page is a great place to get help from the creators and contributors.

Feel free to create a new discussion in the Q&A category and we'll do our best to help!

Contributing to agb itself

In order to contribute to agb itself, you will need a few extra tools on top of what you would need to just write games for the Game Boy Advance using this library:

Recent rustup, see the rust website for instructions for your operating system.
- You can update rustup with rustup update, or using your package manager if you obtained rustup in this way.
arm eabi binutils
- Debian and derivatives: sudo apt install binutils-arm-none-eabi
- Arch Linux and derivatives: pacman -S arm-none-eabi-binutils
- Windows can apparently use the GNU Arm Embedded Toolchain. Make sure to select "Add path to environment variable" during the install.
- This process has only been tested on Ubuntu and Arch Linux.
libelf and cmake
- Debian and derivatives: sudo apt install libelf-dev cmake
- Arch Linux and derivatives: pacman -S libelf cmake
mgba-test-runner
- Run cargo install --path mgba-test-runner inside this directory
The 'just' build tool
- Install with cargo install just
mdbook
- Install with cargo install mdbook
gbafix
- Install with cargo install gbafix

With all of this installed, you should be able to run a full build of agbrs using by running

just ci

Note that before you create a PR, please file an issue so we can discuss what you are looking to change.

Structure of the repo

agb-fixnum - a simple fixed point number storage since the GBA doesn't have a floating point unit, so required for performant decimals.

agb-image-converter - a crate which converts images in normal formats to a format supported by the game boy advance

agb-macros - miscellaneous proc-macros which have to be in a different crate

agb-sound-converter - a crate which converts wav files into a format supported by the game boy advance

agb - the main library code

agb/examples - basic examples often targeting 1 feature, you can run these using just run-example <example-name>

book - the source for the tutorial and website

book/games - games made as part of the tutorial

examples - bigger examples of a complete game, made during game jams

mgba-test-runner - a wrapper around the mgba emulator which allows us to write unit tests in rust

template - the source for the template repository

Stability

While in 0.x releases, we are following a semi-semantic versioning. So 0.x.y will be compatible with 0.x.z provided that y > z, but any changes to the minor version will be incompatible with one another.

Once we hit version 1.0, we will maintain stronger semantic versioning.

Acknowledgments

AGBRS would not be possible without the help from the following (non-exhaustive) list of projects:

The amazing work of the rust-console for making this all possible in the first place
The asefile crate for loading aseprite files
agbabi for providing high performance alternatives to common methods
mgba for all the useful debugging / developer tools built in to the emulator

Licence

AGBRS and all its subcrates are released under MPL version 2.0. See full licence text in the LICENSE file.

AGBRS contains a subset of the code from agbabi which is released under a zlib style licence, details for which you can find under agb/src/agbabi.

The template is released under CC0 to allow you to make whatever changes you wish.

The AGBRS logo is released under Creative Commons Attribution-ShareAlike 4.0

The music used for the examples is by Josh Woodward and released under Creative Commons Attribution 4.0

Lymia / agb