Home > Resources > Articles > Introduction to the Event System

Introduction to the Event System

Events constitute a system that runs in parallel with tasks. Tasks are great at running the temporal logic of the experience, but require a lot of work when you want to signal the occurrence of an event throughout the whole experience (you’d need members on all the actors that should be notified).

Events and functions should be used to handle events in the world of the experience.

How to receive an event

For a component to receive an event, it needs to signal its interest in it. To do so, you can either:

  • Trigger an entire function: functions can directly be triggered by events, whether they are schematic graphs or VSL scripts. Double click on the trigger section of the function to see the list of all the provided events. For instance, triggering a function with a vkBehaviorActivatedEvent allows for some easy initialization function.
  • Trigger part of a schematic graph: on top of the function trigger system, there are ways to wait for an event inside a schematic task. The WaitEvent building block activates its output upon receipt of an event. This allows the triggering of limited parts of a graph. You can find WaitEvent’s description here.

How to create custom events

Most of the time, the default events provided by 3DVIA Studio (clickable events, zone events or component activation events, etc.) will be sent for you, and you only need to worry about catching them. However, 3DVIA Studio allows the creation of custom user events.

To create a custom event, you need to create a class type with vkUserEvent as its parent class. Additional members can be attached to the event. The resulting user event can be used just like regular events. Open the function trigger menu to see it listed with the others.

NOTE: any subsequent user event you create can inherit from the user events you already have created. This allows for some complex event-related schemes.

Once you’re done, it’s up to you to send this event.

How to send an event

Because sending an event is not linked to the passing of time, it can be done with a task or a function, in both languages. There are different levels of propagation:

Broadcast

All components listening for the event will receive it:

vkClickableClickEvent event;
event.item = this;

event.Broadcast();

Send to a Component Ring

All components of a ring listening for the event will receive it:

vkClickableClickEvent event; event.item = this; vkActorPtr actor = GetStage().GetActor(…); actor.BroadcastEventInRing(event);

Send to a Component

Only the component calling the function receives the event, if it is listening for it:

vkClickableClickEvent event;
event.item = this; vkActorPtr actor = GetStage().GetActor(…); actor.BroadcastEventInRing(event);

Message Event

A simple event type for generic events. It is made of:

  • an identifier (vkString) that identifies the message
  • a variant set that holds the data associated to the message
  • a component which should be the sender of the event.

Available (bound) constructors for this class are:

  • vkMessageEvent(const vkString& iID);
    Constructs a simple message event containing an ID.
  • vkMessageEvent(const vkString& iID, vkComponent* iSource);
    Constructs a simple message event containing an ID and a source component.
  • vkMessageEvent(const vkString& iID, vkComponent* iSource, const vkVariantsSet& iData);
    Constructs a simple message event containing an ID, a source component and associated data.

Available (bound) members for this class are:

  • vkComponentPtr               source;
    Component that sends the event.
  • vkString                      id;
    id of the message.
  • vkVariantsSet                 data;
    Data associated to the message.
In a Schematic Graph

All the functions we’ve seen above can also be used as function-callers in a graph.

In a schematic task, the SendEvent building block allows the broadcasting of any event. To see how to use and configure the BB, click here.

How to access to event members

We’ve seen events can have user-defined members. If you want to access them, some additional work is required, namely, adding an input parameter to the function.

In VSL Script

Upon creation, a function doesn’t have parameters. You need to add the event itself to access its members:

void
MyBehavior::OnEvent(Anchor::CustomEvent& iEvent)
{
if (iEvent.action == 0) Print("Is missing an action");
else Print("Has an action");
}

In Schematic Graphs

A schematic function can also have input and output parameters. You need to add the right type of event in the pin tab:

EventInputParam

How it works

Sending an event is much like calling a function; when calling Broadcast(), BroadcastEventInRing() or HandleEvent(), the event handling is instantaneous.

Additionally, the term broadcast might make you think that the whole world will be notified. This is of course not the case. Only the components that listened for an event (either with function triggers or with WaitEvent building blocks) will be notified.

Finally, the propagation of an event can be stopped, provided the input parameter fStopIfHandled has been set to true. You just need to return false in any function triggered by the event to prevent its propagation.


Related Pages