From 59c63182ab0a2b66cd152fea4677760a2ecd86ca Mon Sep 17 00:00:00 2001
From: Ricardo Antunes <me@riscadoa.com>
Date: Thu, 1 Dec 2022 15:30:41 +0000
Subject: [PATCH] Add asset manager docs

---
 .../2_engine/2_plugins/3_assets.md            | 87 ++++++++++++++++++-
 1 file changed, 86 insertions(+), 1 deletion(-)

diff --git a/docs/1_structure/2_engine/2_plugins/3_assets.md b/docs/1_structure/2_engine/2_plugins/3_assets.md
index 859da214f..4ce960e75 100644
--- a/docs/1_structure/2_engine/2_plugins/3_assets.md
+++ b/docs/1_structure/2_engine/2_plugins/3_assets.md
@@ -1,3 +1,88 @@
 # Assets {#engine-plugins-assets}
 
-TODO
+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.
+};
+```
+
+