View source

class FlxTween

package flixel.tweens

implements IFlxDestroyable

extended by AngleTween, ColorTween, NumTween, ShakeTween, VarTween, Motion

@:directlyUsed

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/or

      end 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 (200200) and (600800), 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

@:value(FlxTweenType.BACKWARD)staticBACKWARD:FlxTweenType = FlxTweenType.BACKWARD

Deprecated: "Use FlxTweenType.BACKWARD instead"

Deprecated, use FlxTweenType.BACKWARD instead.

@:value(FlxTweenType.LOOPING)staticLOOPING:FlxTweenType = FlxTweenType.LOOPING

Deprecated: "Use FlxTweenType.LOOPING instead"

Deprecated, use FlxTweenType.LOOPING instead.

@:value(FlxTweenType.ONESHOT)staticONESHOT:FlxTweenType = FlxTweenType.ONESHOT

Deprecated: "Use FlxTweenType.ONESHOT instead"

Deprecated, use FlxTweenType.ONESHOT instead.

@:value(FlxTweenType.PERSIST)staticPERSIST:FlxTweenType = FlxTweenType.PERSIST

Deprecated: "Use FlxTweenType.PERSIST instead"

Deprecated, use FlxTweenType.PERSIST instead.

@:value(FlxTweenType.PINGPONG)staticPINGPONG:FlxTweenType = FlxTweenType.PINGPONG

Deprecated: "Use FlxTweenType.PINGPONG instead"

Deprecated, use FlxTweenType.PINGPONG instead.

staticglobalManager:FlxTweenManager

The global tweening manager that handles global tweens

Available since

4.2.0

.

Static methods

@:value({ Duration : 1 })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.

Available since

4.9.0

.

@:value({ UseDuration : true, DurationOrSpeed : 1 })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.

@:value({ Duration : 1 })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.

Available since

4.9.0

.

@:value({ Duration : 1 })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.

@:value({ UseDuration : true, DurationOrSpeed : 1 })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.

@:value({ UseDuration : true, DurationOrSpeed : 1 })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.

@:value({ Duration : 1 })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.

@:value({ UseDuration : true, DurationOrSpeed : 1 })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.

@:value({ UseDuration : true, DurationOrSpeed : 1 })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.

@:value({ Duration : 1, Intensity : 0.05 })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 FlxAxes.XY / both.

Options

A structure with tween options.

Returns:

The added ShakeTween object.

@:value({ Duration : 1 })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

@:value(false)active:Bool = false

read onlybackward:Bool

@:value(0)duration:Float = 0

ease:EaseFunction

@:value(0)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

read onlyfinished:Bool

@:value(0)loopDelay:Float = 0

Seconds to wait between loops of this tween, 0 by default

manager:FlxTweenManager

The manager to which this tween belongs

Available since

4.2.0

.

onComplete:TweenCallback

onStart:TweenCallback

onUpdate:TweenCallback

percent:Float

Value between 0 and 1 that indicates how far along this tween is in its completion. A value of 0.33 means that the tween is 33% complete.

@:value(0)read onlyscale:Float = 0

@:value(0)startDelay:Float = 0

Seconds to wait until starting this tween, 0 by default

type:FlxTweenType

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.

Available since

4.3.0

.

destroy():Void

start():FlxTween

Starts the Tween, or restarts it if it's currently running.

then(tween:FlxTween):FlxTween

Specify a tween to be executed when this one has finished (useful for creating "tween chains").

wait(delay:Float):FlxTween

How many seconds to delay the execution of the next tween in a tween chain.