Examples » Engine » Events

Using the EventReader and EventWriter.

This example shows how the EventReader and the EventWriter system arguments can be used to communicate from one system to another.

Firstly, we need to create and register the event we want to emit. Here, our event is a simple struct with a single field, however, you can use any type you want.

struct MyEvent
{
    CUBOS_ANONYMOUS_REFLECT(MyEvent);

    int value;
};

    cubos.event<MyEvent>();

To receive these events, we can make a simple system which takes the EventReader system argument and iterates through all the events it has. This will be the layout of all our reader systems (A, C, D).

    cubos.system("A").before(eventB).call([](EventReader<MyEvent> reader) {
        for (const auto& event : reader)
        {
            CUBOS_INFO("A read {}", event.value);
        }
    });

    cubos.system("C").tagged(eventC).after(eventB).call([](EventReader<MyEvent> reader) {
        for (const auto& event : reader)
        {
            CUBOS_INFO("C read {}", event.value);
        }
    });

    cubos.system("D").after(eventC).call([](EventReader<MyEvent> reader) {
        for (const auto& event : reader)
        {
            CUBOS_INFO("D read {}", event.value);
        }
    });

Now, to emit these events, we will use the EventWriter system argument. 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.

    cubos.system("B").tagged(eventB).call([](EventWriter<MyEvent> writer, State& state, ShouldQuit& 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");
        }
    });

These are the expected results with this order.

    // Should print:
    // B wrote 1 2 3
    // C read 1
    // C read 2
    // C read 3
    // D read 1
    // D read 2
    // D read 3
    // A read 1
    // A read 2
    // A read 3
    // B wrote 4 5 6
    // C read 4
    // C read 5
    // C read 6
    // D read 4
    // D read 5
    // D read 6

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.