jasper/developer-handbook.md

# Olympic Developer Handbook

## About

The purpose of the Developer Handbook is similar to that of the README.
The README should be viewed as a prerequisite to the Developer Handbook.
The README should provide information needed to build the project, which might
be used by an advanced user or a person trying to build and package the
project.
The Developer Handbook should focus on information needed by a developer
working on the project.

## Project Structure

### Overview

All components have a platform indicator next to them:

    (PG) - PC, GBA
    (-G) - GBA
    (P-) - PC

* Nostalgia
  * modules
    * core - graphics system for Nostalgia (PG)
      * gba - GBA implementation (PG)
      * opengl - OpenGL implementation (P-)
      * studio - studio plugin for core (P-)
      * keel - keel plugin for core (PG)
    * scene - defines & processes map data (PG)
      * studio - studio plugin for scene (P-)
      * keel - keel plugin for scene (PG)
  * player - plays the games (PG)
  * studio - makes the games (P-)
  * tools - command line tools (P-)
    * pack - packs a studio project directory into an OxFS file (P-)
* Olympic
    * Applib - Library for creating apps as libraries that injects Keel and Studio modules
    * Keel - asset management system (PG)
    * Studio - where most of the studio code lives as library (P-)
        * applib - used for per project studio executables
        * modlib - used for studio modules to interact with studio
    * Turbine - platform abstraction and user I/O (PG)
        * gba - GBA implementation (PG)
        * glfw - GLFW implementation (P-)
* deps - project dependencies
  * Ox - Library of things useful for portable bare metal and userland code.
    Not really that external... (PG)
  * GlUtils - OpenGL helpers (P-)
  * teagba - GBA assembly startup code (mostly pulled from devkitPro under MPL
	          2.0), and custom GBA hardware interop code (-G)

Most GBA code is built on PC because it is small and helps to work on both
projects with the same CMake build dir, but GBA code is never linked with any
executables on PC.

## Platform Notes

### GBA

The GBA has two major resources for learning about its hardware:

* [Tonc](https://www.coranac.com/tonc/text/toc.htm) - This is basically a short
  book on the GBA and low level development.
* [GBATEK](https://rust-console.github.io/gbatek-gbaonly/) - This is a more
  concise resource that mostly tells about memory ranges and registers.

#### Graphics

* Background Palette: 256 colors
* Sprite Palette:     256 colors

## Code Base Conventions

### Formatting

* Indentation is done with tabs.
* Alignment is done with spaces.
* Opening brackets go on the same line as the thing they are opening for (if,
  while, for, try, catch, function, etc.)
* No space between function parentheses and arguments.
* Spaces between arithmetic/bitwise/logical/assignment operands and operators.
* Pointer and reference designators should be bound to the identifier name and
  not the type, unless there is not identifier name, in which case it should be
  bound to the type.
* East const

### Write C++, Not C

On the surface, it seems like C++ changes the way we do things from C for no
reason, but there are reasons for many of these duplications of functionality.
The C++ language designers aren't stupid. Question them, but don't ignore them.

#### Casting

Do not use C-style casts.
C++ casts are more readable, and more explicit about the type of cast being
used.
Do not use ```dynamic_cast``` in code building for the GBA, as RTTI is disabled
in GBA builds.

#### Library Usage

C++ libraries should generally be preferred to C libraries.
C libraries are allowed, but pay extra attention.

This example from nostalgia::core demonstrates the type of problems that can
arise from idiomatically mixed code.

```cpp
uint8_t *loadRom(const char *path) {
	auto file = fopen(path, "r");
	if (file) {
		fseek(file, 0, SEEK_END);
		const auto size = ftell(file);
		rewind(file);
		// new can technically throw, though this project considers out-of-memory
		// to be unrecoverable
		auto buff = new uint8_t[size];
		fread(buff, size, 1, file);
		fclose(file);
		return buff;
	} else {
		return nullptr;
	}
}
```

In practice, that particular example is not something we really care about
here, but it does demonstrate that problems can arise when mixing what might be
perceived as cool old-school C-style code with lame seemingly over-complicated
C++-style code.

Here is another more concrete example observed in another project:
```cpp
int main() {
	// using malloc does not call the constructor
	std::vector<int> *list = (std::vector<int>*) malloc(sizeof(std::vector<int>));
	doStuff(list);
	// free does not call the destructor, which causes memory leak for array
	// inside list
	free(list);
	return 0;
}
```

The code base where this was observed actually got away with this for the most
part, as the std::vector implementation used evidently waited until the
internal array was needed before initializing and the memory was zeroed out
because the allocation occurred early in the program's execution.
While the std::vector implementation in question worked with this code and the
memory leak is not noticeable because the std::vector was meant to exist for
the entire life of the process, other classes likely will not get away with it
due to more substantial constructors and more frequent instantiations of the
classes in question.

## Project Systems

Olympic builds on Ox as its standard-ish library.
Please read the [Ox documentation](deps/ox/ox-docs.md).
The Ox way of doing things is the Olympic way of doing things.

### Error Handling

Instead of throwing exceptions, generally try to use
[ox::Errors](deps/ox/ox-docs.md#error-handling) for error reporting,
but exceptions may be used where they make sense.

Exceptions should generally just use ```OxException```, which is bascially an
exception form of ```ox::Error```.

### File I/O

All engine file I/O should go through Keel, which should go through
```ox::FileSystem```.
Similarly, all studio file I/O should go thorough
```nostalgia::studio::Project```, which should go through ```ox::FileSystem```.

```ox::FileSystem``` abstracts away differences between conventional storage
devices and ROM.

Olympic files are generally just [Claw objects](deps/ox/ox-docs.md#serialization).

#### Keel

Keel, as its name implies, is a foundational component of Olympic.
Keel is the asset management system.

Keel provides for the following needs:

* Type conversion
* Asset bundling
* Asset loading (including flyweighting on PC and preloading to ROM on the GBA)