mirror of
https://github.com/italicsjenga/agb.git
synced 2024-12-24 16:51:33 +11:00
121 lines
5.3 KiB
Markdown
121 lines
5.3 KiB
Markdown
# 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](https://docs.rs/agb/latest/agb/).
|
|
|
|
## 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](https://github.com/agbrs/template).
|
|
|
|
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](https://agbrs.github.io/agb/).
|
|
|
|
## 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](https://www.rust-lang.org/tools/install)
|
|
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](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads).
|
|
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](https://github.com/casey/just)
|
|
* Install with `cargo install just`
|
|
* [mdbook](https://rust-lang.github.io/mdBook/index.html)
|
|
* Install with `cargo install mdbook`
|
|
* [gbafix](https://crates.io/crates/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
|
|
```sh
|
|
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](https://mgba.io) emulator which allows us to write unit tests in rust
|
|
|
|
`template` - the source for the [template repository](https://github.com/agbrs/template)
|
|
|
|
## 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](https://github.com/rust-console) for making this all possible in the first place
|
|
* The [asefile](https://crates.io/crates/asefile) crate for loading aseprite files
|
|
* [agbabi](https://github.com/felixjones/agbabi) for providing high performance alternatives to common methods
|
|
* [mgba](https://mgba.io) 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](https://github.com/felixjones/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](https://creativecommons.org/share-your-work/public-domain/cc0/) to allow you to make whatever
|
|
changes you wish.
|
|
|
|
The AGBRS logo is released under [Creative Commons Attribution-ShareAlike 4.0](http://creativecommons.org/licenses/by-sa/4.0/)
|
|
|
|
The music used for the examples is by [Josh Woodward](https://www.joshwoodward.com) and released under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) |