Adding Animation

Setup

You may find a completed “features/display/AddingAnimation” sample project for TypeScript, Haxe, ES6 or ES5 online, the following describes how to add animation from an empty project or from the previous Displaying a Bitmap.

If you have completed the Displaying a Bitmap tutorial, you can continue using the same project files. Otherwise you can run the following commands:

mkdir AddingAnimation
cd AddingAnimation
yo openfl

If you start fresh, download an image file into your dist directory, such as this one.

Animating Your Project

In the Displaying a Bitmap tutorial, we added an image using the openfl.display.Bitmap class, and made it renderable. We also suggested that you try changing some properties, such as the x or y property of the Bitmap object to change how it would be rendered.

Although this is a good way to understand some of the fundamental principles of the display list works in OpenFL, interactive projects often benefit by updating these properties over time to create an animation.

In the following steps, we will illustrate how you can create animation using Event.ENTER_FRAME, using a timer, a combination of both Event.ENTER_FRAME and time, as well as using an animation library.

Before we continue, your “src/app.ts”, “src/app.js” or “src/App.hx” should be able to load and display a bitmap, similar to the following:

Using Event.ENTER_FRAME

One of the ways that you can begin to add animation in OpenFL is by listening to the Event.ENTER_FRAME event. This event occurs every time that OpenFL enters a new animation frame (which is by default the same as requestAnimationFrame, but is configurable).

All we need to do to create an animation is update a property of our Bitmap object (such as the x, y or alpha property) in our listener. This will occur repeatedly over time, making it possible to play an animation.

The following code will animate the image from it’s initial y position of 0, increasing by 1 each frame until it reaches y == 200. Then it changes direction, and moves back toward y == 0 before finally repeating:

Using Timer

Sometimes, you may need to update a property based upon time, rather than animation frames. In general, it is recommended that updates are made within an animation frame. In the next section, we will show you can combine Event.ENTER_FRAME with openfl.utils.getTimer to handle time, but in the meantime, this is a short description of openfl.utils.Timer could be used to trigger animation based on time.

Both setTimeout and setInterval could be used to trigger an event repeatedly, as well as a final complete event, but the Timer class combines the two behaviors into a single utility which may be helpful for time-based behaviors.

Using Event.ENTER_FRAME and getTimer

This approach is common for many games, which need to know the amount of time that has elapsed since the last frame. It also tends to blend the best elements of both Event.ENTER_FRAME and time-based animation.

Using an Animation Library

When you move beyond a simple illustration, and begin building real interactive projects, use of an animation (or “tween”) library is more productive for expressive animation than animating by hand. In addition to automatically animating based upon requestAnimationFrame, an animation library may make it simpler to combine animation of multiple properties at once, make it simple to receive callbacks when the object has been updated or completes an animation, and often includes multiple “easing” equations in order to animate properties along a quadratic, exponential or elastic animation equation rather than a simple linear equation, similar to the examples above.

In the following example code, we have integrated a tween library called Actuate. If you wish, you may use the “features/display/AddingAnimation” sample (for TypeScript, Haxe, ES6 and ES5), which is already configured for use with Actuate, otherwise we can add Actuate to your current project.

First, open a command-prompt or terminal, and change to your project directory and run the following command:

npm install--save-dev actuate

Next, in order to make it easier to import modules from the Actuate library, edit “webpack.common.js”, and update the resolve section to include an alias for Actuate: