Timeline

The Timeline object allows timelines to be controlled in events.

Tagging

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.

About picking

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.

Timeline Conditions

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.

Timeline Actions

Play
Start playing a timeline, with tags to identify this playback.
Play all
Play all the timelines in the layout.
Pause
Pause a timeline by its tag. Paused timelines can subsequently be resumed.
Pause all
Pause all currently playing timelines.
Resume
Resume a paused timeline by its tag.
Resume all
Resume all paused timelines.
Stop
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.

Timeline Expressions

Time(nameOrTags)
Retrieve the current time of the first matching timeline by either name or tags.
Progress(nameOrTags)
Retrieve the progress of the first matching timeline by either name or tags, returning a value in the range [0, 1].
TotalTime(nameOrTags)
The total time of the first matching timeline by either name or tags.
KeyframeTags
In a On keyframe reached or On any keyframe reached trigger, a string with the Tags property of the keyframe that was reached.
TimelineName
In a trigger, a string with the name of the relevant timeline.
TimelineTags
In a trigger, a string with the tags of the relevant timeline.
Construct 3 Manual 2020-06-16

On this page