alex/agb
1
0
Fork 0
mirror of https://github.com/italicsjenga/agb.git synced 2024-10-17 07:31:39 +11:00
Code Issues Packages Projects Releases Wiki Activity

Do an editing pass of the book using chatgpt (#398)

Browse source 
- [x] Changelog updated / no changelog update needed
This commit is contained in:
Gwilym Inzani 2023-03-23 21:50:19 +00:00 committed by GitHub
parent ea55278c7d cf8210c421
commit 5ad2ad092e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 179 additions and 132 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
README.md
View file

@ -1,4 +1,4 @@
# AGBRS
# AGB
## Rust for the Game Boy Advance
@ -10,17 +10,17 @@
![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.
programming language. The library's main focus is to provide an abstraction
that allows you to develop games which take advantage of the GBA's capabilities
without needing to have extensive knowledge of its low-level implementation.
AGBRS provides the following features:
agb 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`
* Easy to use sprite and tiled background usage
* A 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/).
@ -69,7 +69,7 @@ to just write games for the Game Boy Advance using this library:
* [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
With all of this installed, you should be able to run a full build of agb using by running
```sh
just ci
```
@ -103,15 +103,14 @@ for performant decimals.
## 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.
While agb is in the pre-1.0 phase, we follow a semi-semantic versioning scheme to ensure compatibility between minor releases.
Specifically, any 0.x.y release is guaranteed to be compatible with another 0.x.z release provided that y > z, but there may be breaking changes between minor releases (i.e., changes to the second digit, e.g., between 0.1 and 0.2).
Once we hit version 1.0, we will maintain stronger semantic versioning.
Once agb reaches version 1.0, we will transition to stronger semantic versioning, meaning that any breaking changes will be indicated by an increment to the major version (i.e., the first digit, e.g., from 1.0 to 2.0).
## Acknowledgments
AGBRS would not be possible without the help from the following (non-exhaustive) list of projects:
agb 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
@ -120,15 +119,15 @@ AGBRS would not be possible without the help from the following (non-exhaustive)
## Licence
AGBRS and all its subcrates are released under MPL version 2.0. See full licence
agb 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,
agb 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 agb 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/)

30
book/src/hardware/hardware.md
View file

@ -1,21 +1,20 @@
# The Game Boy Advance hardware
The Game Boy Advance was released by Nintendo in Japan in March 2001 and in North America in the following June.
It has a 2.9 inch screen with a 240x144 pixel resolution, and contains a 32-bit 16.8MHz ARM CPU.
It was developed to be the successor to the Game Boy Color and internally codenamed the 'Advanced Game Boy' (agb) which is where this crate gets its name.
The Game Boy Advance is a handheld gaming console released by Nintendo in March 2001 in Japan and in North America in June of the same year.
It features a 2.9 inch screen with a 240x144 pixel resolution and is powered by a 32-bit 16.8MHz ARM CPU.
The console was developed as a successor to the Game Boy Color and was internally codenamed the 'Advanced Game Boy' (agb), which is where this crate gets its name.
# What makes the GBA unique?
The Game Boy Advance is (fairly) unique amongst retro handheld consoles.
It was developed at a time where processors weren't powerful enough to be able to push an entire screen of pixels to the screen every frame.
Therefore, it has a special Pixel Processing Unit (PPU) which is sort of similar to a modern day graphics card, except it is very games focused.
For example, the GBA has a concept of 'hardware sprites' and 'hardware backgrounds' which we'll go in to more detail in the next section.
This hardware 2d capabilities gives the GBA the unique characteristics with the games developed for it.
The Game Boy Advance is a (fairly) unique console among retro handheld consoles.
It was developed at a time when processors were not powerful enough to push an entire screen of pixels to the screen every frame.
As a result, it features a special Pixel Processing Unit (PPU) that is similar to a modern-day graphics card, but is optimized for gaming.
The console has a concept of "hardware sprites" and "hardware backgrounds," which we will explain in more detail in the next section.
These hardware 2D capabilities give the GBA its unique characteristics.
However, despite this, it is possible to write code for it using modern tools and programming languages thanks to the ARM CPU it contains.
The CPU is modern enough to be supported by LLVM and rust to give a reasonably trouble free experience.
So the GBA lets you take advantage of modern tooling while also giving you the ability to see what programming for retro consoles was like at the time!
Despite being a retro console, the GBA is still compatible with modern tools and programming languages thanks to the ARM CPU it contains.
The CPU is modern enough to be supported by LLVM and Rust, which provide a reasonably trouble-free experience.
This allows developers to take advantage of modern tooling while experiencing what it was like to program for retro consoles at the time.
# Capabilities of the hardware
@ -25,9 +24,8 @@ The relevant features for this book are:
* 256 sprites which can be from 8x8 to 64x64 pixels in size
* 4 background layers which are enabled / disabled depending on the graphics mode
* Background tiles, 8x8 pixel tiles are used in the background layers if they are in tile mode.
* 8-bit sound. You have the ability to send 8-bit raw audio data to the speakers (optionally stereo).
* 8-bit sound. You have the ability to send 8-bit raw audio data to the speakers, optionally stereo.
You can read more about the specifics of the GBA on [gbatek](https://rust-console.github.io/gbatek-gbaonly/).
agb tries to abstract some of this away from you to give you less to remember and less that can go wrong.
If you want to try playing around directly with the hardware, the best place to look is [tonc](https://www.coranac.com/tonc/text/).
To simplify the development process, agb abstracts some of the GBA's hardware away from the developer, which reduces the number of things to remember and lessens the chance of something going wrong.
If you wish to experiment with the hardware directly, the best place to look is [tonc](https://www.coranac.com/tonc/text/).

60
book/src/introduction/introduction.md
View file

@ -1,30 +1,52 @@
# Introduction
**agb** is a library for writing games for the Game Boy Advance (GBA) in rust.
It is intended to make the process of producing games for the Game Boy Advance as easy as possible by giving you access to the hardware in an abstracted format, which allows you to take advantage of all that it has to offer, without needing to know the specifics of how it is implemented.
**agb** is a powerful and easy-to-use library for writing games for the Game Boy Advance (GBA) in rust.
It provides an abstracted interface to the hardware, allowing you to take full advantage of its capabilities without needing to know the low-level details of its implementation.
## A little bit about agb
`agb` is a library for making games on the Game Boy Advance using the Rust
programming language. The library's main focus is to provide an abstraction
that allows you to develop games which take advantage of the GBA's capabilities
without needing to have extensive knowledge of its low-level implementation.
agb provides the following features:
* Simple build process with minimal dependencies
* Built in importing of sprites, backgrounds, music and sound effects
* High performance audio mixer
* Easy to use sprite and tiled background usage
* A global allocator allowing for use of both `core` and `alloc`
## Why rust?
Rust is an excellent choice of language for developing games on low-level embedded hardware like the GBA.
Its strong type system, memory safety, and performance optimizations make it well-suited for building reliable and efficient code in this context.
Agb leverages rust's unique features by using the type system to model the GBA's hardware.
This approach helps prevent common programming errors and allows developers to quickly build games that function correctly on the GBA platform.
In addition to safety and correctness, rust's performance optimizations are crucial for developing games on the GBA's slow processor.
With a limited amount of time per frame, every optimization counts, and rust's speed and efficiency help ensure that games built with agb run smoothly on the GBA hardware.
# What is in this book?
This book is intended as an introduction to what **agb** has to offer, and should set you up nicely to start writing games of your own.
This book will not give a thorough overview of the specifics of the hardware implementation of the GBA unless it is needed as part of an explanation.
An overview of the hardware can be found in chapter 2.
This book serves as an introduction to agb, showcasing its capabilities and providing guidance on how to use it to build your own GBA games.
It assumes that you have some experience with rust and game development, and provides detailed explanations of the unique challenges of writing games for the GBA.
# Who is this book for?
This book is for:
* **People who want to make games for the GBA.** First and foremost, games written using agb cannot run on any other platform except the GBA and emulators. If you don't want to write a game for the GBA, you should probably use a different library.
* **People who have experience in rust.** Unless the rust specific syntax or semantics are important, we will not discuss details here and instead recommend reading the rust book before coming back.
* **People with experience in writing games.** Game programming is hard, and harder still in rust on a GBA. We recommend writing a game for a more user friendly platform before coming back here.
If you fit into all of those categories, welcome!
It is super rewarding being able to play a game you made yourself on a piece of 20+ year old hardware.
This book is ideal for anyone interested in writing games for the GBA using rust.
If you're new to either rust or game development, you may want to start with some introductory resources before diving into this book.
This book assumes a basic understanding of rust syntax and semantics, as well as game development concepts.
# Helpful links
* [agb's GitHub](https://github.com/agbrs/agb) all development happens here
* [agb's Discussion Page](https://github.com/agbrs/agb/discussions) a forum where you can ask for help on the usage of agb
* [agb's crates.io page](https://crates.io/crates/agb)
* [agb's documentation](https://docs.rs/agb) which is useful if you need a quick reference
* [Awesome Game Boy Advance development](https://github.com/gbdev/awesome-gbadev) contains links to popular libraries, emulators and the super friendly gbadev discord
* [Example game](https://lostimmortal.itch.io/the-hat-chooses-the-wizard) written using agb as part of the 2021 GMTK game jam.
* [More example games](https://github.com/agbrs/agb/releases/latest) built using agb. See them in `examples.zip` attached to the latest release.
* [agb's GitHub](https://github.com/agbrs/agb) is the primary development hub for the library.
* [agb's Discussion Page](https://github.com/agbrs/agb/discussions) is a helpful forum where you can ask for help on using agb or share your projects with the community.
* [agb's crates.io page](https://crates.io/crates/agb) the latest version of the library on crates.io.
* [agb's documentation](https://docs.rs/agb) is a useful reference for the library's API and features.
* [Awesome Game Boy Advance development](https://github.com/gbdev/awesome-gbadev) is a comprehensive resource for GBA development, with links to popular libraries, emulators, and the friendly gbadev Discord server.
* [Example games](https://github.com/agbrs/agb/releases/latest) built using agb can be found in the `examples.zip` file attached to the latest release. Additionally, you can also check out [The Hat Chooses the Wizard](https://lostimmortal.itch.io/the-hat-chooses-the-wizard), a game written using agb as part of the GMTK 2021 game jam.
In addition to these resources, this book provides step-by-step instructions for getting started with agb.

26
book/src/pong/01_introduction.md
View file

@ -1,25 +1,23 @@
# Learn agb part I - pong
# Learn agb part I: Pong
In this section, we'll make a simple pong style game for the Game Boy Advance using `agb`.
You will learn:
In this section, you'll learn how to make a simple pong-style game for the Game Boy Advance using agb.
By following the steps in this section below, you'll gain an understanding of:
* How to use tiled graphics modes.
* How to import graphics using `agb`.
* What Game Boy Advance sprites are and how to put them on the screen.
* How to detect button input and react to it.
* How to add a static background.
* How to make a dynamic background for a score display.
* How to add music to your game.
* How to add sound effects to your game.
* What Game Boy Advance sprites are, how to create them, and how to display them on the screen.
* How to detect button input and use it to control game objects.
* How to add a static background to your game.
* How to make a dynamic background to display scores.
* How to add music and sound effects to your game.
With this knowledge, you'll be well equipped to start making your own games!
With this knowledge, you'll be well equipped to start making your own games for the GBA!
## Getting started
To start, create a new repository based on the [agb template](https://github.com/agbrs/template).
We'll call this `pong`.
To get started, create a new repository based on the [agb template](https://github.com/agbrs/template) and name it `pong`.
Then replace the `name` field in `Cargo.toml` with `pong`, to end up with something similar to:
Next, update the `name` field in `Cargo.toml` to `pong` like so:
```toml
[package]
@ -31,4 +29,4 @@ edition = "2021"
# ...
```
You are now ready to get started learning about how `agb` works.
Now, you're ready to dive and and start learning about `agb`!

24
book/src/pong/02_the_gba_struct.md
View file

@ -4,14 +4,17 @@ In this section, we'll cover the importance of the Gba struct and how it gets cr
# The importance of the Gba struct
Almost all interaction with the Game Boy Advance's hardware goes through the [Gba singleton struct](https://docs.rs/agb/latest/agb/struct.Gba.html).
You should not create the Gba struct yourself, instead having it be passed into your main function.
The [Gba singleton struct](https://docs.rs/agb/latest/agb/struct.Gba.html) is a crucial part of agb game development.
It is used for almost all interactions with the Game Boy Advance's hardware, such as graphics rendering, timer access and audio playback.
The Gba struct is used to take advantage of rust's borrow checker, and lean on it to ensure that access to the Game Boy Advance hardware is done 'sensibly'.
You won't have to worry about 2 bits of your code modifying data in the wrong way!
You should not create the Gba struct yourself. Instead, it is passed to your main function as an owned reference.
This allows rust's borrow checker to ensure that access to the Game Boy Advance hardware is done in a safe and sensible manner, preventing two bits of your code from modifying data in the wrong way.
# How all agb games start
To use the Gba struct in your agb game, you'll need to create a function (normally called `main`) which takes an owned reference to the Gba instance.
The recommended way to do this is by using the `#[agb::entry]` attribute macro provided by the `agb` crate.
Replace the content of the `main` function with the following:
```rust,ignore
@ -23,15 +26,14 @@ loop {} // infinite loop for now
# }
```
and ignore warnings for now.
This creates an infinite loop and allows you to start building your game.
# Running your pong game
Although there isn't much to see at the moment (just a black screen), you can start the game by using `cargo run` or whatever worked for you in the introduction.
At this point, your game won't do much except display a black screen. To run your game, use the `cargo run` command as before.
# What we did
# What we covered
This was a very simple but incredibly important part of any game using `agb`.
All interactions with the hardware are gated via the Gba struct, which you never create yourself.
You are now ready to learn about display modes and how to start getting things onto the screen!
In this section, we covered the importance of the Gba struct in agb game development.
By using the Gba struct as a gatekeeper for all hardware interactions, you can ensure that your code is safe and efficient.
You are now ready to learn about sprites and start getting things onto the screen!

52
book/src/pong/03_sprites.md
View file

@ -1,56 +1,44 @@
# Sprites
In this section, we'll put the sprites needed for our pong game onto the screen.
We'll cover what sprites are in the Game Boy Advance, and how to get them to show up on screen.
We'll briefly cover vblank and by the end of this section, you'll have a ball bouncing around the screen!
In this section, we'll cover what sprites are in the Game Boy Advance and how to put them on the screen in our pong game.
We'll briefly cover vblank, and by the end of this section, you'll have a ball bouncing around the screen!
# Why do we need sprites in the first place?
# Why do we need sprites?
The Game Boy Advance has a 240x160px screen, with 15-bit RGB colour support.
In order to manually set the colour for each pixel in the screen, you would need to update a total of 38,400 pixels per frame, or 2,304,000 pixels per second at 60 fps.
With a 16MHz processor, that means you would need to be able to calculate 1 pixel every 8 clock cycles, which is pretty much impossible.
You could get clever with how you update these pixels, but using the tools provided by the Game Boy Advance to put pixels on the screen, you'll have a much easier time.
The Game Boy Advance has a 240x160px screen with 15-bit RGB color support. Setting the color for each pixel manually would require updating 38,400 pixels per frame, or 2,304,000 pixels per second at 60 fps.
With a 16 MHz processor, this means calculating 1 pixel every 8 clock cycles, which is pretty much impossible.
he Game Boy Advance provides two ways to easily put pixels on the screen: tiles and sprites.
So there are 2 ways that the Game Boy Advance allows you to get these pixels on screen much more easily.
Tiles and sprites.
Tiles are 8x8 pixels in size and can be placed in a grid on the screen.
You can also scroll the whole tile layer to arbitrary positions, but the tiles will remain in this 8x8 pixel grid.
We'll cover tiles in more detail later.
The other way you can draw things on screen is using sprites, which we'll cover in more detail in this section.
Sprites are the other way to draw things on the screen, which we'll cover in this section.
The Game Boy Advance supports 256 hardware sprites, with different sizes ranging from square 8x8 to more exotic sizes like 8x32 pixels.
In our pong game, all the sprites will be 16x16 pixels to make things simpler.
# Sprites on the Game Boy Advance
Sprites are stored in a special area of video memory called the 'Object Attribute Memory' (OAM).
OAM has space for the 'attributes' of the sprites, such as their location, whether or not they are visible, and which tile to use, but it does not store the actual pixel data.
The pixel data is stored in video RAM (VRAM).
This split allows multiple sprites to refer to the same tiles in VRAM, which saves space and allows for more objects on screen than would be possible by repeating them.
The Game Boy Advance supports 256 hardware sprites.
These can be in one of many sizes, ranging from square 8x8 to more exotic sizes like 8x32 pixels.
For our pong game, all the sprites will be 16x16 pixels to make things a bit simpler.
Since RAM is in short supply and expensive, the tile data is stored as indexed palette data.
Instead of storing the full color data for each pixel in the tile, the Game Boy Advance stores a 'palette' of colors, and the tiles that make up the sprites are stored as indexes to the palette.
Each sprite can use a maximum of 16 colors out of the total sprite palette of 256 colors.
Sprites are stored in the Game Boy Advance in a special area of video memory called the 'Object Attribute Memory' (OAM).
This has space for the 'attributes' of the sprites (things like whether or not they are visible, the location, which tile to use etc) but it does not store the actual pixel data.
The pixel data is stored in a video RAM (VRAM).
Because of this split, it is possible to have multiple sprites refer to the same tiles in video RAM which saves space and allows for more objects on screen at once then repeating them would otherwise allow.
Since RAM is in short supply, and at the time was quite expensive, the tile data is stored as indexed palette data.
So rather than storing the full colour data for each pixel in the tile, the Game Boy Advance instead stores a 'palette' of colours and the tiles which make up the sprites are stored as indexes to the palette.
You don't need to worry about this though, because `agb` handles it for you, but it is important to keep in mind that each sprite can use a maximum of 16 colours out of the total sprite palette of 256 colours.
There are technically 2 types of sprite, regular and affine sprites.
There are technically two types of sprites: regular and affine sprites.
For now, we will only be dealing with regular sprites.
# Import the sprite
Firstly, you're going to need to import the sprites into your project.
`agb` has great support for the [aseprite](https://www.aseprite.org/) sprite editor which can be bought for $20 or you can compile it yourself for free.
`agb` has excellent support for the [aseprite](https://www.aseprite.org/) sprite editor which can be bought for $20 or you can compile it yourself for free.
Aseprite files can be natively imported by `agb` for use on the Game Boy Advance.
Here is the sprite sheet we will use as a png, but you should [download the aseprite file](sprites.aseprite) and place it in `gfx/sprites.aseprite`.
![pong sprites](sprites.png)
This contains 5 `16x16px` sprites.
The first is the end cap for the paddle.
The second is the centre part of the paddle, which could potentially be repeated a few times.
The third until the fifth is the ball, with various squashed states.
The aseprite file defines tags for these sprites, being "Paddle End", "Paddle Mid", and "Ball".
This contains 5 `16x16px` sprites: the end cap for the paddle, the center part of the paddle, which could potentially be repeated a few times, and the ball with various squashed states.
The aseprite file defines tags for these sprites: "Paddle End," "Paddle Mid," and "Ball."
```rust
use agb::{

64
book/src/setup/building.md
View file

@ -1,31 +1,71 @@
# Building the template
# Building and running the agb template
By the end of this section, you should be able to build and run the **agb** template.
In this section, you will learn how to build and run the agb template.
By the end of this section, you will have a working GBA game that you can run on your emulator of choice.
# 1. Get the source code
## 1. Clone the repository
The source code can be fetched using `git clone https://github.com/agbrs/template.git`.
The first step is to clone the agb template repository using Git.
Open a terminal or command prompt and run the following command:
# 2. Build the template
```sh
git clone https://github.com/agbrs/template.git
```
Build a copy of the template using `cargo build --release`.
This could take quite a while, but eventually you'll end up with a copy of the template in `target/thumbv4t-none-eabi/release/template` or `target/thumbv4t-none-eabi/release/template.elf` depending on platform.
This will create a copy of the agb template repository on your local machine.
This can be run directly by some emulators, but we need to run an extra step in order to convert the elf file into a '.gba' file.
## 2. Build the template
Next, navigate to the `template` directory in the repository and build the template using the following command:
```sh
cd template
cargo build --release
```
This command will compile the agb template in release mode.
The resulting binary file can be found in the `target/thumbv4t-none-eabi/release` directory.
Depending on your platform, the file will have either a `.elf` extension or no extension.
## 3. Convert the binary to a GBA file
In order to run the game on an emulator, we need to convert the binary file to a GBA file.
To do this, we'll use two tools: `arm-none-eabi-objcopy` and `gbafix`.
Run the following command to convert the binary file to a GBA file:
```sh
arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/template template.gba
gbafix template.gba
```
or
```sh
arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/template.elf template.gba
```
Depending on whether your file has the .elf extension.
This command will create a template.gba file in the template directory.
Next, run the following command to fix the GBA header:
```sh
gbafix template.gba
```
And then load the resulting file in your emulator of choice.
That's all there is to it!
This command will add the correct GBA header to the template.gba file.
If you have `mgba-qt` in your path, then you can launch the template directly using `cargo run --release`.
## 4. Run the game
Finally, you can run the game on your emulator of choice.
Load the template.gba file in your emulator, and you should see the agb template running.
If you have mgba-qt installed on your machine, you can run the game directly from the command line using the following command:
```sh
cargo run --release
```
This will build and run the agb template in a single step.
That's it! You now have a working agb template that you can use as a starting point for your own GBA game.

2
book/src/setup/getting_started.md
View file

@ -1,6 +1,6 @@
# Running an example
In this section, we will get to the point where you can build and run the game built for the GMTK game jam using agb known as 'The Hat Chooses the Wizard'.
In this section, we will get to the point where you can build and run the agb template repository.
This will prove that your development environment is ready for the future tutorials and later building.
You can run the game using real hardware and a flash card.

12
book/src/setup/linux.md
View file

@ -4,31 +4,31 @@ This guide has been tested on Ubuntu, Arch Linux and Raspberry Pi OS running on
# 1. Install a recent version of rust
agb unfortunately relies on a few nightly rust features, so you need to ensure you have that installed.
To use agb, you'll need to use nightly rust since it requires a few nightly features.
Firstly, ensure that you have **rustup** installed which you can do by following the instructions on the [rust website](https://www.rust-lang.org/tools/install)
You can update rustup with `rustup update` if you have already installed it.
If you have already installed rustup, you can update it with `rustup update`.
# 2. arm-none-eabi
We need this installed in order to be able to assemble the small amount of assembly in agb, and to do the final linking.
To assemble the small amount of assembly in agb and to do the final linking, you'll need to install the `arm-none-eabi` binutils.
* On Debian and derivatives (like Ubuntu): `sudo apt install binutils-arm-none-eabi`
* On Arch Linux and derivatives: `pacman -S arm-none-eabi-binutils`
# 3. git
The source code for the game is hosted on github, so you will need git installed.
The source code for the game is hosted on github, so you will need to install git.
* On Debian and derivatives (like Ubuntu): `sudo apt install git`
* On Arch Linux and derivatives: `pacman -S git`
# 4. gbafix
In order to be able to play on real hardware or on some emulators, you may need to install 'gbafix'.
In order to be able to play games made with agb on real hardware or on some emulators, you will need to install 'gbafix'.
The rust implementation can be installed very easily using `cargo install gbafix`.
Make sure that the Cargo bin directory is in your `PATH` as we'll need to use it later.
That is all you need to get started.
That is all you need to get started!
You can now move on to 'building the game'.

10
book/src/setup/mac.md
View file

@ -4,14 +4,14 @@ This guide has been tested on MacOS 13.0.1 on an M1 chip.
# 1. Install a recent version of rust
agb unfortunately relies on a few nightly rust features, so you need to ensure you have that installed.
To use agb, you'll need to use nightly rust since it requires a few nightly features.
Firstly, ensure that you have **rustup** installed which you can do by following the instructions on the [rust website](https://www.rust-lang.org/tools/install)
You can update rustup with `rustup update` if you have already installed it.
If you have already installed rustup, you can update it with `rustup update`.
# 2. Install arm-none-eabi
We need this installed in order to be able to assemble the small amount of assembly in agb, and to do the final linking.
To assemble the small amount of assembly in agb and to do the final linking, you'll need to install the `arm-none-eabi` binutils.
## Install from ARM
@ -43,10 +43,10 @@ After installing to your `/Applications` folder you can add the binary to your p
# 5. Real hardware - gbafix
In order to be able to play on real hardware or on some emulators, you may need to install 'gbafix'.
In order to be able to play games made with agb on real hardware or on some emulators, you will need to install 'gbafix'.
The rust implementation can be installed very easily using `cargo install gbafix`.
Make sure that the Cargo bin directory is in your `PATH` as we'll need to use it later.
That is all you need to get started.
That is all you need to get started!
You can now move on to 'building the game'.