Tween Engine API

Other posts of the serie

  1. Tween Engine API (Octo­ber 28, 2010)
  2. Tween Engine Overview (Octo­ber 28, 2010)

With this engine you can eas­i­ly and quick­ly ani­mate dif­fer­ent prop­er­ties of such objects as sprites, mod­els, cam­eras, etc. In case you need to add extra func­tion­al­i­ty you can use the Plug-in archi­tec­ture to write your own plug­in. All of the ani­ma­tions are time-based. Below are list­ed Tween Engine’s pub­lic meth­ods and prop­er­ties:


to( tar­get, dura­tion, vars )

to( tar­get, dura­tion, vars )
Sta­t­ic method for cre­at­ing a Tween instance. The fol­low­ing lines of code pro­duce exact­ly the same result:

-- variant 1
myTween = script("TweenLite").new( sprite(1), 1, [#x:100] )

-- variant 2
Tween = script("TweenLite").getInstance()
Tween.to( sprite(1), 1, [#x:100] )

Para­me­ters:
tar­get — *; Tar­get object whose prop­er­ties this tween affects. This can be ANY object, not just a sprite.
dura­tion — #float; Dura­tion in sec­onds.
vars — #pro­pList; A prop­er­ty list con­tain­ing the end val­ues of the prop­er­ties you’re tween­ing.
For exam­ple, to tween to x=100, y=100, you could pass [#x:100, #y:100].
It can also con­tain spe­cial prop­er­ties like #onCom­plete, #onCom­pleteParams, #ease, #delay, etc.

from( tar­get, dura­tion, vars )

from( tar­get, dura­tion, vars )
Sta­t­ic method for cre­at­ing a Tween instance that tweens in the oppo­site direc­tion com­pared to a to() tween.
In oth­er words, you define the START val­ues in the vars object instead of the end val­ues, and the tween will
use the cur­rent val­ues as the end val­ues. This can be very use­ful for ani­mat­ing things into place on the stage
because you can build them in their end posi­tions and do some sim­ple from() calls to ani­mate them into place.

Para­me­ters:
tar­get — *; Tar­get object whose prop­er­ties this tween affects. This can be ANY object, not just a sprite.
dura­tion — #float; Dura­tion in sec­onds.
vars — #pro­pList; A prop­er­ty list con­tain­ing the end val­ues of the prop­er­ties you’re tween­ing.
For exam­ple, to tween to x=100, y=100, you could pass [#x:100, #y:100].
It can also con­tain spe­cial prop­er­ties like #onCom­plete, #ease, #delay, etc.

tweener = script( "TweenLite" ).getInstance()
tweener.from( sprite( me.spritenum ), 1, [#x:"800", #delay:3, #ease:"Back.EaseInOut"] )

delayed­Call( delay, onCom­plete, onCom­pleteParams )

delayed­Call( delay, onCom­plete, onCom­pleteParams )
Pro­vides a sim­ple way to call a func­tion after a set amount of time.
You can option­al­ly pass any num­ber of para­me­ters to the func­tion too.
For exam­ple:
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

Para­me­ters:
delay — #float; Delay in sec­onds before the func­tion should be called
onCom­plete — #pro­pList; Han­dler to call
onCom­pleteParams — #list; A list of para­me­ters to pass the han­dler.

pause­All()

pause­All()
Paus­es all exist­ing tweens and delayedCalls/callbacks

resumeAll()

resumeAll()
Resumes all exist­ing tweens

killTween­sOf( tar­get )

killTween­sOf( tar­get )
Dis­pos­es all tweens of a given object.

Para­me­ters:
tar­get — *; Tar­get object.
Exam­ple:

Tween = script( "TweenLite" ).getInstance()
Tween.killTweensOf( sprite(1) ) -- This will remove all tweens of sprite(1)

kil­lAllTweens( com­plete, tweens, delayed­Calls )

kil­lAllTweens( com­plete, tweens, delayed­Calls )
Dis­pos­es all tweens and/or delayedCalls/callbacks, option­al­ly forc­ing them to com­ple­tion first. The var­i­ous para­me­ters provide a way to dis­tin­guish between delayed­Calls and tweens, so if you want to kill EVERYTHING (tweens and delayed­Calls), you’d do:
script( "TweenMax" ).getInstance().killAll( false, true, true )

But if you want to kill only the tweens but allow the delayed­Calls to con­tin­ue, you’d do:

script( "TweenMax" ).getInstance().killAll( false, true, false )

And if you want to kill only the delayed­Calls but not the tweens, you’d do:

script( "TweenMax" ).getInstance().killAll( false, false, true )

Para­me­ters:
com­plete — #Boolean (default = false); Deter­mi­nes whether or not the tweens/delayedCalls/callbacks should be forced to com­ple­tion before being killed.
tweens — #Boolean (default = true); If true, all tweens will be killed
delayed­Calls — #Boolean (default = true); If true, all delayed­Calls will be killed. Time­line­Max call­backs are treat­ed the same as delayed­Calls.

dis­poseTwee­nEngine()

dis­poseTwee­nEngine()
Dis­pos­es all exist­ing tweens and delayedCalls/callbacks and removes any Tween instances from the actorlist.


timeScale( float )

timeScale( float )
increases/decreases the dura­tion of the tween

Exam­ple:

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

pro­gress( float )

pro­gress( float )
Sets the tween at a given per­cent of com­ple­tion ( 0 = 0%, 1 = 100% )
Exam­ple:
Tween = script("TweenMax").getInstance()
animation = Tween.to( sprite(1), 2, [#x:500] )
animation.currentProgress( 0.75 ) -- This will force the tween to 75% completion

pause()

pause()
Paus­es the tween.

resume()

resume()
Resumes the tween.

restart()

restart()
Forces the tween to its begin­ing.

reverse()

reverse()
Revers­es the tween.

dis­pose()

dis­pose()
Dis­pos­es the tween.



Any of the fol­low­ing spe­cial prop­er­ties can option­al­ly be passed in through the vars prop­er­ty list (the third para­me­ter):

#delay — #float
Amount of delay in sec­onds before the tween should begin.


#ease — #String
Use any stan­dard eas­ing equa­tion to con­trol the rate of change.
For exam­ple, “Elastic.easeOut”. The Default is “Linear.None”.

#loop — #inte­ger
Num­ber of times that the tween should repeat. To repeat indef­i­nite­ly, use -1.


#yoyo — #boolean
Works in con­junc­tion with the #loop prop­er­ty, deter­min­ing the behav­ior of each cycle.
When #yoyo is true, the tween will go back and forth, appear­ing to reverse every oth­er cycle
(this has no affect on the “reversed” prop­er­ty 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.


#over­write — #inte­ger
Con­trols how (and if) oth­er tweens of the same tar­get are over­writ­ten by this tween.
There are sev­er­al mod­es to choose from, and Tween auto­mat­i­cal­ly calls OverwriteManager.init()
if you haven’t already man­u­al­ly dones so, which means that by default AUTO mode is used.

  • 0 ( none ) — no over­writ­ing will occur.
  • 1 ( all ) — imme­di­ate­ly over­writes all exist­ing tweens of the same tar­get even if they haven’t start­ed yet or don’t have con­flict­ing prop­er­ties.
  • 2 ( auto ) — when the tween ren­ders for the first time, it will ana­lyze tweens of the same tar­get that are cur­rent­ly active/running and only over­write indi­vid­u­al tween­ing prop­er­ties that overlap/conflict. Tweens that haven’t begun yet are ignored. For exam­ple, if anoth­er active tween is found that is tween­ing 3 prop­er­ties, only 1 of which it shares in com­mon with the new tween, the oth­er 2 prop­er­ties will be left alone. Only the con­flict­ing prop­er­ty gets overwritten/killed. This is the default mode and typ­i­cal­ly the most intu­itive for devel­op­ers.
  • 3 ( con­cur­rent ) — when the tween ren­ders for the first time, it kills only the active (in-pro­gress) tweens of the same tar­get regard­less of whether or not they con­tain con­flict­ing prop­er­ties. Like a mix of “all” and “auto”. Good for sit­u­a­tions where you only want one tween con­trol­ing the tar­get at a time.
  • 4 ( allOn­Start ) — Iden­ti­cal to “all” but waits to run the over­write log­ic until the tween begins (after any delay). Kills tweens of the same tar­get even if they don’t con­tain con­flict­ing prop­er­ties or haven’t start­ed yet.
  • 5 ( pre­ex­ist­ing ) — when the tween ren­ders for the first time, it kills only the tweens of the same tar­get that exist­ed BEFORE this tween was cre­at­ed regard­less of their sched­uled start times. So, for exam­ple, if you cre­ate 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 tar­get), the 2nd tween would over­write the first but not the sec­ond even though sched­ul­ing might seem to dic­tate oth­er­wise. “pre­ex­ist­ing” only cares about the order in which the instances were actu­al­ly cre­at­ed. This can be use­ful when the order in which your code runs plays a crit­i­cal role.

#onCom­plete — #pro­pList
A han­dler that should be called when the tween has fin­ished.
Exam­ple: [#handler:#animationEnd, #object:_movie ]


#onCom­pleteParams — #list
A list of para­me­ters to pass the #onCom­plete han­dler.


#ampli­tude — #inte­ger
Addi­tion­al para­me­ter for “Elas­tic” eas­ing func­tion.


#peri­od — #inte­ger
Addi­tion­al para­me­ter for “Elas­tic” eas­ing func­tion.


#over­shoot — #inte­ger
Addi­tion­al para­me­ter for “Back” eas­ing func­tion.


#bezier — #pro­pList
Bezier tween­ing allows you to tween in a non-lin­ear way. For exam­ple, you may want to tween a sprite’s posi­tion from the orig­in (0,0) 500 pix­els to the right (500,0) but curve down­wards through the mid­dle of the tween. Sim­ply pass as many objects in the bezier prop­er­ty list as you’d like, one for each “con­trol point”. In this exam­ple, let’s say the con­trol point would be at x/y coor­di­nates 250,50. Just make sure your sp1 is at coor­di­nates 0,0 and then do:

Tween = script( "TweenLite" ).getInstance()
Tween.to( sp1, 3, [#bezier:[[#x:250, #y:50], [#x:500, #y:0]]])

#bezierThrough — #pro­pList
Iden­ti­cal to bezier except that instead of pass­ing bezier con­trol point
val­ues, you pass points through which the bezier val­ues should move.
This can be more intu­itive than using con­trol points.


#ori­ent­To­Bezier — #Boolean
A com­mon effect that designers/developers want is for a sprite to ori­ent
itself in the direc­tion of a Bezier path (alter its rota­tion). #ori­ent­To­Bezier makes it easy.


 
Comments

No comments yet.