Other posts of the serie
- Tween Engine API (October 28, 2010)
- Tween Engine Overview (October 28, 2010)
With this engine you can easily and quickly animate different properties of such objects as sprites, models, cameras, etc. In case you need to add extra functionality you can use the Plug-in architecture to write your own plugin. All of the animations are time-based. Below are listed Tween Engine’s public methods and properties:
to( target, duration, vars )
Static method for creating a Tween instance. The following lines of code produce exactly the same result:
[code lang=”lingo” gutter=”false” toolbar=”false”]
— variant 1
myTween = script("TweenLite").new( sprite(1), 1, [#x:100] )
— variant 2
Tween = script("TweenLite").getInstance()
Tween.to( sprite(1), 1, [#x:100] )
[/code]
Parameters:
target – *; Target object whose properties this tween affects. This can be ANY object, not just a sprite.
duration – #float; Duration in seconds.
vars – #propList; A property list containing the end values of the properties you’re tweening.
For example, to tween to x=100, y=100, you could pass [#x:100, #y:100].
It can also contain special properties like #onComplete, #onCompleteParams, #ease, #delay, etc.
from( target, duration, vars )
Static method for creating a Tween instance that tweens in the opposite direction compared to a to() tween.
In other words, you define the START values in the vars object instead of the end values, and the tween will
use the current values as the end values. This can be very useful for animating things into place on the stage
because you can build them in their end positions and do some simple from() calls to animate them into place.
Parameters:
target – *; Target object whose properties this tween affects. This can be ANY object, not just a sprite.
duration – #float; Duration in seconds.
vars – #propList; A property list containing the end values of the properties you’re tweening.
For example, to tween to x=100, y=100, you could pass [#x:100, #y:100].
It can also contain special properties like #onComplete, #ease, #delay, etc.
[code lang=”lingo” gutter=”false” toolbar=”false”]
tweener = script( "TweenLite" ).getInstance()
tweener.from( sprite( me.spritenum ), 1, [#x:"800", #delay:3, #ease:"Back.EaseInOut"] )
[/code]
delayedCall( delay, onComplete, onCompleteParams )
Provides a simple way to call a function after a set amount of time.
You can optionally pass any number of parameters to the function too.
For example:
[code lang=”lingo” gutter=”false” toolbar=”false”]
Tween = script("TweenLite").getInstance()
Tween.delayedCall( 3, [#handler:#myHandler, #object:_movie], ["param1", 2 ] )
on myHandler( params )
trace( "called myHandler and passed params:" && params )
end myHandler
[/code]
Parameters:
delay – #float; Delay in seconds before the function should be called
onComplete – #propList; Handler to call
onCompleteParams – #list; A list of parameters to pass the handler.
pauseAll()
Pauses all existing tweens and delayedCalls/callbacks
resumeAll()
Resumes all existing tweens
killTweensOf( target )
Disposes all tweens of a given object.
Parameters:
target – *; Target object.
Example:
[code lang=”lingo” gutter=”false” toolbar=”false”]
Tween = script( "TweenLite" ).getInstance()
Tween.killTweensOf( sprite(1) ) — This will remove all tweens of sprite(1)
[/code]
killAllTweens( complete, tweens, delayedCalls )
Disposes all tweens and/or delayedCalls/callbacks, optionally forcing them to completion first. The various parameters provide a way to distinguish between delayedCalls and tweens, so if you want to kill EVERYTHING (tweens and delayedCalls), you’d do:
[code lang=”lingo” gutter=”false” toolbar=”false”]script( "TweenMax" ).getInstance().killAll( false, true, true )[/code]
But if you want to kill only the tweens but allow the delayedCalls to continue, you’d do:
[code lang=”lingo” gutter=”false” toolbar=”false”]script( "TweenMax" ).getInstance().killAll( false, true, false )[/code]
And if you want to kill only the delayedCalls but not the tweens, you’d do:
[code lang=”lingo” gutter=”false” toolbar=”false”]script( "TweenMax" ).getInstance().killAll( false, false, true )[/code]
Parameters:
complete – #Boolean (default = false); Determines whether or not the tweens/delayedCalls/callbacks should be forced to completion before being killed.
tweens – #Boolean (default = true); If true, all tweens will be killed
delayedCalls – #Boolean (default = true); If true, all delayedCalls will be killed. TimelineMax callbacks are treated the same as delayedCalls.
disposeTweenEngine()
Disposes all existing tweens and delayedCalls/callbacks and removes any Tween instances from the actorlist.
timeScale( float )
increases/decreases the duration of the tween
Example:
[code lang=”lingo” gutter=”false” toolbar=”false”]
Tween = script("TweenLite").getInstance()
animation = Tween.to( sprite(1), 2, [#x:500] )
animation.timeScale( 0.25 ) — This will decrease four times the duration of the tween
[/code]
progress( float )
Sets the tween at a given percent of completion ( 0 = 0%, 1 = 100% )
Example:
[code lang=”lingo” gutter=”false” toolbar=”false”]
Tween = script("TweenMax").getInstance()
animation = Tween.to( sprite(1), 2, [#x:500] )
animation.currentProgress( 0.75 ) — This will force the tween to 75% completion
[/code]
pause()
Pauses the tween.
resume()
Resumes the tween.
restart()
Forces the tween to its begining.
reverse()
Reverses the tween.
dispose()
Disposes the tween.
Any of the following special properties can optionally be passed in through the vars property list (the third parameter):
#delay – #float
Amount of delay in seconds before the tween should begin.
#ease – #String
Use any standard easing equation to control the rate of change.
For example, “Elastic.easeOut”. The Default is “Linear.None”.
#loop – #integer
Number of times that the tween should repeat. To repeat indefinitely, use -1.
#yoyo – #boolean
Works in conjunction with the #loop 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 #loop is 2 and #yoyo is false, it will look like: start – 1 – 2 – 3 – 1 – 2 – 3 – 1 – 2 – 3 – end.
But if #loop is 2 and #yoyo is true, it will look like: start – 1 – 2 – 3 – 3 – 2 – 1 – 1 – 2 – 3 – end.
#overwrite – #integer
Controls how (and if) other tweens of the same target are overwritten by this tween.
There are several modes to choose from, and Tween automatically calls OverwriteManager.init()
if you haven’t already manually dones so, which means that by default AUTO mode is used.
- 0 ( none ) – no overwriting will occur.
- 1 ( all ) – immediately overwrites all existing tweens of the same target even if they haven’t started yet or don’t have conflicting properties.
- 2 ( auto ) – when the tween renders for the first time, it will analyze tweens of the same target that are currently active/running and only overwrite individual tweening properties that overlap/conflict. Tweens that haven’t begun yet are ignored. For example, if another active tween is found that is tweening 3 properties, only 1 of which it shares in common with the new tween, the other 2 properties will be left alone. Only the conflicting property gets overwritten/killed. This is the default mode and typically the most intuitive for developers.
- 3 ( concurrent ) – when the tween renders for the first time, it kills only the active (in-progress) tweens of the same target regardless of whether or not they contain conflicting properties. Like a mix of “all” and “auto”. Good for situations where you only want one tween controling the target at a time.
- 4 ( allOnStart ) – Identical to “all” but waits to run the overwrite logic until the tween begins (after any delay). Kills tweens of the same target even if they don’t contain conflicting properties or haven’t started yet.
- 5 ( preexisting ) – when the tween renders for the first time, it kills only the tweens of the same target that existed BEFORE this tween was created regardless of their scheduled start times. So, for example, if you create a tween with a delay of 10 and then a tween with a delay of 1 and then a tween with a delay of 2 (all of the same target), the 2nd tween would overwrite the first but not the second even though scheduling might seem to dictate otherwise. “preexisting” only cares about the order in which the instances were actually created. This can be useful when the order in which your code runs plays a critical role.
#onComplete – #propList
A handler that should be called when the tween has finished.
Example: [#handler:#animationEnd, #object:_movie ]
#onCompleteParams – #list
A list of parameters to pass the #onComplete handler.
#amplitude – #integer
Additional parameter for “Elastic” easing function.
#period – #integer
Additional parameter for “Elastic” easing function.
#overshoot – #integer
Additional parameter for “Back” easing function.
#bezier – #propList
Bezier tweening allows you to tween in a non-linear way. For example, you may want to tween a sprite’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 property list as you’d like, one for each “control point”. In this example, let’s say the control point would be at x/y coordinates 250,50. Just make sure your sp1 is at coordinates 0,0 and then do:
[code lang=”lingo” gutter=”false” toolbar=”false”]
Tween = script( "TweenLite" ).getInstance()
Tween.to( sp1, 3, [#bezier:[[#x:250, #y:50], [#x:500, #y:0]]])
[/code]
#bezierThrough – #propList
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 – #Boolean
A common effect that designers/developers want is for a sprite to orient
itself in the direction of a Bezier path (alter its rotation). #orientToBezier makes it easy.