TweenMax – TweenLite on Steroids

• Version: 11.2, Updated 2010-03-06
• File size added to compressed SWF: About 8.7kb (base), or 17.6kb with default plugins and OverwriteManager

What's new in v11?
v11 represents the biggest update to the platform ever, by far. Please check out the official announcement page for details about the changes and new features.

Description

TweenMax extends the extremely lightweight, fast TweenLite engine, adding many useful features like timeScale, AS3 event dispatching, updateTo(), yoyo, repeat, repeatDelay, rounding, and more. It also activates many extra plugins by default, making it extremely full-featured. Since TweenMax extends TweenLite, it can do anything TweenLite can do plus much more. The syntax is identical. With plenty of other tweening engines to choose from, here's why you might want to consider TweenMax:

• SPEED - TweenMax has been highly optimized for maximum performance. See some speed comparisons here.
• Feature set - In addition to tweening any numeric property of any object, TweenMax can tween filters, hex colors, volume, tint, frames, saturation, contrast, hue, colorization, brightness, and even do bezier tweening, orientToBezier, round values, jump to any point in the tween with the currentTime or currentProgress property, automatically rotate in the shortest direction, plus LOTS more. Overwrite management is an important consideration for a tweening engine as well which is another area where the GreenSock Tweening Platform shines. You have options for AUTO overwriting or you can manually define how each tween will handle overlapping tweens of the same object.
• Expandability - With its plugin architecture, you can activate as many (or as few) features as your project requires. Write your own plugin to handle particular special properties in custom ways. Minimize bloat, and maximize performance.
• Sequencing, grouping, and management features - TimelineLite and TimelineMax make it surprisingly simple to create complex sequences or groups of tweens that you can control as a whole. play(), pause(), restart(), or reverse(). You can even tween a timeline's currentTime or currentProgress property to fastforward or rewind the entire timeline. Add labels, gotoAndPlay(), change the timeline's timeScale, nest timelines within timelines, and lots more.
• Ease of use - Designers and Developers alike rave about how intuitive the platform is.
• Updates - Frequent updates and feature additions make the GreenSock Tweening Platform reliable and robust.
• AS2 and AS3 - Most other engines are only developed for AS2 or AS3 but not both.

Getting started

If you're new to the GreenSock Tweening Platform, check out the "getting started" page. You'll be up and running in no time.

Documentation

Please view full ASDoc documentation here. For your convenience, the special properties are listed below as well, but to read up on all the methods and properties, definitely check the ASDocs.

Interactive demo - tweening basics

Special properties

You can pass any of the following special properties in through the constructor's "vars" parameter like new TweenMax(mc, 1, {x:100, delay:1.5, paused:true, onComplete:myFunction}) to control various aspects of the tween:

• delay : Number - Number of seconds (or frames if useFrames is true) that should elapse before the tween begins.
• paused : Boolean - Sets the initial paused state of the timeline (by default, tweens automatically begin playing)
• useFrames : Boolean - If useFrames is set to true, the tween's timing mode will be based on frames. Otherwise, it will be based on seconds/time. NOTE: a tween's timing mode is always determined by its parent timeline.
• ease : FunctionUse any standard easing equation to control the rate of change. For example, Elastic.easeOut. The Default is Quad.easeOut.
• easeParams : Array An Array of extra parameters to feed the easing equation (beyond the standard first 4). This can be useful when using an ease 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.
• reversed : Boolean - If true, the tween will be reversed initially. This does not swap the starting/ending values in the tween - it literally changes its orientation/direction. Imagine the playhead moving backwards instead of forwards. This does NOT force it to the very end and start playing backwards. It simply affects the orientation of the tween, so if reversed is set to true initially, it will appear not to begin because it is already at the beginning. To cause it to play backwards from the end, set reversed to true and then set the currentProgress property to 1 immediately after creating the tween (or set the currentTime to the duration).
• immediateRender : Boolean Normally when you create a tween, it begins rendering on the very next frame (when the Flash Player dispatches an ENTER_FRAME event) unless you specify a delay. This allows you to insert tweens into timelines and perform other actions that may affect its timing. However, if you prefer to force the tween to render immediately when it is created, set immediateRender to true. Or to prevent a tween with a duration of zero from rendering immediately, set this to false.
• overwrite : int Controls how (and if) other tweens of the same target are overwritten by this tween. There are several modes to choose from, and TweenMax automatically calls OverwriteManager.init() if you haven't already manually dones so, which means that by default AUTO mode is used (please see http://www.greensock.com/overwritemanager/ for details and a full explanation of the various modes):
  • NONE (0) (or false)
  • ALL_IMMEDIATE (1) (or true)
  • AUTO (2) - this is the default mode for TweenMax.
  • CONCURRENT (3)
  • ALL_ONSTART (4)
  • PREEXISTING (5)

  Example: TweenMax.to(mc, 1, {x:100, overwrite:5});

• repeat : int - Number of times that the tween should repeat. To repeat indefinitely, use -1.
• repeatDelay : Number - Amount of time in seconds (or frames for frames-based tweens) between repeats.
• yoyo : Boolean - Works in conjunction with the repeat property, determining the behavior of each cycle. When yoyo is true, the tween will go back and forth, appearing to reverse every other cycle (this has no affect on the "reversed" property though). So if repeat is 2 and yoyo is false, it will look like: start - 1 - 2 - 3 - 1 - 2 - 3 - 1 - 2 - 3 - end. But if repeat is 2 and yoyo is true, it will look like: start - 1 - 2 - 3 - 3 - 2 - 1 - 1 - 2 - 3 - end.
• startAt : Object Allows you to define the starting values for each property. Typically, TweenMax uses the current value (whatever it happens to be at the time the tween begins) as the start value, but startAt allows you to override that behavior. Simply pass an object in with whatever properties you'd like to set just before the tween begins. For example, if mc.x is currently 100, and you'd like to tween it from 0 to 500, do TweenMax.to(mc, 2, {x:500, startAt:{x:0}});
• onInit : Function - A function that should be called just before the tween inits (renders for the first time). Since onInit runs before the start/end values are recorded internally, it is a good place to run code that affects the target's initial position or other tween-related properties. onStart, by contrast, runs AFTER the tween inits and the start/end values are recorded internally. onStart is called every time the tween begins which can happen more than once if the tween is restarted multiple times.
• onInitParams : Array - An Array of parameters to pass the onInit function.
• onStart : Function - A function that should be called when the tween begins (when its currentTime is at 0 and changes to some other value which can happen more than once if the tween is restarted multiple times).
• onStartParams : Array - An Array of parameters to pass the onStart function.
• onUpdate : Function A function that should be called every time the tween's time/position is updated (on every frame while the tween is active)
• onUpdateParams : Array - An Array of parameters to pass the onUpdate function
• onRepeat : Function - A function that should be called every time the tween repeats
• onRepeatParams : Array - An Array of parameters to pass the onRepeat function
• onComplete : Function - A function that should be called when the tween has completed. To sense when a tween has reached its starting point again after having been reversed, use onReverseComplete.
• onCompleteParams : Array - An Array of parameters to pass the onComplete function
• onReverseComplete : Function - A function that should be called when the tween has reached its starting point again after having been reversed
• onReverseCompleteParams : Array - An Array of parameters to pass the onReverseComplete function
• onStartListener : Function - A function to which the TweenMax instance should dispatch a TweenEvent when it begins. This is the same as doing myTween.addEventListener(TweenEvent.START, myFunction);
• onUpdateListener : Function - A function to which the TweenMax instance should dispatch a TweenEvent every time it updates values. This is the same as doing myTween.addEventListener(TweenEvent.UPDATE, myFunction);
• onCompleteListener : Function - A function to which the TweenMax instance should dispatch a TweenEvent when it completes. This is the same as doing myTween.addEventListener(TweenEvent.COMPLETE, myFunction);
• onReverseCompleteListener : Function A function to which the TweenMax instance should dispatch a TweenEvent when it completes in the reverse direction. This is the same as doing myTween.addEventListener(TweenEvent.REVERSE_COMPLETE, myFunction);
• onRepeatListener : Function A function to which the TweenMax instance should dispatch a TweenEvent when it repeats. This is the same as doing myTween.addEventListener(TweenEvent.REPEAT, myFunction);

Plugins

Plugins allow you to expand the capabilities of TweenLite/Max by handling specific properties in unique ways. Each plugin is associated with a special property name and it takes responsibility for handling that property. For example, the FrameLabelPlugin is associated with the "frameLabel" special property 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, TweenMax 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 shows interactive examples of each plugin and the assocaited code so that it's easy to see the correct syntax.

TweenMax automatically activates many plugins by default, but you can change which plugins it activates by opening the class file and commenting or uncommenting the necessary lines towards the top of the class (clearly labeled).

Sample code

NOTE: All sample code is in AS3, but the AS2 version works exactly the same except the property names may be different, like "_x" instead of "x", "_alpha" instead of "alpha", etc. And in AS3, alpha/scaleX/scaleY go from 0-1 whereas in AS2, _alpha/_xscale/_yscale go from 0-100. This has nothing to do with TweenLite/Max - it's just a change Adobe made in the AS3 language.

FAQ

1. Is the new version of TweenMax backwards compatible with v10?
   The short answer is "yes, mostly", but I'd strongly encourage you to check out the official announcement page for details because a few things have changed.
2. I don't want to use v11 - can I get a legacy copy of v10?
   Sure. But I do not plan to update previous versions. v10 was very stable and you can get it here: Download AS2 | Download AS3
3. How do I activate extra plugins?
   Check out the Plugin Explorer above. Not only does it provide interactive examples of each plugin, but it also writes the activation code for you and shows how many kb the plugins will cost.
4. How do I install the class? Do I have to import it on every frame?
   Please refer to the "getting started" page.
5. Can I set up a sequence of tweens so that they occur one after the other?
   Of course! That's precisely what TimelineLite and TimelineMax are for. But if file size is a big concern and you don't need all the fancy extras those tools offer, you could just use the delay property in TweenMax. Here's an example where we tint 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:
   PLAIN TEXT
   Actionscript:

   1. import com.greensock.TweenMax;
   2. TweenMax.to(mc, 2, {tint:0xFF0000});
   3. TweenMax.to(mc, 1, {y:300, delay:2});

6. Do the properties have to be in a specific order?
   Nope. So TweenMax.to(mc, 1, {x:100, y:200, alpha:0.5}) is the same as TweenMax.to(mc, 1, {alpha:0.5, y:200, x:100});
7. Is there a way I can get code hinting and strict datatyping in the vars object I pass to TweenLite/TweenMax?
   Sure, the TweenMaxVars class does exactly that.
8. Do I have to purchase a license to use this code? Can I use it for commercial purposes?
   You may use the code at no charge in commercial or non-commercial web sites, games, components, applications, and other software as long as end users are not charged a fee of any kind to use your product or gain access to it. If your client pays you a one-time fee to create the site/product, that's perfectly fine and qualifies under the "no charge" license. If multiple end users are charged a usage/access/license fee of any kind, please simply sign up for a corporate Club GreenSock membership which comes with a special commercial license granting you permission to do so. See http://www.greensock.com/club/ for details. Club GreenSock members get several nifty bonus plugins, classes, update notifications, SVN access, and more. Your donations keep this project going. Please see the licensing page for details on licensing.

Need help?

Feel free to post your question on the forums. 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.