Events

IntermediateProgrammer

Events facilitate communication between scripts. They work one-way, broadcast from broadcasters to receivers. Events come in two flavors, a non-generic version for basic event broadcasting, and a generic version for when data needs to be passed to receivers.

For example, imagine your game has a "Game Over" state that occurs when the player dies. To handle this, you can create a "Game Over" event, which is broadcast to all scripts with receivers listening for the event. When the event is broadcast, the receivers run appropriate scripts to handle the Game Over event (eg reset enemies, replace level objects, start a new timer, etc). You can also send information related to the "Game Over" state (eg game stats, who won, etc).

Note

Events are handled entirely in scripts. You can't configure them in Game Studio.

Create and broadcast an event

Broadcasters in the Xenko API are of type EventKey or EventKey<T>. They use the method Broadcast or Broadcast(T) to broadcast events to receivers.

For example, this code creates two "Game Over" events. One with a non-generic and the other with a generic version of EventKey:

  1. public static class GlobalEvents
  2. {
  3.     public static EventKey GameOverEventKey = new EventKey("Global", "Game Over");
  4.     public static EventKey<string> GameOverWithDataEventKey = new EventKeyKey<string>("Global", "Game Over With Data");
  6.     public static void SendGameOverEvent()
  7.     {
  8.         GameOverEventKey.Broadcast();
  9.         GameOverWithDataEventKey.Broadcast("Player 1");
  10.     }
  11. }

Create a receiver

Receivers in the Xenko API are of type EventReceiver or EventReceiver<T>.

To receive the "Game Over" events described above, use:

  1. var gameOverListener = new EventReceiver(GlobalEvents.GameOverEventKey);
  2. var gameIsOver = gameOverListener.TryReceive();
  4. var gameOverListenerWithData = new EventReceiver<string>(GlobalEvents.GameOverWithDataEventKey);
  5. if(gameOverListenerWithData.TryReceive(out string data))
  6. {
  7.     //data == "Player 1"
  8. }
  10. //Or in Async
  11. await gameOverListener.ReceiveAsync();
  12. string asyncData = await gameOverListenerWithData.ReceiveAsync();
  13. //asyncData == "Player 1"

See also