Information

Most of the communication between systems and entities is done asynchronously via events. That’s why events and requests were created.

An overview of events and requests can be found in the game reflection of the workspace editor.

Requests

It is used when a system should do some job on behalf of an entity.

Example

QueueEvent( "DamageRequest", target, 200.0, "physical", 1, 0 )

In that case, you are requesting some system to deal damage to an entity on your behalf.

Events

It is a notification that something happened with an entity.

Example

So after DamageSystem handled the DamageRequest sent earlier (see above) and dealt damage to that entity, it sends a notification in form of a DamageEvent.
To use an event, the entity needs to be able to “listen” for events, for that purpose the RegisterHandler is used.

Functions

For event functions, see Event class.

RegisterHandler

Allows entities to “listen” for events / requests happening in the same or other files all around.

Example 1

self:RegisterHandler( event_sink, "DamageRequest", ... )
self:RegisterHandler( event_sink, "DamageEvent", ... )

Explanation 1

Your function here will be called for all damage requests / events sent for all entities, it uses the event_sink.

event_sink: Your function will be called on this kind of request / event sent to any entity

Example 2

self:RegisterHandler( self.entity, "DamageRequest", ... )
self:RegisterHandler( self.entity, "DamageEvent", ... )

Explanation 2

Uses this function only when someone requests / notifies damage on this entity and ignore everything else, it uses self.entity.

Example 3

self:RegisterHandler( spawned_entity, "DamageRequest", ... )
self:RegisterHandler( spawned_entity, "DamageEvent", ... )

Explanation 3

Uses this function only when someone request / notifies damage on entity spawned_entity and ignore everything else. Can add any known entity.

UnregisterHandler

Stops “listening” for events / requests happening to entities

Example

self:UnregisterHandler( event_sink, "DamageRequest", ... )
self:UnregisterHandler( event_sink, "DamageEvent", ... )

Create a custom event

Besides using events which have already been given a purpose, you can create your own events.

Example

QueueEvent("LuaGlobalEvent", sender, "CustomYourNameEvent", { 
    param_1 = 2,
    xyz = "test"
} );  

self:RegisterHandler( event_sink, "LuaGlobalEvent", "_OnLuaGlobalEvent" )

function script_name:_OnLuaGlobalEvent(evt)
    local eventName = evt:GetEvent()
    if eventName == "CustomYourNameEvent"  then
          local params = evt:GetDatabase()
          local param_1 = params:GetFloat("param_1")
          local xyz = params:GetString("xyz")
    end
end  

Explanation

Here, you use the LuaGlobalEvent but assign it a custom name with custom parameters.
In the code you create a RegisterHandler for the LuaGlobalEvent, so you can use the _OnLuaGlobalEvent(evt) function to access your parameters.