diff --git a/docs/pages/3_examples/2_engine/main.md b/docs/pages/3_examples/2_engine/main.md index 414e77a51d..af83b9113f 100644 --- a/docs/pages/3_examples/2_engine/main.md +++ b/docs/pages/3_examples/2_engine/main.md @@ -2,4 +2,7 @@ @brief Showcases features of the @ref engine library. -@note Under construction. +The following examples have fully documented tutorials on how to use the +multiple plugins of the engine: + +- @subpage examples-engine-events - @copybrief examples-engine-events diff --git a/engine/samples/events/main.cpp b/engine/samples/events/main.cpp index 476d40d543..9ab6ea3f7b 100644 --- a/engine/samples/events/main.cpp +++ b/engine/samples/events/main.cpp @@ -5,71 +5,87 @@ using namespace cubos::core; +/// [Event struct] struct MyEvent { int value; }; +/// [Event struct] struct State { int step; }; +/// [Event reader system] +static void firstSystem(ecs::EventReader reader) +{ + for (const auto& event : reader) + { + CUBOS_INFO("A read {}", event.value); + } +} +/// [Event reader system] + +/// [Event writer system] +static void secondSystem(ecs::EventWriter writer, ecs::Write state, ecs::Write quit) +{ + state->step += 1; + if (state->step == 1) // Write 1 2 3 on first run. + { + writer.push({1}); + writer.push({2}); + writer.push({3}); + CUBOS_INFO("B wrote 1 2 3"); + } + else if (state->step == 2) + { + quit->value = true; // Stop the loop. + writer.push({4}); + writer.push({5}); + writer.push({6}); + CUBOS_INFO("B wrote 4 5 6"); + } +} +/// [Event writer system] + +static void thirdSystem(ecs::EventReader reader) +{ + for (const auto& event : reader) + { + CUBOS_INFO("C read {}", event.value); + } +} + +static void fourthSystem(ecs::EventReader reader) +{ + for (const auto& event : reader) + { + CUBOS_INFO("D read {}", event.value); + } +} + int main() { cubos::engine::Cubos cubos; cubos.addResource(State{.step = 0}); + + /// [Add Event] cubos.addEvent(); + /// [Add Event] + + /// [Set ShouldQuit resource] cubos.startupSystem([](ecs::Write quit) { quit->value = false; }); - cubos - .system([](ecs::EventReader reader) { - for (const auto& event : reader) - { - CUBOS_INFO("A read {}", event.value); - } - }) - .tagged("A") - .beforeTag("B"); - cubos - .system( - [](ecs::EventWriter writer, ecs::Write state, ecs::Write quit) { - state->step += 1; - if (state->step == 1) // Write 1 2 3 on first run. - { - writer.push({1}); - writer.push({2}); - writer.push({3}); - CUBOS_INFO("B wrote 1 2 3"); - } - else if (state->step == 2) - { - quit->value = true; // Stop the loop. - writer.push({4}); - writer.push({5}); - writer.push({6}); - CUBOS_INFO("B wrote 4 5 6"); - } - }) - .tagged("B"); - cubos - .system([](ecs::EventReader reader) { - for (const auto& event : reader) - { - CUBOS_INFO("C read {}", event.value); - } - }) - .tagged("C") - .afterTag("B"); - cubos - .system([](ecs::EventReader reader) { - for (const auto& event : reader) - { - CUBOS_INFO("D read {}", event.value); - } - }) - .tagged("D") - .afterTag("C"); + /// [Set ShouldQuit resource] + /// [Add systems] + cubos.system(firstSystem).tagged("A").beforeTag("B"); + cubos.system(secondSystem).tagged("B"); + cubos.system(thirdSystem).tagged("C").afterTag("B"); + cubos.system(fourthSystem).tagged("D").afterTag("C"); + /// [Add systems] + + /// [Expected results] // Should print: // B wrote 1 2 3 // C read 1 @@ -88,5 +104,7 @@ int main() // D read 4 // D read 5 // D read 6 + /// [Expected results] + cubos.run(); } diff --git a/engine/samples/events/page.md b/engine/samples/events/page.md new file mode 100644 index 0000000000..ea5875ee1c --- /dev/null +++ b/engine/samples/events/page.md @@ -0,0 +1,27 @@ +# Events {#examples-engine-events} + +@brief Using the @ref cubos::core::ecs::EventReader and @ref cubos::core::ecs::EventWriter + +This example shows how the @ref cubos::core::ecs::EventReader and the @ref cubos::core::ecs::EventWriter can be used and configured, in a simple scene, to emit and read events. These are in the core, meaning, you don't need to add them to cubos. + +Firstly, we need to create and register the event we want to emit. Here, our event has one variable, however, you can give it any number of variables of any type you want. + +@snippet Event struct + +To receive these events, we can make a simple system, using the @ref cubos::core::ecs::EventReader and iterating through all the events it has. This will be the layout of all our reader systems (A, C, D). + +@snippet Event reader system + +Now, to emit these events, we will use the @ref cubos::core::ecs::EventWriter. This system will emit 3 events on the first frame and another 3 on the second frame. By setting the value of the ShouldQuit resource to true on the second frame, the engine stops before reaching the third frame. + +@snippet Event writer system + +Lastly, let's set the order we want these system to execute in. + +@snippet Adding the systems + +These are the expected results with this order. + +@snippet Expected results + +There are a couple of things to note here. First, the order in which the systems appear to receive the event. C receives the event, followed by D, this happens because even though A comes before C it also come before B, which is where the event is emitted, this means that C and D can read the event emitted by B on that same frame, while A will only read it on the next frame. This also explains why on the second run, A is never displayed, indeed, the engine quit before A got a chance to receive it's so desired events. This shows how the results of the execution of systems that use events may vary with the order set for them, so special care should be taken when defining this. \ No newline at end of file