Tween
The Tween
object allows you to create and manipulate Tweeners
and Timers
.
Tween.Tweener
Tweener
s are objects that interpolate a value or the property of an object from a startValue
to an endValue
during a duration
, optionally using an easing
equation.
Tweeners can work with number
, Vector2
, Vector3
and string
(it display the text one letter at a time).
The "property" may be virtual in that it just need to match the name of a couple of getter/setter (ie : "position"
for transform:Get/SetPosition()
).
Create a tweener using one of the following constructors :
Tween.Tweener.New( target, property, endValue, duration[, params] )
Tween.Tweener.New( startValue, endValue, duration[, params] )
Tween.Tweener.New( params )
Parameters
The properties of a tweener you can set are described below. Except for the ones that are arguments of the contructors, they are all optionnals.
Like for game objects and components, you may mass-set properties on tweeners during their creation or afterward via tweener:Set({params})
.
target
(table) : Any object or table that has the specified property (or corresponding getter/setter).property
(string) : The target's property to animate the value of.startValue
(number, Vector2, Vector3 or string) : The value to starts the tweener at. If not set, it will be set at the current value of the target's property.endValue
(number, Vector2, Vector3 or string) : The value to ends the tweener at.duration
(number) : The time or frames the tweener (one loop, actually) should take (indurationType
units).durationType
(string) [default="time"] : The unit of time fordelay
,duration
,elapsed
andfullElapsed
. Can be"time"
,"realTime"
or"frame"
. If set to"time"
, the tweener is tied to the time scale.isEnabled
(boolean) [true]: A disabled tweener won't update and the functions likePlay()
,Pause()
,Complete()
,Destroy()
will have no effect.isPaused
(boolean) [false] : A paused tweener doesn't update.delay
(number) [0] : The delay before the tweener starts (indurationType
unit). The delay do not updates when the tweener is paussed.loops
(number) [1] : The number of loops to run. Set to-1
for an infinite loop. Tweeners always run at least one loop, so a value of 0 or 1 does not make any differences.loopType
(string) ["simple"] : The type of the loop. Possible values are"simple"
(X to Y, and repeat) or"yoyo"
(X to Y the first loop, then Y to X the next loop, and repeat)isRelative
(boolean) [false] : Tell wetherendValue
is an absolute value or is relative tostartValue
. If false, tween the value TO endValue. If true, tween the value BY endValue.destroyOnComplete
(boolean) [true] : Tell wether to destroy the tweener when it completes. You may reuse non-destroyed tweeners by restarting them with theRestart()
function.destroyOnSceneLoad
(boolean) [true] : Tell wether to destroy the tweener when a new scene is loadedeaseType
(string) ["linear"] : The type of easing to apply to the value. This will impact how the value change over time. Possible values are :- linear
- inQuad, outQuad, inOutQuad, outInQuad
- inCubic, outCubic, inOutCubic, outInCubic
- inQuart, outQuart, inOutQuart, outInQuart
- inQuint, outQuint, inOutQuint, outInQuint
- inSine, outSine, inOutSine, outInSine
- inExpo, outExpo, inOutExpo, outInExpo
- inCirc, outCirc, inOutCirc, outInCirc
- inElastic, outElastic, inOutElastic, outInElastic
- inBack, outBack, inOutBack, outInBack
- inBounce, outBounce, inOutBounce, outInBounce
Other properties :
Id
value
(number) : The current value.hasStarted
(boolean) : Become true when the tweener started updating the value (stays false as long as the delay is superior to zero).isCompleted
(boolean) : True when all loops are completed. The tweener then stops running.elapsed
(number) : The time or frames (indurationType
unit) that have passed since the beginning of the current loop, delay and pauses excluded.fullElapsed
(number) : The total time or frames (indurationType
unit) that have passed since the tweener started, delay and pauses excluded.completedLoops
(number) : The number of loops that have been completed.
Easing functions
Easing functions impact how the tweener's value change over time. They can be divided into several big families:
linear
is the default interpolation. It’s the simplest easing function.quad
,cubic
,quart
,quint
,expo
,sine
andcirc
are all "smooth" curves that will make transitions look natural.- The
elastic
family simulates inertia in the easing, like an elastic gum. - The
back
family starts by moving the interpolation slightly "backwards" before moving it forward. - The
bounce
family simulates the motion of an object bouncing.
Each family (except linear) has 4 variants:
in
starts slow, and accelerates at the endout
starts fast, and decelerates at the endinOut
starts and ends slow, but it’s fast in the middleoutIn
starts and ends fast, but it’s slow in the middle
Control functions
You may control how the tweener runs via the following functions. The same result may be achieved by setting the corresponding properties (isEnabled
, isPaused
, etc...) but the functions also fire the corresponding event.
Pause()
: pause the tweener and fires theOnPause
event at the tweener.Play()
: unpause the tweener and fires theOnPlay
event at the tweener.Update()
: update the tweener and fires theOnUpdate
event at the tweener.Complete()
: complete the tweener and fires theOnComplete
event at the tweener.Restart()
: completely restart the tweener, including the loops. TheOnStart
event will be fired again the next time the tweener startsDestroy()
: disable the tweener and remove it from the list of tweener.
You may fast-forward or (fast-rewind) a tweener by changing the value of the elapsed
property then by calling the Update()
function.
Tweener events
They are fired at the tweener, passing the tweener as first and only argument.
OnStart
: when the tweener starts, when the delay is equal to zero (only called once, before the first loop begins). May be called again if the tweener is restarted viaRestart()
.OnPause
: when the tweener is paused viaPause()
.OnPlay
: when the tweener is unpaused viaPlay()
.OnUpdate
: when the tweener is updated.OnLoopComplete
: when the tweener has completed one loop and at least one loop remains to complete.OnComplete
: when the tweener has completed all its loops (never called for infinite loops).
Examples
function Behavior:Start()
-- Example 1 :
Tween.Tweener.New( self.gameObject.modelRenderer, "opacity", 0, 10, {
loops = -1,
loopType = "yoyo",
durationType = "frame",
OnUpdate = function( tweener ) print( "The model's opacity is " .. tweener.value ) end,
} )
-- this tweener makes the model's opacity goes down to 0 then back up to 1 in 20 frames
-- Example 2 :
-- tweener also makes great timers :
local tweener = Tween.Tweener.New( 10, 0, 10, {
isPaused = true,
OnUpdate = function( tweener )
self.gameObject.textRenderer.text = math.floor( tweener.value )
end
} )
tweener.OnComplete = function() print("Boom !") end
tweener:Play()
-- in this example, the tweener "count" from 10 to 0 in 10 seconds and displays the time remaining via a textRenderer, then prints "Boom !" when the time is up
-- Example 3 :
Tween.Tweener.New( {
target = self.gameObject.transform,
property = "localScale",
startValue = Vector3:New(0.7),
endValue = Vector3:New(1),
duration = 1, -- time
loops = -1,
loopType = "yoyo",
} )
-- in this example, we animate the game object's local scale to create a "heart beat" effect
end
Timer
The Tween.Timer
object, which only provides the New()
function, is just a convenient interface to create tweeners used as timers.
Create a timer with one of the following constructors (which return a regular tweener) :
Tween.Timer.New( duration, OnComplete[, params] )
Tween.Timer.New( duration, OnLoopComplete, true[, params] )
The first one creates a one-time timer which calls the function provided as second argument at the end of the duration.
The second one creates an infinite looping timer which calls the provided function everytime the duration passes.
In both cases, the tweener's endValue
is 0
while startValue
has the value of the duration
.
You may customize the tweener (time unit, paused state, etc...) via the optional params
argument.
Tween.Timer.New( 5, CS.Exit ) -- exit the game in 5 seconds
-- is the same as :
Tween.Tweener.New( 5, 0, 5, {
OnComplete = CS.Exit
} )
Tween.Timer.New( 10, function() self:DoSomethingRepeatedly() end, true )
-- call self:DoSomethingRepeatedly() every 10 seconds
-- is the same as :
Tween.Tweener.New( 10, 0, 10, {
loops = -1,
OnLoopComplete = function()
self:DoSomethingRepeatedly()
end
})
Game object animations
To easily works with tweeners and game objects, you can use the following function : GameObject.Animate(gameObject, property, endValue, duration[, onCompleteCallback, params])
.
Ie :
self.gameObject:Animate( "opacity", 0, 1, function() self.gameObject:Destroy() end )
-- this fades the opacity of the game object's (model, map or text) renderer to 0 in 1 second then destroy the game object
This also works with custom components :
-- The Hud component introduced by the GUI module :
local slideInTweener = self.gameObject:Animate("localPosition", Vector2(10,0), 1, { easeType = "inElastic" })
-- in this case, the Animate() function will automatically detect that the target component is the hud component and not the transform
-- The LineRenderer component introduced by the Draw module :
self.gameObject:Animate("length", 10, 1)
-- this updates the line renderer's length to 10 units over the course of 1 second
Remember that the "property" may be virtual in that it just need to match the name of a couple of getter/setter. Ie :
"opacity"
formodelRenderer:Get/SetOpacity()
, also works for the map, circle and text renderers, as well as for the text area."length"
forlineRenderer:Get/SetLength()
."position"
fortransform:Get/SetPosition()
, also works for the hud component."text"
fortextRenderer:Get/SetText()
. Doesn't automatically work for text areas, you have to specify the target (the text area component) via theparams
table.- ...