The VRSimulator is internally structured around a comprehensive event system. Methods can listen or subscribe to events, and then when an event gets fired/invoked, the listener methods will execute. Events themselves can be invoked using static methods exposed by the EventManager singleton.

	Please Note
	A comprehensive diagram mapping the flow of events throughout the VRSimulator is in progress. When it is complete, you'll be able to find it on the Order of Events page. Until it is ready, your best resource for understanding events is to review the events exposed by the EventManager in our scripting reference. For More Information... Order of Events Scripting Reference: EventManager

Listening for Events

Any method can "listen" for an event exposed by the VRSimulator EventManager.  A method that is listening for (subscribed to) an event will always execute whenever that event is fired/invoked. Below is a sample of a custom listener method that is subscribed to the OnInputActionStart event:

public class myCustomClass : MonoBehaviour {
   void OnEnable() {
      // "Listen" for the Input Action.
      EventManager.OnInputActionStart += myCustomListener;
   }

   void OnDisable() {
      // "Unlisten" for the Input Action.
      EventManager.OnInputActionStart -= myCustomListener;
   }

   void myCustomListener(InputAction firedAction) {
      if (firedAction.name == "DesiredInputAction") {
         // Do something (or call another method) here.
      }
   }
}

In the code above, the OnEnable() method is where you set myCustomListener to "listen" for the event EventManager.OnInputActionStart to occur.  Essentially, what you're doing is adding the method myCustomListener to a list of methods that will be called whenever OnInputActionStart occurs.

	Best Practice
	To make our code easier to follow / keep straight, we always name our listener methods the same as the event they're listening to. Thus, we wouldn't actually use myCustomListener but instead OnInputActionStart. Of course, you can use whatever naming conventions you like, but this one works well for us.

The OnDisable() method is where you then remove the myCustomListener method from the list of methods listening for OnInputActionStart. This is to prevent memory leaks - if you didn't "unlisten", then even when you closed Unity, shut down your game, and went off to get a cup of coffee there would still be a lonely little bit of software somewhere waiting in vain for the OnInputActionStart event to occur. That's a textbook definition of a nasty memory leak problem.

Reacting to an Event

The sample code above contains a method called myCustomListener which is a good example of reacting to an event. Here is that code again, just so we can go over its important parts:

void myCustomListener(InputAction firedAction) {
   if (firedAction.name == "DesiredInputAction") {
      // Do something (or call another method) here.
   }
}

Please notice the return type and parameters for the method. Every single method that listens for the OnInputActionStart event must have the same return type (void) and the same parameters (a single InputAction object). However, that is not true for all events! Every single event expects its listeners to have a specific return type, and a specific set of parameters. To review those details, please review the event's documentation in the Scripting Reference: EventManager.

	Be Careful!
	If your custom listener for an event does not have the return type or parameters expected by the event, your code will throw an exception.

In this example, if the OnInputActionStart event is invoked, the myCustomListener method will be called. It will check the InputAction passed to it against a particular string, and then execute a bunch of logic. This is just one example - what actually happens in an event listener method is entirely up to you!

Event Conventions

There are several design conventions that we have used when creating the VRSimulator's event system:

• Naming Convention. Events are named On<Something> where <Something> is a CamelCase description of what invoked the event. If the event has a start and an end, there will be two separate events: On<Something>Start and On<Something>End.
• Default InputActions have associated events.  The Default InputActions supported by our input/movement system all have corresponding events associated with them. These events are fired whenever their related InputAction is detected.  For events related either to toggles or button InputActions, the MovementManager tracks the state of each InputAction and either calls On<Input>Activation or On<Input>Deactivation as appropriate.

2017 Copyright © Immerseum Inc. All rights reserved.