docs(engine): document Scene sample

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

@@ -7,3 +7,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

engine/samples/scene/main.cpp

@@ -15,19 +15,24 @@ using cubos::core::ecs::Write;
 
 using namespace cubos::engine;
 
+/// [Setting the asset]
 static const Asset<Scene> SceneAsset = AnyAsset("f0d86ba8-5f34-440f-a180-d9d12c8e8b91");
+/// [Setting the asset]
 
 static void settings(Write<Settings> settings)
 {
     settings->setString("assets.io.path", SAMPLE_ASSETS_FOLDER);
 }
 
+/// [Spawning the scene]
 static void spawnScene(Commands commands, Read<Assets> assets)
 {
     auto sceneRead = assets->read(SceneAsset);
     commands.spawn(sceneRead->blueprint);
 }
+/// [Spawning the scene]
 
+/// [Displaying the scene]
 static void printStuff(Read<World> world)
 {
     using cubos::core::data::Context;
@@ -44,18 +49,25 @@ static void printStuff(Read<World> world)
         Stream::stdOut.put('\n');
     }
 }
+/// [Displaying the scene]
 
 int main(int argc, char** argv)
 {
     Cubos cubos(argc, argv);
 
+    /// [Adding the plugin]
     cubos.addPlugin(scenePlugin);
+    /// [Adding the plugin]
 
     cubos.addComponent<Num>();
     cubos.addComponent<Parent>();
 
     cubos.startupSystem(settings).tagged("cubos.settings");
+
+    /// [Adding the system]
     cubos.startupSystem(spawnScene).tagged("spawn").tagged("cubos.assets");
+    /// [Adding the system]
+
     cubos.startupSystem(printStuff).after("spawn");
     cubos.run();
 }

engine/samples/scene/page.md

@@ -0,0 +1,64 @@
+# Scene {#examples-engine-scene}
+
+@brief Using the @ref scene-plugin plugin.
+
+This example shows how the @ref scene-plugin plugin can be used to spawn a
+scene from an asset.
+
+The plugin function is included from the @ref engine/scene/plugin.hpp header.
+You may need to include other headers, depending on what you want to access.
+
+@snippet scene/main.cpp Adding the plugin
+
+Let's start by taking a look at a scene file.
+@include assets/sub.cubos
+
+A scene file has two parts: the `imports` and the `entities`.
+Each entity is a list of components, with their values set.
+So in this file we have two entities, one named `root` and the other named `child`.
+`root` has a single component, `num`, with a value of 1.
+`child` has two components, a `parent` and a `num`.
+In this sample, `num` is used so we can later identify the entities.
+
+@warning Make sure all the components in a scene file are added to CUBOS., or it will raise an error.
+
+Let's look at a different scene file now, to talk about `imports`, which is the way we can put subscenes within other scenes.
+
+@include assets/main.cubos
+
+This file imports the asset with id `cd007ba2-ee0d-44fd-bf36-85c829dbe66f`, which is the scene we looked at in the previous file.
+It gives this scene the deisgnation of `sub1`.
+It then imports the very same scene again, but this time with the name `sub2` instead.
+This allows us to have two instances of the same subscene.
+
+Under `entities`, we can reference these labels to change some particular values of the subscenes.
+For example, by referencing `sub1.root` we are making local changes to the `root` entity of that instance of the subscene.
+The result of the changes we make to both `sub1.root` and `sub2.root` is that the parent of these entities will be set to be the `main` entity.
+
+Now that we have our scene file, let's get CUBOS. to load it.
+The first thing we're going to need is a reference to the scene asset. 
+For the purposes of this sample we can simply use an hardcoded reference to the asset.
+
+@snippet scene/main.cpp Setting the asset
+
+Then we'll need a system that spawns that scene.
+To do this we simply get the Scene object from the asset, and then spawn its entities.
+`commands.spawn` will create in the world a copy of every entitiy defined in the scene.
+It won't remove the entities already there, so if you want to close a scene, you'll have to do it yourself.
+
+@snippet scene/main.cpp Spawning the scene
+
+And now we'll have this system run at startup.
+It is not required, you can spawn scenes at any point in the execution of the program,
+but for the purpose of demonstrating the functionality, spawning once at startup is enough.
+
+@snippet scene/main.cpp Adding the system
+
+Finally, let's print the loaded scene, to check that everything is working correctly.
+
+@snippet scene/main.cpp Displaying the scene
+
+If you run the sample, it should give you a list that has:
+- an entity with `num` set to 0, with no parent. This is the `main` entity.
+- two entities with `num` set to 1, with same parent, who has `num` set to 0. These are the `root` entities of each instance of the subscene.
+- two entities with `num` set to 2, with different parents, but both of them having `num` set to 1.  These are the `child` entities of each instance of the subscene.