Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Tween

Inherits: RefCounted < Object

Lightweight object used for general-purpose animation via script, using Tweeners.

Description

Tweens are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name tween comes from in-betweening, an animation technique where you specify keyframes and the computer interpolates the frames that appear between them. Animating something with a Tween is called tweening.

Tween is more suited than AnimationPlayer for animations where you don't know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a Tween; it would be difficult to do the same thing with an AnimationPlayer node. Tweens are also more light-weight than AnimationPlayer, so they are very much suited for simple animations or general tasks that don't require visual tweaking provided by the editor. They can be used in a fire-and-forget manner for some logic that normally would be done by code. You can e.g. make something shoot periodically by using a looped CallbackTweener with a delay.

A Tween can be created by using either SceneTree.create_tween or Node.create_tween. Tweens created manually (i.e. by using Tween.new()) are invalid and can't be used for tweening values.

A tween animation is created by adding Tweeners to the Tween object, using tween_property, tween_interval, tween_callback or tween_method:

var tween = get_tree().create_tween()
tween.tween_property($Sprite, "modulate", Color.RED, 1)
tween.tween_property($Sprite, "scale", Vector2(), 1)
tween.tween_callback($Sprite.queue_free)

This sequence will make the $Sprite node turn red, then shrink, before finally calling Node.queue_free to free the sprite. Tweeners are executed one after another by default. This behavior can be changed using parallel and set_parallel.

When a Tweener is created with one of the tween_* methods, a chained method call can be used to tweak the properties of this Tweener. For example, if you want to set a different transition type in the above example, you can use set_trans:

var tween = get_tree().create_tween()
tween.tween_property($Sprite, "modulate", Color.RED, 1).set_trans(Tween.TRANS_SINE)
tween.tween_property($Sprite, "scale", Vector2(), 1).set_trans(Tween.TRANS_BOUNCE)
tween.tween_callback($Sprite.queue_free)

Most of the Tween methods can be chained this way too. In the following example the Tween is bound to the running script's node and a default transition is set for its Tweeners:

var tween = get_tree().create_tween().bind_node(self).set_trans(Tween.TRANS_ELASTIC)
tween.tween_property($Sprite, "modulate", Color.RED, 1)
tween.tween_property($Sprite, "scale", Vector2(), 1)
tween.tween_callback($Sprite.queue_free)

Another interesting use for Tweens is animating arbitrary sets of objects:

var tween = create_tween()
for sprite in get_children():
    tween.tween_property(sprite, "position", Vector2(0, 0), 1)

In the example above, all children of a node are moved one after another to position (0, 0).

You should avoid using more than one Tween per object's property. If two or more tweens animate one property at the same time, the last one created will take priority and assign the final value. If you want to interrupt and restart an animation, consider assigning the Tween to a variable:

var tween
func animate():
    if tween:
        tween.kill() # Abort the previous animation.
    tween = create_tween()

Some Tweeners use transitions and eases. The first accepts a TransitionType constant, and refers to the way the timing of the animation is handled (see easings.net for some examples). The second accepts an EaseType constant, and controls where the trans_type is applied to the interpolation (in the beginning, the end, or both). If you don't know which transition and easing to pick, you can try different TransitionType constants with EASE_IN_OUT, and use the one that looks best.

Tween easing and transition types cheatsheet

Note: Tweens are not designed to be re-used and trying to do so results in an undefined behavior. Create a new Tween for each animation and every time you replay an animation from start. Keep in mind that Tweens start immediately, so only create a Tween when you want to start animating.

Note: The tween is processed after all of the nodes in the current frame, i.e. node's Node._process method would be called before the tween (or Node._physics_process depending on the value passed to set_process_mode).

Methods

Tween

bind_node ( Node node )

Tween

chain ( )

bool

custom_step ( float delta )

int

get_loops_left ( ) const

float

get_total_elapsed_time ( ) const

Variant

interpolate_value ( Variant initial_value, Variant delta_value, float elapsed_time, float duration, TransitionType trans_type, EaseType ease_type ) static

bool

is_running ( )

bool

is_valid ( )

void

kill ( )

Tween

parallel ( )

void

pause ( )

void

play ( )

Tween

set_ease ( EaseType ease )

Tween

set_loops ( int loops=0 )

Tween

set_parallel ( bool parallel=true )

Tween

set_pause_mode ( TweenPauseMode mode )

Tween

set_process_mode ( TweenProcessMode mode )

Tween

set_speed_scale ( float speed )

Tween

set_trans ( TransitionType trans )

void

stop ( )

CallbackTweener

tween_callback ( Callable callback )

IntervalTweener

tween_interval ( float time )

MethodTweener

tween_method ( Callable method, Variant from, Variant to, float duration )

PropertyTweener

tween_property ( Object object, NodePath property, Variant final_val, float duration )


Signals

finished ( )

Emitted when the Tween has finished all tweening. Never emitted when the Tween is set to infinite looping (see set_loops).


loop_finished ( int loop_count )

Emitted when a full loop is complete (see set_loops), providing the loop index. This signal is not emitted after the final loop, use finished instead for this case.


step_finished ( int idx )

Emitted when one step of the Tween is complete, providing the step index. One step is either a single Tweener or a group of Tweeners running in parallel.


Enumerations

enum TweenProcessMode:

TweenProcessMode TWEEN_PROCESS_PHYSICS = 0

The Tween updates after each physics frame (see Node._physics_process).

TweenProcessMode TWEEN_PROCESS_IDLE = 1

The Tween updates after each process frame (see Node._process).


enum TweenPauseMode:

TweenPauseMode TWEEN_PAUSE_BOUND = 0

If the Tween has a bound node, it will process when that node can process (see Node.process_mode). Otherwise it's the same as TWEEN_PAUSE_STOP.

TweenPauseMode TWEEN_PAUSE_STOP = 1

If SceneTree is paused, the Tween will also pause.

TweenPauseMode TWEEN_PAUSE_PROCESS = 2

The Tween will process regardless of whether SceneTree is paused.


enum TransitionType:

TransitionType TRANS_LINEAR = 0

The animation is interpolated linearly.

TransitionType TRANS_SINE = 1

The animation is interpolated using a sine function.

TransitionType TRANS_QUINT = 2

The animation is interpolated with a quint