class flaxen.component.Tween implements Completable
Available on all platforms
Alters one or more values between two points over a series of time.
General interpolation class. Supports easing, looping, and onComplete operations. This example moves myEntity to the upper left corner over the course of two seconds, after which the Tween component removes itself from myEntity.
var pos = myEntity.get(Position);
var tween = new Tween(2)
.addTarget(pos, "x", 0)
.addTarget(pos, "y", 0)
.setOnComplete(DestroyComponent);
myEntity.add(t);
For a tween to be processed, you must use TweenSystem (added by default),
the Tween instance must be added to an entity (done automatically with
Flaxen.newTween
), the entity must be added to Ash (ditto), and either
autoStart must be true on creation (the default) or running set to true
after creation.
- TODO: Add some static methods for creating Tweens with common settings, say Tween.createAndDestroy, or with a typedef create(props:TweenOptions)
- TODO: Add multitween static method to tween more than one property of the same object, in a single call
Instance Fields
var easing:EasingFunction
The default easing function for all tween targets without a specified easing; set before adding targets
var maxLoops:Int
Sets the maximum number of loops; only applicable if loop
is not None; a value of 0 is ignored (endless looping)
var name:String
The name is primarily intended for the holding entity's name, which can be
helpful in some cases; Flaxen.newTween
sets this automatically;
can be null if not defined
var running:Bool
The tween is only being updated when running is true; you can set
this false to pause automatic tweening; you can pass false for autoStart to
delay execution; see scrub
function new(duration:Float, ?easing:EasingFunction, ?loop:LoopType, ?onComplete:OnComplete, ?autoStart:Bool = true, ?name:String):Void
Constructs a new Tween
For a tween to be processed, it must have targets added to it (see
addTarget
) and be added to an Ash Entity.
duration | The duration of the tween in seconds |
easing | A easing function, which will be applied to all targets that don't specify an easing; defaults to |
loop | The loop type of the tween; |
onComplete | What to do after the tween completes |
autoStart | If true (default) kicks off the tween automatically; if false, you must kick it off by setting |
name | The duration of the tween in seconds |
function addTarget(obj:Dynamic, prop:String, target:Float, ?initial:Float, ?easing:EasingFunction):Tween
Internal method for adding a TweenTarget
to the tween
Each TweenTarget is an individual object property that can be tweened.
For a shorter convenience method, see to
.
- TODO: Add basic pathing support by allowing Array for target
obj | The object with the property that is to be tweened |
prop | The name of the property within the object |
target | The target value to tween to |
initial | The initial value to tween from; if not supplied, defaults to the current value of the property |
easing | The easing function to use for this tween; if not supplied, defaults to the current value of |
returns | This |
Pauses the tween.
This prevents all automatic tweening, and enables scrubbing. See scrub
. Call resume
to continue.
returns | This tween |
Resumes a paused tween.
This resumes from the last pause point.
If it was paused due to scrubbing (see scrub
) this resumes from the last scrub point.
returns | This tween |
function scrub(val:Float, ?asPercentage:Bool = false):Tween
UNTESTED. Enables manual tweening aka scrubbing.
Immediately scrubs all targets to a specific tween time. The
val should be between 0 and the tween duration, or 0-1 if you
set asPercentage to true. This method sets running
to false
(see pause
) which turns off automatic tweening for this
instance. When you want to stop scrubbing and resume automatic
tweening, set it back to true or call resume
.
function setElapsed(val:Float):Tween
Sets the elapsed time.
This is generally managed automatically. You might call this before the tween begins to "fast-forward" the tween to a particular point. For example, 1.5 seconds into a 3.0 second tween would start the tween at the midpoint.
Another possibility is to "scrub" over values of the tween. See scrub()
val | The elapsed time, must be positive |
returns | This Tween |
function setLoop(?loop:LoopType):Tween
Sets the loop
type of this tween.
loop | The |
returns | This Tween |
function setMaxLoops(count:Int):Tween
Sets the maximum number of loops a looping tween will have before it completes.
If loop
is None, this setting has no effect. Supply 0 to disable this feature
(endless looping).
count | The maximum number of loops; may not be negative; 0 means no limit |
returns | This tween |
function setName(name:String):Tween
Sets the name
of this tween.
The name is primarily intended for the holding entity's name, which can be
used to look up the entity in Ash. See name
for more.
name | The name of the tween (may be null) |
returns | This Tween |
function setOnComplete(?onComplete:OnComplete):Tween
Immediately sets onComplete
.
OnComplete | What to do after the tween completes; defaults to |
returns | This Tween |
function to(obj:Dynamic, prop:String, target:Float, ?initial:Float, ?easing:EasingFunction):Tween
Convenience method, see addTarget
for behavior.
function update(time:Float):Void
Updates automatic tweening for all targets in this instance.
Internal method, called by the TweenSystem
.
time | The elapsed time in seconds |