Add engine structure docs

docs/1_structure/2_engine/1_cubos.md

@@ -0,0 +1,23 @@
+# Cubos {#engine-cubos}
+
+Game development revolves around the \ref cubos::engine::Cubos "Cubos" class.
+It is used to configure and initialize the engine and the game, and it runs the
+main update loop.
+
+\ref cubos::engine::Cubos "Cubos" by itself doesn't do much: it is as barebones
+as possible. Internally, it uses two \ref cubos::core::ecs::Dispatcher
+"core::ecs::Dispatcher" objects, one for the startup phase and one for the main
+loop. It also keeps a \ref cubos::core::ecs::World "core::ecs::World" object,
+on which the whole engine and game logic is built.
+
+There are only two resources that are added to the world by default: the
+\ref cubos::engine::ShouldQuit "ShouldQuit" resource and the
+\ref cubos::core::Settings "core::Settings" resource. The first one is used to
+signal the main loop to stop, and the second one is used to store the settings
+of the engine and the game.
+
+Custom resource types can be added using the \ref
+cubos::engine::Cubos::addResource "Cubos::addResource" method.
+
+No component types are added by default. To register your own, use the \ref
+cubos::engine::Cubos::addComponent "Cubos::addComponent" method.

docs/1_structure/2_engine/2_plugins/1_env_settings.md

@@ -0,0 +1,16 @@
+# Environment Settings {#engine-plugins-env-settings}
+
+The \ref cubos::engine::plugins::env_settings "env_settings" plugin adds a
+startup system which runs on the stage `"env-settings"`. This system reads
+the environment argument variables and adds any settings it finds to the \ref
+cubos::core::Settings "core::Settings" resource.
+
+The state is by default put as the first stage, so it will be executed before
+any other startup systems.
+
+Settings are read as key-value pairs, where the key is the name of the setting
+and the value is the value of the setting. Example input:
+
+```bash
+    ./mygame renderer.ssao=true window.vsync=true window.width=1920 window.height=1080
+```

docs/1_structure/2_engine/2_plugins/2_file_settings.md

@@ -0,0 +1,36 @@
+# File Settings {#engine-plugins-file-settings}
+
+The \ref cubos::engine::plugins::file_settings "file_settings" plugin adds a
+startup system which runs on the stage `"file-settings"`. This system reads the
+settings file specified by the `settings.path` setting (default:
+`"settings.json"`), and adds any settings it finds to the \ref
+cubos::core::Settings "core::Settings" resource.
+
+The `"file-settings"` stage is by default put after the `"env-settings"` stage,
+or, if the `"env-settings"` stage is not present, as the first stage.
+
+Settings are stored as a *JSON* object, where the keys are the names of the
+settings and the values are the values of the settings. Example input:
+
+```json
+{
+    "renderer": {
+        "ssao": true
+    },
+    "window": {
+        "vsync": true,
+        "width": 1920,
+        "height": 1080
+    }
+}
+```
+
+Which is equivalent to:
+```json
+{
+    "renderer.ssao": true,
+    "window.vsync": true,
+    "window.width": 1920,
+    "window.height": 1080
+}
+```

docs/1_structure/2_engine/2_plugins/3_assets.md

@@ -0,0 +1,88 @@
+# Assets {#engine-plugins-assets}
+
+The \ref cubos::engine::plugins::assets "assets" plugin adds the \ref
+cubos::engine::data::AssetManager "AssetManager" resource, which is manages
+loading and unloading of assets.
+
+It also adds a startup system to the stage `"import-meta"`. This system calls
+the \ref cubos::engine::data::AssetManager::importMeta
+"AssetManager::importMeta" function on the virtual file specified by the
+setting `assets.path` (default: `"/assets"`).
+
+## Meta files
+
+Meta files are files which describe and define what assets are available.
+You can have multiple meta files on your project. Meta files are expected to be
+in the JSON format.
+
+An example meta file:
+```json
+{
+    {
+        "palette": {
+            "type": "Palette",
+            "usage": "Static",
+            "params": {
+                "path": "/assets/main.pal"
+            }
+        },
+        "car": {
+            "type": "Grid",
+            "usage": "Static",
+            "params": {
+                "path": "/assets/car.grd"
+            }
+        }
+    }
+}
+```
+
+Each entry has its identifier, and specifies the type of the asset, its usage
+mode and the parameters to be passed to the asset loader.
+
+## Loading assets
+
+Assets are loaded using the \ref cubos::engine::data::AssetManager::load
+"AssetManager::load" function. This function takes the identifier of the asset
+and returns a \ref cubos::engine::data::Asset "Asset" object. This object as
+a handle to the asset, which guarantees that the asset will not be unloaded
+while the handle is alive.
+
+### Usage modes
+
+Assets can be in one of two usage modes: `Static` or `Dynamic`.
+`Static` assets are never unloaded, while `Dynamic` assets are unloaded when
+they are not used for a while.
+
+## Storing assets
+
+Let's say you have generated a grid of voxels procedurally and you want to get
+an asset handle to it. You can use the \ref
+cubos::engine::data::AssetManager::store "AssetManager::store" method to store
+the data in the asset manager, which then returns an \ref
+cubos::engine::data::Asset "Asset" pointing to the data.
+
+## Defining asset types
+
+If you want to define your own asset types, you can do so by adding a
+`static constexpr const char* TypeName` member to your type, with the name you
+want to use to identify the asset type. You also need to create a child class
+of the \ref cubos::engine::data::Loader "Loader" class, which will be used to
+load your asset. Finally, add `using Loader = MyLoader;` to your asset type to
+tell the asset manager which loader to use.
+
+For example, the \ref cubos::engine::data::Grid "Grid" asset type is defined
+like this:
+
+```cpp
+struct Grid
+{
+    static constexpr const char* TypeName = "Grid";
+    using Loader = impl::GridLoader;
+
+    core::gl::Grid grid;           ///< Raw grid data.
+    gl::RendererGrid rendererGrid; ///< Handle of the grid uploaded to the GPU.
+};
+```
+
+

docs/1_structure/2_engine/2_plugins/4_window.md

@@ -0,0 +1,10 @@
+# Window {#engine-plugins-window}
+
+The \ref cubos::engine::plugins::window "window" plugin adds the \ref
+cubos::core::io::Window "core::io::Window" resource, and a startup system on
+the stage `"window"` which initializes it, by opening the window and creating a
+\ref cubos::core::gl::RenderDevice "core::gl::RenderDevice" for it.
+
+The window is created using the settings `window.width`, `window.height`,
+`window.title` and `window.vsync`. The default values are `800`, `600`,
+`"Cubos Game"` and `true`, respectively.

docs/1_structure/2_engine/2_plugins/5_renderer.md

@@ -0,0 +1,3 @@
+# Renderer {#engine-plugins-renderer}
+
+TODO

docs/1_structure/2_engine/2_plugins/6_collisions.md

@@ -0,0 +1,3 @@
+# Collisions {#engine-plugins-collisions}
+
+TODO

docs/1_structure/2_engine/2_plugins/main.md

@@ -0,0 +1,22 @@
+##Plugins {#engine-plugins}
+
+The \ref cubos::engine::Cubos "Cubos" class is designed to be extended using
+plugins. Plugins are simple functions which receive a reference to the \ref
+cubos::engine::Cubos "Cubos" object and can add resources, components, systems
+and even other plugins to it.
+
+If a plugin is added twice, it will only be called once, so when you write
+a plugin, its safe to add any plugins you depend on, without worrying about
+the user already having added them.
+
+Here is a list of the plugins that are included in the engine:
+- \subpage engine-plugins-env-settings - adds support for loading settings from
+  environment variables.
+- \subpage engine-plugins-file-settings - adds support for loading settings
+  from files.
+- \subpage engine-plugins-assets - adds support for loading assets.
+- \subpage engine-plugins-window - opens a window and provides input events.
+- \subpage engine-plugins-renderer - provides 3D rendering components and
+  systems.
+- \subpage engine-plugins-collisions - provides 3D collision detection
+  components and systems.

docs/1_structure/2_engine/main.md

@@ -0,0 +1,12 @@
+# Engine {#engine}
+
+The `engine` library includes the high-level functionality of the game engine.
+It is built on top of the `core` library and provides the
+\ref cubos::engine::Cubos "Cubos" class, which is the entry point of the
+engine. It also includes plugins for use with this class, such as the
+\ref cubos::engine::plugins::renderer "plugins::renderer" and the
+\ref cubos::engine::plugins::collisions "plugins::collisions".
+
+This section of the documentation is split into:
+- \subpage engine-cubos - the main class of the engine;
+- \subpage engine-plugins - list of plugins included in the engine;