Getting Started Tweening

Quick links

• Introduction
• Installing the code
• Importing
• Basic tweening with TweenLite
• Special properties
• Plugins
• Overwriting other tweens
• Controling tweens
• Which class do I use? TweenLite? TweenMax? TweenNano?
• Building a sequence with TimelineLite
• Tips & tricks
• Video tutorials & lessons
• Need help?

Introduction

Animating with code may seem intimidating at first, but don't worry - you'll get the hang of it quickly. The GreenSock Tweening Platform was engineered to make it simple and intuitive. For now, we'll focus on getting you up and running with the core engine, TweenLite, and then we'll discuss if and when you might want to put the other tools to work for you (like TweenMax, TimelineLite, TimelineMax, etc.).

Installing the code

Go to www.TweenLite.com and click the "Download AS3" or "Download AS2" button to download a zip file containing the entire GreenSock Tweening Platform in the language you specified. Unzip the file and you'll see a folder containing several swfs, documentation, and a folder named "com" - that's the critical one. Take that "com" folder with all its contents and drop it into the same folder as your FLA file (or if you're an advanced user, set up a classpath to wherever you want). Make sure that you leave the directory structure inside the "com" folder in-tact; it has a "greensock" folder with several ActionScript files inside, along with a few subdirectories.

You can throw away the swfs from the zip download and the documentation, etc. if you want. The only critical files are inside that "com" folder.

When you publish your swf, Flash looks for that "com" folder, reads the code from inside of it, and embeds it into your published swf. You do NOT need to put the "com" folder on your web server. Once the swf is created, it is completely independent and has no dependencies on the class files because they have been embedded into the compressed swf. Your FLA file has the dependencies, not the swf.

Importing

In order for Flash to understand what you mean when you type "TweenLite" (or "TweenMax" or any of the GreenSock classes), you must tell it where to find the class file(s). That's what an import statement does. It acts as a pointer that tells Flash where it should look. After all, there could be a completely different "TweenLite" class that another author created, and you need a way to tell Flash which one you're talking about. Typically you put your import statement at the top of the frame or the custom class you created. And, yes, just like any class, you must add the import statement to all frames or classes that contain code referencing it. This does not add extra kb to your file every time you import it. Flash is smart enough to embed it once and all the import statements just act as a "pointer" to the embedded class.

To import just the TweenLite class, do:

To import TweenLite and TweenMax, do:

To import all of the classes in the com.greensock package (don't worry, Flash will only embed the classes that you actually use in your code), do:

You'll probably also want to import the easing classes as well (we'll talk more about them later), so this is code that you should get used to putting at the top of your frames or class files because it covers almost everything you'd need and it's shorter than typing out each class every time:

Basic tweening with TweenLite

Each tween you create needs a target (the object you want to tween), the duration of the tween (typically described in seconds), and the properties that you want to tween, along with their corresponding end values. Let's say, for example, you have a MovieClip named "mc" and you'd like to tween its "x" property to a value of 100 (sliding it across the screen) over the course of 1.5 seconds. You can use TweenLite's to() method to do it:

The first parameter is the target, the second is the duration, and the third is an object with one or more properties that correspond to your target object's properties. Since it's a to() tween, you're telling TweenLite to tween from whever the x property happens to be at the time the tween begins (now in this case), to a value of 100. If you want to also tween the "y" property to 200 and the "alpha" property to 0.5, you'd do:

There is no limit to the number of properties you can tween. And TweenLite can tween any numeric property of any object, not just a predetermined list of DisplayObject/MovieClip properties. Since there's an AS2 version as well, you can simply change the property names to reflect their AS2 equivalents, like:

Here's an interactive demo that allows you to build tweens yourself and see the corresponding code at the bottom:

There is also a very useful from() method that allows you to define the starting values in the tween and go backwards. So the current values will be used as the end values, and the ones you define in the tween will be the starting values. This makes it easy to, for example, set things up on the stage where you'd like the objects to end, and then animate them into place. Let's say your mc object's y property is at 200 and alpha is at 1, and you'd like to have it "drop" into place from above while fading in over the course of 1.5 seconds, you could do:

If you prefer a more object-oriented approach and/or would like to store references to your tweens in variables so that you can control them later (for example, pause(), resume(), reverse(), restart()), you can create a tween like this (which is identical to a to() tween):

Special properties

A special property is a reserved keyword that TweenLite recognizes and handles differently than it would a normal property. One example is "delay" which allows you to delay a tween from starting until a certain number of seconds has elapsed. For example, this tween will wait 2 seconds before beginning:

TweenLite recognizes several special properties that are quite useful, like onComplete, ease, overwrite, paused, useFrames, immediateRender, onStart, onUpdate, onCompleteParams, and more. Please read the full documentation for details. Two of the most common special properties you'll likely use are "ease" and "onComplete". To alter the rate of change during a tween, you can choose from many different easing equations from either the com.greensock.easing package or Flash's own easing clases or Robert Penner's. The interactive demo above allows you to chose different equations and see how they affect the tween. The onComplete special property gives you a way to call any function when the tween completes, making it simple to create a chain of events.

Here is a tween that uses the Elastic.easeOut ease, delays its start time by 0.5 seconds, and calls myFunction() when it completes:

Plugins

Think of plugins like special properties that are dynamically added to TweenLite (and/or TweenMax), giving it extra abilities that it doesn't normally have by default. Each plugin is associated with a property name and it takes responsibility for handling that property. For example, the FrameLabelPlugin is associated with the "frameLabel" property name so if it is activated it will intercept the "frameLabel" property in the following tween and manage it uniquely:

If the FrameLabelPlugin wasn't activated, TweenLite would act as though you were trying to literally tween the mc.frameLabel property (and there is no such thing).

Activating a plugin requires a single line of code and you only need to do it once in your application, so it's pretty easy. Simply pass an Array containing the names of all the plugins you'd like to activate to the TweenPlugin.activate() method, like this:

To make it even easier, I created the Plugin Explorer which writes the code for you. All you need to do is select the plugins and copy/paste the code from the bottom of the tool. It also displays interactive examples of each plugin and the assocaited code so that it's easy to see the correct syntax.

TweenLite does not activate any plugins by default, but TweenMax does. When a plugin is activated, it affects both TweenLite and TweenMax.

Overwriting other tweens

An often overlooked aspect of tweening is how (and if and when) tweens overwrite other tweens of the same object. For example, let's say you have a button with ROLL_OVER and ROLL_OUT handlers that tween its alpha higher on ROLL_OVER and lower on ROLL_OUT. To further complicate things, let's say the ROLL_OVER tween lasts 2 seconds and the ROLL_OUT tween lasts 1 second. What should happen if the user rolls over/out/over/out quickly? See the problem? If tweens are allowed to run without any kind of overwriting, they'll build up and fight with each other (one trying to tween the alpha higher, and the other lower). In this example, when the user rolls over, a 2-second tween would start increasing the alpha to 1, but if the user rolled off 0.2 seconds later, another tween would begin, causing the alpha to decrease. When that tween finishes 1 second later, the ROLL_OVER tween is still going (since it had a duration of 2 seconds), so the alpha would suddenly jump up and finish off at a value of 1 even though the user rolled out!

By default, TweenLite completely overwrites all existing tweens of the same object immediately which avoids problems like the one mentioned above. However, there's another side effect - if you want to set up a sequence of tweens using various delay values, they'll keep overwriting each other, so you'll only end up seeing your last tween. This is why TweenLite has an "overwrite" special property. You can set it to true (the default) to kill all preexisting tweens of the same object, or you can set it to false to allow those tweens to continue unaffected. But what if you want more advanced control? What if you want the engine to be smart enough to analyze existing tweens and only overwrite individual overlapping properties of existing tweens of the same object that are actually running at the time the new tween begins? That's exactly what the AUTO mode in OverwriteManager does. OverwriteManager is a separate class that you can optionally use to enable advanced overwriting management. There are many modes to choose from (view the documentation), but the most popular one is AUTO. To cause TweenLite to use AUTO mode, all you need to do is call this line of code once in your swf (you can call it more often if you want, but it doesn't do any good or harm):

This will have a global effect on all of your tweens. If you want fine-grain control over individual tweens, you can define any overwrite mode you want on an individual tween basis using the overwrite special property, like this:

In most cases all you'll need to do is init() OverwriteManager and that's it - you do not need to define the overwrite mode for each tween unless you want it to use a different mode than the one you set OverwriteManager to as the default. For ROLL_OVER/ROLL_OUT tweens, it's generally a good idea to set the overwrite mode to true (or 1) for optimal performance, but AUTO mode can work great too.

Controlling tweens

Once a tween is created, you may want to pause() resume(), reverse(), play(), restart(), invalidate(), or kill() it. It's pretty easy, actually:

TweenMax has some additional static methods for getting all the tweens of a particular object, pausing them all, resuming, getting tweens of objects that are children of a certain DisplayObject, and more (see documentation for details).

Which class do I use? TweenLite? TweenMax? TweenNano?

First of all, check out the feature comparison chart to see exactly how the engines compare. If you can afford the file size (roughly 17.7k with the default plugins), just use TweenMax. It is the most full-featured tweening engine and it automatically handles activating a bunch of useful plugins by default, as well as the AUTO mode in OverwriteManager, so it makes things very easy. If, however, you're concerned about file size and want precise control over which plugins get activated, TweenLite is for you. It's amazingly capable for its size and has all the essentials crammed into about 4.7k. It is really the core of the whole platform and has become incredibly popular. If you simply must shave off another 3.1k and are willing to sacrifice quite a few features (most notably lack of support for plugins and insertion into TimelineLite/Max instances), use the ridiculously small 1.6k TweenNano (2k in AS2). I would strongly recommend sticking with TweenLite or TweenMax if you can, though, because they offer much more flexibility than TweenNano. All of the engines use exactly the same syntax, so these lines will produce identical results:

Keep in mind that TweenMax extends TweenLite, so it does everything TweenLite does, plus more. And the plugins that are activated by default in TweenMax can also be activated in TweenLite (the only exception being roundProps), as can the AUTO mode of OverwriteManager, so with a couple of extra lines of code at the start of your application, TweenLite can have many of the same capabilities as TweenMax (activating plugins and using OverwriteManager increases the file size beyond 4.7k obviously). There are several features that are only available in TweenMax, though, so check the feature comparison chart or the documentation.

Building a sequence with TimelineLite

Watch a video that explains the basics of working with TimelineLite and TimelineMax.

You can build sequences of tweens by using the "delay" property in each one or chaining them together with onComplete calls, but what happens if you want to be able to control an entire sequence or group of tweens as a whole? Let's say you've got a menu that needs to tween out, then down, then colorize, and if the user rolls their mouse out anytime during that animation, it must reverse itself from wherever it happens to be? Never fear. TimelineLite is here (and its big brother, TimelineMax). Think of a TimelineLite instance like a container for your tweens, allowing you to place them exactly where you want over the course of time and then control the entire group as a whole with pause(), resume(), reverse(), play(), or restart(). In fact, they're very similar to MovieClip timelines where designers animate things in the Flash IDE - they're just ActionScript-based, making them far more dynamic and able to be smoothly interpolated. You can add labels and then gotoAndPlay() or gotoAndStop() just like a MovieClip. You can alter their timeScale to speed them up or slow them down. TimelineLite instances can be nested inside other TimelineLite instances as deeply as you want too. This opens up entirely new animation possibilities. Trust me: once you get the hang of how they work, you'll fall in love.

Let's start by building a simple sequence where an "mc" object tweens its x property, then its y property, then its tint:

By default, the timeline will immediately begin playing, but since we only want it to begin when the user rolls over our menu object, we'll pause it initially either by calling pause() immediately or simply passing "paused:true" in the vars object. Let's add the event listeners too:

That's it! Now the animation will play forwards on rollover, and smoothly reverse itself on rollout.

You do not need to always have tweens line up end-to-end in your timelines. You can place them wherever you want. The insert() method allows you to define a precise time or even a label at which to place the tween. The append() method accepts a 2nd parameter called "offset", allowing you to position tweens relative to the end of the timeline (leaving a gap or overlapping, depending on whether the offset is positive or negative). so here is some sample code:

So tweens can overlap as much as you want. There is no limitation on the number of tweens or how much they can overlap. You can also insert multiple tweens at the same time using the insertMultiple() and appendMultiple() methods which offer unique alignment and staggering capabilities (see documentation for details). In fact, these methods work great with TweenMax.allTo() and allFrom(). For example, let's say you have 100 Sprites that you want to animate down from above and fade in - you can do it in one line of code:

Just like the way TweenMax extends TweenLite, TimelineMax extends TimelineLite, using identical syntax and adding several useful (but non-essential) features like AS3 event dispatching, repeat, repeatDelay, addCallback(), getActive(), getLabelAfter(), getLabelBefore(), currentLabel, and more. Please refer to the documentation for details. Here's an interactive demo of TimelineMax:

Tips & tricks

• You can define values as relative by passing them in as Strings. So, for example, if you want to move mc 100 pixels greater than what it is now, do this:
  PLAIN TEXT
  Actionscript:

  1. TweenLite.to(mc, 1, {x:"100"});
  2. //or if the value is in a variable, cast it as a String like this:
  3. TweenLite.to(mc, 1, {x:String(myVariable)});

• Use the delayedCall() method to call a function after a certain amount of time (more reliable than setTimeout()):
  PLAIN TEXT
  Actionscript:

  1. //calls myFunction(myParam1, myParam2) after 2 seconds
  2. TweenLite.delayedCall(2, myFunction, [myParam1, myParam2]);

• Use the Plugin Explorer to not only write activation code for any plugins you want, but also to look at examples and see the correct syntax.
• To eliminate the easing in a tween, simply use the Linear.easeNone ease.
• You can pause() a timeline or tween and then tween its currentTime property to fastforward or rewind it, complete with easing.
• You can tween the timeScale property of a TweenMax tween or a TimelineLite or TimelineMax instance to make it gradually speed up or slow down.
• If you don't want your tween or timeline to begin immediately, simply pass paused:true in the vars object.
• By default, tweens with a duration of zero will render immediately unless you pass immediateRender:false in the vars object.
• You can nest timelines within timelines for complex effects. In fact, you could build various functions that create timelines and return them and you could use those to drop into a more global timeline, giving you great control over the whole animation process.

Video & tutorials & lessons

• Watch a video that explains the basics of working with TimelineLite and TimelineMax.
• The folks at DN Digital created some nifty YouTube videos here that cover several aspects of working with the GreenSock platform.
• Lee Brimelow did a v10 video that uses a cool 3D hover and scale effect here.

Need help?

Feel free to post your question on the forums. Keep in mind that you'll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified FLA file (and any class files) that clearly demonstrates the problem.