agb/README.md

129 lines
5.6 KiB
Markdown

# AGBRS
## Rust for the Game Boy Advance
![AGB logo](.github/logo.png)
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/).
## Help / Support
If you need any help, the [discussions page](https://github.com/agbrs/agb/discussions)
is a great place to get help from the creators and contributors.
Feel free to [create a new discussion in the Q&A category](https://github.com/agbrs/agb/discussions/new?category=Q-A) 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](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/)