docs(engine): add assets.saving

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

@@ -8,5 +8,4 @@ multiple plugins of the engine:
 - @subpage examples-engine-settings - @copybrief examples-engine-settings
 - @subpage examples-engine-renderer - @copybrief examples-engine-renderer
 - @subpage examples-engine-scene - @copybrief examples-engine-scene
-- @subpage examples-engine-assets-bridge - @copybrief examples-engine-assets-bridge
-- @subpage examples-engine-assets-json - @copybrief examples-engine-assets-json
+- @subpage examples-engine-assets - @copybrief examples-engine-assets

engine/samples/CMakeLists.txt

@@ -40,8 +40,9 @@ make_sample(DIR "settings")
 make_sample(DIR "events")
 make_sample(DIR "systems")
 make_sample(DIR "input" ASSETS)
-make_sample(DIR "assets/json" ASSETS)
 make_sample(DIR "assets/bridge" ASSETS)
+make_sample(DIR "assets/json" ASSETS)
+make_sample(DIR "assets/saving" ASSETS)
 make_sample(DIR "renderer")
 make_sample(DIR "collisions" COMPONENTS)
 make_sample(DIR "scene" COMPONENTS ASSETS)

engine/samples/assets/page.md

@@ -0,0 +1,7 @@
+# Assets {#examples-engine-assets}
+
+@brief How to use the @ref assets-plugin plugin.
+
+- @subpage examples-engine-assets-bridge - @copybrief examples-engine-assets-bridge
+- @subpage examples-engine-assets-json - @copybrief examples-engine-assets-json
+- @subpage examples-engine-assets-saving - @copybrief examples-engine-assets-saving

engine/samples/assets/saving/main.cpp

@@ -0,0 +1,86 @@
+#include <cubos/core/data/fs/file_system.hpp>
+#include <cubos/core/settings.hpp>
+
+#include <cubos/engine/assets/bridges/json.hpp>
+#include <cubos/engine/assets/plugin.hpp>
+
+using cubos::core::Settings;
+using cubos::core::data::Deserializer;
+using cubos::core::data::FileSystem;
+using cubos::core::data::Serializer;
+using cubos::core::ecs::Read;
+using cubos::core::ecs::Write;
+using cubos::core::memory::Stream;
+using namespace cubos::engine;
+
+/// [Asset type]
+struct IntegerAsset
+{
+    int value;
+};
+/// [Asset type]
+
+template <>
+void cubos::core::data::serialize<IntegerAsset>(Serializer& ser, const IntegerAsset& obj, const char* name)
+{
+    ser.beginObject(name);
+    ser.write(obj.value, "value");
+    ser.endObject();
+}
+
+template <>
+void cubos::core::data::deserialize<IntegerAsset>(Deserializer& des, IntegerAsset& obj)
+{
+    des.beginObject();
+    des.read(obj.value);
+    des.endObject();
+}
+
+/// [Setting]
+static void configSystem(Write<Settings> settings)
+{
+    // If we want to save assets, we must set this to false.
+    settings->setBool("assets.io.readOnly", false);
+    /// [Setting]
+
+    settings->setString("assets.io.path", SAMPLE_ASSETS_FOLDER);
+}
+
+static void bridgeSystem(Write<Assets> assets)
+{
+    assets->registerBridge(".int", std::make_unique<JSONBridge<IntegerAsset>>());
+}
+
+/// [Create a new asset]
+static void saveSystem(Write<Assets> assets)
+{
+    // Create a new asset (with a random UUID).
+    auto handle = assets->create(IntegerAsset{1337});
+    /// [Create a new asset]
+
+    /// [Save the asset]
+    assets->writeMeta(handle)->set("path", "/assets/sample/sample.int");
+    assets->save(handle);
+    /// [Save the asset]
+
+    // Wait for input before exiting.
+    Stream::stdOut.print("You can now check the contents of the file!\nPress enter to exit...");
+    Stream::stdIn.get();
+
+    // Cleanup the created asset.
+    FileSystem::destroy("/assets/sample");
+}
+
+int main()
+{
+    Cubos cubos{};
+
+    /// [Configure]
+    cubos.addPlugin(assetsPlugin);
+    cubos.startupSystem(saveSystem).tagged("cubos.assets");
+    /// [Configure]
+
+    cubos.startupSystem(configSystem).tagged("cubos.settings");
+    cubos.startupSystem(bridgeSystem).tagged("cubos.assets.bridge");
+    cubos.run();
+}

engine/samples/assets/saving/page.md

@@ -0,0 +1,38 @@
+# Creating and Saving {#examples-engine-assets-saving}
+
+@brief Creating and saving assets.
+
+This example demonstrates how a new asset be created programatically and how it
+can be saved to the assets directory, which is useful while working on tools
+such as **TESSERATOS.**
+
+Before we go any further, if we want to save assets to the filesystem, we must
+allow assets to be modified. This is done through the following setting:
+
+@snippet assets/saving/main.cpp Setting
+
+We'll use the following asset type as an example, with a @ref
+cubos::engine::JSONBridge "JSONBridge" registered for it with the extension
+`.int`.
+
+@snippet assets/saving/main.cpp Asset type
+
+First, we'll create an asset of this type:
+
+@snippet assets/saving/main.cpp Create a new asset
+
+Then, we'll assign it a path and save it. Its important that the path ends with
+the correct extension, so that @ref cubos::engine::Assets "Assets" knows which
+bridge to use when loading it.
+
+@snippet assets/saving/main.cpp Save the asset
+
+With this, the files `sample/sample.int` and `sample/sample.int.meta` should
+have appeared on the `assets/` directory. The `.meta` file contains the UUID of
+the asset, which is used by the engine to identify it.
+
+Finally, the engine is configured the following way:
+
+@snippet assets/saving/main.cpp Configure
+
+Try running the sample yourself to see the files being created!