Artemis Animation Timeline

What is it?

In editor timeline allowing you to animate any entity and preview the results in realtime. Combine multiple animations to create cut-scenes and scripted events!

../_images/animation-timeline.jpg

Features

  • Record multiple tracks, animating entity transforms (position, rotation, scale) directly inside the PlayCanvas editor.
  • Keyframes and complex animation curves supported.
  • Each animation timeline can be played separately and controlled by any script.
  • Live editor preview.

Where to find?

After you enable the extension in the PIC browser extension, reload your PlayCanvas editor and you will see a new panel underneath the Assets panel named Timeline.

../_images/timeline-position.png

How it works?

  1. Use the Timeline panel to add, edit and sync animations for any entity.
  2. Use the artemis-playback.js script to control the playback of any animation.

Timeline panel

To start using the Timeline panel:

  1. Expand it by pressing on the Timeline label.
  2. Press the New Timeline button to create a new timeline.
  3. or drag and drop any timeline .json asset to continue editing an existing timeline.

Note

What is a timeline?

A timeline is a collection of tracks that can be played in parallel. It is an easy way to group animations together.

Each track in a timeline can animate a single entity in a given instant.

As soon as the Timeline panel is active a number of buttons will be activated alongside the timeline editor.

You can start adding tracks in two ways:

  1. From the toolbar click the Add track button.
  2. or by double clicking in a blank space in the editor.
../_images/timeline-new-track.png

Timeline track

A timeline track has the following properties:

  • Referenced entity.
  • Duration info.
  • It is movable, it can be drag and dropped at any place.
  • It is resizable, it can be easily resized to change its duration.
  • Record button.
  • Keyframes line.

Referenced entity

To reference an entity on a track, simple drag and drop an entity from the Hierarchy to the Select Entity field. You can change that selection at any time.

Duration, Start, End

Each track has a Start and End timestamp automatically calculated by its position inside the Timeline editor.

  • To change the Start timestamp simple click and move the track to your desired time.
  • To change the End timestamp click and resize the track to your desired time.

The duration of the track is automatically calculated and displayed on the track.

../_images/track-duration.png

Recording

To record a new animation the following steps should be followed each time:

  1. Move the record handler at the desired start time. Usually that is the start of track.
../_images/track-record-start.png
  1. Click the Record button to enter the recording mode.
  2. Select your recording entity in the Hierarchy (it will be highlighted).
../_images/track-record-entity.png
  1. Move, rotate, scale the entity at the desired values. Either by using the PlayCanvas editor gizmos or using the Inspector relevant fields.
../_images/track-record-inspector.png

As soon as you do that a new Keyframe will appear in the keyframes line on the track.

Repeat the 1-4 steps to create additional keyframes as required. At the end the track should have at least two keyframes for an animation to be played.

../_images/track-record-keyframes.png

Warning

Don’t forget to press again the Record button as soon as you are finished to exit the recording mode.

Warning

All changes to a track live inside the Timeline editor.

To save your changes to the timeline asset you have to manually press the Save timeline button in the Timeline panel toolbar.

If you are unhappy with your changes to you can press the Revert timeline button to remove all changes done since the last time this timeline was saved.

Timeline preview

While the Timeline panel is active all tracks are animated as a live preview inside the PlayCanvas editor.

You can control the playback preview by:

  • Moving the record handler around in the Timeline editor.

  • Using the playback buttons in the Timeline panel toolbar:

    • Go to Start
    • Start Playback
    • Stop Playback
    • Go to End

Note

If you are animating a Camera to preview it inside the PlayCanvas editor you must first select it from the Cameras list in the PlayCanvas editor.

../_images/playcanvas-camera-list.png

Advanced keyframe editing

You can select a keyframe by clicking on it and the following control buttons will appear:

  • Delete keyframe
  • Move to the left arrow
  • Move to the right arrow
../_images/keyframe-controls.png

Using the arrow buttons you can change the time on which this keyframe is placed.

For finer grained control you can edit the animation curve that is used to interpolate the transformation values between keyframes. Normally a linear interpolation is used but you can change that at any minute by right-clicking the start keyframe to access the curve editor. The following curves are available:

  • Linear
  • Spline
  • Smoothstep
../_images/keyframe-curve.png

You can place any number of intermediate points and also change the scale and sign of the animation curve.

Animation PlayBack

When you are finished editing and saving changes on a Timeline you will end up with a JSON asset that contains the data required to playback the timeline.

Note

The timeline JSON assets saved to your projects are project-independent and can be download and re-uploaded to any other PlayCanvas project. The only thing that you need to make sure of is that the refereneced entities are named the same.

A special PlayCanvas script named artemis-playback.js will also be added to your project. That script exposes methods and properties to playback a timeline.

../_images/animation-script.png

Note

You may notice that a second script named _artemis-editor-curve.js has been added to your project. That script is used automatically when editing a Timeline keyframe curve and isn’t required to run your application and playback a timeline. You can safely remove it at any point.

To play an animation in your PlayCanvas project follow these steps:

  1. Attach the artemis-playback.js script to a script component of any entity.
  2. Drag and drop to the Timeline field the timeline JSON asset you created.
  3. Set the properties and your animation is ready to play.
../_images/animation-properties.png

Here is an explanation of the properties provided that help play the animation without using code in many common scenarios.

Speed

The speed of the animation playback.

On Init

Start the animation as soon as the entity is initialised. That means when the entity is enabled for the first time.

Reverse

If set to true the animation will be played in reverse.

Loop

Loop the animation infinitely.

Yoyo

If loop and yoyo is enabled the animation will start playing in the opposite direction as soon as it finishes.

If you would like more control of how and when an animation is played you can use the API exposed in the artemis-playback.js script.

Artemis API

You can call the exposed animation methods in two ways:

  • Using pc.Events
  • Directly referencing the script instance and method on the entity that the script is attached to.

The following code samples are using the first way which is easier to work as a beginner.

How to start an animation?

All methods use the Timeline name which is the name of timeline JSON asset, minus the .json extension.

e.g. A Camera.json timeline the name would be Camera.

// method signature
this.app.fire('Artemis:startPlaying:[timelineName]');

// e.g.
this.app.fire('Artemis:startPlaying:Camera');

How to stop/reset an animation?

In the same manner the methods used to stop (pause) and reset (pause and reset to start) an animation are similar.

// stop an animation
this.app.fire('Artemis:stopPlaying:Camera');

// reset an animation
this.app.fire('Artemis:resetPlaying:Camera');

Code Samples

Click on an entity to play

  • Using Physics to pick an entity that has a Collision component attached.
  • Support both desktop mouse clicks and mobile touch events.
  • When an entity is picked start playing an animation using the name of that entity.
  • The artemis-playback.js script needs to be attached to an entity, referencing a timeline JSON asset by that name.
var RaycastToPlay = pc.createScript('raycastToPlay');

// initialize code called once per entity
RaycastToPlay.prototype.initialize = function() {
    // Find the first entity in the hierarchy with the name 'Camera'
    this.cameraEntity = this.app.root.findByName('Camera');

    // Add a mousedown event handler
    this.app.mouse.on(pc.EVENT_MOUSEDOWN, this.mouseDown, this);

    // Add touch event only if touch is available
    if (this.app.touch) {
        this.app.touch.on(pc.EVENT_TOUCHSTART, this.touchStart, this);
    }
};

RaycastToPlay.prototype.mouseDown = function (e) {
    this.doRaycast(e);
};

RaycastToPlay.prototype.touchStart = function (e) {
    // Only perform the raycast if there is one finger on the screen
    if (e.touches.length == 1) {
        this.doRaycast(e.touches[0]);
    }
    e.event.preventDefault();
};

RaycastToPlay.prototype.doRaycast = function (screenPosition) {
    // The vec3 to raycast from
    var from = this.cameraEntity.getPosition ();
    // The vec3 to raycast to
    var to = this.cameraEntity.camera.screenToWorld(screenPosition.x, screenPosition.y, this.cameraEntity.camera.farClip);

    // Raycast between the two points
    var result = this.app.systems.rigidbody.raycastFirst(from, to);

    // If there was a hit, store the entity
    if (result) {
        var hitEntity = result.entity;

        if( hitEntity ){

            // play the animation named after the entity
            this.app.fire('Artemis:startPlaying:'+hitEntity.name);
        }
    }
};