TweenMax (AS3) - TweenLite on Steroids
- Compatibility: Flash Player 9 and later (ActionScript 3.0) (Click here for the AS2 version)
- File Size added to published SWF: About 8Kb
|
|
|
Join Club GreenSock to get updates and a lot more
DESCRIPTION
TweenMax builds on top of the TweenLite core class and its big brother, TweenFilterLite, to round out the tweening family with popular (though not essential) features like bezier tweening, pause/resume capabilities, easier sequencing, hex color tweening, and more. TweenMax uses the same easy-to-learn syntax as its siblings. In fact, since it extends them, TweenMax can do anything TweenLite and/or TweenFilterLite can do, plus more. So why build 3 classes instead of one? Good question. The goal was to maximize efficiency and minimize file size. Frankly, TweenLite is probably all most developers will need for 90% of their projects, and it only takes up 3k. It's extremely efficient and compact considering its features. But if you need to tween filters or rich imaging effects like saturation, contrast, hue, colorization, etc., step up to TweenFilterLite at 6k (total). Still need more? No problem - snag TweenMax to add extra features jam-packed into 8k (total). See below for a chart describing the differences between the classes. TweenMax introduces an innovative feature called "bezierThrough" that allows you to define points through which you want the bezier curve to travel (instead of normal control points that simply attract the curve). Or use regular bezier curves - whichever you prefer. It'll even handle rotating your object so that it aligns with the direction of the bezier (orientToBezier)! See the sample below. Click to add bezier points.
Other links: AS2 Version | Speed Comparison | Bezier Speed Comparison
FEATURE COMPARISON
| TweenLite | TweenFilterLite | TweenMax | |
File size |
3k | 6k | 8k |
AS2 and AS3 versions with identical syntax |
|||
Extremely fast performance |
|||
Tween ANY numeric property of any object |
|||
Tween multiple properties with a single line of code |
|||
Syncronized tweens |
|||
Use any standard easing equation |
|||
onComplete, onStart, and onUpdate callbacks, including the ability to pass any number of parameters to those functions (onCompleteParams, onStartParams, onUpdateParams) |
|||
Delay any tween by a set amount (good for sequencing) |
|||
Automatic garbage collection |
|||
Tween frames of a MovieClip |
|||
Tween tint of a MovieClip/DisplayObject |
|||
autoAlpha (toggles visibility of an object off when the alpha hits zero) |
|||
Tween the volume of any MovieClip/SoundChannel |
|||
Unique "from()" call that allows you to use the current properties as the end values |
|||
Use relative values |
|||
Tween arrays of numeric values with a single call |
|||
Automatically overwrite tweens of the same object by default in order to avoid conflicts (this behavior can easily be turned off too) |
|||
Pass extra parameters to easing equations (like Elastic.easeOut or Back.easeOut) for added control |
|||
Tween standard filters like Blur, Glow, DropShadow, Bevel, and ColorMatrix |
|||
Simple controls for tweening a MovieClip's/DisplayObject's saturation, hue, brightness, contrast, threshold, and colorization |
|||
Bezier tweening |
|||
Bezier "through" tweening (define points to hit instead of just control points) |
|||
Automatically orient an object's rotation to a Bezier path |
|||
Pause/Resume capability |
|||
Easier sequencing |
|||
Tween multiple objects with a single call, including a special "delayIncrement" property that staggers the starting time of each tween |
|||
isTweening() function for easily determining if an object is currently tweening |
|||
Jump to any point in the tween using the "progress" property |
|||
Tween any number of hex color properties |
|||
Get an array of all TweenMax (and TweenLite and TweenFilterLite) instances that are currently affecting a particular target object. |
|||
Price: |
FREE (supported by donations)
|
||
USAGE
- 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.
- Parameters:
- target : Object - Target 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 TweenMax.from() method, these variables would define the BEGINNING values).
Special Properties:- delay : Number - The 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, mx.transitions.easing.Elastic.easeOut. The Default is Regular.easeOut.
- easeParams : Array - An array of extra parameter values to feed the easing equation. This can be useful when you use an equation like Elastic and want to control extra parameters like the amplitude and period. Most easing equations, however, don't require extra parameters so you won't need to pass in any easeParams.
- autoAlpha : Number - Use it instead of the alpha property to gain the additional feature of toggling the visible property to false when alpha reaches 0. It will also toggle visible to true before the tween starts if the value of autoAlpha is greater than zero.
- volume : Number - To change a MovieClip's or SoundChannel's volume, just set this to the value you'd like the MovieClip/SoundChannel to end up at (or begin at if you're using TweenMax.from()).
- tint : Number - To change a DisplayObject's tint/color, set this to the hex value of the tint you'd like the MovieClip to end up at(or begin at if you're using TweenMax.from()). An example hex value would be 0xFF0000. If you'd like to remove the color from a DisplayObject, just pass null as the value of tint.
- frame : Number - Use this to tween a MovieClip to a particular frame.
- bezier : Array - Bezier tweening allows you to tween in a non-linear way. For example, you may want to tween a DisplayObject's position from the origin (0,0) 500 pixels to the right (500,0) but curve downwards through the middle of the tween. Simply pass as many objects in the bezier array as you'd like, one for each "control point" (see documentation on Flash's curveTo() drawing method for more about how control points work). In this example, let's say the control point would be at x/y coordinates 250,50. Just make sure your my_mc is at coordinates 0,0 and then do: TweenMax.to(my_mc, 3, {_x:500, _y:0, bezier:[{_x:250, _y:50}]});
- bezierThrough : Array - Identical to bezier except that instead of passing bezier control point values, you pass points through which the bezier values should move. This can be more intuitive than using control points.
- orientToBezier : Array (or Boolean) - A common effect that designers/developers want is for a MovieClip/Sprite to orient itself in the direction of a Bezier path (alter its rotation). orientToBezier makes it easy. In order to alter a rotation property accurately, TweenMax needs 4 pieces of information:
- 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)
The orientToBezier property should be an Array containing one Array for each set of these values. For maximum flexibility, you can pass in any number of arrays inside the container array, one for each rotational property. This can be convenient when working in 3D because you can rotate on multiple axis. If you're doing a standard 2D x/y tween on a bezier, you can simply pass in a boolean value of true and TweenMax will use a typical setup, [["x", "y", "rotation", 0]]. Hint: Don't forget the container Array (notice the double outer brackets)
- hexColors : Object - Although hex colors are technically numbers, if you try to tween them conventionally, you'll notice that they don't tween smoothly. To tween them properly, the red, green, and blue components must be extracted and tweened independently. TweenMax makes it easy. To tween a property of your object that's a hex color to another hex color, use this special hexColors property of TweenMax. It must be an OBJECT with properties named the same as your object's hex color properties. For example, if your my_obj object has a "myHexColor" property that you'd like to tween to red (0xFF0000) over the course of 2 seconds, do: TweenMax.to(my_obj, 2, {hexColors:{myHexColor:0xFF0000}}); You can pass in any number of hexColor properties.
- 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)
- renderOnStart : Boolean - If you're using TweenMax.from() 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 TweenMax.from() to render its values immediately, even before the delay has expired.
- overwrite : Boolean - If you do NOT want the tween to automatically overwrite any other tweens that are affecting the same target, make sure this value is false.
- blurFilter : Object - To apply a BlurFilter, pass an object with one or more of the following properties:
- blurX
- blurY
- quality
- glowFilter : Object - To apply a GlowFilter, pass an object with one or more of the following properties:
- alpha
- blurX
- blurY
- color
- strength
- quality
- inner
- knockout
- colorMatrixFilter : Object - To apply a ColorMatrixFilter, pass an object with one or more of the following properties:
- colorize
- amount
- contrast
- brightness
- saturation
- hue
- threshold
- relative
- matrix
- dropShadowFilter : Object - To apply a DropShadowFilter, pass an object with one or more of the following properties:
- alpha
- angle
- blurX
- blurY
- color
- distance
- strength
- quality
- bevelFilter : Object - To apply a BevelFilter, pass an object with one or more of the following properties:
- angle
- blurX
- blurY
- distance
- highlightAlpha
- highlightColor
- shadowAlpha
- shadowColor
- strength
- quality
- Description: Exactly the same as TweenMax.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 the way the should end up and you just want to tween them to where they are.
- Parameters: Same as TweenMax.to(). (see above)
- Description: Provides an easy way to sequence a set of tweens, one after the other. It's essentially the same thing as making a bunch of individual TweenMax.to() calls on the object with overwrite set to false, and the delays stacked.
- Parameters:
- target : Object - The object whose properties to tween.
- tweenObjects : Array - An array of tween objects. IMPORTANT: each object must contain a "time" property defining the duration of that tween. Example: TweenMax.sequence(mc, [{time:1, x:"200"}, {time:2, autoAlpha:0, onComplete:myFunction}]);
- Description: Provides an easy way to tween multiple objects to the same values. It also accepts a few special properties, one of which is "delayIncrement" which staggers the start time of each tween. For example, you might want to have 5 MovieClips move down 100 pixels while fading out, and stagger the start times slightly by 0.2 seconds, you could do:
TweenMax.allTo([mc1, mc2, mc3, mc4, mc5], 1, {y:"100", alpha:0, delayIncrement:0.2}); - Parameters:
- targets : Array - An array of objects to tween.
- duration : Number - Duration (in seconds) of the tween
- vars : Object - An object containing the end values of all the properties you'd like to have tweened (or if you're using the TweenMax.allFrom() method, these variables would define the BEGINNING values).
Special Properties:- IMPORTANT: Accepts the exact same special properties as the to() and from() methods (see list above), and adds these:
- delayIncrement : Number - delay (in seconds) between each tween's start time. This is useful for staggering the tweens.
- onCompleteAll : Function - If you'd like to call a function when ALL of the tweens have finished, use this.
- onCompleteAllParams : Array - An array of parameters to pass the onCompleteAll function
- Description: Exactly the same as TweenMax.allTo(), 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. This is handy for when things are set up on the stage the way they should end up and you just want to tween them into place.
- Parameters: Same as TweenMax.allTo(). (see above)
- Description: Pauses the tween. When a tween is paused, it's "paused" property is set to true.
- Description: Resumes a paused tween. When a tween is resumed, it's "paused" property is set to false.
- Description: Gets an array of all tweens affecting the target object.
- Parameters:
- target : Object - The object whose tweens you want to get.
- Description: Checks to see if a particular object is currently being tweened (paused tweens don't count).
- Parameters:
- target : Object - The object whose tweens you want to check.
- Description: Returns an array of all tweens (including paused tweens).
- 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 - Number of seconds before the function should be called.
- onComplete : Function - The function to call
- onCompleteParams : Array - [optional] An array of parameters to pass the onComplete function when it's called.
- Description: Provides an easy way to kill all tweens of a particular Object/MovieClip. You can optionally force it to immediately complete (which will also call the onComplete function if you defined one)
- Parameters:
- target : Object - Any/All tweens of this Object will be killed.
- complete : Boolean - If true, the tweens for this object will immediately complete (go to the ending values and call the onComplete function if you defined one).
- Description: Provides an easy way to kill all delayed calls to a particular function (ones that were instantiated using the TweenMax.delayedCall() method).
- Parameters:
- function : Function - Any/All delayed calls to this function will be killed.
- Description: Kills ALL tweens (but not delayedCalls).
- Parameters:
- complete: Boolean - If you'd like to force the tweens to complete, set this to true. (it's false by default)
- Description: Kills ALL delayedCalls.
- Parameters:
- complete: Boolean - If you'd like to force the delayedCall to complete, set this to true. (it's false by default)
- Description: Provides a way to pause all TweenMax tweens and/or delayedCalls (not TweenLite/TweenFilterLite tweens or delayedCalls).
- Parameters:
- tweens: To pause tweens, set this to true. (it is true by default)
- delayedCalls: To pause delayedCalls, set this to true. (it is false by default)
- Description: Resumes all TweenMax tweens
- Parameters:
- tweens: To resume tweens, set this to true. (it is true by default)
- delayedCalls: To resume delayedCalls, set this to true. (it is false by default)
- Description: Kills a single tween instance.
- Parameters:
- tween: The TweenMax/TweenFilterLite/TweenLite instance that you'd like to kill.
EXAMPLES
-
import gs.TweenMax;
-
TweenMax.sequence(clip_mc, [{time:2, alpha:0.5}, {time:1, y:300}]);
-
import gs.TweenMax;
-
import fl.motion.easing.Back;
-
TweenMax.to(clip_mc, 5, {alpha:0.5, x:120, ease:Back.easeOut, delay:2, onComplete:onFinishTween, onCompleteParams:[5, clip_mc]});
-
function onFinishTween(argument1:Number, argument2:MovieClip):void {
-
trace("The tween has finished! argument1 = " + argument1 + ", and argument2 = " + argument2);
-
}
-
import gs.TweenMax;
-
import fl.motion.easing.Elastic;
-
TweenMax.from(clip_mc, 5, {y:"-100", ease:Elastic.easeOut});
FAQ
- How do I install the class? Do I have to import it on every frame?
Just make sure the "gs" folder from the download is in the same folder as your FLA file. Keep the class files in the "gs" folder (don't remove them). That's it. And, yes, just like any Class, you need to import TweenMax at the top of any frame that contains code referencing it. This does NOT add extra Kb to your file size very time you import it. Flash is smart enough to embed it once and all the other import statments just act as a "pointer" to the embedded Class. -
Why doesn't the tweening engine selectively overwrite ONLY tweens that are affecting the same property? How can I achieve this effect?
As you can tell from the speed tests, performance is a primary concern. Searching through potentially hundreds or thousands of tweens for overlapping tween properties can get expensive in terms of performance. Therefore, the TweenLite family opted for a much faster approach: all or nothing. But don't worry - in almost every case, you can achieve the result you're after with a little bit of extra code. Trust me, it's worth the increased speed and efficiency you'll get.You can selectively kill tweens by keeping track of the TweenMax instance that’s returned by the to() or from() methods, and calling removeTween() on them. For example, if you want to have a button scale up when you roll over it, and scale back down when you roll off (those tweens should overwrite each other) but you don't want them to overwrite a from() call that fades the button in over the course of 2 seconds, you could do:
-
myButton.addEventListener(MouseEvent.MOUSE_OVER, onMouseOver);
-
myButton.addEventListener(MouseEvent.MOUSE_OUT, onMouseOut);
-
var scaleTween:TweenMax;
-
TweenMax.from(myButton, 2, {alpha:0, overwrite:false});
-
function onMouseOver($e:MouseEvent):void {
-
TweenMax.removeTween(scaleTween);
-
scaleTween = TweenMax.to(myButton, 0.5, {scaleX:1.2, scaleY:1.2, overwrite:false});
-
}
-
function onMouseOut($e:MouseEvent):void {
-
TweenMax.removeTween(scaleTween);
-
scaleTween = TweenMax.to(myButton, 0.5, {scaleX:1, scaleY:1, overwrite:false});
-
}
Remember, other tweens of the same object will always be overwritten by default. You must set overwrite:false to avoid that behavior. The above example is essentially allowing you to selectively handle overwriting yourself instead of relying on the tweening engine to do the "all or nothing" technique.
-
- How do I pause/resume a tween?
Simple. Whenever you do a to() or from() tween, the function returns a reference to that particular tween, so just keep track of that and call pause() or resume() on it, like this:-
import gs.TweenMax;
-
var myTween = TweenMax.to(mc, 2, {colorMatrixFilter:{colorize:0xFF0000, amount:1}});
-
myTween.pause();
-
myTween.resume();
-
- How do I get/set the progress of a tween?
Just use the "progress" property. The value should always be between 0 and 1 (0 = tween is at its starting values, 0.5 = half-way finished, and 1 = the tweening is complete) Whenever you do a to() or from() tween, the function returns a reference to that particular tween, so just keep track of that and call get/set the progress property, like this:-
import gs.TweenMax;
-
var myTween = TweenMax.to(mc, 2, {colorMatrixFilter:{colorize:0xFF0000, amount:1}});
-
myTween.progress = 0.75;
-
- Why aren't my filters working?
If you're using a filter that has an alpha property, try setting it to 1. The default alpha value is zero, so the filter may be working just fine, but you're not seeing it. - Do the properties have to be in a specific order?
Nope. The only thing that matters is that the first parameter is the object you're tweening, the second parameter is the time (in seconds), and the third parameter contains all the properties you want to tween (in any order). So TweenMax.to(clip_mc, 1, {colorMatrixFilter:{colorize:0xFF0000, amount:1}}) is the same as TweenMax.to(clip_mc, 1, {colorMatrixFilter:{amount:1, colorize:0xFF0000}}); - Do I have to purchase a license to use this code? Can I use it for commercial purposes?
TweenMax is free. You're welcome to use it for commercial purposes - I only ask that you donate what you think the class is worth in your project(s), and consider joining Club GreenSock which gives you some bonus classes, updates, and more. If you want to use one (or more) of my classes in your commerical software product which would entail distributing the class files, please get my permission first by e-mailing me at jack -at- greensock.com.
Need Help?
Feel free to e-mail me a question. I'd highly recommend joining Club GreenSock to get prioritized access to my time in answering your question, and so that you receive updates and lots more. When you e-mail your question, please include a simplified FLA file (and any class files) that clearly demonstrates the problem and provide a brief explanation.
on April 6th, 2008 at 12:13 pm
Thank you sooooooooo much!!!
That is simply “perfect” ;)
on April 6th, 2008 at 5:02 pm
I’m glad with this release! Thank you very much Jack! :)
pd: bezierThrough is pretty cool, great idea (I never like the bezier system)
on April 7th, 2008 at 5:46 am
Great release - thank you! :) I especially like the new tween sequencing options which will save me a lot of time having to test delay and tween numbers and see which combination fits! Love the pause/resume too. I’ve used TweenLite in all my games to date, and this will replace it without hesitation.
on April 7th, 2008 at 6:51 pm
It’s amazing. Thanks a lot for your work. :-)
on April 8th, 2008 at 3:29 am
Hi Jack,
First of all thanks for this great tweening engine!
Just a notice to anyone who is experiencing problems tweening a “frame” property:
I just upgraded from Tweenlite v 5.87 to the latest Version (6.1) and i found out that it didn’t work anymore.
The problem was that i use TweenLite to tween a setter/getter called “frame” which TweenLite seems to work with internally on the target since version 6.
Best regards,
Thomas
on April 8th, 2008 at 7:53 am
Thanks! These classes are awesome! They have become an invaluable part of my AS3 coding arsenal . . . finding uses in almost every project on which I’m working. I made a donation today to support your work and encourage others to do the same.
on April 8th, 2008 at 1:46 pm
Nice job Jack! Very impressive!
on April 8th, 2008 at 5:03 pm
Unbelievable , great , beautiful work !!
Thank you Jack !! it is what we were waiting for !!
on April 8th, 2008 at 6:10 pm
Absolutely brilliant, Jack.
Much thanks =)
on April 8th, 2008 at 6:15 pm
Absolutely incredible. Thank you so much for all your releases. TweenLite especially has been magical, even in 3D.
on April 8th, 2008 at 9:31 pm
i don’t know what to say…
this is just too good to be true.
thank u so much, jack!
on April 8th, 2008 at 10:12 pm
Thank you so much for all of your hard work and for freely releasing TweenLite, it’s been a tremendous tool for me while learning and advancing my understanding of actionscript! :)
on April 8th, 2008 at 10:38 pm
This is really great. I really like the feature of tweening through beizer points.
on April 9th, 2008 at 12:40 am
Man…. you are THE MAN!
I love your work and as always… its very impressive…. I’ve been tweening with tweenlite like crazy…. but now… its MAX-crazy time!
keep up the great work…
by the way… I love combining your tween engine with my new hobby (Papervision3d)… they work awsome together.
on April 9th, 2008 at 8:23 am
Awsome! I was fidling around, and guess what… bezier tweening is not just for position objects! you can bezier tween anything (i guess) as long as there are two pair of properties of an object. The two below tweens do the same thing.
// there are two children on the stage called mmO and wwO
import gs.TweenMax
import fl.motion.easing.*
var mm=1
var zz=100
var ww=1
mmO.x=wwO.x=mm
mmO.y=wwO.y=zz
TweenMax.to(wwO,2,{x:100,y:100,bezier:[{x:250,y:250}],ease:Linear.easeIn,onUpdate:tr})
TweenMax.to(this,2,{mm:100,zz:100,bezier:[{mm:250,zz:250}],ease:Linear.easeIn,onUpdate:tr})
function tr () {
mmO.x=mm+10
mmO.y=zz+10
}
on April 9th, 2008 at 11:01 am
Have I overlooked any .fla source files that will show usage for things like sequencing with an array, tweening filter properties, etc. other than the ones above? Thanks!
on April 9th, 2008 at 2:29 pm
I’m so glad you brought that up, Stephanie. I just updated the samples that come with TweenMax so that you can see how to tween filters, basic properties, etc. There are now 4 FLA files included in the download.
on April 10th, 2008 at 9:25 am
Hey Jack,
Amazing work. Can’t wait to take the new code for a spin. I’m definitely sending out some donation love your way.
Quick question. Are the filesizes that you quote for each of the libraries cumulative? In other words, if I use TweenMax is it 8k or 17k (8k + 6k + 3k)?
on April 10th, 2008 at 9:35 am
Great question, Paul. The filesizes are TOTAL, not cumulative. So TweenMax combines TweenLite (3k) with TweenFilterLite (another 3k) with some new stuff (2k), adding up to a TOTAL of 8k.
on April 10th, 2008 at 4:46 pm
Omg, you are the god of Tween ^^
Very nice work :) TweenMax its very impressive.
on April 11th, 2008 at 3:11 pm
I agree with everyone else. TweenMax is the absolute greatest - now that it consolidates the other 2 engines, and still VERY small size. As a designer / flash developer, i highly recommend this to everyone! Thank you for all of your hard work. Keep it up!
on April 18th, 2008 at 10:41 pm
I’d like to praise you for THE greateste piece of programming I’ve seen in ActionScript… Small, fast, reliable… What else? ;)
on April 24th, 2008 at 12:01 pm
Again, you rock brother — TweenMax is a God send and just in the nick-o-time especially with the BezierTo and OrientToBezier funcs — fantastic, I’m already use this on Pro Projects right now — and yes I will donate as soon as I can paid from the client :) You deserve it, seriously.
ROCK ON! Ozzy
on April 24th, 2008 at 11:54 pm
TweenMax is awesome!
I made a nifty looping slideshow with crossfades:
import gs.TweenMax;
import fl.motion.easing.*
TweenMax.allTo([mc1, mc2, mc3, mc4], 0, {autoAlpha:0, onCompleteAll:loop, overwrite:false});
function loop(): void{
TweenMax.allTo([mc1, mc2, mc3, mc4], 3, {autoAlpha:1, delayIncrement:3, onCompleteAll:loop, ease:Linear.easeOut, overwrite:false});
TweenMax.allTo([mc1, mc2, mc3, mc4], 1, {autoAlpha:0, delay:3, delayIncrement:3, ease:Linear.easeOut, overwrite:false});
}
on May 5th, 2008 at 3:58 am
Very amazing tweening engine. I replaced it with the Adobe tween class in my current project, and well.. Tweens where smooth again :). I’m going to develop futher with it, hoping to find the perfect tween engine in this.
Keep on the good work!