docs(engine): document and cleanup Hello Cubos sample

.githooks/pre-commit

@@ -1,3 +1,4 @@
+#!/bin/sh
 for file in $(git diff --cached --name-only | grep -E '.*\.(c|cpp|h|hpp)$')
 do
         clang-format -i $file

.github/workflows/clang-format-check.yml

@@ -22,5 +22,8 @@ jobs:
     - name: Check
       run: |
         for file in $(git diff -U0 --name-only HEAD^ | grep -E '.*\.(c|cpp|h|hpp)$'); do
+          if [ ! -f $file ]; then
+            continue
+          fi
           clang-format --dry-run -Werror $file || exit 1
         done

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

@@ -5,6 +5,7 @@
 The following examples have fully documented tutorials on how to use the
 multiple plugins of the engine:
 
+- @subpage examples-engine-hello-cubos - @copybrief examples-engine-hello-cubos
 - @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/CMakeLists.txt

@@ -17,6 +17,7 @@ macro(make_sample)
 
     # Get the source files
     set(sources "${CMAKE_CURRENT_SOURCE_DIR}/${MAKE_SAMPLE_DIR}/main.cpp")
+
     foreach(source IN LISTS MAKE_SAMPLE_SOURCES)
         list(APPEND sources "${CMAKE_CURRENT_SOURCE_DIR}/${MAKE_SAMPLE_DIR}/${source}")
     endforeach()
@@ -36,9 +37,9 @@ macro(make_sample)
 endmacro()
 
 # Add samples
+make_sample(DIR "hello-cubos" COMPONENTS)
 make_sample(DIR "settings")
 make_sample(DIR "events")
-make_sample(DIR "systems")
 make_sample(DIR "input" ASSETS)
 make_sample(DIR "assets/bridge" ASSETS)
 make_sample(DIR "assets/json" ASSETS)

engine/samples/hello-cubos/components.hpp

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <cubos/core/ecs/world.hpp>
+
+struct [[cubos::component("num", VecStorage)]] Num
+{
+    int value;
+};

engine/samples/hello-cubos/main.cpp

@@ -0,0 +1,101 @@
+/// [Include Components]
+#include "components.hpp"
+/// [Include Components]
+
+/// [Include]
+#include <cubos/engine/cubos.hpp>
+
+using cubos::engine::Cubos;
+/// [Include]
+
+/// [Include Entity Stuff]
+using cubos::core::ecs::Commands;
+using cubos::core::ecs::Query;
+using cubos::core::ecs::Read;
+using cubos::core::ecs::Write;
+/// [Include Entity Stuff]
+
+/// [Resource Decl]
+struct Pop
+{
+    int count;
+};
+/// [Resource Decl]
+
+/// [Hello Cubos]
+static void sayHelloCubosSystem()
+{
+    CUBOS_INFO("Hello CUBOS");
+}
+/// [Hello Cubos]
+
+/// [Hello World]
+static void sayHelloSystem()
+{
+    CUBOS_INFO("Hello");
+}
+
+static void sayWorldSystem()
+{
+    CUBOS_INFO("World");
+}
+/// [Hello World]
+
+/// [Entity Spawn]
+static void spawnEntitiesSystem(Commands cmds, Write<Pop> pop)
+{
+    for (int i = 0; i < 10; i++)
+    {
+        cmds.create(Num{i});
+        pop->count += 1;
+    }
+}
+/// [Entity Spawn]
+
+/// [Entity Print]
+static void checkEntitiesSystem(Query<Read<Num>> query, Read<Pop> pop)
+{
+    for (auto [entity, num] : query)
+    {
+        CUBOS_INFO("Entity '{}' of '{}'", num->value, pop->count);
+    }
+}
+/// [Entity Print]
+
+/// [Engine]
+int main()
+{
+    Cubos cubos{};
+    /// [Engine]
+
+    /// [Tags]
+    cubos.tag("helloTag").before("worldTag");
+    /// [Tags]
+
+    /// [Set Startup]
+    cubos.startupSystem(sayHelloCubosSystem);
+    /// [Set Startup]
+
+    /// [Set Systems]
+    cubos.system(sayHelloSystem).tagged("helloTag");
+    cubos.system(sayWorldSystem).tagged("worldTag");
+    /// [Set Systems]
+
+    /// [Component Add]
+    cubos.addComponent<Num>();
+    /// [Component Add]
+
+    /// [Resource Add]
+    cubos.addResource<Pop>();
+    /// [Resource Add]
+
+    /// [Entity System]
+    cubos.startupSystem(spawnEntitiesSystem);
+
+    cubos.system(checkEntitiesSystem);
+    /// [Entity System]
+
+    /// [Run]
+    cubos.run();
+}
+/// [Run]

engine/samples/hello-cubos/page.md

@@ -0,0 +1,107 @@
+# Hello CUBOS. {#examples-engine-hello-cubos}
+
+@brief Using @ref cubos::engine::Cubos "Cubos" to create a simple program.
+
+This example shows the basics of how @ref cubos::engine::Cubos is used, by making a simple "Hello World" program.
+
+@snippet hello-cubos/main.cpp Include
+
+First we'll need to get a `Cubos` object.
+
+@snippet hello-cubos/main.cpp Engine
+
+The @ref cubos::engine::Cubos "Cubos" class represents the engine.
+We'll need it to add functionality to our program.
+
+Let's start by defining what functionality we want to add.
+
+@snippet hello-cubos/main.cpp Hello Cubos
+
+This function simply prints `Hello CUBOS` to the console.
+It uses one of CUBOS.'s logging macros.
+You can find more about them @ref core/include/cubos/core/log.hpp "here".
+However, this function is not currently called, so we'll need to tell CUBOS. that we want it to run.
+
+@snippet hello-cubos/main.cpp Set Startup
+
+Startup systems run only once when the engine is loaded.
+Now let's make things more interesting.
+Let's print `Hello World`, but split it over two different systems.
+
+@snippet hello-cubos/main.cpp Hello World
+
+Instead of using `startupSystem`, we'll use @ref cubos::engine::Cubos::system "Cubos::system".
+This means the systems will be called after the startup systems and repeat every cycle, instead of just once at startup.
+
+@note As we don't have anything that would require multiple cycles (such as a window to draw to), the CUBOS. main cycle will run only once.
+
+However, we can't just do as we did for `sayHelloCubos` and call it a day.
+We want `sayHello` to come before `sayWorld`, so we'll have to explicitly tell that to the engine, or else we risk having them in the wrong order.
+To do that we use tags.
+Let's create two tags, one for each system.
+
+@snippet hello-cubos/main.cpp Tags
+
+@ref cubos::engine::Cubos::tag "Cubos::tag" creates a new tag, and @ref cubos::engine::TagBuilder::before "before" makes any systems tagged with it come before systems tagged with the one given as parameter.
+There's also an @ref cubos::engine::TagBuilder::after "after" that has the inverse effect.
+Now all we have to do is to assign these tags to our systems.
+@note If we wanted to give these tags to a system running on startup, we'd have to use @ref cubos::engine::Cubos::startupTag "Cubos::startupTag" instead.
+
+@snippet hello-cubos/main.cpp Set Systems
+
+Now let's see a bit about entities, components and resources.
+First we are going to need to use a few more things.
+We'll go over what each does as it comes up.
+
+@snippet hello-cubos/main.cpp Include Entity Stuff
+
+Entities have components, so let's create one to give our entities.
+Because of how the engine works, we cannot declare a component on our `main.cpp` file.
+We'll need to create a `components.hpp` for that.
+
+@include hello-cubos/components.hpp
+
+Here we create a component called "num" that stores a single integer.
+We'll use it as the id of the entity it is attached to.
+Back on our `main.cpp` file we'll need to include our new file.
+
+@snippet hello-cubos/main.cpp Include Components
+
+And the component needs to be registered.
+
+@snippet hello-cubos/main.cpp Component Add
+
+Let's create a resource now.
+Unlike components, resources can be declared on the `main.cpp` file, so let's do that.
+
+@snippet hello-cubos/main.cpp Resource Decl
+
+This resource will store the total number of spawned entities, a population counter of sorts.
+It too needs to be registered.
+
+@snippet hello-cubos/main.cpp Resource Add
+
+Now let's create a startup system that spawns some entities.
+
+@snippet hello-cubos/main.cpp Entity Spawn
+
+@ref cubos::core::ecs::Commands "Commands" is a system argument that allows us to interact with the world, in this case, by creating entities that have a `Num` component.
+
+@ref cubos::core::ecs::Write "Write" is a system argument that allows us to modify a resource, in this case `Pop`.
+
+Finally, we'll want a system that prints our entities.
+
+@snippet hello-cubos/main.cpp Entity Print
+
+@ref cubos::core::ecs::Read "Read" is similar to `Write`, only it just gives us permission to read data from resources and components, we cannot alter them.
+
+@ref cubos::core::ecs::Query "Query" allows us to access all entities with a given configuration of components. In this case, it will give us all entities with the `Num` component.
+
+To finish configuring our program, we just need to register these two new systems.
+We'll also have the entities be printed after our `Hello World` message.
+
+@snippet hello-cubos/main.cpp Entity System
+
+With everything properly set up, all that remains is to run the engine.
+
+@snippet hello-cubos/main.cpp Run