docs(engine): cleanup and document assets.bridge

docs/pages/3_examples/2_engine/main.md

@@ -6,3 +6,4 @@ The following examples have fully documented tutorials on how to use the
 multiple plugins of the engine:
 
 - @subpage examples-engine-renderer - @copybrief examples-engine-renderer
+- @subpage examples-engine-assets-bridge - @copybrief examples-engine-assets-bridge

engine/samples/assets/bridge/main.cpp

@@ -1,10 +1,3 @@
-/// @file
-/// @brief A sample demonstrating how to create a custom asset bridge.
-///
-/// This sample demonstrates how we can create a custom asset bridge to load assets of a custom
-/// type. In this case, a bridge is created to load text files (.txt) as strings. The bridge is
-/// registered with the asset manager, and then a text file is loaded and printed to the console.
-
 #include <cubos/core/settings.hpp>
 
 #include <cubos/engine/assets/bridges/file.hpp>
@@ -14,8 +7,10 @@ using cubos::core::Settings;
 using cubos::core::ecs::Read;
 using cubos::core::ecs::Write;
 using cubos::core::memory::Stream;
+
 using namespace cubos::engine;
 
+/// [TextBridge]
 /// This bridge inherits from the FileBridge, since it will be loading/saving assets from/to single
 /// files.
 class TextBridge : public FileBridge
@@ -25,7 +20,9 @@ class TextBridge : public FileBridge
         : FileBridge(typeid(std::string))
     {
     }
+    /// [TextBridge]
 
+    /// [TextBridge::loadFromFile]
     bool loadFromFile(Assets& assets, const AnyAsset& handle, Stream& stream) override
     {
         // Dump the file's contents into a string.
@@ -36,7 +33,9 @@ class TextBridge : public FileBridge
         assets.store(handle, std::move(contents));
         return true;
     }
+    /// [TextBridge::loadFromFile]
 
+    /// [TextBridge::saveToFile]
     bool saveToFile(const Assets& assets, const AnyAsset& handle, Stream& stream) override
     {
         // Get the asset's data.
@@ -47,35 +46,44 @@ class TextBridge : public FileBridge
         return true;
     }
 };
+/// [TextBridge::saveToFile]
 
-// We specify the same UUID as the one defined in the `.meta` file.
-static const Asset<std::string> SampleAsset = AnyAsset("6f42ae5a-59d1-5df3-8720-83b8df6dd536");
-
-static void config(Write<Settings> settings)
+static void configSystem(Write<Settings> settings)
 {
     settings->setString("assets.io.path", SAMPLE_ASSETS_FOLDER);
 }
 
-static void bridge(Write<Assets> assets)
+/// [Registering the bridge]
+static void bridgeSystem(Write<Assets> assets)
 {
     // Add a custom bridge to load .txt files.
     assets->registerBridge(".txt", std::make_unique<TextBridge>());
 }
+/// [Registering the bridge]
 
-static void load(Read<Assets> assets)
+/// [Loading the asset]
+// Assets are identified through UUIDs which are defined in their .meta files.
+static const Asset<std::string> SampleAsset = AnyAsset("6f42ae5a-59d1-5df3-8720-83b8df6dd536");
+
+static void loadSystem(Read<Assets> assets)
 {
     // Access the text asset - will be loaded automatically.
     auto text = assets->read(SampleAsset);
     Stream::stdOut.print(*text);
 }
+/// [Loading the asset]
 
 int main()
 {
     auto cubos = Cubos();
+
+    /// [Configuration]
     cubos.addPlugin(assetsPlugin);
-    cubos.startupSystem(config).tagged("cubos.settings");
-    cubos.startupSystem(bridge).tagged("cubos.assets.bridge");
-    cubos.startupSystem(load).tagged("cubos.assets");
+    cubos.startupSystem(bridgeSystem).tagged("cubos.assets.bridge");
+    cubos.startupSystem(loadSystem).tagged("cubos.assets");
+    /// [Configuration]
+
+    cubos.startupSystem(configSystem).tagged("cubos.settings");
     cubos.run();
     return 0;
 }

engine/samples/assets/bridge/page.md

@@ -0,0 +1,59 @@
+# Custom Asset Bridges {#examples-engine-assets-bridge}
+
+@brief Creating your own bridges for the @ref assets-plugin plugin.
+
+This example demonstrates how we can create a custom asset bridge to load
+assets of a given type. More specifically, we'll go through how we can create a
+bridge which loads `std::string`s from text files.
+
+We define our bridge class by inheriting from @ref cubos::engine::FileBridge,
+which offers a simple interface for loading and saving assets from files.
+
+@snippet assets/bridge/main.cpp TextBridge
+
+We pass `typeid(std::string)` to the base class, so that the engine knows which
+type of assets this bridge can load. Then, we'll need to implement both the @ref
+cubos::engine::FileBridge::loadFromFile "loadFromFile" and @ref
+cubos::engine::FileBridge::saveToFile "saveToFile" methods.
+
+In the first method, we receive the @ref cubos::engine::Assets
+"assets manager" where we should store the loaded data, the handle to the asset
+we're loading, and a stream to read the file data from.
+
+@snippet assets/bridge/main.cpp TextBridge::loadFromFile
+
+In the second method, we receive the @ref cubos::engine::Assets
+"assets manager", the handle to the asset we're saving, and a stream to write
+the file data to.
+
+@snippet assets/bridge/main.cpp TextBridge::saveToFile
+
+Now that we have our bridge type, we must register it with the assets manager
+before using it.
+
+@snippet assets/bridge/main.cpp Registering the bridge
+
+After this system runs, any time we load an asset whose path ends with `.txt`,
+the assets manager will use our bridge to load it.
+
+In this sample we have a file `sample.txt` on the `assets/` directory containing the following text:
+
+@include assets/bridge/assets/sample.txt
+
+We also have a file `sample.txt.meta`, which describes the asset for the
+engine. In this case, we only need to specify its UUID, which was generated on
+a [UUID generator website](https://www.uuidgenerator.net/):
+
+@include assets/bridge/assets/sample.txt.meta
+
+Then, we can load it from our code:
+
+@snippet assets/bridge/main.cpp Loading the asset
+
+Some care must be taken when registering bridges or loading assets during the
+startup phase. Systems which add bridges should be tagged with
+`cubos.assets.bridge` so that they run before any assets are loaded.
+Similarly, startup systems which load assets should be tagged with
+`cubos.assets` so that they run after all bridges have been registered.
+
+@snippet assets/bridge/main.cpp Configuration