The panic screen
If a game written using agb
panics, you'll be greeted with a crash screen.
This screen provides both the panic message along with a special code which you can use to produce a stack trace for the error.
The QR code shown will also link you to the agb
website where you can view more details about the crash (in the case for the example above, here).
If using the mGBA emulator, the link will also be printed to the console.
All the information is calculated from the code (3K8CDNW010O2W013KgQFq05i05av1
in the above case), and no information about your game is transmitted to the crash page.
It mainly exists to provide you with an easy way to transfer the code to your computer so you can examine the crash more easily.
Decoding the results
The crash screen will include the file and line number where the panic occurred. This is often enough to work out where the issue may lie. However, sometimes it is useful to get the full stack trace.
The agb-debug
cli
You can install the agb-debug
tool with the following command:
cargo install --git=https://github.com/agbrs/agb.git agb-debug
Then with agb-debug
, you can give it a link to the elf
file for your ROM and the code and it'll give the full stack trace.
For example:
$ agb-debug target/thumbv4t-none-eabi/release/the_hat_chooses_the_wizard 3K8CDNW010O2W013KgQFq05i05av1
0: __rustc::rust_begin_unwind <agb>/lib.rs:407
let frames = backtrace::unwind_exception();
^
1: core::panicking::panic_fmt <core>/panicking.rs:75
2: the_hat_chooses_the_wizard::sfx::SfxPlayer::snail_death <the-hat-chooses-the-wizard>/sfx.rs:94
panic!("Unknown sound");
^
3: the_hat_chooses_the_wizard::enemies::Snail::update <the-hat-chooses-the-wizard>/enemies.rs:350
sfx_player.snail_death();
^
(inlined into) the_hat_chooses_the_wizard::enemies::Enemy::update <the-hat-chooses-the-wizard>/enemies.rs:51
Enemy::Snail(snail) => snail.update(level, player_pos, hat_state, timer, sfx_player),
^
4: the_hat_chooses_the_wizard::PlayingLevel::update_frame <the-hat-chooses-the-wizard>/lib.rs:681
match enemy.update(
^
(inlined into) the_hat_chooses_the_wizard::main <the-hat-chooses-the-wizard>/lib.rs:813
match level.update_frame(&mut sfx) {
^
5: the_hat_chooses_the_wizard::_agb_main_func_2381583852303396514::inner <the-hat-chooses-the-wizard>/main.rs:9
the_hat_chooses_the_wizard::main(gba);
^
6: main <the-hat-chooses-the-wizard>/main.rs:7
#[agb::entry]
^
The agb-debug
cli will include the actual code snippets from your filesystem if it can find it.
agbrs.dev/crash
You can also use the crash page itself, giving it your elf file.
All this is done within your browser, and nothing gets passed to the agb
servers.
Debugging .gba
files
When creating a .gba
file using agb-gbafix
, it will, by default, strip out the debug information which is required to provide the backtrace information as shown.
You are able to run the .gba
file and pass agb-gbafix
the elf file which was converted into the gba
file if needed.
However, you can also include all the debug information in the gba
file itself by passing the -g
argument to agb-gbafix
.
$ agb-gbafix -g target/thumbv4t-none-eabi/release/my_game target/my_game.gba
Both the backtrace viewer on the agbrs.dev/crash website and the agb-debug
cli tool will be able to parse the debug information out of the gba file.
Note that this will quite drastically increase the size of your .gba
file and it could end up getting close to the cartridge size limits.
Configuring the target website
The target website can be configured by setting the AGBRS_BACKTRACE_WEBSITE
environment during the build.
# Direct players to your website
AGBRS_BACKTRACE_WEBSITE="https://example.com/test#" cargo build
# Don't have a website at all. The QR code will just be the ID
AGBRS_BACKTRACE_WEBSITE="" cargo build
To completely disable the backtraces, you can disable the backtrace
feature in agb
by editing your Cargo.toml
as follows:
# Disable the `backtrace` feature
agb = { version = "...", default-features = false, features = ["testing"] }


