agb/template

AGBRS template

A basic template example for agb projects

This makes getting started with a new project for the Game Boy Advance in rust really simple, by providing all the boiler plate files for you.

Building

Prerequisites

You will need the following installed in order to build and run this project:

• A recent version of rustup. See the rust website for instructions for your operating system
• arm-none-eabi-binutils for assembling and linking
  • Windows: GNU Arm Embedded Toolchain. Make sure you select "Add path to environment variable" during the install
  • Debian and derivatives (e.g. Ubuntu, raspberry pi OS, linux mint): sudo apt install binutils-arm-none-eabi
  • Arch linux and derivatives: sudo pacman -S arm-none-eabi-binutils

You will also want to install an emulator. The best support in agb is with mgba, with println! support via agb::println! but any emulator should work. You'll get the best experience if mgba-qt is in your PATH.

If you want to run your game on real hardware, you will also need to install gbafix which you can do after installing rust with the following: cargo install gbafix. This is not required if you are only running your game in an emulator.

Running in an emulator

Once you have the prerequisites installed, you should be able to build using

cargo build

or in release mode (recommended for the final version to ship to players)

cargo build --release

The resulting file will be in target/thumbv4t-none-eabi/debug/<your game> or target/thumbv4t-none-eabi/release/<your game> depending on whether you did a release or debug build.

If you have mgba-qt in your path, you will be able to run your game with

cargo run

or in release mode

cargo run --release

Starting development

You can find the documentation for agb here.

You may also want to change the package name and version in Cargo.toml before you start.

Shipping a .gba file for real hardware

To make a game run on real hardware, you will need to convert the built file into a file suitable for running on the real thing.

First build the binary in release mode using the instructions above, then do the following:

arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/<your game> <your game>.gba
gbafix <your game>.gba