Events are a way to communicate across State Machines, timelines, and scripts. They’re useful when building interactive apps. In this tutorial, we step through how to use Events in the State Machine by creating a simple action: rotate a Box entity when we click a Sphere.
You’ll learn about:
- State Machine
- Emit and Listen actions
This is the scene we will build in this tutorial. Click on the Sphere to rotate the Box. For best results, use the latest version of your browser..
Before you begin, you should have completed the following tasks and tutorials:
- Sign in to Amazon Sumerian with your AWS account
- All Amazon Sumerian beginner tutorials
- Revisit the beginner State Machine tutorial
What Is an Event?
An Event is a messenger that goes between two or more State Machines. It’s also a State Machine action that emits a message telling a second State Machine (or more) to initiate. A basic Event consists of a name that is used to indicate that something happened. For example, if you create a button entity, or make an object “clickable”, you can make it emit a “buttonClicked” Event (i.e., a message) when it’s clicked. Other entities can listen to this Event and react to it as you want them to.
An Event can also carry more information about what happens, such as “which button was clicked?” or “how was the button clicked?”
In this tutorial, we’ll use a sphereclicked Event to indicate when the Sphere is clicked.
Step 1: Set up the Scene
From the Dashboard, create a new scene using the Default Lighting template. This scene will come with a Camera, a Light, and a Skybox.
Once you’re inside the scene, add a Box entity and a Sphere entity to your canvas.
Position the Box and Sphere so they don’t overlap. Use either the Transform component or your mouse to drag the gizmos in the canvas.
Step 2: Emitting an Event from the Sphere
You will use the State Machine to emit an Event.
Add a State Machine component to the Sphere.
Add a Behavior to the State Machine. Name it “Emit on click”.
Open the new Behavior, and rename the initial State to “Listen for pick”.
Add a Pick action to the Initial State.
Create a second State, and name it “Emit Event”.
Add an Emit Message action to the second State, and set the channel name to “sphereclicked”.
Connect the Transition of the Pick action to the second state. The result should look like this.
Step 3: Listening for an Event in the Box
Any script or state in the State Machine can listen to Events. Then it can do whatever you choose in reaction to that Event. For this exercise, we need to create another Behavior on the Box.
Select the Box, add a State Machine component, and then create a new Behavior.
To listen to an Event using the State Machine, we rename our first state “Listening” and add a Listen action. Be sure to specify the Event name correctly: “sphereclicked”.
Create a new State, and rename it “Rotate”. In the new Rotate state, add a Rotate action. To rotate around the Y axis, set the Y Rotation value to 90.
Finally, connect the Listening state to the Rotate state.
To summarize, the Sphere is waiting, or “listening” for a click. Once it’s clicked, it emits the message (or Event) “sphereclicked”. The Box is listening for the message “sphereclicked”. Once it hears that message, it rotates.
You can now press play and click the Sphere. When clicked, the Box will rotate.
Tips and Best Practices
If you’re not getting your behavior to function properly, there are several common mistakes that take place when using the State machine, and specifically Event messages.
- Be sure to use your Event Channels (or the messages) consistently across behaviors. Be sure that you have no typos or differences in capitalization. The messages have to match exactly between the Emit and Listen actions. This is the most common mistake made when using the Emit and Listen actions.
- Be sure your Initial State is correctly selected for each behavior. Your first state is by default Set as Initial State, so it’s helpful to start your behavior by creating first the behavior you want to be Set as Initial.
- Be sure that all behaviors are correctly connected with transitions.
- If you want your behavior to fire more than once in a scene, make sure the states to create a loop. This is done by making your last state transition back to the initial state.
- If a state doesn’t have an action that transition label, add the Transition or Transition on Next Frame action to that particular state.
Publish and share your scene!
Related Tasks and Tutorials
You should now have a much better understanding of the State Machine and Events. Next, check out the following tutorials: