Merge pull request #134 from gwilymk/book

Start writing the agb book

book/.gitignore

@@ -0,0 +1 @@
+book

book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Gwilym Kuiper", "Corwin Kuiper"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The agb book"

book/src/SUMMARY.md

@@ -0,0 +1,10 @@
+# Summary
+
+- [Introduction](./introduction/introduction.md)
+- [The Game Boy Advance hardware](./hardware/hardware.md)
+- [Running an example](./setup/getting_started.md)
+    - [Environment setup](./setup/setup.md)
+        - [Linux setup](./setup/linux.md)
+        - [Windows setup]()
+        - [Mac OS setup]()
+    - [Building the game](./setup/building.md)

book/src/hardware/hardware.md

@@ -0,0 +1,33 @@
+# 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.
+
+# 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.
+
+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!
+
+# Capabilities of the hardware
+
+The GBA is fundamentally a 2D system, and a lot of the hardware accelerated graphics is designed to support this.
+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).
+
+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/).

book/src/introduction/introduction.md

@@ -0,0 +1,28 @@
+# 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.
+
+# 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.
+
+# 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.
+
+# Helpful links
+
+* [agb's GitHub](https://github.com/agbrs/agb) all development happens here
+* [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.

book/src/setup/building.md

@@ -0,0 +1,34 @@
+# Building the game
+
+By the end of this section, you should be able to build and run an example game made using agb!
+**This section is optional.**
+If you just want to get straight into building your own games, you don't need to do this.
+However, we recommended doing this section to prove that your setup works.
+
+# 1. Get the source code
+
+The source code can be fetched using `git clone https://github.com/agbrs/joinedtogether.git`.
+
+# 2. Build the game
+
+Build a copy of the game using `cargo build --release`.
+This could take quite a while, but eventually you'll end up with a copy of the game in `target/thumbv4t-none-eabi/release/joinedtogether` or `target/thumbv4t-none-eabi/release/joinedtogether.elf` depending on platform.
+
+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.
+
+```sh
+arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/joinedtogether joinedtogether.gba
+gbafix joinedtogether.gba
+```
+
+or
+
+```sh
+arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/joinedtogether.elf joinedtogether.gba
+gbafix joinedtogether.gba
+```
+
+And then load the resulting file in your emulator of choice.
+That's all there is to it!
+
+If you have `mgba-qt` in your path, then you can launch the game directly using `cargo run --release`

book/src/setup/getting_started.md

@@ -0,0 +1,11 @@
+# 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'.
+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.
+However, at this stage, it is much easier to play on an emulator.
+agb is guaranteed to work well using [mgba](https://mgba.io/), but other emulators will also work.
+
+Note that some emulators will require a special 'fixed' gba ROM file.
+See the later steps in this section for how to do this.

book/src/setup/linux.md

@@ -0,0 +1,34 @@
+# Linux setup
+
+This guide has been tested on Ubuntu, Arch Linux and Raspberry Pi OS running on a raspberry pi 4.
+
+# 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.
+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.
+
+# 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.
+
+* On Debian and derivatives (like Ubuntu): `sudo apt install binutils-arm-non-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.
+
+* 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'.
+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.
+You can now move on to 'building the game'.

book/src/setup/setup.md

@@ -0,0 +1,6 @@
+# Environment setup
+
+Environment setup will depend on the platform you are using.
+agb's requirements are [rust nightly](https://www.rust-lang.org/) edition and the gnu binutils for `arm-none-eabi`.
+
+See the subpages here for platform specific setup guides.