Visual Effects and Timeline
Use Unity’s Timeline to control a Visual Effect Graph’s properties and Events. To do this, add the following to a Timeline instance:
Visual Effect Control track
The Visual Effect Control track is a type of Timeline track that determines when Timeline can send Events and Event Attribute Payloads.
To control a Visual Effect in a Control track, create a Visual Effect Control Track and add a Visual Effect to it:
- Open the Timeline Window (menu: Window > Sequencing > Timeline)
- Navigate to the Hierarchy window and select a Visual Effect GameObject
- In the Timeline window, select Create.
- Save your Timeline asset.
- Click the + button at the top-left of the Timeline window.
- Select Visual Effect Control Track.
- Select the
icon and choose a Visual Effect Asset.
You can also configure the attributes of an Event in an Event Attribute Payload in script with VFXEventAttribute.
Properties
When you select a Visual Effect Control track, the following property appears in the Inspector window:
| Property | Description |
|---|---|
| Reinit | Controls when Unity resets the Visual Effect Control Track: • On Binding Enable Or Disable: Resets the control track when you bind or unbind a Visual Effect in the Timeline. Reinit uses this setting by default. • On Binding Enable: Resets the control track when you bind a Visual Effect in the Timeline. • On Binding Disable: Resets the Visual Effect Control track when you unbind a Visual Effect in the Timeline. • None: Unity doesn’t reset the Visual Effect Control track . |
Visual Effect Control clip
A control clip is a section of the Timeline track that controls the Visual Effect. You can use a control clip to scrub through a Visual Effect and to add clip events and single events. A Visual Effect Control clip exists inside a Visual Effect Control track.
To add a Visual Effect Control Clip:
- In the Clips view, right-click on an empty area within the Visual Effect Control track.
- Select Add Visual Effect Control Clip.
- Select the clip to display its properties in the inspector.
Each clip in a Visual Effect Control Track controls how that Visual Effect behaves in your scene. You can send Visual Effect events to the clip in the Clip Events and Single Events sections of the Inspector window.
Properties
When you select a Visual Effect Control clip, the following properties appears in the Inspector window:
| Property | Description | ||
|---|---|---|---|
| Scrubbing | Use Scrubbing to synchronize an effect with other animated GameObjects in the Timeline instance.Enable this option to play the Visual Effect backwards and forwards when you drag the Timeline Playhead. When you enable Scrubbing, Reinit defaults to On Enter And Exit Clip. This is because scrubbing can only control a Visual Effect that starts at the beginning of the Visual Effect Control clip. Enable this property to use the Prewarm property. Disable Scrubbing to: • Expose the Enable PreWarm property when you set Reinit to On Enter or Exit. • Send the Enter Event when the playhead enters the Visual Effect Control clip. |
||
| Reinit | Controls when Timeline initializes the Visual Effect: • None: Timeline does not initialize the Visual Effect again. • On Exit Clip: Timeline restarts the Visual Effect at the end of the Visual Effect Control clip. • On Enter Clip: Timeline reinitializes the Visual Effect at the beginning of the Visual Effect Control clip. When Scrubbing is disabled, this mode exposes the Enable PreWarm property. • On Enter or Exit: Timeline reinitializes the Visual Effect at the beginning and end of the Visual Effect Control clip. Reinit uses this mode by default. When Scrubbing is disabled, this mode exposes the Enable PreWarm property. |
||
| Start Seed | This property represents the initial seed that Unity uses for its random number generator (see also VisualEffect.startSeed).When you enable Scrubbing or when the Reinit mode is set to On Enter Clip, the Visual Effect Control clip controls this property. |
||
| Enable PreWarm | Enable this property to start processing the Visual Effect before it appears. When you set this property, it doesn’t affect the PreWarm settings in the Visual Effect Asset. This means you can have more than one animation clip that uses the same Visual Effect Asset with different PreWarm settings. This property is only available when you enable Scrubbing or when you set the Reinit mode to On Enter Clip or On Enter or Exit. |
||
| PreWarm Total Time | Simulates the Visual Effect for a given amount of time before it starts. The value for this property is in seconds. Set this value to recalculate PreWarm Delta Time. | ||
| PreWarm Step Count | Sets the number of simulation steps that Unity uses to calculate the PreWarm. A higher number of steps makes the PreWarm more precise but it can impact performance. When you change this value, Unity calculates a new value for PreWarm Delta Time. |
||
| PreWarm Delta Time | Sets the delta time, in seconds, that Unity uses for the PreWarm. When you change this value, Unity calculates new values for PreWarm Total Time and PreWarm Step Count. Adjust this value, instead of PreWarm Total Time and PreWarm Step Count individually, if you need to use a precise delta time for your simulation. |
||
| PreWarm Event Name | The name of the Event that Unity sends when the effect starts. You can customize this name, or leave it blank to make it so that every system does not spawn by default. The default value is OnPlay. |
||
| Clip Events | Select + to add a Visual Effect Event in the VisualEffect Control clip. A Clip Event has a start and an end. When you disable scrubbing and the playhead enters the Visual Effect Control clip, it sends the Enter Event. |
||
| Enter | Unity starts the Visual Effect when the Timeline Playhead is at the beginning of the Clip Event. | ||
| Time | The value Unity uses to determine when to play the Visual Effect within the clip. The unit changes depending on the Time Space mode you select. | ||
| Time Space | • After Clip Start: Plays the Event after the beginning of the Visual Effect Control clip, plus the number of seconds you enter in the Time field. • Before Clip End: Plays the Event before the end of the Visual Effect Control clip, minus the number of seconds you enter in the Time field. • Percentage: Plays the Event at a percentage of the total time of the Visual Effect Control clip. For example, a Time value of 0 indicates the start of the clip and a value of 100 indicates the end. • Absolute: Plays the Event at the second you specify in the Time property. |
||
| Name | The name of the Clip Event. The default name of the Enter Clip Event is OnPlay. This name appears in the Visual Effect Control track. | ||
| Attributes | Select + to add an attribute that Timeline sends with a corresponding Visual Effect Event.. For example, position, color or a custom attribute. | ||
| Exit | Unity stops the Visual Effect when the Timeline Playhead reaches the end of the clip. | ||
| Time | The value Unity uses to determine when to play the Visual Effect within the Clip. The unit changes depending on the Time Space mode you select. | ||
| Time Space | • After Clip Start: Plays the event after the beginning of the Visual Effect Control clip. • Before Clip End: Plays the event before the end of the Visual Effect Control clip. • Percentage: Plays the event at a percentage of the total time of the Visual Effect Control clip. For example, a value of 0 indicates the start of the clip and 100 indicates the end. • Absolute: Plays the event at a specific second in the track. |
||
| Name | The name of the Clip Event. The default name of the Exit Clip Event is OnStop. This name appears in the Visual Effect Control track. | ||
| Attributes | Select + to add an attribute that Timeline sends with a corresponding Visual Effect Event. For example, position, color or a custom attribute. Unity uses these attributes to create a VFXEventAttribute which it sends with the single Event. | ||
| Single Events | Select + to add a single Visual Effect Event in the Visual Effect Control clip. A Single Event happens once. This is useful for a burst spawn system. When you disable Scrubbing, Single Events only play when the timeline is playing forward. | ||
| Editor Color | The color that indicates the Single Event in the Timeline Window. | ||
| Time | The value Unity uses to determine when to send the Single Event within the Visual Effect Control clip. The unit changes depending on the Time Space mode you select. | ||
| Time Space | • After Clip Start: Plays the Single Event after the beginning of the Visual Effect Control clip. • Before Clip End: Plays the Single Event before the end of the Visual Effect Control clip. • Percentage: Plays the Single Event at a percentage of the total time of the Visual Effect Control clip. For example, a value of 0 indicates the start of the clip and 100 indicates the end. • Absolute: Plays the single Event at a specific second in the track. |
||
| Name | The name of the Single Event. This name appears in the Visual Effect Control track. | ||
| Attributes | Select + to add an attribute that Timeline sends with a corresponding Visual Effect Event. For example, position, color or a custom attribute. Unity uses these attributes to create a VFXEventAttribute which it sends with the single Event. |
Animating Properties
To animate the animatable properties of a Visual Effect graph in the Timeline and Animation window, assign an Animation Track to your Visual Effect GameObject. To animate a Visual Effect properties in the Timeline window:
- Create a Visual Effect control track.
- In the Timeline window, open the + drop down and select Animation Track.
- Select the Animation Track’s icon and choose a Visual Effect Asset that has an Animator component.
This binds the Visual Effect GameObject to an animation track and adds a Playable Director component in the Inspector window.
Limitations
- Unity limits the amount of time you can skip when you enable Scrubbing. You can change this limit in Project Settings > VFX > Max Scrub Time. If you exceed this limit, Unity displays a warning.
- When you play a Visual Effect backwards in the Timeline in runtime, it causes a high peak in GPU use. This is because this implementation uses Simulate.
- When you enable scrubbing for more than one Timeline track that controls the same Visual Effect, Unity displays a warning in Scene view.
Automatic Migration
When you upgrade to Unity version 2022.2.0a9 or newer Unity automatically migrates the Visual Effect integration in Timeline. To do this, it upgrades:
- Visual Activation track to Visual Effect Control track
- Visual Activation clip to Visual Effect Control clip
To keep the same behavior and avoid any breaking changes, Unity automatically:
- Sets up a mirrored Visual Effect Control track with a Visual Effect Control clip.
- Sets the mirrored Visual Effect Control track’s Reinit property to None.
- Disables Scrubbing on the mirrored Visual Effect Control clip.
- Copies the Name and Attributes property values into the Clip Events and Single Events.