Events

An event is a message. It is sent when something happens in your story, for example when a state finishes playing, or when a viewer points the camera at a trigger.

You use these event messages to control the flow and timing of your story. For example, your story can start an animation clip when it gets the event message that the viewer is looking at a particular spot; or you can play a sound on queue; or you can choose which branch of a story graph to take.

To act on these event messages, you need to set up transitions or actions to listen for them. In the Properties window for transitions and actions, there is a menu called On Event. If you choose an event under this menu, your transition or action will launch only when it receives that event message.

Event Menu

Three types of events occur in a story: state events, trigger events and user events.

State Events

A state event is sent when a state in your story has one of the following things happen:

  • done: Sent when the state completes, which means it runs once all the way through or it finishes its loop count if it has one.
    • If the state is complete but has not yet transitioned, this event message will continue to be sent.
    • If the state exits without completing, you may not get a "done" event message.
  • begin: Sent when the state begins.
  • end: Sent when the story transitions out of the state even if it doesn't complete, such as when it is interrupted.
    • You will always get an "end" event message unless the state is marked as an end state.
  • begin_loop: In a looping state, this event is sent at the beginning of each loop.
  • end_loop: In a state with a loop count, this event is sent at the end of each loop.
    • Unless it is the last loop, "end_loop" will usually be followed immediately by the "begin_loop" event message.
  • update: This event is sent once per frame. It can be used to start actions or transitions on a specific frame.

Trigger Events

Trigger events involve the viewer's camera being pointed at a trigger. When the camera turns to point at the trigger, the event message starts being sent. It will continue to be sent on each frame as long as the camera points at the trigger. It will stop being sent when the camera turns away.

When you click on the On Event pull-down, then hover your mouse over the LookAt Trigger Events menu, you see a list of all the trigger names taken from the source Maya scene. Hovering over one of the trigger names, you will see three options for specifying when transitions and actions will respond to the trigger event:

  • onEnter: When you first get a trigger event
  • whileLookingAt: While you continue to get a trigger event
  • onExit: When you stop getting a trigger event

User Events

A user event is an event message with a custom name that you create. User events allow you to send a message at any time without depending on a state or trigger status. That can be important for flexibility in controlling the timing and flow of your story.

To create a user event, use the On Event menu and choose User Event > Create. This opens a dialog allowing you to enter a name for your event.

Once you create your user event, you can send it out at any point in the story to launch actions or transitions that are listening for it. To send a user event, create an action in your Timeline called Broadcast Event. In that action, you enter the name of your user event and choose the timing for when it will be sent.

You can see a list of the user events you have created in the Outliner. If you click on one of the user events in that list, the Properties window displays all the states and transitions that use the event. You can also right-click on the user event name to rename or delete it, or choose Select Usages to highlight the places where it is used in the Graph Editor.

Should I Use Events or Conditions?

In many cases, you can set up similar behavior in your story transitions using either events or conditions. Both include ways to control the flow of your story. In some cases, it might be easier, or give you better performance, if a transition uses a condition to start, rather than an event.