FlixelTween

View source

class

org.flixelgdx.tween.FlixelTween

public abstract class FlixelTween implements Poolable

Base class for all FlixelGDX tweens and motion interpolators.

A FlixelTween provides a flexible system for animating properties, variables, or custom behaviors over time, often used for smooth transitions, UI animations, procedural effects, and advanced gameplay motions. FlixelTweens can manipulate values such as position, color, angle, scale, or arbitrary numbers, and support features like easing, delay, repeats, ping-pong (reverse-on-repeat), pausing, and callbacks for completion events.

Common Use Cases

• Smoothly moving sprites or objects from one position to another
• Animating color transitions (e.g., fading to black, flashing effects)
• Pulsing, scaling, or rotating objects for visual effects
• Chaining tweens to create sequenced or looping animations
• Triggering sound or code when an animation completes

How Tweens are Managed

Tweens are not updated automatically unless added to a FlixelTweenManager. By default, all tweens are managed by a single global manager, but you can create and control your own managers for local tween control (such as for a specific state or menu screen).

Each tween may be paused, resumed, finished (immediately), restarted (for repeat behavior), or canceled. Tweens are generally pooled for efficient memory use.

Extension and Implementation

Subclasses of FlixelTween implement specialized behavior:

• FlixelGoalTween: interpolates properties of objects using lambda getters and setters
• FlixelNumTween: tweens a simple numeric value via a callback
• FlixelColorTween: tweens between colors
• FlixelAngleTween: smoothly rotates a value
• FlixelLinearMotion and others: for advanced motion paths

Key Fields

• tweenSettings: the configuration parameters for this tween (duration, repeat, easing, etc.)
• manager: the manager that updates and contains this tween instance
• paused, active, finished: control and status flags
• scale: represents current tween progress, interpolated from 0 to 1
• secondsSinceStart, executions: time-tracking for tween progress and repeats

Usage Example

// Start a tween that moves a sprite's x value from 0 to 100 over 1 second.
FlixelTween tween = FlixelTween.tween(sprite, new FlixelTweenSettings()
  .addGoal(sprite::getX, 100f, sprite::setX)
  .setDuration(1f)
  .setEase(FlixelEase::cubicInOut)
  .setOnComplete(tween -> Flixel.info("Done!")));

Lifecycle and Pooling

When a tween completes (naturally or by calling FlixelTween.finish()), it is automatically released back to a pool unless flagged otherwise. Do not hold references to finished or canceled tweens if using pooling, as they may be reused. If you must keep the reference of a tween, consider taking a look at FlixelTweenType.PERSIST.

Thread Safety

Tweens and their managers are generally intended for use on the game thread only.

See Also: FlixelTweenManager, FlixelTweenSettings

Constructors

FlixelTween()

protected FlixelTween()

Default constructor for pooling purposes.

---

FlixelTween(FlixelTweenSettings)

protected FlixelTween(FlixelTweenSettings tweenSettings)

Constructs a new tween with the provided settings.

Parameters:

Name	Description
tweenSettings	The settings that configure and determine how the tween should animate.

---

Fields

tweenSettings

protected FlixelTweenSettings tweenSettings

The settings used for how the tween is handled and calculated (aka how it looks and animates).

---

manager

protected FlixelTweenManager manager

The parent manager that this tween gets updated in.

---

scale

protected float scale

How far the tween is tweening itself. This is what's used to actually tween the object!

---

secondsSinceStart

protected float secondsSinceStart

How many seconds has elapsed since this tween started.

---

executions

protected int executions

How many times this tween has updated.

---

paused

public boolean paused

Is this tween currently paused?

---

active

protected boolean active

Is this tween active?

---

finished

public boolean finished

Is this tween finished tweening?

---

backward

protected boolean backward

Is this tween tweening backwards?

---

internalRestart

protected boolean internalRestart

Set during FlixelTween.finish() when restarting for LOOPING/PINGPONG so subclasses keep original start values.

---

Methods

tween(Object, FlixelTweenSettings)

public static FlixelTween tween(Object object, FlixelTweenSettings tweenSettings)

Creates a tween with the provided settings and adds it to the global tween manager (which starts it automatically).

Goals must be property goals (getter and setter references). The legacy string-based var goals API has been removed from the framework; use explicit getter and setter pairs so tweens stay compatible with ahead-of-time targets, or integrate a third-party reflection helper in your game project if you still need name-driven access (for example the ReflectAOT Gradle plugin).

Parameters:

Name	Description
object	The logical tween subject for FlixelGoalTween.setObject(Object) and FlixelGoalTween.isTweenOf(Object, String).
tweenSettings	Settings including property goals.

Returns: The newly created and started tween.

Throws:

Type	Description
IllegalArgumentException	If no property goals are present.

---

num(float, float, FlixelTweenSettings, UpdateCallback)

public static FlixelTween num(float from, float to, FlixelTweenSettings tweenSettings, UpdateCallback updateCallback)

Creates a new numerical tween with the provided settings and adds it to the global tween manager (which starts it automatically). Shorthand for create, add and start.

Parameters:

Name	Description
from	The starting floating point value.
to	The ending floating point value.
tweenSettings	The settings that configure and determine how the tween should animate.
updateCallback	Callback function for updating any variable(s) that needs the current value when the tween updates.

Returns: The newly created and started tween.

---

angle(FlixelAngleable, float, FlixelTweenSettings)

public static FlixelTween angle(FlixelAngleable target, float toAngle, FlixelTweenSettings tweenSettings)

Creates a new angle tween with the provided settings and adds it to the global tween manager.

Parameters:

Name	Description
target	The object to tween the angle of.
toAngle	The ending angle (degrees).
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

angle(FlixelAngleable, float, float, FlixelTweenSettings)

public static FlixelTween angle(FlixelAngleable target, float fromAngle, float toAngle, FlixelTweenSettings tweenSettings)

Creates a new angle tween with the provided settings and adds it to the global tween manager.

Parameters:

Name	Description
target	The object to tween the angle of.
fromAngle	The starting angle (degrees).
toAngle	The ending angle (degrees).
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

color(FlixelColorable, FlixelColor, FlixelColor, FlixelTweenSettings)

public static FlixelTween color(FlixelColorable colorable, FlixelColor from, FlixelColor to, FlixelTweenSettings tweenSettings)

Creates a new color tween with the provided settings and adds it to the global tween manager.

It's advised you use this method rather than directly changing the color of a sprite, as FlixelColorTween will handle the color interpolation and apply it to the sprite smoothly, rather than causing a flash or jump in color.

Parameters:

Name	Description
colorable	The tint target; often a FlixelSprite.
from	The starting color.
to	The ending color.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

color(FlixelColorable, FlixelColor, FlixelColor, FlixelTweenSettings, Runnable)

public static FlixelTween color(FlixelColorable colorable, FlixelColor from, FlixelColor to, FlixelTweenSettings tweenSettings, Runnable onColor)

Creates a new color tween with the provided settings and adds it to the global tween manager.

It's advised you use this method rather than directly changing the color of a sprite, as FlixelColorTween will handle the color interpolation and apply it to the sprite smoothly, rather than causing a flash or jump in color.

Parameters:

Name	Description
colorable	The tint target; often a FlixelSprite.
from	The starting color.
to	The ending color.
tweenSettings	The settings that configure and determine how the tween should animate.
onColor	The callback to run when the tween is complete.

Returns: The newly created and started tween.

---

color(FlixelColorable, Color, Color, FlixelTweenSettings)

public static FlixelTween color(FlixelColorable colorable, Color from, Color to, FlixelTweenSettings tweenSettings)

Creates a new color tween using libGDX Color values with the provided settings and adds it to the global tween manager.

It's advised you use this method rather than directly changing the color of a sprite, as FlixelColorTween will handle the color interpolation and apply it to the sprite smoothly, rather than causing a flash or jump in color.

Parameters:

Name	Description
colorable	The tint target; often a FlixelSprite.
from	The starting color.
to	The ending color.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

color(FlixelColorable, Color, Color, FlixelTweenSettings, Runnable)

public static FlixelTween color(FlixelColorable colorable, Color from, Color to, FlixelTweenSettings tweenSettings, Runnable onColor)

Creates a new color tween using libGDX Color values with the provided settings and adds it to the global tween manager.

It's advised you use this method rather than directly changing the color of a sprite, as FlixelColorTween will handle the color interpolation and apply it to the sprite smoothly, rather than causing a flash or jump in color.

Parameters:

Name	Description
colorable	The tint target; often a FlixelSprite.
from	The starting color.
to	The ending color.
tweenSettings	The settings that configure and determine how the tween should animate.
onColor	The callback to run when the tween is complete.

Returns: The newly created and started tween.

---

color(FlixelColorable, FlixelColor, Color, FlixelTweenSettings)

public static FlixelTween color(FlixelColorable colorable, FlixelColor from, Color to, FlixelTweenSettings tweenSettings)

Creates a new color tween using mixture of libGDX's Color and FlixelGDX's FlixelColor values with the provided settings and adds it to the global tween manager.

It's advised you use this method rather than directly changing the color of a sprite, as FlixelColorTween will handle the color interpolation and apply it to the sprite smoothly, rather than causing a flash or jump in color.

Parameters:

Name	Description
colorable	The tint target; often a FlixelSprite.
from	The starting color.
to	The ending color.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

color(FlixelColorable, Color, FlixelColor, FlixelTweenSettings)

public static FlixelTween color(FlixelColorable colorable, Color from, FlixelColor to, FlixelTweenSettings tweenSettings)

Creates a new color tween using mixture of libGDX's Color and FlixelGDX's FlixelColor values with the provided settings and adds it to the global tween manager.

It's advised you use this method rather than directly changing the color of a sprite, as FlixelColorTween will handle the color interpolation and apply it to the sprite smoothly, rather than causing a flash or jump in color.

Parameters:

Name	Description
colorable	The tint target; often a FlixelSprite.
from	The starting color.
to	The ending color.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

shake(FlixelShakeable, FlixelAxes, float, FlixelTweenSettings)

public static FlixelTween shake(FlixelShakeable shakeable, FlixelAxes axes, float intensity, FlixelTweenSettings tweenSettings)

Creates a shake tween using defaults FlixelShakeUnit.FRACTION and fadeOut == false (full strength each frame until the tween ends). Pooled instances are reset to those defaults before configuration.

Parameters:

Name	Description
shakeable	The shake channel to jitter (sprite offset, object position, window, etc.).
axes	Axes that receive position jitter.
intensity	With FlixelShakeUnit.FRACTION, use a small value (for example 0.05f).
tweenSettings	Duration, ease, and callbacks.

Returns: The new tween, already added to the global manager.

---

shake(FlixelShakeable, FlixelAxes, float, FlixelTweenSettings, FlixelShakeUnit, boolean)

public static FlixelTween shake(FlixelShakeable shakeable, FlixelAxes axes, float intensity, FlixelTweenSettings tweenSettings, FlixelShakeUnit shakeUnit, boolean fadeOut)

Creates a shake tween with explicit FlixelShakeUnit and fade-out taper.

Parameters:

Name	Description
shakeable	The shake channel to jitter.
axes	Axes that receive position jitter.
intensity	Interpretation depends on shakeUnit.
tweenSettings	Duration, ease, and callbacks.
shakeUnit	FlixelShakeUnit.FRACTION or FlixelShakeUnit.PIXELS.
fadeOut	If true, amplitude is scaled by (1 - scale) toward the end of the tween.

Returns: The new tween, already added to the global manager.

---

flicker(FlixelVisible, FlixelTweenSettings)

public static FlixelTween flicker(FlixelVisible visible, FlixelTweenSettings tweenSettings)

Creates a new flicker tween with the provided settings and adds it to the global tween manager.

Parameters:

Name	Description
visible	The visibility target to flicker.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

flicker(FlixelVisible, float, float, boolean, FlixelTweenSettings, Predicate<FlixelFlickerTween>)

public static FlixelTween flicker(FlixelVisible visible, float period, float ratio, boolean endVisibility, FlixelTweenSettings tweenSettings, Predicate<FlixelFlickerTween> tweenFunction)

Creates a new flicker tween with the provided settings and adds it to the global tween manager.

Parameters:

Name	Description
visible	The visibility target to flicker.
period	Length of one full on/off cycle, in seconds.
ratio	Fraction of each period spent invisible, clamped to [0, 1]. A ratio of 0.5 reproduces HaxeFlixel's FlxFlicker.flicker even toggle, where HaxeFlixel's Interval parameter is half of this period. Other ratios bias the cycle toward mostly visible or mostly invisible, which HaxeFlixel's toggle-only flicker cannot do.
endVisibility	The visibility of the flicker at the end.
tweenSettings	The settings that configure and determine how the tween should animate.
tweenFunction	The function to use for the flicker.

Returns: The newly created and started tween.

---

linearMotion(FlixelPositional, float, float, float, float, float, boolean, FlixelTweenSettings)

public static FlixelTween linearMotion(FlixelPositional target, float fromX, float fromY, float toX, float toY, float durationOrSpeed, boolean useDuration, FlixelTweenSettings tweenSettings)

Creates a new linear motion tween with the provided settings and adds it to the global tween manager.

Parameters:

Name	Description
target	The target to move.
fromX	The starting X position.
fromY	The starting Y position.
toX	The ending X position.
toY	The ending Y position.
durationOrSpeed	The duration or speed of the motion.
useDuration	Whether to use the duration or speed.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

circularMotion(FlixelPositional, float, float, float, float, boolean, float, boolean, FlixelTweenSettings)

public static FlixelTween circularMotion(FlixelPositional target, float centerX, float centerY, float radius, float angleDeg, boolean clockwise, float durationOrSpeed, boolean useDuration, FlixelTweenSettings tweenSettings)

Creates a new circular motion tween with the provided settings and adds it to the global tween manager.

Parameters:

Name	Description
target	The target to move.
centerX	The center X position.
centerY	The center Y position.
radius	The radius of the motion.
angleDeg	The angle of the motion.
clockwise	The direction of the motion.
durationOrSpeed	The duration or speed of the motion.
useDuration	Whether to use the duration or speed.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

quadMotion(FlixelPositional, float, float, float, float, float, float, float, boolean, FlixelTweenSettings)

public static FlixelTween quadMotion(FlixelPositional target, float fromX, float fromY, float cx, float cy, float toX, float toY, float durationOrSpeed, boolean useDuration, FlixelTweenSettings tweenSettings)

Quadratic Bézier motion (one control point). Same timing rules as FlixelTween.linearMotion(...). If useDuration is true, durationOrSpeed is seconds; otherwise pixels per second along the approximated curve length.

Parameters:

Name	Description
target	The target to move.
fromX	The starting X position.
fromY	The starting Y position.
cx	The control point X position.
cy	The control point Y position.
toX	The ending X position.
toY	The ending Y position.
durationOrSpeed	The duration or speed of the motion.
useDuration	Whether to use the duration or speed.

---

cubicMotion(FlixelPositional, float, float, float, float, float, float, float, float, float, boolean, FlixelTweenSettings)

public static FlixelTween cubicMotion(FlixelPositional target, float p0x, float p0y, float p1x, float p1y, float p2x, float p2y, float p3x, float p3y, float durationOrSpeed, boolean useDuration, FlixelTweenSettings tweenSettings)

Cubic Bézier motion. (p0x, p0y) through (p3x, p3y) with control points (p1x, p1y) and (p2x,p2y).

Parameters:

Name	Description
target	The target to move.
p0x	The starting X position.
p0y	The starting Y position.
p1x	The first control point X position.
p1y	The first control point Y position.
p2x	The second control point X position.
p2y	The second control point Y position.
p3x	The ending X position.
p3y	The ending Y position.
durationOrSpeed	The duration or speed of the motion.
useDuration	Whether to use the duration or speed.
tweenSettings	The settings that configure and determine how the tween should animate.

Returns: The newly created and started tween.

---

linearPath(FlixelPositional, float, boolean, FlixelTweenSettings, float...)

public static FlixelTween linearPath(FlixelPositional target, float durationOrSpeed, boolean useDuration, FlixelTweenSettings tweenSettings, float... xy)

Piecewise-linear path through vertices x0,y0,x1,y1,.... Requires at least two points (four floats).

Parameters:

Name	Description
target	The target to move.
durationOrSpeed	The duration or speed of the motion.
useDuration	Whether to use the duration or speed.
tweenSettings	The settings that configure and determine how the tween should animate.
xy	Alternating x and y coordinates along the path.

Returns: The newly created and started tween.

---

quadPath(FlixelPositional, float, boolean, FlixelTweenSettings, float...)

public static FlixelTween quadPath(FlixelPositional target, float durationOrSpeed, boolean useDuration, FlixelTweenSettings tweenSettings, float... xy)

Chain of quadratic Bézier segments. Points are start, control, end, control, end, ... (odd vertex count, at least three points and six floats minimum).

Parameters:

Name	Description
target	The target to move.
durationOrSpeed	The duration or speed of the motion.
useDuration	Whether to use the duration or speed.
tweenSettings	The settings that configure and determine how the tween should animate.
xy	Alternating x and y for each vertex.

Returns: The newly created and started tween.

---

start()

public FlixelTween start()

Starts this tween and resets every value to its initial state.

---

update(float)

public final void update(float elapsed)

Updates this tween by the given delta time.

If you wish to change how a tween's values are updated, then consider looking at FlixelTween.updateTweenValues()

Parameters:

Name	Description
elapsed	The amount of time that has passed since the last update.

---

finish()

public void finish()

Called when the tween reaches the end of its duration.

Invokes onComplete (including for LOOPING/PINGPONG each cycle). LOOPING/PINGPONG restart (PINGPONG flips direction). Non-looping tweens (ONESHOT, PERSIST, BACKWARD) are deactivated so they stop updating and no longer overwrite the target; only ONESHOT is removed from the manager.

---

destroy()

public void destroy()

Sets this tween's FlixelTweenSettings and FlixelTweenManager to null.

---

updateTweenValues()

protected void updateTweenValues()

Hook method called by FlixelTween.update(float) after FlixelTween.scale has been computed and all common checks have passed. Subclasses should override this to apply their tween-specific value updates instead of overriding FlixelTween.update(float).

This method is guaranteed to only be called when the tween is active (not paused, not finished, has a manager and settings). The FlixelTween.scale field is already set to the correct value for the current frame.

---

resume()

public FlixelTween resume()

Resumes this tween if it was previously paused.

Returns: this tween.

---

pause()

public FlixelTween pause()

Pauses this tween, stopping it from updating until resumed.

Returns: this tween.

---

stop()

public FlixelTween stop()

Stops this tween. Note that this does not remove the tween from the active tweens in its manager.

Returns: this tween.

---

restart()

public void restart()

Restarts this tween from the beginning. Resets elapsed time and scale so the tween runs again from the start (or from current property values for property/var tweens when restarted manually).

---

cancel()

public FlixelTween cancel()

Cancels this tween, removes it from its manager and automatically defaults its values.

---

reset()

public void reset()

---

resetBasic()

public void resetBasic()

Resets only the basic values of this tween without removing any references to the object, its settings or its callback function.

---

getTweenSettings()

public FlixelTweenSettings getTweenSettings()

---

setTweenSettings(FlixelTweenSettings)

public FlixelTween setTweenSettings(FlixelTweenSettings tweenSettings)

---

registerTweenType(Class<T>, Supplier<T>)

public static FlixelTweenManager registerTweenType(Class<T> tweenClass, Supplier<T> poolFactory)

Registers a tween type with a pool factory on the global manager. Returns the manager so calls can be chained when registering several types at startup.

Parameters:

Name	Description
tweenClass	The tween class to register.
poolFactory	A supplier for new tween instances when the pool is empty.

Returns: The global manager, for chaining.

Throws:

Type	Description
NullPointerException	If poolFactory is null.

See Also: FlixelTweenManager.registerTweenType

---

updateTweens(float)

public static void updateTweens(float elapsed)

Advances every active tween on the global manager by elapsed seconds.

Parameters:

Name	Description
elapsed	The elapsed time in seconds.

---

cancelTweensOf(Object, String...)

public static void cancelTweensOf(Object object, String... fieldPaths)

Cancels active tweens whose FlixelTween.isTweenOf(Object, String) matches object and optional fieldPaths (OR semantics). Empty fieldPaths matches any field on object for supporting tween types.

Parameters:

Name	Description
object	The object to cancel tweens of.
fieldPaths	The field paths to cancel tweens of.

Throws:

Type	Description
NullPointerException	If the object is null.

See Also: FlixelTweenManager.cancelTweensOf

---

completeTweensOf(Object, String...)

public static void completeTweensOf(Object object, String... fieldPaths)

Snaps matching non-looping tweens to their end state in one step (large delta) and runs completion logic where applicable.

Parameters:

Name	Description
object	The object to complete tweens of.
fieldPaths	The field paths to complete tweens of.

Throws:

Type	Description
NullPointerException	If the object is null.

See Also: FlixelTweenManager.completeTweensOf

---

completeAllTweens()

public static void completeAllTweens()

Completes all active non-looping tweens on the global manager.

---

completeTweensOfType(Class<? extends FlixelTween>)

public static void completeTweensOfType(Class<? extends FlixelTween> type)

Completes active non-looping tweens assignable to type.

Parameters:

Name	Description
type	The type of tween to complete.

Throws:

Type	Description
NullPointerException	If the type is null.

See Also: FlixelTweenManager.completeTweensOfType

---

containsTweensOf(Object, String...)

public static boolean containsTweensOf(Object object, String... fieldPaths)

Checks if the global manager contains tweens of the given object and field paths.

Parameters:

Name	Description
object	The object to check.
fieldPaths	The field paths to check.

Returns: True if the global manager contains tweens of the given object and field paths, false otherwise.

Throws:

Type	Description
NullPointerException	If the object is null.

See Also: FlixelTweenManager.containsTweensOf

---

clearTweenPools()

public static void clearTweenPools()

Clears every tween pool on the global manager (e.g. after a major state reset).

---

resetRegistry()

public static void resetRegistry()

Resets the registry of all registered tween types and their respective pools.

It is advised to only call this if you know what you are doing, as this will include the default registered tween types. If you call this, you will need to register the tween types again.

---

cancelActiveTweens()

public static void cancelActiveTweens()

Cancels every active tween on the global manager. Does not clear pools; pair with FlixelTween.clearTweenPools() if you want a full reset (as Flixel.switchState does when clearTweens is true).

---

getGlobalManager()

public static FlixelTweenManager getGlobalManager()

---

getManager()

public FlixelTweenManager getManager()

---

isFinished()

public boolean isFinished()

---

getFinished()

public boolean getFinished()

Returns whether this tween has completed all of its iterations.

---

isActive()

public boolean isActive()

---

getActive()

public boolean getActive()

Returns whether this tween is currently active and updating.

---

setActive(boolean)

public void setActive(boolean active)

---

setManager(FlixelTweenManager)

public FlixelTween setManager(FlixelTweenManager newManager)

---

isTweenOf(Object, String)

public boolean isTweenOf(Object object, String field)

Whether this tween is considered to animate object for the given logical field or path. Used by FlixelTweenManager.cancelTweensOf(Object, String...) and related APIs.

Parameters:

Name	Description
object	The instance to test (e.g. the root passed to cancelTweensOf).
field	Optional goal key or dotted path (e.g. "x" or "weapon.rotation"); null or empty matches any field on object for types that support it.

Returns: false by default; subclasses override.

---