Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Tween

Hérite de : RefCounted < Object

Objet léger utilisé pour l'animation générale par script, en utilisant des 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(), tween_method(), tween_subtween(), or tween_await():

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)

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

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)

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)

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 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 Node._process() method would be called before the tween (or Node._physics_process() depending on the value passed to set_process_mode()).

Méthodes

Tween

bind_node(node: Node)

Tween

chain()

bool

custom_step(delta: float)

int

get_loops_left() const

float

get_total_elapsed_time() const

bool

has_tweeners() const

Variant

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

bool

is_running()

bool

is_valid()

void

kill()

Tween

parallel()

void

pause()

void

play()

Tween

set_ease(ease: EaseType)

Tween

set_ignore_time_scale(ignore: bool = true)

Tween

set_loops(loops: int = 0)

Tween

set_parallel(parallel: bool = true)

Tween

set_pause_mode(mode: TweenPauseMode)

Tween

set_process_mode(mode: TweenProcessMode)

Tween

set_speed_scale(speed: float)

Tween

set_trans(trans: TransitionType)

void

stop()

AwaitTweener

tween_await(signal: Signal)

CallbackTweener

tween_callback(callback: Callable)

IntervalTweener

tween_interval(time: float)

MethodTweener

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

PropertyTweener

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

SubtweenTweener

tween_subtween(subtween: Tween)


Signaux

finished() 🔗

Émis quand le Tween a fini tout le tweening. Jamais émis lorsque le Tween est défini à une boucle infinie (voir set_loops()).


loop_finished(loop_count: int) 🔗

Émis lorsqu'une boucle complète est finie (voir set_loops()), fournissant l'index de la boucle. Ce signal n'est pas émis après la boucle finale, utilisez finished à la place pour ce cas.


step_finished(idx: int) 🔗

Émis lorsqu'une étape du Tween est terminée, en fournissant l'index de l'étape. Une étape est soit un seul Tweener ou un groupe de Tweeners fonctionnant en parallèle.


Énumérations

enum TweenProcessMode: 🔗

TweenProcessMode TWEEN_PROCESS_PHYSICS = 0

Le Tween se met à jour après chaque trame de physique (voir Node._physics_process()).

TweenProcessMode TWEEN_PROCESS_IDLE = 1

Le Tween se met à jour après chaque trame de traitement (voir Node._process()).


enum TweenPauseMode: 🔗

TweenPauseMode TWEEN_PAUSE_BOUND = 0

Si le Tween a un nœud lié, il traitera quand ce nœud peut traiter (voir Node.process_mode). Sinon, identique à TWEEN_PAUSE_STOP.

TweenPauseMode TWEEN_PAUSE_STOP = 1

Si le SceneTree est en pause, le Tween le sera aussi.

TweenPauseMode TWEEN_PAUSE_PROCESS = 2

Le Tween traitera peu importe l'état de pause du SceneTree.


enum TransitionType: 🔗

TransitionType TRANS_LINEAR = 0

L'animation est interpolée linéairement.

TransitionType TRANS_SINE = 1

L'animation est interpolée à l'aide d'une fonction sinusoïdale.

TransitionType TRANS_QUINT = 2

L'animation est interpolée avec une fonction quintique (à la puissance 5).

TransitionType TRANS_QUART = 3

L'animation est interpolée avec une fonction quartique (à la puissance 4).

TransitionType TRANS_QUAD = 4

L'animation est interpolée avec une fonction quadratique (à la puissance 2).

TransitionType TRANS_EXPO = 5

L'animation est interpolée avec une fonction exponentielle (à la puissance x).

TransitionType TRANS_ELASTIC = 6

L'animation est interpolée avec un effet élastique, se balançant aux niveaux des bornes.

TransitionType TRANS_CUBIC = 7

L'animation est interpolée avec une fonction cubique (à la puissance 3).

TransitionType TRANS_CIRC = 8

L'animation est interpolée avec la fonction de racine carrée.

TransitionType TRANS_BOUNCE = 9

L'animation est interpolée en rebondissant à la fin.

TransitionType TRANS_BACK = 10

L’animation est interpolée en reculant aux extrémités.

TransitionType TRANS_SPRING = 11

L'animation est interpolée comme un ressort vers la fin.


enum EaseType: 🔗

EaseType EASE_IN = 0

L'interpolation démarre lentement puis s'accélère à la fin.

EaseType EASE_OUT = 1

L'interpolation démarre rapidement puis ralentit à la fin.

EaseType EASE_IN_OUT = 2

Une combinaison de EASE_IN et de EASE_OUT. L'interpolation est plus lente au début et à la fin.

EaseType EASE_OUT_IN = 3

Une combinaison de EASE_IN et de EASE_OUT. L'interpolation est plus rapide au début et à la fin.


Descriptions des méthodes

Tween bind_node(node: Node) 🔗

Lie ce Tween avec le nœud node donné. Les Tweens sont traités directement par le SceneTree, donc ils fonctionnent indépendamment des nœuds animés. Lorsque vous liez un Node avec le Tween, le Tween arrêtera l'animation lorsque l'objet n'est pas à l'intérieur de l'arborescence et le Tween sera automatiquement tué lorsque l'objet lié est libéré. TWEEN_PAUSE_BOUND rendra aussi le comportement de pause dépendant du nœud lié.

Pour un moyen plus court de créer et de lier un Tween, vous pouvez utiliser Node.create_tween().


Tween chain() 🔗

Utiliser pour enchaîner deux Tweener après que set_parallel() est appelé avec true.

var tween = create_tween().set_parallel(true)
tween.tween_property(...)
tween.tween_property(...) # S'exécutera en parallèle de l'appel au-dessus.
tween.chain().tween_property(...) # S'exécutera que quand les deux appels au-dessus seront terminés.

bool custom_step(delta: float) 🔗

Traite le Tween par la valeur delta donnée, en secondes. Cela est surtout utile pour du contrôle manuel lorsque le Tween est mis en pause. Elle peut également être utilisée pour mettre fin à l'animation du Tween immédiatement, en fixant delta à une valeur plus longue que toute la durée de l'animation du Tween.

Renvoie true si le Tween a encore des Tweeners qui ne sont pas finis.


int get_loops_left() const 🔗

Renvoie le nombre de boucles restantes pour ce Tween (voir set_loops()). Une valeur de renvoie de -1 indique un Tween bouclant infiniement, et une valeur de renvoi de 0 indique que le Tween s'est déjà terminé.


float get_total_elapsed_time() const 🔗

Renvoie le temps total en secondes durant lequel Tween a animé (c.-à-d. le temps depuis son début, sans compter les pauses, etc.). Le temps est affecté par set_speed_scale(), et stop() le réinitialisera à 0.

Note : Comme il résulte de l'accumulation des deltas de trames, le temps renvoyé après que le Tween ait fini d'animer sera légèrement supérieur à la durée réelle du Tween.


bool has_tweeners() const 🔗

Returns true if any Tweener has been added to the Tween and the Tween is valid. Useful when tweeners are added dynamically and the tween can end up empty. Killing an empty tween before it starts will prevent errors.


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

Cette méthode peut être utilisée pour de l'interpolation manuelle d'une valeur, lorsque vous ne voulez pas que Tween fasse l'animation pour vous. Elle est similaire à @GlobalScope.lerp(), mais avec du support pour des transitions et accélérations personnalisées.

initial_value est la valeur de départ de l'interpolation.

delta_value est le changement de la valeur dans l'interpolation, c'est-à-dire qu'il est égal à final_value - initial_value.

elapsed_time est le temps en secondes passé après que l'interpolation ait commencé et il est utilisé pour contrôler la position de l'interpolation. Par exemple, lorsqu'il est égal à la moitié de duration, la valeur interpolée sera à mi-chemin entre les valeurs initiales et finales. Cette valeur peut également être supérieure à duration ou inférieure à 0, ce qui extrapolera la valeur.

duration est le temps total de l'interpolation.

Note : Si duration est égal à 0, la méthode renverra toujours la valeur finale, peu importe l'elapsed_time fourni.


bool is_running() 🔗

Renvoie si le Tween est actuellement en cours d'exécution, c'est-à-dire qu'il n'a pas été mis en pause et il n'est pas fini.


bool is_valid() 🔗

Renvoie si le Tween est valide. Un Tween valide est un Tween contenu par l'arborescence de scène (c.-à-d. le tableau de SceneTree.get_processed_tweens() contiendra ce Tween). Un Tween peut devenir invalide lorsqu'il a fini de tweening, est tué, ou lorsqu'il est créé avec Tween.new(). Les Tween invalides ne peuvent pas avoir de Tweeners ajoutés.


void kill() 🔗

Avorte toutes les opérations de tweening et invalide le Tween.


Tween parallel() 🔗

Fait que le prochain Tweener s'exécute en parallèle au précédent.

var tween = create_tween()
tween.tween_property(...)
tween.parallel().tween_property(...)
tween.parallel().tween_property(...)

Tous les Tweener de l'exemple s'exécuteront en même temps.

Vous pouvez rendre le Tween parallèle par défaut en utilisant set_parallel().


void pause() 🔗

Met en pause le tweening. L'animation peut être reprise en utilisant play().

Note : Si un Tween est en pause et n'est pas lié à un nœud, il existera indéfiniment jusqu'à ce qu'il soit manuellement démarré ou invalidé. Si vous perdez une référence à ce Tween, vous pouvez le récupérer en utilisant SceneTree.get_processed_tweens().


void play() 🔗

Reprend un Tween en pause ou arrêté.


Tween set_ease(ease: EaseType) 🔗

Sets the default ease type for PropertyTweeners and MethodTweeners appended after this method.

Before this method is called, the default ease type is EASE_IN_OUT.

var tween = create_tween()
tween.tween_property(self, "position", Vector2(300, 0), 0.5) # Uses EASE_IN_OUT.
tween.set_ease(Tween.EASE_IN)
tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # Uses EASE_IN.

Tween set_ignore_time_scale(ignore: bool = true) 🔗

Si ignore vaut true, le tween ignorera Engine.time_scale et se met à jour avec le temps réel écoulé. Cela affecte tous les Tweener et leurs délais. La valeur par défaut est false.


Tween set_loops(loops: int = 0) 🔗

Définit le nombre de fois que la séquence de tweening sera répétée, c'est-à-dire que set_loops(2) exécutera l'animation deux fois.

Appeler cette méthode sans argument fera s'exécuter le Tween de manière infinie, jusqu'à ce qu'il soit tué avec kill(), le nœud lié du Tween est libéré, ou tous les objets animés ont été libérés (ce qui rend la suite de l'animation impossible).

Attention : Assurez-vous d'ajouter toujours une durée ou un délai lors de l'utilisation de boucles infinies. Pour éviter le gel du jeu, les animations en boucle de durée nulle (p. ex. un single CallbackTweener sans délai) sont arrêtées après un petit nombre de boucles, qui peut produire des résultats inattendus. Si la durée de vie d'un Tween dépend d'un nœud, utilisez toujours bind_node().


Tween set_parallel(parallel: bool = true) 🔗

Si parallel vaut true, les Tweeners ajoutés après cette méthode s'exécuteront par défaut simultanément, au lieu de séquentiellement.

Note : Tout comme avec parallel(), le tweener ajouté juste avant cette méthode fera également partie de l'étape parallèle.

tween.tween_property(self, "position", Vector2(300, 0), 0.5)
tween.set_parallel()
tween.tween_property(self, "modulate", Color.GREEN, 0.5) # S'exécute ensemble avec le tweener de position.

Tween set_pause_mode(mode: TweenPauseMode) 🔗

Détermine le comportement du Tween lorsque le SceneTree est mis en pause.

La valeur par défaut est TWEEN_PAUSE_BOUND.


Tween set_process_mode(mode: TweenProcessMode) 🔗

Détermine si le Tween devrait s'exécuter après les cadres de traitement (voir Node._process()) ou les trames de physique (voir Node._physics_process()).

La valeur par défaut est TWEEN_PROCESS_IDLE.


Tween set_speed_scale(speed: float) 🔗

Redimensionne la vitesse du tweening. Cela affecte tous les Tweeners et leurs délais.


Tween set_trans(trans: TransitionType) 🔗

Définit le type de transition par défaut pour les PropertyTweeners et MethodTweeners ajoutés après cette méthode.

Avant que cette méthode soit appelée, le type de transition par défaut est TRANS_LINEAR.

var tween = create_tween()
tween.tween_property(self, "position", Vector2(300, 0), 0.5) # Utilise TRANS_LINEAR.
tween.set_trans(Tween.TRANS_SINE)
tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # Utilise TRANS_SINE.

void stop() 🔗

Arrête le tweening et réinitialise le Tween à son état initial. Cela ne supprimera pas de Tweeners ajoutés.

Note : Cela ne réinitialise pas les cibles des PropertyTweeners à leur valeurs de quand le Tween a démarré pour la première fois.

var tween = create_tween()

# Se déplacera de 0 à 500 en une 1 seconde.
position.x = 0.0
tween.tween_property(self, "position:x", 500, 1.0)

# Sera à (environ) 250 quand le minuteur se finit.
await get_tree().create_timer(0.5).timeout

# Se déplacera maintenant d'environ 250 à 500 en une 1 seconde,
# donc à la moitié de la vitesse d'avant.
tween.stop()
tween.play()

Note : Si un Tween est arrêté et n'est pas lié à un nœud, il existera toujours jusqu'à ce qu'il soit démarré ou invalidé manuellement. Si vous perdez une référence à ce genre de Tween, vous pouvez la récupérer en utilisant SceneTree.get_processed_tweens().


AwaitTweener tween_await(signal: Signal) 🔗

Creates and appends an AwaitTweener. This method can be used to await a signal to be emitted and create asynchronous animations or cutscenes.

The animation will not progress to the next step until the awaited signal is emitted or the connection becomes invalid (e.g. as a result of freeing the target object). If you know that the emission may not happen, use AwaitTweener.set_timeout().

Note: The awaited signal should be emitted during the step when AwaitTweener is active.

Example: An object launches itself and explodes upon collision or after 4 seconds.

var tween = create_tween()
tween.tween_callback(launch)
tween.tween_await(collided).set_timeout(4.0)
tween.tween_callback(explode)

Example: A character walks to a specific point, says some lines and walks back when the player closes the message box.

var tween = create_tween()
tween.tween_callback(walk_to.bind(600.0))
tween.tween_await(destination_reached)
tween.tween_callback(say_dialogue.bind("Good day, sir!"))
tween.tween_await(dialogue_closed)
tween.tween_callback(walk_to.bind(0.0))

Note: If you are awaiting a signal from a callback called in the same Tween, make sure the signal is emitted after the await starts. If it can't be reasonably guaranteed, you can await and emit in the same step:

var tween = create_tween()
tween.tween_await(signal)
tween.parallel().tween_callback(method_that_emits_signal)

CallbackTweener tween_callback(callback: Callable) 🔗

Crée et ajoute un CallbackTweener. Cette méthode peut être utilisée pour appeler une méthode arbitraire sur n'importe quel objet. Utilisez Callable.bind() pour passer des arguments additionnels lors de l'appel.

Exemple : Un objet qui tire toujours les secondes :

var tween = get_tree().create_tween().set_loops()
tween.tween_callback(tirer).set_delay(1.0)

Exemple : Changer un sprite en rouge puis en bleu, avec un délai de 2 secondes :

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(time: float) 🔗

Crée et ajoute un IntervalTweener. Cette méthode peut être utilisée pour créer des délais lors de l'interpolation du tween, ou comme une alternative pour utiliser le délai dans d'autres Tweeners, ou quand il n'y a pas d'animation (dans ce cas le Tween se comporte comme un minuteur). time est le durée du délai, en secondes.

Exemple : Créer un délai dans l'exécution du code :

# ... du code
await create_tween().tween_interval(2).finished
# ... encore du code

Exemple : Créer un objet qui se déplace d'avant en arrière et saute toutes les quelques secondes :

var tween = create_tween().set_loops()
tween.tween_property($Sprite, "position:x", 200.0, 1.0).as_relative()
tween.tween_callback(sauter)
tween.tween_interval(2)
tween.tween_property($Sprite, "position:x", -200.0, 1.0).as_relative()
tween.tween_callback(sauter)
tween.tween_interval(2)

MethodTweener tween_method(method: Callable, from: Variant, to: Variant, duration: float) 🔗

Crée et ajoute un MethodTweener. Cette méthode est similaire à une combinaison de tween_callback() et tween_property(). Elle appelle une méthode au fil du temps avec une valeur tweenée fournie comme argument. La valeur est tweenée entre from et to au cours du temps spécifié par duration, en secondes. Utilisez Callable.bind() pour lier des arguments supplémentaires à l'appel. Vous pouvez utiliser MethodTweener.set_ease() et MethodTweener.set_trans() pour modifier l'assouplissement et la transition de la valeur ou MethodTweener.set_delay() pour retarder le tweening.

Exemple: Faire regarder un objet 3D d'un point à un autre :

var tween = create_tween()
tween.tween_method(look_at.bind(Vector3.UP), Vector3(-1, 0, -1), Vector3(1, 0, -1), 1.0) # La méthode look_at() prend le vecteur up comme arguement.

Exemple : Définir le texte d'un Label, en utilisant une méthode intermédiaire et après un délai :

func _ready():
    var tween = create_tween()
    tween.tween_method(set_label_text, 0, 10, 1.0).set_delay(1.0)

func definir_texte_label(valeur: int):
    $Label.text = "Comptage " + str(valeur)

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

Crée et ajoute un PropertyTweener. Cette méthode interpole une propriété property d'un objet object entre une valeur initiale et une valeur finale final_val durant la durée duration, en secondes. La valeur initiale par défaut est la valeur de la propriété au moment où le tweening du PropertyTweener commence.

var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2(100, 200), 1.0)
tween.tween_property($Sprite, "position", Vector2(200, 300), 1.0)

déplacera la sprite à la position (100, 200) puis ensuite à (200, 300). Si vous utilisez PropertyTweener.from() ou PropertyTweener.from_current(), la position de départ sera remplacée par la valeur donnée à la place. Voir les autres méthodes de PropertyTweener pour voir comment le tweening peut être encore plus ajusté.

Note : Vous pouvez trouver les noms corrects des propriétés en survolant ces propriétés dans l'Inspecteur. Vous pouvez aussi fournir les composantes d'une propriété directement en utilisant "propriété:composante" (ex. position:x), l'interpolation ne se fera alors que sur cette unique composante.

Exemple : Déplacer un objet deux fois depuis la même position, avec différents types de transition.

var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1.0).as_relative().set_trans(Tween.TRANS_SINE)
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1.0).as_relative().from_current().set_trans(Tween.TRANS_EXPO)

SubtweenTweener tween_subtween(subtween: Tween) 🔗

Crée et ajoute un SubtweenTweener. Cette méthode peut être utiliser pour imbriquer un subtween dans ce Tween, permettant la création de séquences composables et plus complexes.

# Le sous-tween tournera l'objet.
var subtween = create_tween()
subtween.tween_property(self, "rotation_degrees", 45.0, 1.0)
subtween.tween_property(self, "rotation_degrees", 0.0, 1.0)

# Le tween parent exécutera le sous-tween comme l'une de ses étapes.
var tween = create_tween()
tween.tween_property(self, "position:x", 500, 3.0)
tween.tween_subtween(subtween)
tween.tween_property(self, "position:x", 300, 2.0)

Note : Les méthodes pause(), stop(), et set_loops() peuvent faire que le Tween parent soit bloqué à l'étape du sous-tween, voir la documentation sur ces méthodes pour plus d'informations.

Note : Les modes de pause et de traitement définis par set_pause_mode() et set_process_mode() sur subtween seront redéfinies par les paramètres du Tween parent.