Struct Tween

pub struct Tween { /* private fields */ }

Expand description

Godot class Tween.

Inherits RefCounted.

Related symbols:

tween: sidecar module with related enum/flag types
ITween: virtual methods
SignalsOfTween: signal collection

§Not instantiable

This class cannot be constructed. Obtain Gd<Tween> instances via Godot APIs.

§Godot docs

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 create_tween or 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.0)
tween.tween_property($Sprite, "scale", Vector2(), 1.0)
tween.tween_callback($Sprite.queue_free)

Tween tween = GetTree().CreateTween();
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f);
tween.TweenCallback(Callable.From(GetNode("Sprite").QueueFree));

This sequence will make the $Sprite node turn red, then shrink, before finally calling 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.0).set_trans(Tween.TRANS_SINE)
tween.tween_property($Sprite, "scale", Vector2(), 1.0).set_trans(Tween.TRANS_BOUNCE)
tween.tween_callback($Sprite.queue_free)

Tween tween = GetTree().CreateTween();
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f).SetTrans(Tween.TransitionType.Sine);
tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f).SetTrans(Tween.TransitionType.Bounce);
tween.TweenCallback(Callable.From(GetNode("Sprite").QueueFree));

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.0)
tween.tween_property($Sprite, "scale", Vector2(), 1.0)
tween.tween_callback($Sprite.queue_free)

var tween = GetTree().CreateTween().BindNode(this).SetTrans(Tween.TransitionType.Elastic);
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f);
tween.TweenCallback(Callable.From(GetNode("Sprite").QueueFree));

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.0)

Tween tween = CreateTween();
foreach (Node sprite in GetChildren())
	tween.TweenProperty(sprite, "position", Vector2.Zero, 1.0f);

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()

private Tween _tween;

public void Animate()
{
	if (_tween != null)
		_tween.Kill(); // Abort the previous animation
	_tween = CreateTween();
}

Some Tweeners use transitions and eases. The first accepts a [enum TransitionType] constant, and refers to the way the timing of the animation is handled (see easings.net for some examples). The second accepts an [enum 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 [enum TransitionType] constants with [constant EASE_IN_OUT], and use the one that looks best.

Tween easing and transition types cheatsheet

Note: Tweens are not designed to be reused 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 process method would be called before the tween (or physics_process depending on the value passed to set_process_mode).

Implementations§

§

impl Tween

pub fn tween_property( &mut self, object: impl AsArg<Gd<Object>>, property: impl AsArg<NodePath>, final_val: &Variant, duration: f64, ) -> Gd<PropertyTweener>

pub fn tween_interval(&mut self, time: f64) -> Gd<IntervalTweener>

pub fn tween_callback(&mut self, callback: &Callable) -> Gd<CallbackTweener>

pub fn tween_method( &mut self, method: &Callable, from: &Variant, to: &Variant, duration: f64, ) -> Gd<MethodTweener>

pub fn tween_subtween( &mut self, subtween: impl AsArg<Gd<Tween>>, ) -> Gd<SubtweenTweener>

pub fn custom_step(&mut self, delta: f64) -> bool

pub fn stop(&mut self)

pub fn pause(&mut self)

pub fn play(&mut self)

pub fn kill(&mut self)

pub fn get_total_elapsed_time(&self) -> f64

pub fn is_running(&self) -> bool

pub fn is_valid(&self) -> bool

pub fn bind_node(&mut self, node: impl AsArg<Gd<Node>>) -> Gd<Tween>

pub fn set_process_mode(&mut self, mode: TweenProcessMode) -> Gd<Tween>

pub fn set_pause_mode(&mut self, mode: TweenPauseMode) -> Gd<Tween>

pub fn set_ignore_time_scale(&mut self) -> Gd<Tween>

To set the default parameters, use Self::set_ignore_time_scale_ex and its builder methods. See the book for detailed usage instructions.

pub fn set_ignore_time_scale_ex<'ex>(&'ex mut self) -> ExSetIgnoreTimeScale<'ex>

pub fn set_parallel(&mut self) -> Gd<Tween>

To set the default parameters, use Self::set_parallel_ex and its builder methods. See the book for detailed usage instructions.

pub fn set_parallel_ex<'ex>(&'ex mut self) -> ExSetParallel<'ex>

pub fn set_loops(&mut self) -> Gd<Tween>

To set the default parameters, use Self::set_loops_ex and its builder methods. See the book for detailed usage instructions.

pub fn set_loops_ex<'ex>(&'ex mut self) -> ExSetLoops<'ex>

pub fn get_loops_left(&self) -> i32

pub fn set_speed_scale(&mut self, speed: f32) -> Gd<Tween>

pub fn set_trans(&mut self, trans: TransitionType) -> Gd<Tween>

pub fn set_ease(&mut self, ease: EaseType) -> Gd<Tween>

pub fn parallel(&mut self) -> Gd<Tween>

pub fn chain(&mut self) -> Gd<Tween>

pub fn interpolate_value( initial_value: &Variant, delta_value: &Variant, elapsed_time: f64, duration: f64, trans_type: TransitionType, ease_type: EaseType, ) -> Variant

Methods from Deref<Target = RefCounted>§

pub fn get_reference_count(&self) -> i32

Methods from Deref<Target = Object>§

pub fn get_script(&self) -> Option<Gd<Script>>

pub fn set_script(&mut self, script: impl AsArg<Option<Gd<Script>>>)

pub fn connect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, ) -> Error

pub fn connect_flags( &mut self, signal: impl AsArg<StringName>, callable: &Callable, flags: ConnectFlags, ) -> Error

pub fn get_class(&self) -> GString

pub fn is_class(&self, class: impl AsArg<GString>) -> bool

pub fn set(&mut self, property: impl AsArg<StringName>, value: &Variant)

pub fn get(&self, property: impl AsArg<StringName>) -> Variant

pub fn set_indexed( &mut self, property_path: impl AsArg<NodePath>, value: &Variant, )

pub fn get_indexed(&self, property_path: impl AsArg<NodePath>) -> Variant

pub fn get_property_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn get_method_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn property_can_revert(&self, property: impl AsArg<StringName>) -> bool

pub fn property_get_revert(&self, property: impl AsArg<StringName>) -> Variant

pub fn set_meta(&mut self, name: impl AsArg<StringName>, value: &Variant)

pub fn remove_meta(&mut self, name: impl AsArg<StringName>)

pub fn get_meta(&self, name: impl AsArg<StringName>) -> Variant

To set the default parameters, use Self::get_meta_ex and its builder methods. See the book for detailed usage instructions.

pub fn get_meta_ex<'ex>( &'ex self, name: impl AsArg<StringName> + 'ex, ) -> ExGetMeta<'ex>

pub fn has_meta(&self, name: impl AsArg<StringName>) -> bool

pub fn get_meta_list(&self) -> Array<StringName>

pub fn add_user_signal(&mut self, signal: impl AsArg<GString>)

To set the default parameters, use Self::add_user_signal_ex and its builder methods. See the book for detailed usage instructions.

pub fn add_user_signal_ex<'ex>( &'ex mut self, signal: impl AsArg<GString> + 'ex, ) -> ExAddUserSignal<'ex>

pub fn has_user_signal(&self, signal: impl AsArg<StringName>) -> bool

pub fn remove_user_signal(&mut self, signal: impl AsArg<StringName>)

pub fn emit_signal( &mut self, signal: impl AsArg<StringName>, varargs: &[Variant], ) -> Error

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_emit_signal( &mut self, signal: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Error, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn call( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Variant

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_call( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Variant, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn call_deferred( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Variant

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_call_deferred( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Variant, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn set_deferred( &mut self, property: impl AsArg<StringName>, value: &Variant, )

pub fn callv( &mut self, method: impl AsArg<StringName>, arg_array: &AnyArray, ) -> Variant

pub fn has_method(&self, method: impl AsArg<StringName>) -> bool

pub fn get_method_argument_count(&self, method: impl AsArg<StringName>) -> i32

pub fn has_signal(&self, signal: impl AsArg<StringName>) -> bool

pub fn get_signal_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn get_signal_connection_list( &self, signal: impl AsArg<StringName>, ) -> Array<Dictionary<Variant, Variant>>

pub fn get_incoming_connections(&self) -> Array<Dictionary<Variant, Variant>>

pub fn disconnect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, )

pub fn is_connected( &self, signal: impl AsArg<StringName>, callable: &Callable, ) -> bool

pub fn has_connections(&self, signal: impl AsArg<StringName>) -> bool

pub fn set_block_signals(&mut self, enable: bool)

pub fn is_blocking_signals(&self) -> bool

pub fn notify_property_list_changed(&mut self)

pub fn set_message_translation(&mut self, enable: bool)

pub fn can_translate_messages(&self) -> bool

pub fn tr(&self, message: impl AsArg<StringName>) -> GString

To set the default parameters, use Self::tr_ex and its builder methods. See the book for detailed usage instructions.

pub fn tr_ex<'ex>(&'ex self, message: impl AsArg<StringName> + 'ex) -> ExTr<'ex>

pub fn tr_n( &self, message: impl AsArg<StringName>, plural_message: impl AsArg<StringName>, n: i32, ) -> GString

To set the default parameters, use Self::tr_n_ex and its builder methods. See the book for detailed usage instructions.

pub fn tr_n_ex<'ex>( &'ex self, message: impl AsArg<StringName> + 'ex, plural_message: impl AsArg<StringName> + 'ex, n: i32, ) -> ExTrN<'ex>

pub fn get_translation_domain(&self) -> StringName

pub fn set_translation_domain(&mut self, domain: impl AsArg<StringName>)

pub fn is_queued_for_deletion(&self) -> bool

pub fn cancel_free(&mut self)

pub fn notify(&mut self, what: ObjectNotification)

⚠️ Sends a Godot notification to all classes inherited by the object.

Triggers calls to on_notification(), and depending on the notification, also to Godot’s lifecycle callbacks such as ready().

Starts from the highest ancestor (the Object class) and goes down the hierarchy. See also Godot docs for Object::notification().

§Panics

If you call this method on a user-defined object while holding a GdRef or GdMut guard on the instance, you will encounter a panic. The reason is that the receiving virtual method on_notification() acquires a GdMut lock dynamically, which must be exclusive.