Animation sequence

Simple examples of animations that can be done with animation sequence:

• Animating the albedo of a material component

  

• Animating the position of a local transform component

  

What is an animation sequence?

Animation sequences are used to animate the component data of entities. They can be used to make a complex mind-bending cut scene, or a simple animation that livens up your application. They can also emit events as they play, which are listenable in client-side Livelink.js code and in scripts, allowing your application to react to key points in a sequence.

Animation sequences are intrinsically linked to the scene that you work on them with, because they are linked to the entities of that scene. You cannot use the same animation sequence with two different scenes. However, you can still play the animation sequences of your scene’s linkers (or subscenes).

Animation sequences are composed of tracks. A track is made of up keys which have an associated value and time. There are three different kinds of tracks: animation, trigger and event. Animation and trigger tracks are used to animate an entity’s component attribute, and event tracks are used to emit events.

Animation Track

Animation tracks are used to animate an entity’s component attribute. An animation track will interpolate between keys. At a time t of the animation sequence playing, the two keys between which t fall will be the keys that are interpolated.

In the example below, at time 600ms, the animation sequence will set the entity’s position to the result of the interpolation between the values of keys A and B.

Trigger Track

Trigger tracks are also used to animate an entity’s component attribute. Unlike animation tracks, a trigger track will not interpolate between keys, but will simply set the key value at the key time.

In the example below, at time 1000ms, the animation sequence will set the entity’s position to the value specified by key B.

Event Track

Event tracks are used to emit events of an event map asset. Its keys correspond to specific events in the event map specified upon creating the track. While the animation sequence plays, these specified events will be emitted at their specified times.

Event tracks are also associated to an entity, which will be the one emitting the specified events.

In the example below, at time 1000ms, the entity “cube” will emit the event specified in key B.

To create and edit event maps, you must do so in the Event Maps tab of the script editor (create a script and double click on the asset browser). Unfortunately event maps do not have their own dedicated editor for the moment.

To listen and react to events emitted by an animation sequence, you can do so either in a script asset:

Or you can do so in Livelink.js client code with registerToEvent:

const eventMapUUID = 'my-event-map-uuid';
const eventName = 'Start';
SDK3DVerse.engineAPI.registerToEvent(eventMapUUID, eventName, (event) => {
	const { emitterEntity } = event;
	console.log(emitterEntity, 'emitted the event: ', eventName);
});

Animation sequence editor

To edit an animation sequence, you need to use the extension “Animation Sequence Editor” in the scene editor. Click on Extensions in the bottom right of the scene editor and then drag the animation sequence editor where you would like to put it.

A general overview:

Create/publish/delete animation sequence

When you need to publish to see your changes, the publish button will turn PINK!

Modify duration and loop of animation sequence

Under the + Create button, you can modify the duration. Next to it you can enable or disable loop. Make sure to publish after modifying duration.

Create a track

Drag and drop an entity from the scene graph to “drop an entity to create a new track” . You can animate all entities (including external entities).

You will be given the option to decide what component attribute (like transform.position.y or material.albedo.xyz) you want to animate in that track.

🚨 Limitation: You can animate an overridden component of an external entity, but you cannot animate a new or deleted overridden component of an external entity.

There are two different kinds of tracks you can create.

Animation track: the component attribute will be interpolated between keys.

Trigger track: the component attribute will be set at each key. No interpolation will happen.

Event track: the entity will emit an event that can be listened to in Livelink.js code and in a script.

Delete a track

Create a key

Double click on the track to create a new key at that time. You can always modify the time more precisely afterwards (check “modify a key”).

Modify a key

Delete a key

Modify sequencer time range

🐞 🪲 Examples of errors

• Track has no keys. You cannot publish an animation sequence with an empty track, i.e. a track that has no keys. To fix it, just give your track some keys (or delete the track) and publish again.

  

  

• Insufficient permissions. This may happen if you select an animation sequence of a linker that has been deleted while your session has been running.

  

Disabled tracks

How to play

You can play, pause and stop animation sequences. Stopping an animation sequence will restore the values of the first keys of each track.

Animation sequence editor

play, pause, stop:

To control the playback of an animation sequence use the play, pause and stop buttons in the animation sequence editor. You can also control the playback speed in the widget to the right of the play/pause button. A negative playback speed will play the animation sequence in reverse.

play, pause, stop of linker’s animation sequence:

You can also play the animation sequences of your subscenes (of linkers).

The animation sequences of your linkers will appear in the dropdown as <linker name>/<animation sequence name>. You can play them here, but to edit them open the scene referenced by your linker entity.

Livelink.js SDK

Use the SDK functions playAnimationSequence, pauseAnimationSequence and stopAnimationSequence. You will need to pass the UUID of your animation sequence to each of them. You can get the animation sequence UUID by selecting the animation sequence in the asset browser and copying it from the info panel, just like with other assets.

play:

const settings = { playbackSpeed : 0.5 };
SDK3DVerse.engineAPI.playAnimationSequence(animationSequenceUUID, settings);

pause:

SDK3DVerse.engineAPI.pauseAnimationSequence(animationSequenceUUID);

stop:

SDK3DVerse.engineAPI.stopAnimationSequence(animationSequenceUUID);

Play, pause, stop of linker’s animation sequence:

If you want to play/pause/stop the animation sequence of a linker (a subscene), pass the linker as last argument of the functions above.

const settings = { playbackSpeed : 1.0 };
SDK3DVerse.engineAPI.playAnimationSequence(animationSequenceUUID, settings, linkerEntity);

Note: The linkerEntity can be inside a subscene of your current scene.