Add some wishful thinking

1 files changed, 78 insertions, 0 deletions

diff --git a/docs/manual.md b/docs/manual.md
new file mode 100644
index 0000000..9489d94
--- /dev/null
+++ b/docs/manual.md
@@ -0,0 +1,78 @@
+# 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.