6 releases
Uses new Rust 2024
new 0.1.0-rc.6 | Mar 27, 2025 |
---|---|
0.1.0-rc.3 | Mar 26, 2025 |
#594 in Game dev
107 downloads per month
370KB
529 lines
Bevy Mod GameBoy Advance
This crate provides integration between the agb
HAL for the GameBoy Advance, and the Bevy game engine.
Simply add the AgbPlugin
to your no_std
Bevy application, and you'll have access to:
- The gamepad using Bevy's idiomatic
Gamepad
component - A basic renderer providing a
Sprite
component - Integration with
Time
and the built-in hardware timer - A custom application runner chasing V-Blank
- Logging integration when using the mGBA emulator
Below is a screenshot from the game
example on the repository.
Building
Recommended prerequisites
You may want to install the below to allow running the example:
- A GameBoy Advance emulator. The best support in agb is with mgba. Ensure
mgba
is in yourPATH
for the best experience. agb-gbafix
usingcargo install agb-gbafix
. This is not required if you are only running your game in an emulator, but does allow neatly packaging a ROM.- Rust's nightly toolchain.
Setup
Since this is largely based on abg
it's possible to get started using their template.
If you'd like to setup a project from scratch, here's what you'll want to do:
-
Create a new project with
cargo init
. -
Create a
rust-toolchain.toml
file in the project root with the following contents:[toolchain] channel = "nightly" components = ["rust-src", "clippy", "rustfmt"]
Note that this informs
cargo
that we require anightly
toolchain and would like a copy of the Rust source code, and theclippy
andrustfmt
tools. -
Create a
.cargo/config.toml
file with the following contents:[unstable] build-std = ["core", "alloc"] build-std-features = ["compiler-builtins-mem"] [build] target = "thumbv4t-none-eabi" [target.thumbv4t-none-eabi] rustflags = [ "-Clink-arg=-Tgba.ld", "-Ctarget-cpu=arm7tdmi", "-Cforce-frame-pointers=yes", ] runner = ["mgba", "-C", "logToStdout=1", "-C", "logLevel.gba.debug=127"] [target.armv4t-none-eabi] rustflags = [ "-Clink-arg=-Tgba.ld", "-Ctarget-cpu=arm7tdmi", "-Cforce-frame-pointers=yes", ] runner = ["mgba", "-C", "logToStdout=1", "-C", "logLevel.gba.debug=127"]
This informs the compiler that we need to compile
core
andalloc
from source, since we have some custom flags to apply. Additionally, this sets up the mGBA emulator as our runner, allowingcargo run
to work as expected.
Running in an emulator
Once you have the prerequisites installed, you should be able to build using
cargo build
or in release mode (strongly recommended)
cargo build --release
The resulting file will be in target/thumbv4t-none-eabi/debug/my_game
or target/thumbv4t-none-eabi/release/my_game
depending on
whether you did a release or debug build.
If you have mgba
in your path, you will be able to run your game with
cargo run
or in release mode
cargo run --release
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:
agb-gbafix target/thumbv4t-none-eabi/release/my_game -o my_game.gba
Dependencies
~24–33MB
~595K SLoC