254 lines
12 KiB

## A high-level object-oriented Gameboy Advance sprite engine library
[![Build Status](](
That's a mouthful - let's break that down:
#### High-level object-oriented
The GBA is an older piece of hardware that's missing an OS. While that is great (`while(1) {}`), it also means there's little software library support. GBA programming boils down to manipulating **memory-mapped IO** pointers. And that's not a lot of fun.
Instead of writing
vu16* paddle = ((volatile tile_block *)0x06000000)[0][1];
for(int i = 0; i < 4 * sizeof(tile_4bpp) / 2; i++) {
paddle[i] = 0x2222;
Wouldn't it be a bit more readable if one could write
auto paddle = SpriteBuilder<Sprite>()
.withData(paddleTile, sizeof(paddleTile))
.withLocation(10, 10)
To leverage C++11's abilities combined with a clear object-oriented approach using abstraction to hide the hexadecimal addresses? That's the objective of this engine.
**Speed and size are NOT the primary concern**! We value clean readable code above speedy algorithms. This is just a proof-of-concept, intricate games with a lot of data will never work because memory limitations. That said, feel free to fork and/or provide patches.
The C++ cross-compiler and the GBA work, but create more metadata than the typical C cross-compiler. Take a look at the file size of the following binaries:
-rwxr-xr-x 1 staff 8320 Jul 25 13:54 main_c.gba
-rwxr-xr-x 1 staff 23328 Jul 22 20:36 main_cpp.gba
-rwxr-xr-x 1 staff 24032 Jul 25 13:55 main_cpp_stl.gba
The C++ ROM is 280% bigger than the C ROM, and if you include <vector>, even 288% bigger - from 8K to 23K!
Emulating big files is not a problem, and running them on the actual hardware is still possible using cartridges like the EZ-FLASH Omega.
#### GBA sprite engine
That means `MODE0`.
#### library
It's compiled as a static library for your convenience. Simply link with the library and include the header path and you're all set. Take a look at the demo's `CMake` files if you're interested.
## Engine features
A portion of [ToncLib]( has been used as a low-level GBA accessor. If you know what you're doing, you can safely use those, headers are in `<libgba-sprite-engine/gba>`.
BIOS methods and Sin/Cos lookup tables are also compiled in Assembly, as `sin_lut`.
Design overview:
Colored blocks are to be implemented in your own game. See below, in section "implementing your game".
### Implementing your own GBA Game
#### Scenes
Scenes contain sprites and backgrounds. You can transition between scenes with `engine->setScene(scene)` or `engine->transitionToScene(scene, effect)`. The main program bootstraps your first scene - from there on it's each scene's responsibility to load another one.
This is the layout of a main function:
int main() {
std::shared_ptr<GBAEngine> engine(new GBAEngine());
auto startScene = new SampleStartScene(engine);
while (true) {
return 0;
That's it!
To create your own scene, subclass `Scene` and implement:
1. `std::vector<Sprite *> sprites()`: the sprites to load into VRAM
2. `std::vector<Background *> backgrounds()`: your (multilayered) backgrounds
3. `void load()`: one-time scene loading (create your objects here)
4. `void tick(u16 keys)`: gets called each engine `update()`
5. set `foregroundPalette` and `backgroundPalette` in your load.
Loading up a scene usually involves creating some sprites with the builder. Don't forget to set the palettes like this: `std::unique_ptr<ForegroundPaletteManager>(new ForegroundPaletteManager(sharedPal, sizeof(sharedPal)));`
The `sprites()` method gets periodically called to check whether something has been added or deleted and updates the VRAM and OAM accordingly. **You don't need to manage anything yourself!** Take a look at demo 3.
A simple fade out scene effect is implemented in demo 1, that converges the palette colors of both palettes to white. It's easy to **create your own effects** by subclassing `SceneEffect`.
![sample fade out](
Sample fade effect, demo 1.
#### Backgrounds
Scrollable backgrounds are present:
Call `scroll()` in your scene update.
![scroll bg](
Sample scrolling background demo 1.
Creating a background:
bg = std::unique_ptr<Background>(new Background(1, background_data, sizeof(background_data), map, sizeof(map)));
Backgrounds work a bit different in VRAM compared to sprites. There are only 4 backgrounds available, and background #4 is taken by the font. Parameter 1 identifies your background used for prioritizing. Remember to use a screen block different than your map data.
If you want to create bigger maps than 32x32, use `MAPLAYOUT_64x64` or similar in the second constructor.
#### Sprites
Conjuring sprites on the screen is a matter of exposing them to the sprites vector in your scene. Create them in your load and set them as a `std::unique_ptr` member variable in your scene so they get cleaned up automatically.
Creating sprites is easy with the `SpriteBuilder`. Specify what kind of sprite you want to make as a template argument (`<Sprite>` or `<AffineSprite>`) and specify your data `.with...()`. Done? Call `build()` to get a copy or `buildPtr()` to get a copy wrapped in a unique pointer.
**Affine sprites can transform** using for example `rotate(angle)` - check out demo 1 or 3 for that.
Sample rotation demo 3.
**Sprite animation is built-in**! Just feed your sprite data to the builder and use `.withAnimated(amountOfFrames, frameDelay)`. Remember to position each frame in one column in the image itself (vertically). Like this:
![lama gif example](
Useful sprite methods:
* `animate()`, `animateToFrame(x)` or `stopAnimating()`
* `flipVertically(bool)` or `flipHorizontally(bool)`
* `setVelocity(dx, dy)` (auto-updates) or `moveTo(x, y)`
* `setWithinBounds(bool)` automatically keeps your sprite within the GBA resolution bounds
* `collidesWith(otherSprite)` or `isOffScreen()`
* Various getters like `getWidth()` etc
![stay within bounds](
The paddle auto-stays within bounds.
Each sprite has own raw data, so there's no shared sprite image (for the better). The palette of course is shared, so think about that when exporting with a tool like [grit]( or [png2gba]( Grit has flags to export a shared palette:
> grit pic1.png pic2.png kul.png -ftc -pS -gB8 -O shared.c
Consult the [Grit list of cmdline options]( for more information.
Extracting a tilemap from a big image to create a splash-like intro screen can be done using these options:
> grit splashimage.png -gt -gB8 -mRtpf -mLs -ftc
It will export:
1. A tileset. Your data, to be injected into background VRAM char blocks.
2. A tilemap. Your metadata, to be injected into the next free background VRAM screen block.
3. A palette. Your one and only background palette.
#### Sound
The engine supports **sounds** and **background music** using GBA's Active Sound channel A and B. It's a simple implementation meaning no mixing in either channels (but A and B are mixed).
Call `engine->enqueueMusic(data, sizeof(data));` as a repeating music or `enqueueSound()` as a one-timer. If some sound is already playing, it will **not be played**. Background music auto-repeats when done. See demo 1.
Sound can to be converted from a RAW Signed 8-bit PCM using [raw2gba]( Record something with for example [Audacity]( and choose file -> export -> export audio... to change the format. Like sprite raw data, it'll be converted into a C header that you can feed to the methods above.
#### Text
![default font](
There's a **default font embedded into the engine** using the `TextStream::instance()` static instance. It takes up background #4 and claims the last background palette bank so watch out with that!
Useful text manipulation:
* `setText(txt, row, col)`
* `<< text` or `<< int` etc: append to text stream for debugging purposes.
* `setFontColor(COLOR)`: changes default color palette (white).
* `setFontStyle(const void* data, int size)` if you prefer your own font face.
Changing the font style assumes a tile width of 32 and the same symbol indexes! It also resets the font color and map so call this before doing anything else.
#### Utilities
There's a game `Timer` class available using `engine->getTimer()`. It counts miliseconds, seconds, minutes and hours.
Do not forget this is an estimate as modulo and divide operations are expensive.
Each VBlank occurs every 280806 cycles (`CYCLES_PER_BLANK`), each cycle is 59.59ns
So, each VBlank occurs every 16.73322954 miliseconds or 16733.22954 microseconds.
The microseconds after the comma are rounded so irregularities are bound to occur after hours of timing..
#### Error logging
The text stream is also used if something goes wrong, there's a macro `failure_gba(WHOOPS)` that prints file, line, method and "exception" message to the text stream background.
### Unit Testing GBA games
The engine comes with (some) [Google Test]( test cases to show you how separate classes can effectively be unit tested. I had to stub out some ARM-specific ToncLib includes, that's why the `add_definitions(-DCODE_COMPILED_AS_PART_OF_TEST)` CMake statement is there. Gtest compiles library source with `g++` and **not with the cross-compiler**!
### Compiling everything
#### Prerequirements
1. cmake 3.12.x or higher: the cmake linker toolchain set contains a bug in .11
2. A compiled Google Test 1.8.x or higher with `$GTEST_DIR` env. var
3. The [DevkitPro toolchain]( installed in your `$PATH`
4. The [mGBA emulator](
#### Compiling with cmake
The project has been developed with CLion. The `.idea` dir is there for you to get started. The project can be imported as a cmake project.
As such, `CMake` was an easy choice. Use the following commands to build everything, including the demos:
1. `mkdir cmake-build-debug && cd cmake-build-debug`
2. `cmake ./../`
3. `make`
The demos will be in `cmake-build-debug/demos/demoname.gba`.
Things you might need to change in `CMakeLists.txt` files:
1. gba-sprite-engine assumes your GBA cross-compiler is in your `$PATH`. If it's not, add an absolute path to `SET(CMAKE_C_COMPILER arm-none-eabi-gcc)` etc.
2. gba-sprite-engine assumes your Google Test Library is compiled and in your `$GTEST_DIR` path. If not, add an absolute path to: `SET(GTEST_LIBRARY "/Users/jefklak/CLionProjects/googletest-release-1.8.0/googletest")`. The linker searches for 'ligbtest.a' and 'liggtest_main.a' - if you're on Linux it'll likely be a .so extension.
3. Some Linux distributions seem to miss the default link to `pthread` that should be added manually in that case. When you see errors like "undefined reference to 'pthread_setspecific'" while linking Google Test, change target_link_libraries in the CMakeLists.txt file of the subdir test to: `target_link_libraries(unittest ${GTEST_LIBRARY}/build/libgtest.a ${GTEST_LIBRARY}/build/libgtest_main.a pthread)`
##### Building using Windows
Tested and working under Windows 10. Use [MinGW]( or Cygwin, and add the `-G "Unix Makefiles"` option to your `cmake ./../` command.
Cygwin is also a possibility, but combined with CLion the Unix and Windows path structures will clash. If using an IDE like CLion, resort to using MinGW.
#### Running unit tests
After compiling, execute the `unittest` main executable:
And hope for exit code 0!