[AS3] Tween Engine (TweenLite)

TweenBencher 을 이용해서 AS3용 Tween 엔진을 테스트 해 봤다. 1등은 단연 Simple AS3 Tween으로 나왔는데 이것은 따로 클래스화 되어 있는 것이 아니고 fl.motion.easing.Exponential 의 easeInOut 함수만을 따로 빼서 직접 width을 적용한 형태라서 빠를 수 밖에 없다. 테스트를 하지 않은 fl 기본 트윈 클래스나 기타 다른 것들은 비교할만한 속도를 내지 못하여 제외 하였다.

비교 대상이 되는 것들은 Tweener와 TweenLite이다. Tweener은 그 사용법과 Bezier 곡선 처리 기능을 제공하기 때문에 사용성면에서 좋은 엔진이지만 많은 기능들이 포함되어 있는 만큼 속도는 약간 떨어진다.








Benchmark results: Simple AS3 Tween
------------------
125 Sprites    ::    Start Lag: 0 seconds    ::    FPS: 57
250 Sprites    ::    Start Lag: 0 seconds    ::    FPS: 57
500 Sprites    ::    Start Lag: 0 seconds    ::    FPS: 55
1000 Sprites    ::    Start Lag: 0 seconds    ::    FPS: 47
2000 Sprites    ::    Start Lag: 0.01 seconds    ::    FPS: 38
4000 Sprites    ::    Start Lag: 0.06 seconds    ::    FPS: 26

Benchmark results: TweenLite
------------------
125 Sprites    ::    Start Lag: 0 seconds    ::    FPS: 61
250 Sprites    ::    Start Lag: 0 seconds    ::    FPS: 55
500 Sprites    ::    Start Lag: 0.01 seconds    ::    FPS: 40
1000 Sprites    ::    Start Lag: 0.01 seconds    ::    FPS: 31
2000 Sprites    ::    Start Lag: 0.02 seconds    ::    FPS: 23
4000 Sprites    ::    Start Lag: 0.18 seconds    ::    FPS: 19

Benchmark results: Tweener
------------------
125 Sprites    ::    Start Lag: 0.11 seconds    ::    FPS: 56
250 Sprites    ::    Start Lag: 0.02 seconds    ::    FPS: 61
500 Sprites    ::    Start Lag: 0.06 seconds    ::    FPS: 46
1000 Sprites    ::    Start Lag: 0.2 seconds    ::    FPS: 33
2000 Sprites    ::    Start Lag: 0.45 seconds    ::    FPS: 25
4000 Sprites    ::    Start Lag: 1.4 seconds    ::    FPS: 17

TweenLite는 filter에 관련된 기능들은 TweenFilterLite로 따로 빠져있다. 특별한 기능이 아닌 오브젝트의 모션 처리는 x,y,scaleX, scaleY, width, height, alpha 등과 추가하면 color 적용일 것이다. TweenLite는 tint 속성으로 그것을 대신하고 있다. 기본적인 사용법은 아래와 같다.

import gs.TweenLite;
TweenLite.to(mc, 1, {x:46, y:43, scaleX:1, scaleY:1, rotation:0, alpha:1, tint:0x3399ff});

사용법이 Tweener와 많은 부분 흡사하다. mc는 타겟이되는 Object, 1은 모션 time이고 {} 오브젝트 형태로 적용 속성들과 모션 함수를 적용할 수가 있다. ease 속성으로 모션 함수를 적용할 수가 있는데 함수는 fl.motion.easing 패키지 안에 있는 함수를 적용하게 되므로 fl.motion.easing 패키지를 import 시켜서 사용하면 된다. 그리고 Tweener에서와 같이 onStart, onUpdate, onComplete 를 지원한다. 아래 예,

        import gs.TweenLite;
        import fl.motion.easing.Back;
        TweenLite.to(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);
        }

USAGE

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

• 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:
  1. target: Target MovieClip (or any object) whose properties we're tweening
  2. duration: Duration (in seconds) of the tween
  3. variables: 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 are some examples of properties you might include:
     • alpha: 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.
     • x: 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()).

     Special Properties (**Optional**):

     • delay: The number of seconds you'd like to delay before the tween begins. This is very useful when sequencing tweens
     • ease: 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.
     • easeParams: 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: 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.
     • volume: To change a MovieClip's volume, just set this to the value you'd like the MovieClip to end up at (or begin at if you're using TweenLite.from()).
     • tint: 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 tint. Before version 5.8, tint was called mcColor (which is now deprecated and will likely be removed at a later date although it still works)
     • onStart: 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: An array of parameters to pass the onStart function.
     • onUpdate: 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: An array of parameters to pass the onUpdate function (this is optional)
     • onComplete: If you'd like to call a function when the tween has finished, use this.
     • onCompleteParams: An array of parameters to pass the onComplete function (this is optional)
     • overwrite: 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.

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(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:
  1. delay: Number of seconds before the function should be called.
  2. onComplete: The function to call
  3. onCompleteParams [optional] An array of parameters to pass the onComplete function when it's called.

TweenLite.killTweensOf(target:Object, complete:Boolean);

• 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:
  1. target: Any/All tweens of this Object/MovieClip will be killed.
  2. complete: If true, the tweens for this object will immediately complete (go to the ending values and call the onComplete function if you defined one).

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:
  1. function: Any/All delayed calls to this function will be killed.

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:

1. import gs.TweenLite;
2. 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:

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

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:

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

FAQ

1. Can I set up a sequence of tweens so that they occur one after the other?
   Of course! 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:
   1. import gs.TweenLite;
   2. TweenLite.to(clip_mc, 2, {tint:0xFF0000});
   3. TweenLite.to(clip_mc, 1, {y:300, delay:2, overwrite:false});

2. 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 TweenLite.to(clip_mc, 1, {scaleX:120, y:200, x:1}) is the same as TweenLite.to(clip_mc, 1, {x:1, y:200, scaleX:120});

3. Why are TweenLite and TweenFilterLite split into 2 classes instead of building all the functionality into one class?
   1. File size. Only a portion of projects out there require tweening of filters. Almost every project I work on uses TweenLite, but only a few require tweening filters (TweenFilterLite). TweenLite is 2k whereas TweenFilterLite is 5k. Again, one of the stated purposes of TweenLite is to minimize file size & code bloat. If someone only wants to use TweenFilterLite, fine. But I think many people appreciate being able to use the most lightweight option for their needs and shave off the 3k when possible.
   2. Speed. Tweening filters is a more complex task. There are additional if/else statements and calculations in the rendering loop inside TweenFilterLite which could potentially slow things down a bit, even for non-filter tweens (I doubt anyone would notice a difference unless they’re running hundreds or thousands of simultaneous tweens, but I’m a big fan of keeping things as efficient & fast as possible)

4. Do I have to pay for a license to use this code? Can I use it for commercial purposes?
   Feel free to take the code and use it as you wish, even for commercial purposes. Some people have requested the ability to donate money to reward the work I put into the class(es), so i put a PayPal "donate now" button at the top and bottom of the page, but you certainly don't need to donate anything. I'm just glad to help the Flash community.

5. Are TweenLite and TweenFilterLite better than Tweener, Fuse, MC Tween, and all the other tweening engines out there?
   Maybe, maybe not. It all depends on your objectives, coding style, etc. I certainly don't claim that TweenLite & TweenFilterLite are superior to all other tweening engines, but in terms of the power-to-file-size ratio, I certainly haven't seen anything that comes close. Feedback has been overwhelmingly positive. I've used TweenLite for many years and it hasn't let me down. I never found myself needing features that are available in another tweening engine. But hey, to each his own.

OBJECTIVES

• Minimize file size
• Maximize flexibility and efficiency by extending the TweenLite class. That way, if you don't need to tween filters, you can just use TweenLite (about 2k); otherwise, this class will only add another 3k (5k total)
• Minimize the amount of code required to initiate a tween
• Maximize performance
• Allow for very flexible callbacks (onComplete, onUpdate, onStart, all with the ability to pass any number of parameters)

FITLERS & PROPERTIES:

• type:"Blur" -
  blurX, blurY, quality
• type:"Glow" -
  alpha, blurX, blurY, color, strength, quality
• type:"Color" -
  colorize, amount, contrast, brightness, saturation, hue, threshold, relative
• type:"DropShadow" -
  alpha, angle, blurX, blurY, color, distance, strength, quality
• type:"Bevel" -
  angle, blurX, blurY, distance, highlightAlpha, highlightColor, shadowAlpha, shadowColor, strength, quality

USAGE

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

• 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:
  1. target: Target DisplayObject whose properties we're tweening
  2. duration: Duration (in seconds) of the tween
  3. variables: An object containing the end values of all the properties you'd like to have tweened (or if you're using the TweenFilterLite.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 are some examples of properties you might include:
     • blurX
     • blurY
     • color: An example for red would be 0xFF0000. Several filters use this property, like DropShadow and Glow
     • colorize: Only used with a type:"Color" tween to colorize an entire MovieClip.
     • amount: Only used to control the amount of colorization.

     Special Properties:

     • type: REQUIRED. A string that indicates what type of filter you're tweening. Possible values are: "Color" (for all image effects like colorize, brightness, contrast, saturation, and threshold), "Blur", "Glow", "DropShadow", or "Bevel"
     • delay: Number of seconds to delay before the tween begins. This can be very useful when sequencing tweens.
     • ease: 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.
     • easeParams: 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: 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.
     • volume: To change a MovieClip's volume, just set this to the value you'd like the MovieClip to end up at (or begin at if you're using TweenFilterLite.from()).
     • tint: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 tint. Before version 5.8, tint was called mcColor (which is now deprecated and will likely be removed at a later date although it still works)
     • onStart: 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: An array of parameters to pass the onStart function.
     • onUpdate: 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: An array of parameters to pass the onUpdate function (this is optional)
     • onComplete: If you'd like to call a function when the tween has finished, use this.
     • onCompleteParams: An array of parameters to pass the onComplete function (this is optional)
     • overwrite: 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.

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

• Description: Exactly the same as TweenFilterLite.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 TweenFilterLite.to(). (see above)

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:
  1. delay: Number of seconds before the function should be called.
  2. onComplete: The function to call
  3. onCompleteParams [optional] An array of parameters to pass the onComplete function when it's called.

TweenFilterLite.killTweensOf(target:Object, complete:Boolean);

• 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:
  1. target: Any/All tweens of this Object/MovieClip will be killed.
  2. complete: If true, the tweens for this object will immediately complete (go to the ending values and call the onComplete function if you defined one).

TweenFilterLite.killDelayedCallsTo(function:Function);

• Description: Provides an easy way to kill all delayed calls to a particular function (ones that were instantiated using the TweenFilterLite.delayedCall() method).
• Parameters:
  1. function: Any/All delayed calls to this function will be killed.

EXAMPLES

As a simple example, you could tween the blur of clip_mc from where it's at now to 20 over the course of 1.5 seconds by:

1. import gs.TweenFilterLite;
2. TweenFilterLite.to(clip_mc, 1.5, {type:"Blur", blurX:20, blurY:20});

If you want to get more advanced and tween the clip_mc MovieClip over 5 seconds, changing the saturation to 0, delay starting the whole tween by 2 seconds, and then call a function named "onFinishTween" when it has completed and pass in a few arguments to that function (a value of 5 and a reference to the clip_mc), you'd do so like:

1. import gs.TweenFilterLite;
2. import fl.motion.easing.Back;
3. TweenFilterLite.to(clip_mc, 5, {type:"Color", saturation:0, delay:2, onComplete:onFinishTween, onCompleteParams:[5, clip_mc]});
4. function onFinishTween(argument1_num:Number, argument2_mc:MovieClip):void {
5.     trace("The tween has finished! argument1_num = " + argument1_num + ", and argument2_mc = " + argument2_mc);
6. }

If you have a MovieClip on the stage that already has the properties you'd like to end at, and you'd like to start with a colorized version (red: 0xFF0000) and tween to the current properties, you could:

1. import gs.TweenFilterLite;
2. TweenFilterLite.from(clip_mc, 5, {type:"color", colorize:0xFF0000});

FAQ

1. Can I set up a sequence of tweens so that they occur one after the other?
   Of course! 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 blur it over the course of 1 second:
   1. import gs.TweenFilterLite;
   2. TweenFilterLite.to(clip_mc, 2, {type:"color", colorize:0xFF0000, amount:1});
   3. TweenFilterLite.to(clip_mc, 1, {type:"blur", blurX:20, blurY:20, delay:2, overwrite:false});

2. 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 TweenFilterLite.to(clip_mc, 1, {type:"color", colorize:0xFF0000, amount:1}) is the same as TweenFilterLite.to(clip_mc, 1, {amount:1, colorize:0xFF0000, type:"color"});

3. Can I use TweenFilterLite to tween things other than filters?
   Sure. It extends TweenLite, so you can tween any property you want. TweenFilterLite.to(my_mc, 1, {x:200}) gives you the same result as TweenLite.to(my_mc, 1, {x:200}). However, I'd recommend using TweenLite to tween properties other than filters for two reasons:
   1. In order to accommodate the specialized nature of filters, TweenFilterLite's code is a bit lengthier which translates into more work for the processor. It's doubtful that anyone would notice a performance hit unless you're tweening hundreds or thousands of instances simultaneously, but I'm a bit of an efficiency freak.
   2. TweenLite can tween any property of ANY object whereas TweenFilterLite tweens properties of DisplayObjects (like MovieClips, Sprites, etc.)

4. Why are TweenLite and TweenFilterLite split into 2 classes instead of building all the functionality into one class?
   1. File size. Only a portion of projects out there require tweening of filters. Almost every project I work on uses TweenLite, but only a few require tweening filters (TweenFilterLite). TweenLite is 2k whereas TweenFilterLite is 5k. Again, one of the stated purposes of TweenLite is to minimize file size & code bloat. If someone only wants to use TweenFilterLite, fine. But I think many people appreciate being able to use the most lightweight option for their needs and shave off the 3k when possible.
   2. Speed. Tweening filters is a more complex task. There are additional if/else statements and calculations in the rendering loop inside TweenFilterLite which could potentially slow things down a bit, even for non-filter tweens (I doubt anyone would notice a difference unless they’re running hundreds or thousands of simultaneous tweens, but I’m a big fan of keeping things as efficient & fast as possible)

5. Do I have to pay for a license to use this code? Can I use it for commercial purposes?
   Feel free to take the code and use it as you wish, even for commercial purposes. Some people have requested the ability to donate money to reward the work I put into the class(es), so i put a PayPal "donate now" button at the top and bottom of the page, but you certainly don't need to donate anything. I'm just glad to help the Flash community.

6. Are TweenLite and TweenFilterLite better than Tweener, Fuse, MC Tween, and all the other tweening engines out there?
   Maybe, maybe not. It all depends on your objectives, coding style, etc. I certainly don't claim that TweenLite & TweenFilterLite are superior to all other tweening engines, but in terms of the power-to-file-size ratio, I certainly haven't seen anything that comes close. Feedback has been overwhelmingly positive. I've used TweenLite for many years and it has never let me down. I've never found myself needing features that are available in another tweening engine. But hey, to each his own.