A new game object event can be defined by calling the static method GameObjectCreateEventT(String, String, String, T). For example:

GameEventMetadata<EventArgs> metadata = GameObject.CreateEvent(
  "Click",                              // The name of the event.
  "Interaction",                        // The category (for use in game editors).
  "Occurs when the object is clicked.", // The description.
  EventArgs.Empty);                     // The default event args.

Once this method is called, the game object event is globally defined. If this method is called a second time with the same properties, it will not create a new game object event. Instead it will only return the metadata of the previous call. There cannot be multiple game object events with the same name and type of event arguments!

The metadata of any game object event can be queried by calling GameObjectGetEventMetadataT(String) where game object events can be identified by

• the automatically assigned ID stored in the metadata (see Id), or
• by name and type of the event args.

Either of these ways uniquely identifies a game object event.

The following examples shows how an event handler can be attached to a game object event.

GameObject gameObject = new GameObject();

GameEvent<EventArgs> click = gameObject.Events.Get<EventArgs>("Click");
click.Event += OnGameObjectClicked;

Note, the member OnGameObjectClicked in the example can be any method with the EventHandler<EventArgs> signature.

Detaching an event handler from a game object event is similarly easy.

GameEvent<EventArgs> click = gameObject.Events.Get<EventArgs>("Click");
click.Event -= OnGameObjectClicked;

The Raise method needs to be called to raise a game object event.

GameEvent<EventArgs> click = gameObject.Events.Get<EventArgs>("Click");

// Method #1: Raise the event using the default event args as specified in 
//            the metadata.
click.Raise();

// Method #2: Raise the event and explicitly specify the event args.
click.Raise(EventArgs.Empty);

In some cases it is convenient to wrap a game object event using a standard CLR event. Here is an example that shows how to define a game object event in a class and wrap it using a CLR event:

public class ClickableObject : GameObject
{
  /// <summary> 
  /// The ID of the <see cref="Click"/> game object event.
  /// </summary>
  public static readonly int ClickEventId = 
    CreateEvent("Click", "Interaction", "Occurs when the object is clicked.", EventArgs.Empty).Id;

  /// <summary>
  /// Occurs when the object is clicked. This is a game object event.
  /// </summary>
  public event EventHandler<EventArgs> Click
  {
    add
    {
      var click = Events.Get<EventArgs>(ClickEventId);
      click.Event += value;
    }
    remove
    {
      var click = Events.Get<EventArgs>(ClickEventId);
      click.Event -= value;
    }
  }

  ...
}

The game object event can then be used like any other CLR event. (This pattern is extensively used in the UIControls of the DigitalRune Game UI library.

Game object events have a property RaiseOnEvent, which is an event handler. This event handler can be connected with another game object event. This is very useful to connect game object events of different game objects. When one event is raised, the connected event is raised automatically. Here is an example:

// myButton is game object that represents a GUI button that can be clicked.
// myMachine is a game object that represents an object that starts its operation
// when its "Start" event is raised.
// Connect the "Click" game object event of the button with the "Start" game object 
// event of myMachine. This way a button click automatically starts myMachine.
GameEvent<EventArgs> buttonClick = myButton.Events.Get<EventArgs>("Click");
GameEvent<EventArgs> machineStart = myMachine.Events.Get<EventArgs>("Start");
buttonClick.Event += machineStart.RaiseOnEvent;