# Manual

This document serves as a user-manual to setup & configure and use this project.

_This is not a description of the current state of this project, but rather
where I want it to be._


## Configuring

There's 3 ways I'd recommend compiling and linking with this project. Any other
configurations of these 3 are officially unsupported (everything is officially
unsupported when you're pre-release haha). "Dynamic libraries" refers to the
shared object and dynamically linked libraries, file formats, on linux and
windows respectively.

1. Build each module and state as separate dynamic libraries.
2. Build modules as a single dynamic library, states as separate dynamic
   libraries. (default in DEBUG builds)
3. Build and link everything statically. (default in RELEASE builds)


### Building everything as dynamic libraries

This option is generally intended for engine development, as it allows
hot-reloading each type of module. This option could be used to allow modders to
implement alternative implementations of modules and making the engine
dynamically load them.


### Building states dynamically

States are independant states of your project, such as a main menu screen or
the running in-game state. This configuration option allows you to hot-reload
your game, making development easier.

This is the default in **debug** builds, unless configured otherwise.


### Building a static project

Build and link modules and states statically. This ensures fewer moving parts
and makes sure that your binary can run as a stand-alone binary -- unless you
do not embed resources. This also inlines the standard library and everything
else used for linking, causing a much larger filesize.

This is the default in **release** builds, unless configured otherwise.

## Providing an entrypoint

It is recommended to use the DAW entrypoint by linking against <TODO>. You can
provide one yourself if you need to run other setup and customization before
initializing and running the engine.

```C
int main(int argc, char* argv[]) {
    Configuration* c = engine_setup(argc, argv);
    Instance* i = engine_init_conf(c, "My Game", 640, 480, 0, 0);
    return engine_run(i, 0, NULL);
}
```


## API design

The user-directed API should be designed around the calling convention
`i32 engine_fn(instance*, args...)`. The idea is that each function _might_
change the state (engine "instance"), which is modified in-place. "instance"
should contain everything necessary for the engine -- no global variables.

"args" are specific to the engine-function itself. Errors are returned from the
functions, and needs to be casted to the `EngineError_t` type.

Errors are printed out anywhere, unless the engine is configured to do so
(reporting to stdout is default in debug builds).

The API functions are exposed in a single header file. This differs from how
modules are defined, in terms of API and implementation.