The Timeline object allows timelines to be controlled in events.
Much like tweens, timelines can be optionally tagged when they are played using one of the Play actions. Tags are useful to later control a timeline (or multiple timelines sharing the same tags) with some of the other actions, conditions or expressions.
Setting instances to play
In the simplest case, a timeline will affect the instances that were used to create the timeline in the editor. Using the Set Instance action it is possible to use different instances to the ones used in the editor. Below are some short examples to help illustrate how this action works.
In the below example the timeline plugin Play action is used by itself on startup. This plays the timeline affecting the instances used in the editor to create the timeline. The timeline is tagged "new-timeline".
In this example the timeline plugin Play action is used together with the system plugin Create Object action and the timeline plugin Set Instance action. This plays the timeline affecting the newly created instance. The new instance will be used in the track with ID "a-track-id" and the timeline is tagged "new-timeline"
This example is similar to the last one, but instead of creating a new instance from scratch, the one picked by a collision event is used.
When using the Play action after one or more Set Instance actions, it is possible that one or more similar timelines will start playing. This will depend on the amount of currently picked instances for each given object type.
In the example below a timeline will be played for each group of instances.
This is the preview of the timeline in the editor. It has two different tracks and placeholder instances.
Using the Set Instance action we specify to play a timeline for each picked group of instances at the start of the layout
Lastly the preview of the layout shows that two different timelines where created to accommodate for the four instances found at the start of the layout.
- Is any playing
- True if any timeline is playing.
- Is playing
- True if a specified timeline is playing, given by its tag.
- Is any paused
- True if any timeline is paused.
- Is paused
- True if a specified timeline is paused, given by its tag.
- On started
- Triggered when a timeline starts playing, given by its tag.
- On any started
- Triggered when any timeline starts playing.
- On finished
- Triggered when a timeline finishes playback, given by its tag.
- On any finished
- Triggered when any timeline finishes playback.
- On keyframe reached
- Triggered when a master keyframe with certain tags is reached during playback. The keyframe can be identified by whether it matches any of the given tags, or if it has all of the given tags. Separate tags with spaces.
- On any keyframe reached
- Triggered when any master keyframe is reached during playback. The KeyframeTags expression has a string of the keyframe's Tags property.
- On time set
- Triggered when the time of a timeline is set with the Set Time action.
- Start playing a timeline, with tags to identify this playback.
- Play all
- Play all the timelines in the layout.
- Pause a timeline by its tag. Paused timelines can subsequently be resumed.
- Pause all
- Pause all currently playing timelines.
- Resume a paused timeline by its tag.
- Resume all
- Resume all paused timelines.
- Stop a timeline and reset it to its initial state.
- Stop all
- Stop all timelines, resetting them all to their initial state.
- Set time
- Set the current playback time of a timeline in seconds. Note: you can also use a string with a keyframe tag for the Time parameter, in which case the time is set to the position of that keyframe. If the timeline is playing when its time is set, playback is stopped.
- Set playback rate
- Set the playback rate of a timeline. 1 is normal speed, 0.5 is half speed, etc. Negative numbers will play in reverse.
- Set instance
- Set an instance to be used for the next timeline playback. The instance can be of a different type to the one used in the editor. The instance will be set to the track with the corresponding track ID. The track ID can also be left empty in which case it uses the first track in the timeline. It can also be used repeatedly with an empty ID to keep setting the tracks in the timeline in sequence. When the timeline is played it will then affect this instance instead of the one used in the editor. Playback can be controlled by using unique tags when playing the timeline.
- Retrieve the current time of the first matching timeline by either name or tags.
- Retrieve the progress of the first matching timeline by either name or tags, returning a value in the range [0, 1].
- The total time of the first matching timeline by either name or tags.
- In a On keyframe reached or On any keyframe reached trigger, a string with the Tags property of the keyframe that was reached.
- In a trigger, a string with the name of the relevant timeline.
- In a trigger, a string with the tags of the relevant timeline.