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.
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. Tween
s created manually (i.e. by using Tween.new()
) are invalid and can't be used for tweening values.
A Tween
animation is composed of a sequence of Tweeners, which by default are executed one after another. You can create a sequence by appending Tweeners to the Tween
. Animating something with a Tweener is called tweening. Example tweening sequence looks like this:
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 and finally the Node.queue_free is called to remove the sprite. See methods tween_property, tween_interval, tween_callback and tween_method for more usage information.
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 different transition type in the above example, you can do:
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 this example the Tween
is bound and have set a default transition:
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 Tween
s is animating arbitrary set of objects:
var tween = create_tween()
for sprite in get_children():
tween.tween_property(sprite, "position", Vector2(), 1)
In the example above, all children of a node are moved one after another to position (0, 0).
Some Tweeners use transitions and eases. The first accepts an 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: All Tween
s will automatically start by default. To prevent a Tween
from autostarting, you can call stop immediately after it was created.
Methods¶
chain ( ) |
|
custom_step ( float delta ) |
|
get_total_elapsed_time ( ) const |
|
interpolate_value ( Variant initial_value, Variant delta_value, float elapsed_time, float duration, TransitionType trans_type, EaseType ease_type ) static |
|
is_running ( ) |
|
is_valid ( ) |
|
void |
kill ( ) |
parallel ( ) |
|
void |
pause ( ) |
void |
play ( ) |
set_parallel ( bool parallel=true ) |
|
set_pause_mode ( TweenPauseMode mode ) |
|
set_process_mode ( TweenProcessMode mode ) |
|
set_speed_scale ( float speed ) |
|
set_trans ( TransitionType trans ) |
|
void |
stop ( ) |
tween_callback ( Callable callback ) |
|
tween_interval ( float time ) |
|
tween_method ( Callable method, Variant from, Variant to, float duration ) |
|
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).
Note: The Tween
is removed (invalidated) after this signal is emitted, but it doesn't happen immediately, but on the next processing frame. Calling stop inside the signal callback will preserve the Tween
.
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 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 parallelly.
Enumerations¶
enum TweenProcessMode:
TWEEN_PROCESS_PHYSICS = 0 --- The
Tween
updates during the physics frame.TWEEN_PROCESS_IDLE = 1 --- The
Tween
updates during the idle frame.
enum 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.TWEEN_PAUSE_STOP = 1 --- If SceneTree is paused, the
Tween
will also pause.TWEEN_PAUSE_PROCESS = 2 --- The
Tween
will process regardless of whether SceneTree is paused.
enum TransitionType:
TRANS_LINEAR = 0 --- The animation is interpolated linearly.
TRANS_SINE = 1 --- The animation is interpolated using a sine function.
TRANS_QUINT = 2 --- The animation is interpolated with a quintic (to the power of 5) function.
TRANS_QUART = 3 --- The animation is interpolated with a quartic (to the power of 4) function.
TRANS_QUAD = 4 --- The animation is interpolated with a quadratic (to the power of 2) function.
TRANS_EXPO = 5 --- The animation is interpolated with an exponential (to the power of x) function.
TRANS_ELASTIC = 6 --- The animation is interpolated with elasticity, wiggling around the edges.
TRANS_CUBIC = 7 --- The animation is interpolated with a cubic (to the power of 3) function.
TRANS_CIRC = 8 --- The animation is interpolated with a function using square roots.
TRANS_BOUNCE = 9 --- The animation is interpolated by bouncing at the end.
TRANS_BACK = 10 --- The animation is interpolated backing out at ends.
enum EaseType:
EASE_IN = 0 --- The interpolation starts slowly and speeds up towards the end.
EASE_OUT = 1 --- The interpolation starts quickly and slows down towards the end.
EASE_IN_OUT = 2 --- A combination of EASE_IN and EASE_OUT. The interpolation is slowest at both ends.
EASE_OUT_IN = 3 --- A combination of EASE_IN and EASE_OUT. The interpolation is fastest at both ends.
Method Descriptions¶
Binds this Tween
with the given node
. Tween
s are processed directly by the SceneTree, so they run independently of the animated nodes. When you bind a Node with the Tween
, the Tween
will halt the animation when the object is not inside tree and the Tween
will be automatically killed when the bound object is freed. Also TWEEN_PAUSE_BOUND will make the pausing behavior dependent on the bound node.
For a shorter way to create and bind a Tween
, you can use Node.create_tween.
Tween chain ( )
Used to chain two Tweeners after set_parallel is called with true
.
var tween = create_tween().set_parallel(true)
tween.tween_property(...)
tween.tween_property(...) # Will run parallelly with above.
tween.chain().tween_property(...) # Will run after two above are finished.
Processes the Tween
by given delta
value, in seconds. Mostly useful when the Tween
is paused, for controlling it manually. Can also be used to end the Tween
animation immediately, by using delta
longer than the whole duration.
Returns true
if the Tween
still has Tweeners that haven't finished.
Note: The Tween
will become invalid after finished, but you can call stop after the step, to keep it and reset.
float get_total_elapsed_time ( ) const
Returns the total time in seconds the Tween
has been animating (i.e. time since it started, not counting pauses etc.). The time is affected by set_speed_scale and stop will reset it to 0
.
Note: As it results from accumulating frame deltas, the time returned after the Tween
has finished animating will be slightly greater than the actual Tween
duration.
Variant interpolate_value ( Variant initial_value, Variant delta_value, float elapsed_time, float duration, TransitionType trans_type, EaseType ease_type ) static
This method can be used for manual interpolation of a value, when you don't want Tween
to do animating for you. It's similar to @GlobalScope.lerp, but with support for custom transition and easing.
initial_value
is the starting value of the interpolation.
delta_value
is the change of the value in the interpolation, i.e. it's equal to final_value - initial_value
.
elapsed_time
is the time in seconds that passed after the interpolation started and it's used to control the position of the interpolation. E.g. when it's equal to half of the duration
, the interpolated value will be halfway between initial and final values. This value can also be greater than duration
or lower than 0, which will extrapolate the value.
duration
is the total time of the interpolation.
Note: If duration
is equal to 0
, the method will always return the final value, regardless of elapsed_time
provided.
bool is_running ( )
Returns whether the Tween
is currently running, i.e. it wasn't paused and it's not finished.
bool is_valid ( )
Returns whether the Tween
is valid. A valid Tween
is a Tween
contained by the scene tree (i.e. the array from SceneTree.get_processed_tweens will contain this Tween
). Tween
might become invalid when it has finished tweening or was killed, also when created with Tween.new()
. Invalid Tween
can't have Tweeners appended, because it can't animate them.
void kill ( )
Aborts all tweening operations and invalidates the Tween
.
Tween parallel ( )
Makes the next Tweener run parallelly to the previous one. Example:
var tween = create_tween()
tween.tween_property(...)
tween.parallel().tween_property(...)
tween.parallel().tween_property(...)
All Tweeners in the example will run at the same time.
You can make the Tween
parallel by default by using set_parallel.
void pause ( )
Pauses the tweening. The animation can be resumed by using play.
void play ( )
Resumes a paused or stopped Tween
.
Sets the default ease type for PropertyTweeners and MethodTweeners animated by this Tween
.
Sets the number of times the tweening sequence will be repeated, i.e. set_loops(2)
will run the animation twice.
Calling this method without arguments will make the Tween
run infinitely, until it is either killed by kill or by freeing bound node, or all the animated objects have been freed (which makes further animation impossible).
Warning: Make sure to always add some duration/delay when using infinite loops. 0-duration looped animations (e.g. single CallbackTweener with no delay or PropertyTweener with invalid node) are equivalent to infinite while
loops and will freeze your game. If a Tween
's lifetime depends on some node, always use bind_node.
If parallel
is true
, the Tweeners appended after this method will by default run simultaneously, as opposed to sequentially.
Tween set_pause_mode ( TweenPauseMode mode )
Determines the behavior of the Tween
when the SceneTree is paused. Check TweenPauseMode for options.
Default value is TWEEN_PAUSE_BOUND.
Tween set_process_mode ( TweenProcessMode mode )
Determines whether the Tween
should run during idle frame (see Node._process) or physics frame (see Node._physics_process.
Default value is TWEEN_PROCESS_IDLE.
Scales the speed of tweening. This affects all Tweeners and their delays.
Tween set_trans ( TransitionType trans )
Sets the default transition type for PropertyTweeners and MethodTweeners animated by this Tween
.
void stop ( )
Stops the tweening and resets the Tween
to its initial state. This will not remove any appended Tweeners.
CallbackTweener tween_callback ( Callable callback )
Creates and appends a CallbackTweener. This method can be used to call an arbitrary method in any object. Use Callable.bind to bind additional arguments for the call.
Example: object that keeps shooting every 1 second.
var tween = get_tree().create_tween().set_loops()
tween.tween_callback(shoot).set_delay(1)
Example: turning a sprite red and then blue, with 2 second delay.
var tween = get_tree().create_tween()
tween.tween_callback($Sprite.set_modulate.bind(Color.red)).set_delay(2)
tween.tween_callback($Sprite.set_modulate.bind(Color.blue)).set_delay(2)
IntervalTweener tween_interval ( float time )
Creates and appends an IntervalTweener. This method can be used to create delays in the tween animation, as an alternative for using the delay in other Tweeners or when there's no animation (in which case the Tween
acts as a timer). time
is the length of the interval, in seconds.
Example: creating an interval in code execution.
# ... some code
await create_tween().tween_interval(2).finished
# ... more code
Example: creating an object that moves back and forth and jumps every few seconds.
var tween = create_tween().set_loops()
tween.tween_property($Sprite, "position:x", 200.0, 1).as_relative()
tween.tween_callback(jump)
tween.tween_interval(2)
tween.tween_property($Sprite, "position:x", -200.0, 1).as_relative()
tween.tween_callback(jump)
tween.tween_interval(2)
MethodTweener tween_method ( Callable method, Variant from, Variant to, float duration )
Creates and appends a MethodTweener. This method is similar to a combination of tween_callback and tween_property. It calls a method over time with a tweened value provided as an argument. The value is tweened between from
and to
over the time specified by duration
, in seconds. Use Callable.bind to bind additional arguments for the call. You can use MethodTweener.set_ease and MethodTweener.set_trans to tweak the easing and transition of the value or MethodTweener.set_delay to delay the tweening.
Example: making a 3D object look from one point to another point.
var tween = create_tween()
tween.tween_method(look_at.bind(Vector3.UP), Vector3(-1, 0, -1), Vector3(1, 0, -1), 1) # The look_at() method takes up vector as second argument.
Example: setting a text of a Label, using an intermediate method and after a delay.
func _ready():
var tween = create_tween()
tween.tween_method(set_label_text, 0, 10, 1).set_delay(1)
func set_label_text(value: int):
$Label.text = "Counting " + str(value)
PropertyTweener tween_property ( Object object, NodePath property, Variant final_val, float duration )
Creates and appends a PropertyTweener. This method tweens a property
of an object
between an initial value and final_val
in a span of time equal to duration
, in seconds. The initial value by default is a value at the time the tweening of the PropertyTweener start. For example:
var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2(100, 200), 1)
tween.tween_property($Sprite, "position", Vector2(200, 300), 1)
will move the sprite to position (100, 200) and then to (200, 300). If you use PropertyTweener.from or PropertyTweener.from_current, the starting position will be overwritten by the given value instead. See other methods in PropertyTweener to see how the tweening can be tweaked further.
Note: You can find the correct property name by hovering over the property in the Inspector. You can also provide the components of a property directly by using "property:component"
(eg. position:x
), where it would only apply to that particular component.
Example: moving object twice from the same position, with different transition types.
var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1).as_relative().set_trans(Tween.TRANS_SINE)
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1).as_relative().from_current().set_trans(Tween.TRANS_EXPO)