Tween

Hérite de : RefCounted < Object

Objet léger utilisé pour l'animation générale par script, en utilisant des Tweeners.

Description

Les tweens sont généralement utiles pour des animations ayant besoin d'interpoler une propriété numérique sur une plage de valeurs. Le nom tween provient de l'anglais in-betweening (litt. "entre-dedans"), une technique d'animation où l'on spécifie des clés d'animation et l'ordinateur interpole les trames qui apparaissent entre elles. Animer quelque chose avec un Tween est appelé du tweening.

Tween est plus adapté qu'AnimationPlayer pour les animations où l'on ne connaît pas les valeurs finales à l'avance. Par exemple, interpoler une valeur de zoom de caméra choisie dynamiquement est mieux fait avec un Tween, il serait difficile de faire la même chose avec un nœud AnimationNode. Les tweens sont aussi plus légers qu'AnimationPlayer, car ils sont très adaptés aux animations simples ou aux tâches générales qui ne nécessitent pas d'ajustement manuel dans l'éditeur. Ils peuvent être utilisés d'une manière "déclencher et oublier" pour de la logique qui serait normalement faite dans du code. Vous pouvez par exemple faire tirer quelque chose périodiquement en utilisant un CallbackTweener bouclant avec un délai.

Un Tween peut être créé en utilisant soit SceneTree.create_tween() ou Node.create_tween(). Les Tweens créés manuellement (par ex. en utilisant Tween.new()) sont invalides et ne peuvent être utiliser pour tweener des valeurs.

Une animation de tween est créée en ajoutant des Tweeners à l'objet Tween, en utilisant tween_property(), tween_interval(), tween_callback() ou tween_method() :

GDScriptC#

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)

Cette séquence changera le nœud $Sprite en rouge, puis le réduira jusqu'à le faire disparaître et enfin Node.queue_free() sera appelée pour libérer le sprite. Les Tweeners sont exécutés l'un après l'autre par défaut. Ce comportement peut être changé en utilisant parallel() et set_parallel().

Quand un Tweener est créé avec une des méthodes tween_*, une méthode peut être enchaînée pour ajuster les propriétés de ce Tweener. Par exemple, si vous souhaitez définir un autre type d'accélération dans l'exemple précédent, vous pouvez utiliser set_trans() :

GDScriptC#

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)

La plupart des méthodes Tween peuvent aussi être enchaînées de cette façon. Dans cet exemple, le Tween est lié au nœud du script en cours d'exécution et une transition par défaut sera définie pour ses Tweeners :

GDScriptC#

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)

Un autre usage intéressant des Tweens est l'animation d'ensembles arbitraires d'objets :

GDScriptC#

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

Dans l'exemple au-dessus, tous les enfants d'un nœud sont déplacés à leur tour à la position (0, 0).

Vous devriez éviter d'utiliser plus d'un Tween par propriété d'un objet. Si deux tweens ou plus animent une propriété en même temps, le dernier créé prendra la priorité et assignera la valeur finale. Si vous voulez interrompre et redémarrer une animation, envisagez d'assigner le Tween à une variable :

GDScriptC#

var tween
func animer():
    if tween:
        tween.kill() # Avorter l'animation précédente.
    tween = create_tween()

Certains Tweeners utilisent des transitions et des accélérations. Le premier accepte une constante TransitionType, et se réfère à la manière dont le timing de l'animation est gérée (voir easings.net pour quelques exemples). Le second accepte une constante EaseType, et contrôle où le trans_type s'applique durant l'interpolation (au début, à la fin, ou les deux). Si vous ne savez pas quel transition et accélération choisir, vous pouvez essayer différentes constantes TransitionType avec EASE_IN_OUT, et utiliser celle qui vous semble la meilleure.

Aide-mémoire des types de transitions et d'accélération des Tween

Note : Les Tweens ne sont pas prévus pour être réutilisés et essayer de le faire résulte en un comportement indéfini. Créez un nouveau Tween pour chaque animation et chaque fois que vous recommencez une animation du début. Gardez à l'esprit que les Tweens commencent immédiatement, donc ne créez un Tween que lorsque vous voulez commencer à animer.

Note : Le tween est traité après tous les nœuds de la trame actuelle, c-à-d la méthode Node._process() du nœud serait appelée avant le tween (ou Node._physics_process() selon la valeur passée à 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
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()
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.

GDScriptC#

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.

---

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.

GDScriptC#

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

Définit le type d'accélération 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 d'accélération par défaut est EASE_IN_OUT.

var tween = create_tween()
tween.tween_property(self, "position", Vector2(300, 0), 0.5) # Utilise EASE_IN_OUT.
tween.set_ease(Tween.EASE_IN)
tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # Utilise 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", Couleur. 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().

---

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 :

GDScriptC#

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 :

GDScriptC#

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 :

GDScriptC#

# ... 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 :

GDScriptC#

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 :

GDScriptC#

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 :

GDScriptC#

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.

GDScriptC#

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.

GDScriptC#

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.