AS3 tweening platform

This article or chapter is incomplete and its contents need further attention. Some information may be missing or may be wrong, spelling and grammar may have to be improved, use your judgment!

Introduction

TweenLite, TweenFilterLite, TweenMax, TweenGroup and TransformManager, are Actionscript 3 tweening classs written by Jack Doyle, GreenSock The purpose of this page is to have a printable version of the documentation (useful for teaching in a lab with small screens) and to add some examples that could be useful to "simple" Flash designers.

TweenLite - a light-weight and fast tweenclass to create animation and shape tweens in one go.
TweenFilterLite - extends TweenLite to add more filters (like blurs, glows, contrast, brightness, etc.)
TweenMax - does both of Tweenlite and TweenFilterLite and more.
TweenGroup - allow to manage groups of TweenLite/FilterLite/Max tweens. E.g. you can create a few tweens with TweenLite and then then play these in sequence.
TransformManager - add interactive scaling/rotating/moving of DisplayObjects in your Flash animation.

Please refer to the GreenSock website for official information and also consider donating something to Jack.

In order to undestand what some of the parameters and properties do, you will have to consult the AS3 manuals at Adobe, in particular the ActionScript3 language reference.

Syntax used for datatypes

If you see something like this xxx:YYY, it means that you have to use value of type YYY. Typically, you must specify:

Objects: If you work with CS3, instance names of movie clips)

 target:Object
 e.g. my_rocket

Objects also can refer to ECMAScript objects that you create on the fly

 variables:Object

E.g. an object with properties x=120 and y=110 is created like this:

 {x:120,y:110}

Numbers

 x:Number
 e.g. 15

Color_uint: E.g. for red you could use the following Hex value:

 0xFF0000

Boolean

 knockout : Boolean
 true

Functions: You will have to give a function name. This can be a Class.method

ease:Strong.easeInOut

Tweenlite Usage summary

This class includes a few static methods that you can use like functions.

TweenLite.to - create a tween of multiple properties of an object
TweenLite.from - same as above (you specify the result of the tween))
TweenLite.delayedCall - Call a function after number of seconds
TweenLite.killDelayedCallsTo - Kill delayed calls (see previous line)
TweenLite.killTweensOf - Kills all tweens of a particular object
TweenLite.removeTween - Removes a tween

TweenLite.removeTween

TweenLite.to

Description: Tweens the target's properties from whatever they are at the time you call the method to whatever you define in the variables parameter.

Disclaimer: Information be wrong and/or outdated - Daniel K. Schneider 17:13, 28 October 2008 (UTC).

Syntax:

 TweenLite.to(target:Object, duration:Number, variables:Object);

You can keep track of an instance if you want to (e.g. to kill it):

 var myTween:TweenLite = TweenLite.to(target:Object, duration:Number, variables:Object);

Alternative object-oriented syntax:

 var myTween:TweenLite = new TweenLite(target:Object, duration:Number, variables:Object);

This is almost equivalent to the above. The former is usually preferrable since it will handle garbage collection.

Mandatory parameters

target:Object Target MovieClip (or any object) whose properties we're tweening
duration:Number Duration (in seconds) of the tween
variables:Object An object containing the end values of all the properties you'd like to have tweened (or if you're using the TweenLite.from() method, these variables would define the BEGINNING values). Putting quotes around values will make the tween relative to the current value. For example, x:"-20" will tween x to whatever it currently is minus 20 whereas x:-20 will tween x to exactly -20.

Here is a simple example that will move a symbol called "mouse" to position x=120 in about 1.5 seconds)

TweenLite.to(clip_mc, 1.5, {x:120}

Properties you can defined in the variables object:

You can change many properties at the same time and this one reason why this library is so nice. In the following example a movie clip called "clip:mc" will move to position x=120, it's alpha will fade to 50% and its volume will fade out completely:

TweenLite.to(clip_mc, 1.5, {alpha:0.5, x:120, volume:0});

alpha:Number: The alpha (opacity level) that the target object should finish at (or begin at if you're using TweenLite.from()). For example, if the target.alpha is 1 when this script is called, and you specify this parameter to be 0.5, it'll transition from 1 to 0.5.

autoAlpha:

Same as changing the "alpha" property but with the additional feature of toggling the "visible" property to false if the alpha ends at 0. It will also toggle visible to true before the tween starts if the value of autoAlpha is greater than zero.

x:Number: To change a MovieClip's x position, just set this to the value you'd like the MovieClip to end up at (or begin at if you're using TweenLite.from()).

y:Number: To change a MovieClip's y position (like above).

scaleX:Number: Scaling in X direction, i.e. making the with smaller or larger

scaleY:Number: Scaling in Y direction, i.e. making the height smaller or larger

rotation:Number: Clock-wise rotation in degrees.

delay:Number: Number of seconds you'd like to delay before the tween begins. This is very useful when sequencing tweens

ease:Function

You can specify a function to use for the easing with this variable. For example, fl.motion.easing.Elastic.easeOut. The Default is Regular.easeOut (and Linear.easeNone for volume).

You can use all the standard AS3 methods defined in fl.motion.easing and fl.transitions.easing

If you want to create your own easing equation use Jack's Custom Ease Builder on-line tool.

Example

TweenLite.to(logo,0.4,{scaleX:1,scaleY:1,alpha:1,ease:Strong.easeInOut,delay:0.8,overwrite:false});

Example of custom function definition and use

 import gs.easing.CustomEase;
 CustomEase.create("myCustomEase", 
  [{s:0,cp:0.509,e:0.612},{s:0.612,cp:0.715,e:0.412},{s:0.412,cp:0.109,e:1}]);
 TweenLite.to(mc, 2, {x:"250", ease:CustomEase.byName("myCustomEase"")});

easeParams:Array: Allows to pass parameters to the ease function (see above)

TweenLite.to(my_mc, 2, {_x:200, ease:Elastic.easeOut, easeParams:[1.5, 2.45]});

volume: Number: To change a MovieClip's volume, i.e. the SoundTransform property. Set this to the value you'd like the MovieClip to end up at (or begin at if you're using TweenLite.from()).

tint:Color_uint

To change a MovieClip's color, set this to the hex value of the color you'd like the MovieClip to end up at(or begin at if you're using TweenLite.from()). An example hex value would be 0xFF0000. If you'd like to remove the color from a MovieClip, just pass null as the value of mcColor.

roundProps:Array
Allows to define inbetween rounding values. E.g.

TweenMax.to(my_mc, 3, {_x:500, _y:0, bezier:[{_x:250, _y:50}]});

onStart:Function: If you'd like to call a function as soon as the tween begins, pass in a reference to it here. This can be useful when there's a delay and you want something to happen just as the tween begins.

onStartParams:Array: An array of parameters to pass the onStart function.

onUpdate:Function: If you'd like to call a function every time the property values are updated (on every frame during the time the tween is active), pass a reference to it here.

onUpdateParams:Array: An array of parameters to pass the onUpdate function (this is optional)

onComplete:Function: If you'd like to call a function when the tween has finished, use this.

onCompleteParams:Array: An array of parameters to pass the onComplete function (this is optional)

overwrite:Int: You can enter 4 values: 0 (NONE) = No tweens are overwritten; 1 (ALL) = All tweens of the same object are completely overwritten immediately when the tween is created; 2 (AUTO) = Searches for and overwrites only individual overlapping properties in tweens that are active when the tween begins; 3 (CONCURRENT): Overwrites all tweens of the same object that are active when the tween begins.

persist:Boolean If true, the TweenLite instance will not automatically be removed by the garbage collector when it is complete. By default, it is false.

renderOnStart:Boolean: If you're using TweenLite.from() (or runBackwards:true) with a delay and want to prevent the tween from rendering until it actually begins, set this special property to true. By default, it's false which causes TweenLite.from() to render its values immediately, even before the delay has expired.

runBackwards:Boolean: Flips the start and end values in a tween. That's the same as using the from() methdod (see below).

TweenLite.from

TweenLite.from(target:Object, duration:Number, variables:Object);

Description: Exactly the same as TweenLite.to(), but instead of tweening the properties from where they're at currently to whatever you define, this tweens them the opposite way - from where you define TO where ever they are now (when the method is called). This is handy for when things are set up on the stage where the should end up and you just want to animate them into place.

Parameters: Same as TweenLite.to(). (see above)

TweenLite.delayedCall

TweenLite.delayedCall(delay:Number,onComplete:Function,onCompleteParams:Array);

Description: Provides an easy way to call any function after a specified number of seconds. Any number of parameters can be passed to that function when it's called too.

Parameters:

delay: Number of seconds before the function should be called.
onComplete: The function to call
onCompleteParams [optional] An array of parameters to pass the onComplete function when it's called.

TweenLite.killTweensOf

TweenLite.killTweensOf(target:Object);

Description: Provides an easy way to kill all tweens of a particular Object/MovieClip. Parameters:

target: Any/All tweens of this Object/MovieClip will be killed.

TweenLite.killDelayedCallsTo

TweenLite.killDelayedCallsTo(function:Function);

Description: Provides an easy way to kill all delayed calls to a particular function (ones that were instantiated using the TweenLite.delayedCall() method). Parameters:

function: Any/All delayed calls to this function will be killed.

TweenLite examples

As a simple example, you could tween the alpha to 50% (0.5) and move the x position of a MovieClip named "clip_mc" to 120 and fade the volume to 0 over the course of 1.5 seconds like so:

import gs.TweenLite;
TweenLite.to(clip_mc, 1.5, {alpha:0.5, x:120, volume:0});

If you want to get more advanced and tween the clip_mc MovieClip over 5 seconds, changing the alpha to 50% (0.5), the x coordinate to 120 using the Back.easeOut easing function, delay starting the whole tween by 2 seconds, and then call a function named "onFinishTween" when it has completed and pass in a few parameters to that function (a value of 5 and a reference to the clip_mc), you'd do so like:

import gs.TweenLite;
import fl.motion.easing.Back;
TweenLite.to(clip_mc, 5, {alpha:0.5, x:120, ease:Back.easeOut,
          delay:2, onComplete:onFinishTween, onCompleteParams:[5, clip_mc]});
function onFinishTween(parameter1_num:Number, parameter2_mc:MovieClip):void {
 trace("The tween has finished! parameters: " + parameter1_num + ", and " + parameter2_mc);
  }

If you have a MovieClip on the stage that is already in its end position and you just want to animate it into place over 5 seconds (drop it into place by changing its y property to 100 pixels higher on the screen and dropping it from there), you could:

import gs.TweenLite;
import fl.motion.easing.Elastic;
TweenLite.from(clip_mc, 5, {y:"-100", ease:Elastic.easeOut});

Sequence of tweens so that they occur one after the other. Just use the delay property and make sure you set the overwrite property to false (otherwise tweens of the same object will always overwrite each other to avoid conflicts). Here's an example where we colorize a MovieClip red over the course of 2 seconds, and then move it to a _y coordinate of 300 over the course of 1 second:

import gs.TweenLite;
TweenLite.to(clip_mc, 2, {mcColor:0xFF0000});
TweenLite.to(clip_mc, 1, {y:300, delay:2, overwrite:false});

TweenFilterLite usage

TweenFilterLite extends the TweenLite class, adding the ability to tween filters (like blurs, glows, drop shadows, bevels, etc.) as well as advanced effects like contrast, colorization, brightness, saturation, hue, and threshold.

Syntax (identical to the TweenLite class), e.g.

TweenFilterLite.to (target:Object, duration:Number, variables:Object);

To understand what filters are, you may read documentation at Adobe:

Flash graphic effects learning guide An Adobe tutorial made for CS3 designers and that also explains concepts.
About filters (Chapter of the Adobe Using Flash (CS3) manual)

To understand what the TweenFilterLite filters do, you also could consult the AS3 or Flex documentation. The parameters of the TweenFilter class are much easier to use than the properties and the methods of the "official" AS3 libraries. However this documentation may help to understand the meaning of these parameters and what kind of values you should use.

flash.filters package (ActionScript 3.0 Language and Components Reference) or
Package flash.filters (Adobe Flex 2.0.1 Language Reference)

Example:

 TweenFilterLite.from (clip_mc, 5, {colorMatrixFilter:{colorize:0xFF0000}})

In addition to the TweenLite parameters described above you can use:

timeScale:Number: Speed up or slow down a tween

globalTimeScale: Globally speed up/down all tweens

blurFilter:Object: Create a blur with one or more of the following properties:; Parameters: blurX, blurY, quality.; Example:

TweenFilterLite.to(clip_mc, 2, {blurFilter:{blurX:1, blurY:2}})

glowFilter:Object: Apply a glow effect to display objects; Parameters: alpha, blurX, blurY, color, strength, quality, inner, knockout,

colorMatrixFilter:Object: Apply various color filters; Parameters: colorize, amount, contrast, brightness, saturation, hue, threshold, relative, matrix,; Example

 TweenFilterLite.to(clip_mc, 2, {colorMatrixFilter:{colorize:0xFF0000, amount:1}});

dropShadowFilter:Object: Will add a drop shadow to an object.; Parameters alpha, angle, blurX, blurY, color, distance, strength, quality; Flex Adobe dropShadowFilter doc

bevelFilter:Object: Create a bevel effect gives, i.e. three-dimensional look; Parameters angle, blurX, blurY, distance, highlightAlpha, highlightColor, shadowAlpha, shadowColor, , gth, quality

TweenMax features

TweenMax builds on top of TweenLite and TweenFilterLite. It uses again the same syntax and just adds some functioalities that are less essential. The only tradeoff is some slight increase in size, i.e. 11K of AS code (which is still very small).

In addition to FilterLite and TweenLite, you can do the following (and more that we may document some other time):

bezier : Array Allows to tween with a bezier array.

TweenMax.to(my_mc, 3, {_x:500, _y:0, bezier:[{_x:250, _y:50}]})

bezierThrough : Array - pass points through which the bezier values should move.

orientToBezier : Array (or Boolean) - MovieClip/Sprite to orients itself in the direction of a Bezier path. The arrays need the following elements: Position property 1 (typically "x"), Position property 2 (typically "y"), Rotational property (typically "rotation"), Number of degrees to add (optional - makes it easy to orient your MovieClip/Sprite properly).

 [["x", "y", "rotation", 0]].

Simple Tweenmax example

The goal is to take a picture and make it look old or otherwise bad as in the following tweenmax-photo-filter.html example. Instead, you might have used the TweenFilterLite library too.

Procedure:

Drag a *.jpg picture into the library
Drag it to the stage and make it a movie clip symbol (Right-click->Convert to symbol). Call it "picture_mc".
Kill the picture on the stage
Drag two copies of the new movie clip symbol to the stage
Name the first one "picture" and the second one "picture2". This way the AS3 code can use them as objects.

AS3 code:

import gs.TweenMax;
import gs.easing.*;
TweenMax.to(picture, 
            5, 
            {colorMatrixFilter:{colorize:0xffcc33, amount:0.4, contrast:0.6, brightness:1.1, saturation:0.4}, 
            ease:Back.easeOut});
TweenMax.to(picture2, 
            5, 
            {colorMatrixFilter:{amount:0.4, contrast:0.3, brightness:2.0, saturation:0.8}, 
            ease:Back.easeOut});

Source:

http://tecfa.unige.ch/guides/flash/ex/greensock/ directory
File tweenmax-photo-filter.fla

TweenGroup usage

Pause/Resume capability

reverse() and/or restart()

Grouping and Sequencing

Tween multiple objects with a single call, including a special "stagger" property that staggers the starting time of each tween

AS3 tweening platform

Contents

Introduction

Tweenlite Usage summary

TweenLite.to

TweenLite.from

TweenLite.delayedCall

TweenLite.killTweensOf

TweenLite.killDelayedCallsTo

TweenLite examples

TweenFilterLite usage

TweenMax features

Simple Tweenmax example

TweenGroup usage

Navigation menu

AS3 tweening platform

Introduction

Tweenlite Usage summary

TweenLite.to

TweenLite.from

TweenLite.delayedCall

TweenLite.killTweensOf

TweenLite.killDelayedCallsTo

TweenLite examples

TweenFilterLite usage

TweenMax features

Simple Tweenmax example

TweenGroup usage

Navigation menu

Slow Search