View Source Ecspanse.Event (ECSpanse v0.4.0)

Events act as a one-way communication channel to Ecspanse, enabling elements outside of the framework to dispatch data asynchronously into Ecspanse Systems. Events are also used internally to communicate between Systems. The events are defined by invoking use Ecspanse.Event in their module definition.

Events are scheduled using the Ecspanse.event/2 function. Any events scheduled within the current frame will be batched and then made accessible to the systems in the following Ecspanse.Frame.t/0. The batched events from the current frame are cleared once that frame ends. This implies each system has a single opportunity to process an event that has been scheduled.

Options

  • :fields - a list with all the event struct keys and their initial values (if any) For example: [:direction, type: :hero]

An inserted_at field with the Elixir.System time of the creation is added to all events automatically.

There are two ways of providing the events with their field values:

  1. At compile time, when invoking the use Ecspanse.Event, by providing the :fields option.

      defmodule Demo.Events.HeroMoved do
        use Ecspanse.Event, fields: [:direction, type: :hero]
      end
  2. At runtime when creating the events from specs: t:Ecspanse.Event.event_spec()

      Ecspanse.event({Demo.Events.HeroMoved, [direction: :left]})

Note

There are many ways to filter events in the Systems by their struct like:

 Enum.filter(events, &match?(%Demo.Events.MoveHero{direction: :right}, &1)) # this allows further pattern matching in the event struct
 # or
 Enum.filter(events, & &1.__struct__ == Demo.Events.MoveHero)
 # or
 Enum.filter(events, & fn %event_module{}  -> event_module == Demo.Events.MoveHero end)

Summary

Types

An event_spec is the definition required to create an event.

Types

@type event_spec() ::
  (event_module :: module())
  | {event_module :: module(), event_fields :: keyword()}

An event_spec is the definition required to create an event.

Examples

  Demo.Events.MoveHero
  {Demo.Events.MoveHero, [direction: :left]}