class FlxTween
package flixel.tweens
implements IFlxDestroyable
extended by AngleTween, ColorTween, FlickerTween, NumTween, ShakeTween, VarTween, Motion
Allows you to create smooth interpolations and animations easily. "Tweening" is short
for inbetweening: you only have to specify start and end values and FlxTween
will
generate all values between those two.
Resources
Example
If you want to move a FlxSprite
across the screen:
sprite.x = 200;
sprite.y = 200;
FlxTween.tween(sprite, { x: 600, y: 800 }, 2.0);
The first two lines specify the start position of the sprite, because the tween()
method
assumes the current position is the starting position.
Cancelling a Tween
If you start a tween using the code above, it will run until the desired values are reached,
then stop. As the tween()
method returns an object of type FlxTween
, keeping this object
in a variable allows you to access the current tween running if you wish to control it.
This code stops the translation of the sprite if the player presses the spacebar of their keyboard:
var tween:FlxTween;
public function new()
{
super();
// set up sprite
tween = FlxTween.tween(sprite, { x:600, y:800 }, 2);
}
override public function update(elapsed:Float)
{
super.update(elapsed);
if (FlxG.keys.justPressed.SPACE)
tween.cancel();
}
Tweening Options
The tween()
method takes an optional fourth parameter which is a map of options.
Possible values are:
- type
:
- *ONESHOT*: Stops and removes itself from its core container when it finishes
- *PERSIST*: Like *ONESHOT*, but after it finishes you may call `start()` again
- *BACKWARD*: Like *ONESHOT*, but plays in the reverse direction
- *LOOPING*: Restarts immediately when it finishes
- *PINGPONG*: Like *LOOPING*, but every second execution is in reverse direction
onComplete
: Called once the tween has finished. For looping tweens it is called every execution.-
ease
: The method of interpolating the start and end points. Usually used to make the start and/orend of the tween smoother. `FlxEase` has various easing methods to choose from.
startDelay
: Time to wait before starting this tween, in seconds.loopDelay
: Time to wait before this tween is repeated, in seconds
Example:
public function new()
{
super();
// set up sprite
sprite.x = 200;
sprite.y = 200;
FlxTween.tween(sprite, { x: 600, y: 800 }, 2,
{
type: PINGPONG,
ease: FlxEase.quadInOut,
onComplete: changeColor,
startDelay: 1,
loopDelay: 2
}
);
}
function changeColor(tween:FlxTween):Void
{
sprite.color = tween.executions % 2 == 0 ? FlxColor.RED : FlxColor.BLUE;
}
This code moves the sprite constantly between the two points (200 | 200) and (600 | 800), smoothly |
---|
accelerating and decelerating. Each time the sprite arrives at one of those two points, its color changes. The animation starts after 1 second and then the sprite pauses at each point for 2 seconds.
Special Tweens
There are many more tweening methods in FlxTween
, which are used for special cases:
Color
Tweens the rgb components of a color independently, where normal tweening would screw up the colors.
FlxTween.color(sprite, 3.0, FlxColor.RED, FlxColor.GREEN, { onComplete:onTweenComplete } );
Angle
Tweens the angle of a sprite, normal tweening would have trouble going from negative to positive angles.
FlxTween.angle(sprite, -90, 180, 3.0, { onComplete:onTweenComplete } );
Num
Calls a function with the tweened value over time, no parent object involved.
FlxTween.num(0, totalWinnings, 3.0, function(num) { field.text = addCommas(num); });
Motion
The FlxTween class also contains the methods linearMotion()
, quadMotion()
, cubicMotion()
and circularMotion()
,
which make objects follow straight lines, smooth paths or circles.
Paths
The methods linearPath()
and quadPath()
can be used for longer paths defined through an array of points,
instead of a fixed number of points.
Static variables
staticBACKWARD:FlxTweenType = FlxTweenType.BACKWARD
Deprecated, use FlxTweenType.BACKWARD
instead.
staticLOOPING:FlxTweenType = FlxTweenType.LOOPING
Deprecated, use FlxTweenType.LOOPING
instead.
staticONESHOT:FlxTweenType = FlxTweenType.ONESHOT
Deprecated, use FlxTweenType.ONESHOT
instead.
staticPERSIST:FlxTweenType = FlxTweenType.PERSIST
Deprecated, use FlxTweenType.PERSIST
instead.
staticPINGPONG:FlxTweenType = FlxTweenType.PINGPONG
Deprecated, use FlxTweenType.PINGPONG
instead.
staticglobalManager:FlxTweenManager
The global tweening manager that handles global tweens
4.2.0
.Static methods
staticangle(?Sprite:FlxSprite, FromAngle:Float, ToAngle:Float, Duration:Float = 1, ?Options:Null<TweenOptions>):AngleTween
Tweens numeric value which represents angle. Shorthand for creating a AngleTween object, starting it and adding it to the TweenManager.
FlxTween.angle(Sprite, -90, 90, 2.0, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Sprite | Optional Sprite whose angle should be tweened. |
---|---|
FromAngle | Start angle. |
ToAngle | End angle. |
Duration | Duration of the tween. |
Options | A structure with tween options. |
Returns:
The added AngleTween object.
staticcancelTweensOf(Object:Dynamic, ?FieldPaths:Array<String>):Void
Cancels all related tweens on the specified object.
Note: Any tweens with the specified fields are cancelled, if the tween has other properties they will also be cancelled.
Parameters:
Object | The object with tweens to cancel. |
---|---|
FieldPaths | Optional list of the tween field paths to search for. If null or empty, all tweens on the specified object are canceled. Allows dot paths to check child properties. |
4.9.0
.staticcircularMotion(Object:FlxObject, CenterX:Float, CenterY:Float, Radius:Float, Angle:Float, Clockwise:Bool, DurationOrSpeed:Float = 1, UseDuration:Bool = true, ?Options:Null<TweenOptions>):CircularMotion
Create a new CircularMotion tween.
FlxTween.circularMotion(Object, 250, 250, 50, 0, true, 2, true, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Object | The object to move (FlxObject or FlxSpriteGroup) |
---|---|
CenterX | X position of the circle's center. |
CenterY | Y position of the circle's center. |
Radius | Radius of the circle. |
Angle | Starting position on the circle. |
Clockwise | If the motion is clockwise. |
DurationOrSpeed | Duration of the movement in seconds. |
UseDuration | Duration of the movement. |
Ease | Optional easer function. |
Options | A structure with tween options. |
Returns:
The CircularMotion object.
staticcolor(?Sprite:FlxSprite, Duration:Float = 1, FromColor:FlxColor, ToColor:FlxColor, ?Options:Null<TweenOptions>):ColorTween
Tweens numeric value which represents color. Shorthand for creating a ColorTween object, starting it and adding it to a TweenPlugin.
FlxTween.color(Sprite, 2.0, 0x000000, 0xffffff, 0.0, 1.0, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Sprite | Optional Sprite whose color should be tweened. |
---|---|
Duration | Duration of the tween in seconds. |
FromColor | Start color. |
ToColor | End color. |
Options | A structure with tween options. |
Returns:
The added ColorTween object.
staticcompleteTweensOf(Object:Dynamic, ?FieldPaths:Array<String>):Void
Immediately updates all tweens on the specified object with the specified fields that
are not looping (type FlxTween.LOOPING
or FlxTween.PINGPONG
) and active
through
their endings, triggering their onComplete
callbacks.
Note: if they haven't yet begun, this will first trigger their onStart
callback.
Note: their onComplete
callbacks are triggered in the next frame.
To trigger them immediately, call FlxTween.globalManager.update(0);
after this function.
In no case should it trigger an onUpdate
callback.
Note: Any tweens with the specified fields are completed, if the tween has other properties they will also be completed.
Parameters:
Object | The object with tweens to complete. |
---|---|
FieldPaths | Optional list of the tween field paths to search for. If null or empty, all tweens on the specified object are completed. Allows dot paths to check child properties. |
4.9.0
.staticcubicMotion(Object:FlxObject, FromX:Float, FromY:Float, aX:Float, aY:Float, bX:Float, bY:Float, ToX:Float, ToY:Float, Duration:Float = 1, ?Options:Null<TweenOptions>):CubicMotion
Create a new CubicMotion tween.
FlxTween.cubicMotion(_sprite, 0, 0, 500, 100, 400, 200, 100, 100, 2, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Object | The object to move (FlxObject or FlxSpriteGroup) |
---|---|
FromX | X start. |
FromY | Y start. |
aX | First control x. |
aY | First control y. |
bX | Second control x. |
bY | Second control y. |
ToX | X finish. |
ToY | Y finish. |
Duration | Duration of the movement in seconds. |
Options | A structure with tween options. |
Returns:
The CubicMotion object.
staticflicker(basic:FlxBasic, duration:Float = 1.0, period:Float = 0.08, ?options:Null<FlickerTweenOptions>):FlickerTween
Flickers the desired object
Parameters:
basic | The object to flicker |
---|---|
duration | Duration of the tween, in seconds |
period | How often, in seconds, the visibility cycles |
options | A structure with flicker and tween options |
5.7.0
.staticisFlickering(basic:FlxBasic):Bool
Whether the object is flickering via the global tween manager
5.7.0
.staticlinearMotion(Object:FlxObject, FromX:Float, FromY:Float, ToX:Float, ToY:Float, DurationOrSpeed:Float = 1, UseDuration:Bool = true, ?Options:Null<TweenOptions>):LinearMotion
Create a new LinearMotion tween.
FlxTween.linearMotion(Object, 0, 0, 500, 20, 5, false, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Object | The object to move (FlxObject or FlxSpriteGroup) |
---|---|
FromX | X start. |
FromY | Y start. |
ToX | X finish. |
ToY | Y finish. |
DurationOrSpeed | Duration (in seconds) or speed of the movement. |
UseDuration | Whether to use the previous param as duration or speed. |
Options | A structure with tween options. |
Returns:
The LinearMotion object.
staticlinearPath(Object:FlxObject, Points:Array<FlxPoint>, DurationOrSpeed:Float = 1, UseDuration:Bool = true, ?Options:Null<TweenOptions>):LinearPath
Create a new LinearPath tween.
FlxTween.linearPath(Object, [FlxPoint.get(0, 0), FlxPoint.get(100, 100)], 2, true, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Object | The object to move (FlxObject or FlxSpriteGroup) |
---|---|
Points | An array of at least 2 FlxPoints defining the path |
DurationOrSpeed | Duration (in seconds) or speed of the movement. |
UseDuration | Whether to use the previous param as duration or speed. |
Options | A structure with tween options. |
Returns:
The LinearPath object.
staticnum(FromValue:Float, ToValue:Float, Duration:Float = 1, ?Options:Null<TweenOptions>, ?TweenFunction:Float ‑> Void):NumTween
Tweens some numeric value. Shorthand for creating a NumTween, starting it and adding it to the TweenManager. Using it in conjunction with a TweenFunction requires more setup, but is faster than VarTween because it doesn't use Reflection.
function tweenFunction(s:FlxSprite, v:Float) { s.alpha = v; }
FlxTween.num(1, 0, 2.0, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT }, tweenFunction.bind(mySprite));
Trivia: For historical reasons, you can use either onUpdate or TweenFunction to accomplish the same thing, but TweenFunction gives you the updated Float as a direct argument.
Parameters:
FromValue | Start value. |
---|---|
ToValue | End value. |
Duration | Duration of the tween. |
Options | A structure with tween options. |
TweenFunction | A function to be called when the tweened value updates. It is recommended not to use an anonymous function if you are maximizing performance, as those will be compiled to Dynamics on cpp. |
Returns:
The added NumTween object.
staticquadMotion(Object:FlxObject, FromX:Float, FromY:Float, ControlX:Float, ControlY:Float, ToX:Float, ToY:Float, DurationOrSpeed:Float = 1, UseDuration:Bool = true, ?Options:Null<TweenOptions>):QuadMotion
Create a new QuadMotion tween.
FlxTween.quadMotion(Object, 0, 100, 300, 500, 100, 2, 5, false, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Object | The object to move (FlxObject or FlxSpriteGroup) |
---|---|
FromX | X start. |
FromY | Y start. |
ControlX | X control, used to determine the curve. |
ControlY | Y control, used to determine the curve. |
ToX | X finish. |
ToY | Y finish. |
DurationOrSpeed | Duration (in seconds) or speed of the movement. |
UseDuration | Whether to use the previous param as duration or speed. |
Options | A structure with tween options. |
Returns:
The QuadMotion object.
staticquadPath(Object:FlxObject, Points:Array<FlxPoint>, DurationOrSpeed:Float = 1, UseDuration:Bool = true, ?Options:Null<TweenOptions>):QuadPath
Create a new QuadPath tween.
FlxTween.quadPath(Object, [FlxPoint.get(0, 0), FlxPoint.get(200, 200), FlxPoint.get(400, 0)], 2, true, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Object | The object to move (FlxObject or FlxSpriteGroup) |
---|---|
Points | An array of at least 3 FlxPoints defining the path |
DurationOrSpeed | Duration (in seconds) or speed of the movement. |
UseDuration | Whether to use the previous param as duration or speed. |
Options | A structure with tween options. |
Returns:
The QuadPath object.
staticshake(Sprite:FlxSprite, Intensity:Float = 0.05, Duration:Float = 1, ?Axes:FlxAxes, ?Options:Null<TweenOptions>):ShakeTween
A simple shake effect for FlxSprite. Shorthand for creating a ShakeTween, starting it and adding it to the TweenManager.
FlxTween.shake(Sprite, 0.1, 2, FlxAxes.XY, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Sprite | Sprite to shake. |
---|---|
Intensity | Percentage representing the maximum distance that the sprite can move while shaking. |
Duration | The length in seconds that the shaking effect should last. |
Axes | On what axes to shake. Default value is |
Options | A structure with tween options. |
Returns:
The added ShakeTween object.
staticstopFlickering(basic:FlxBasic):Void
Cancels all flicker tweens on the object in the global tween manager
5.7.0
.statictween(Object:Dynamic, Values:Dynamic, Duration:Float = 1, ?Options:Null<TweenOptions>):VarTween
Tweens numeric public properties of an Object. Shorthand for creating a VarTween, starting it and adding it to the TweenManager.
FlxTween.tween(Object, { x: 500, y: 350, "scale.x": 2 }, 2.0, { ease: easeFunction, onStart: onStart, onUpdate: onUpdate, onComplete: onComplete, type: ONESHOT });
Parameters:
Object | The object containing the properties to tween. |
---|---|
Values | An object containing key/value pairs of properties and target values. |
Duration | Duration of the tween in seconds. |
Options | A structure with tween options. |
Returns:
The added VarTween object.
Variables
read onlyexecutions:Int = 0
How many times this tween has been executed / has finished so far - useful to
stop the LOOPING
and PINGPONG
types after a certain amount of time
Methods
cancel():Void
Immediately stops the Tween and removes it from its
manager
without calling the onComplete
callback.
Yields control to the next chained Tween if one exists.
cancelChain():Void
Immediately stops the Tween and removes it from its
manager
without calling the onComplete
callback
or yielding control to the next chained Tween if one exists.
If control has already been passed on, forwards the cancellation request along the chain to the currently active Tween.
4.3.0
.