How to use Timeline Signals
Since Timeline’s introduction in 2017, we know that you’ve been patiently waiting for a way to send events. Well, wait no more! Starting in Unity 2019.1, a new feature called Signals helps you send events. Let’s dive in and see what this new feature is all about.
Here’s what Signals look like in the Timeline window:
We’ve built Signals to establish a communication channel between Timeline and outside systems. But what does that mean? Why did we decide on this approach?
Let’s say that you are using Timeline to create a cutscene. When the cutscene ends, you want a new scene to be loaded and you want to enable a physics system. There are a couple of ways to implement this scenario:
- When your cutscene ends, use custom scripts to make your Timeline instance interact directly with a scene manager and your physics system.
- When your cutscene ends, create markers and signals to send a ‘’Cutscene finished’’ signal and have interested systems react to the signal.
The Timeline team went with the second approach because it keeps the emitter independent from the receiver. Keeping them independent adds a lot of flexibility, power, and reusability. To understand this more, let’s see how the different pieces work together.
How does it work together?
To use signals to communicate with outside systems, you need three pieces: a Signal Asset, a Signal Emitter, and a Signal Receiver.
- Signal Emitter: A Signal Emitter contains a reference to a Signal Asset. In Timeline, a Signal Emitter is represented visually by a marker. You can place a marker on a track, or in the Markers area under the Timeline ruler.
- Signal Receiver: A Signal Receiver is a component with a list of reactions. Each reaction is linked to a Signal Asset.
- Signal Asset: A Signal Asset is the association between a Signal Emitter and a Signal Receiver. You can reuse the same Signal Asset in many Timeline instances.
Here’s a simple game where you defeat a bunny zombie by pressing the arrow keys that match the directional images shown on-screen:
The directional image randomly changes with each musical beat. If you don’t press the right arrow key before the image changes, you lose. If you press a certain number of arrow keys, you win.
In the game, the GameTimeline instance includes the gameplay. It uses Signals to display new directional images with each musical beat, as shown in the finished GameTimeline instance below:
To demonstrate how to create and set up signals, let’s start from a project where none of the Signals have been created. If you want to follow along, you can download the project here.
First, to view the Markers area where you add Signals, click the Marker icon beside the Clip Edit modes. The Markers area appears beneath the Timeline ruler:
To add a Signal Emitter, right-click in the Markers area and select Add Signal Emitter.
A Signal Emitter appears in the Markers area:
The Signal Emitter you just added is selected and the Inspector window show its properties. The Inspector window also provides buttons for creating the other pieces of a signal:
To link the Signal Emitter to a Signal Receiver, you need to add a new Signal Asset. In the Inspector window, click Create Signal…. Name the Signal Asset “ShowKey” because this Signal Asset will be used to link and emitter with a receiver to change the directional image. Click Save and the Signal Asset is added to the project.
You also want the Signal Emitter to be associated with a Signal Receiver, so click Add Signal Receiver. Your Inspector window should now look like this:
Before continuing, let’s stop and describe what’s going on. When you click the Add Signal Receiver button, two things happen: a new Signal Receiver component is added to the bound GameObject and a new reaction is added and linked to the Signal Asset that you just created. You can see they are linked because “ShowKey” appears as the Emit Signal and “ShowKey” is added to the list of reactions:
The Inspector window shows two things: the Signal Emitter properties and the reactions defined by the Signal Receiver component:
Although the Signal Receiver component is linked to the GameObject that is associated with the Timeline instance, you can edit the Signal Receiver in the Inspector window. The reaction is invoked when the Signal Receiver receives the signal.
The last step is to specify what the reaction does. In this example, there is a component named Manager with a ShowRandomKey method. This method displays a new random arrow key. To have the reaction call the ShowRandomKey method, select this method for the Unity Event, as shown below:
And that’s it! After adding the Signal Emitter and defining its Signal Receiver and the reaction, you now have an example of a Timeline instance that communicates with the scene.
When Timeline hits the Signal Emitter, the ShowKey signal is emitted. The Signal Receiver, that is listening for the ShowKey signal, calls the ShowRandomKey method.
But you don’t have to stop there. Multiple signal emitters can emit the same signal. For example, the following Timeline instance has the same Signal Emitter copied and moved to different times; there is an emitter for every musical beat:
You can also drag a Signal Asset directly from the Project window to the Timeline window. A Signal Emitter is automatically created with the Emit Signal property already set.
To see what the finished project looks like, with all Signals, download it here.
In order to set up your first signal, you need to:
- Right-click on a Marker area or a track that supports signals, then choose Add Signal Emitter…
- In the Inspector window, click Create Signal Asset, choose a file name and press Enter.
- Still in the Inspector, click Create Reaction… button and define the reaction associated with the signal you just created.
- Can I have multiple receivers on a single GameObject? Yes, all Signal Receivers on a GameObject receives the signals sent to that GameObject.
- Can a signal asset be reused between multiple Timeline instances? Yes, a Signal Asset can be used in more than one Timeline instance.
- Can a Signal Asset be extended and customized? Yes, Signal Asset, Signal Emitter and Signal Receiver can all be extended. But this is a subject for another day; there will be another blog post about customization.
- Are signals guaranteed to be emitted? Yes. Signals will not be skipped; they will be emitted on the next frame regardless of the game’s FPS.
- What happens if duplicate a Timeline Asset contains signal emitters? The signal emitters keep their reference to their Signal Assets. Signal Assets are not duplicated.