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.
Checking the stable version of the documentation...
AnimationMixer
Hérité par : AnimationPlayer, AnimationTree
Classe de base pour AnimationPlayer et AnimationTree.
Description
Classe de base pour AnimationPlayer et AnimationTree pour gérer les listes d'animation. Elle possède également des propriétés générales et des méthodes de lecture et de mélange.
Après avoir instancié les données d'information de lecture dans la classe étendue, le mélange est traité par AnimationMixer.
Tutoriels
Propriétés
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Méthodes
_post_process_key_value(animation: Animation, track: int, value: Variant, object_id: int, object_sub_idx: int) virtual const |
|
add_animation_library(name: StringName, library: AnimationLibrary) |
|
void |
|
void |
capture(name: StringName, duration: float, trans_type: TransitionType = 0, ease_type: EaseType = 0) |
void |
|
find_animation(animation: Animation) const |
|
find_animation_library(animation: Animation) const |
|
get_animation(name: StringName) const |
|
get_animation_library(name: StringName) const |
|
get_animation_library_list() const |
|
get_animation_list() const |
|
get_root_motion_position() const |
|
get_root_motion_rotation() const |
|
get_root_motion_scale() const |
|
has_animation(name: StringName) const |
|
has_animation_library(name: StringName) const |
|
void |
|
void |
rename_animation_library(name: StringName, newname: StringName) |
Signaux
animation_finished(anim_name: StringName) 🔗
Notifie quand une animation a fini de jouer.
Note : Ce signal n'est pas émis si une animation boucle.
animation_libraries_updated() 🔗
Notifie quand les bibliothèques d'animation ont changé.
animation_list_changed() 🔗
Notifie quand une liste d'animation est changée.
animation_started(anim_name: StringName) 🔗
Notifie quand une animation commence à jouer.
Note : Ce signal n'est pas émis si une animation boucle.
caches_cleared() 🔗
Notifie quand les caches ont été effacées, soit automatiquement ou soit manuellement par clear_caches().
mixer_applied() 🔗
Notifie quand le résultat de mélange a été appliqué aux objets cibles.
mixer_updated() 🔗
Notifie quand une propriété liée au traitement a été mise à jour.
Énumérations
enum AnimationCallbackModeProcess: 🔗
AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS = 0
Traite l'animation pendant les trames de physique (voir Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS). Ceci est particulièrement utile lors de l'animation de corps physiques.
AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_IDLE = 1
Traite l'animation pendant les trames de traitement (voir Node.NOTIFICATION_INTERNAL_PROCESS).
AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_MANUAL = 2
Ne met à jour l'animation. Utilisez advance() pour mettre à jour l'animation manuellement.
enum AnimationCallbackModeMethod: 🔗
AnimationCallbackModeMethod ANIMATION_CALLBACK_MODE_METHOD_DEFERRED = 0
Regroupe les appels de méthodes durant le processus d'animation, puis effectue les appels après que les évènements ont été traités. Cela évite des bugs impliquant la suppression de nœuds ou la modification de l'AnimationPlayer durant la lecture.
AnimationCallbackModeMethod ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE = 1
Appelle la méthode aussitôt qu'elle est précisée lors de la lecture de l'animation.
enum AnimationCallbackModeDiscrete: 🔗
AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT = 0
Une valeur de piste Animation.UPDATE_DISCRETE a la priorité lors du mélange avec des valeurs de piste Animation.UPDATE_CONTINUOUS ou Animation.UPDATE_CAPTURE et une valeur de piste Animation.UPDATE_DISCRETE.
AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE = 1
Une valeur de piste Animation.UPDATE_CONTINUOUS ou Animation.UPDATE_CAPTURE a la priorité lors du mélange avec des valeurs de piste Animation.UPDATE_CONTINUOUS ou Animation.UPDATE_CAPTURE et une valeur de piste Animation.UPDATE_DISCRETE. C'est le comportement par défaut d'AnimationPlayer.
AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS = 2
Toujours traiter la valeur de piste Animation.UPDATE_DISCRETE comme Animation.UPDATE_CONTINUOUS avec Animation.INTERPOLATION_NEAREST. C'est le comportement par défaut d'AnimationTree.
Si une piste de valeur a des valeurs clés d'un type non-interpolable, elle est convertie en interne pour utiliser ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE avec Animation.UPDATE_DISCRETE.
Liste des types non-interpolables :
@GlobalScope.TYPE_BOOL et @GlobalScope.TYPE_INT sont traités comme @GlobalScope.TYPE_FLOAT pendant le mélange et arrondis lorsque le résultat est récupéré.
Il en va de même pour les tableaux et les vecteurs avec eux tels que @GlobalScope.TYPE_PACKED_INT32_ARRAY ou @GlobalScope.TYPE_VECTOR2I, ils sont traités comme @GlobalScope.TYPE_PACKED_FLOAT32_ARRAY ou @GlobalScope.TYPE_VECTOR2. Notez également que pour les tableaux, la taille est également interpolée.
@GlobalScope.TYPE_STRING et @GlobalScope.TYPE_STRING_NAME sont interpolés entre les codes de caractères et les longueurs, mais notez qu'il y a une différence d'algorithme entre l'interpolation par clé et l'interpolation par mélange.
Descriptions des propriétés
Si true, l’AnimationMixer fera le traitement.
int audio_max_polyphony = 32 🔗
Le nombre de sons simultanés possibles pour chacun des AudioStreamPlayers assignés.
Par exemple, si cette valeur est 32 et que l'animation a deux pistes audio, les deux AudioStreamPlayers assignés peuvent jouer simultanément jusqu'à 32 voix chacun.
AnimationCallbackModeDiscrete callback_mode_discrete = 1 🔗
void set_callback_mode_discrete(value: AnimationCallbackModeDiscrete)
AnimationCallbackModeDiscrete get_callback_mode_discrete()
Habituellement, les pistes peuvent être définies à Animation.UPDATE_DISCRETE pour se mettre à jour infréquemment, habituellement en utilisant l'interpolation du plus proche.
Cependant, lors du mélange avec Animation.UPDATE_CONTINUOUS, plusieurs résultats sont pris en considération. Le callback_mode_discrete le spécifie explicitement. Voir aussi AnimationCallbackModeDiscrete.
Pour que les résultats mélangés soient bons, il est recommandé de définir ceci à ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS pour se mettre à jour à chaque trame pendant le mélange. D'autres valeurs existent pour la compatibilité et elles sont bonnes s'il n'y a pas de mélange, mais pas ainsi, peuvent produire des artéfacts.
AnimationCallbackModeMethod callback_mode_method = 0 🔗
void set_callback_mode_method(value: AnimationCallbackModeMethod)
AnimationCallbackModeMethod get_callback_mode_method()
Le mode d'appel utilisé pour les pistes "Appel de méthode".
AnimationCallbackModeProcess callback_mode_process = 1 🔗
void set_callback_mode_process(value: AnimationCallbackModeProcess)
AnimationCallbackModeProcess get_callback_mode_process()
La notification de processus dans laquelle mettre à jour les animations.
Si true, le mélange utilise l'algorithme déterministe. Le poids total n'est pas normalisé et le résultat est accumulé avec une valeur initiale (0 ou une animation "RESET" si elle est présente).
Cela signifie que si la quantité totale du mélange est de 0.0, le résultat est égal à l'animation "RESET".
Si le nombre de pistes entre les animations mélangées est différent, l'animation avec la piste manquante est traitée comme si elle avait la valeur initiale.
Si false, Le mélange n'utilise pas l'algorithme déterministe. Le poids total est normalisé et vaut toujours 1.0. Si le nombre de pistes entre les animations mélangées est différent, rien n'est fait pour l'animation à laquelle il manque une piste.
Note : Dans AnimationTree, le mélange avec AnimationNodeAdd2, AnimationNodeAdd3, AnimationNodeSub2 ou un poids supérieur à 1.0 peut produire des résultats inattendus.
Par exemple, si AnimationNodeAdd2 mélange deux nœuds avec la quantité 1.0, alors le poids total est de 2.0 mais il sera normalisé pour rendre le montant total égal à 1.0 et le résultat sera égal à AnimationNodeBlend2 avec la quantité 0.5.
Ceci est utilisé par l'éditeur. Si défini à true, la scène sera sauvegardée avec les effets de l'animation de réinitialisation (l'animation avec la clé "RESET") appliqués comme si elle avait été positionnée au temps 0, avec l'éditeur gardant les valeurs que la scène avait avant la sauvegarde.
Cela rend plus commode la prévisualisation et la modification des animations dans l'éditeur, car les modifications de la scène ne seront pas sauvegardées tant qu'elles sont définies dans l'animation de réinitialisation.
bool root_motion_local = false 🔗
Si true, la valeur de get_root_motion_position() est extraite en tant que valeur de translation locale avant le mélange. En d'autres termes, c'est traité comme si la translation est faite après la rotation.
NodePath root_motion_track = NodePath("") 🔗
Le chemin vers la piste d'animation utilisée pour le mouvement racine. Les chemins doivent être des chemins d’arborescence de scène valides vers un nœud, et doivent être spécifiés à partir du nœud parent du nœud qui va reproduire l'animation. La piste du mouvement racine root_motion_track utilise le même format que Animation.track_set_path(), mais notez qu'un os doit être spécifié.
Si la piste est du type Animation.TYPE_POSITION_3D, Animation.TYPE_ROTATION_3D, ou Animation.TYPE_SCALE_3D la transformation sera annulée visuellement, et l'animation semblera rester sur place. Voir aussi get_root_motion_position(), get_root_motion_rotation(), get_root_motion_scale(), et RootMotionView.
NodePath root_node = NodePath("..") 🔗
Le nœud à partir duquel les références de chemin de nœud vont commencer.
Descriptions des méthodes
Variant _post_process_key_value(animation: Animation, track: int, value: Variant, object_id: int, object_sub_idx: int) virtual const 🔗
Une fonction virtuelle pour le traitement après avoir obtenu une clé pendant la lecture.
Error add_animation_library(name: StringName, library: AnimationLibrary) 🔗
Ajoute la bibliothèque library au lecteur d'animation, avec la clé name.
AnimationMixer a une bibliothèque globale par défaut avec une chaîne vide comme clé. Pour ajouter une animation à la bibliothèque globale :
var biblio_globale = mixer.get_animation_library(")
biblio_globale.add_animation("nom_animation", ressource_animation)
Avance manuellement les animations par le temps spécifié (en secondes).
void capture(name: StringName, duration: float, trans_type: TransitionType = 0, ease_type: EaseType = 0) 🔗
Si la piste d'animation spécifiée par name a une option Animation.UPDATE_CAPTURE, stocke les valeurs actuelles des objets indiqués par le chemin de piste en tant que cache. S'il y a déjà un cache capturé, l'ancien cache est supprimé.
Après cela, elle interpolera avec le résultat de mélange d'animation actuel pendant le processus de lecture pendant le temps spécifié par duration, fonctionnant comme un fondu enchaîné.
Vous pouvez spécifier trans_type pour la courbe de l'interpolation. Pour de meilleurs résultats, il peut être approprié de préciser Tween.TRANS_LINEAR pour les cas où la première clé de la piste commence par une valeur non nulle ou où la valeur clé ne change pas, et Tween.TRANS_QUAD pour les cas où la valeur clé change linéairement.
void clear_caches() 🔗
AnimationMixer met en cache des nœuds animés. Il peut ne pas remarquer si un nœud disparaît, clear_caches() le force à mettre à jour le cache à nouveau.
StringName find_animation(animation: Animation) const 🔗
Renvoie la clé de animation ou une chaîne StringName vide si elle n'est pas trouvée.
StringName find_animation_library(animation: Animation) const 🔗
Renvoie la clé pour l'AnimationLibrary qui contient animation ou une chaîne StringName vide si elle n'est pas trouvée.
Animation get_animation(name: StringName) const 🔗
Renvoie l'Animation avec la clé name. Si l'animation n'existe pas, null est renvoyé est une erreur est enregistrée.
AnimationLibrary get_animation_library(name: StringName) const 🔗
Renvoie la première AnimationLibrary avec la clé name ou null si aucune n'est trouvée.
Pour obtenir la bibliothèque d'animation globale d'AnimationMixer, utilisez get_animation_library(").
Array[StringName] get_animation_library_list() const 🔗
Renvoie la liste des clés de bibliothèque stockées.
PackedStringArray get_animation_list() const 🔗
Renvoie la liste des clés d'animations stockées.
Vector3 get_root_motion_position() const 🔗
Récupère le différentiel de position du mouvement avec root_motion_track en tant que Vector3 qui peut être utilisé autre part.
Si root_motion_track n'est pas un chemin vers une piste de type Animation.TYPE_POSITION_3D, renvoie Vector3(0,0,0).
Voir aussi root_motion_track et RootMotionView;
Le plus simple example est d'appliquer la position à CharacterBody3D :
var rotation_actuelle
func _process(delta):
if Input.is_action_just_pressed("animate"):
rotation_actuelle = get_quaternion()
state_machine.travel("Animate")
var velocite = rotation_actuelle * animation_tree.get_root_motion_position() / delta
set_velocity(velocite)
move_and_slide()
En utilisant ceci en combinaison avec get_root_motion_rotation_accumulator(), vous pouvez appliquer la position du mouvement racine correctement pour prendre en compte la rotation du nœud.
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
var vitesse = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta
set_velocity(vitesse)
move_and_slide()
Si root_motion_local vaut true, renvoie la valeur de translation pré-multipliée avec la rotation inversée.
Dans ce cas, le code peut être écrit comme suit :
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
var vitesse = get_quaternion() * animation_tree.get_root_motion_position() / delta
set_velocity(vitesse)
move_and_slide()
Vector3 get_root_motion_position_accumulator() const 🔗
Récupère la valeur mélangée des pistes de position avec root_motion_track en tant que Vector3 qui peut être utilisé autre part.
Ceci est utile dans les cas où vous voulez respecter les valeurs de clés initiales de l'animation.
Par exemple, si une animation avec seulement une clé Vector3(0, 0, 0) est jouée dans la trame précédente et ensuite une animation avec seulement une clé Vector3(1, 0, 1) est jouée à la trame suivante, la différence peut-être calculée comme suit :
var accumulateur_position_mouvement_racine_precedent
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var accumulateur_position_mouvement_racine_actuel = animation_tree.get_root_motion_position_accumulator()
var difference = accumulateur_position_mouvement_racine_actuel - accumulateur_position_mouvement_racine_precedent
accumulateur_position_mouvement_racine_precedent = accumulateur_position_mouvement_racine_actuel
transform.origin += difference
Cependant, si l'animation boucle, un changement discret non intentionnel peut se produire, donc cela n'est utile que pour certains cas d'utilisation simples.
Quaternion get_root_motion_rotation() const 🔗
Récupère le différentiel de rotation du mouvement avec root_motion_track en tant que Quaternion qui peut être utilisé autre part.
Si root_motion_track n'est pas un chemin vers une piste de type Animation.TYPE_ROTATION_3D, renvoie Quaternion(0, 0, 0, 1).
Voir aussi root_motion_track et RootMotionView;
Le plus simple example est d'appliquer la rotation à CharacterBody3D :
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
Quaternion get_root_motion_rotation_accumulator() const 🔗
Récupère la valeur du mélange des pistes de rotation avec le root_motion_track en tant que Quaternion qui peut être utilisé ailleurs.
Ceci est nécessaire pour appliquer correctement la position du mouvement racine, en tenant compte de la rotation. Voir aussi get_root_motion_position().
En outre, cela est utile dans les cas où vous voulez respecter les valeurs de clés initiales de l'animation.
Par exemple, si une animation avec une seule clé Quaternion(0, 0, 1) est jouée dans la trame précédente, puis une animation avec une seule clé Quaternion(0, 0.707, 0, 0.707) est jouée dans la trame suivante, la différence peut être calculée comme suit :
var accumulateur_rotation_mouvement_source_precedent
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var accumulateur_rotation_mouvement_source_actuel = animation_tree.get_root_motion_rotation_accumulator()
var difference = accumulateur_rotation_mouvement_source_precedent.inverse() * accumulateur_rotation_mouvement_source_actuel
accumulateur_rotation_mouvement_source_precedent = accumulateur_rotation_mouvement_source_actuel
transform.basis *= Basis(difference)
Cependant, si l'animation boucle, un changement discret non intentionnel peut se produire, donc cela n'est utile que pour certains cas d'utilisation simples.
Vector3 get_root_motion_scale() const 🔗
Récupère le différentiel d'échelle du mouvement avec root_motion_track en tant que Vector3 qui peut être utilisé autre part.
Si root_motion_track n'est pas un chemin vers une piste de type Animation.TYPE_SCALE_3D, renvoie Vector3(0, 0, 0).
Voir aussi root_motion_track et RootMotionView;
Le plus simple exemple est d'appliquer l'échelle à CharacterBody3D :
var echelle_actuelle = Vector3(1, 1, 1)
var accum_echelle = Vector3(1, 1, 1)
func _process(delta):
if Input.is_action_just_pressed("animate"):
echelle_actuelle = get_scale()
accum_echelle = Vector3(1, 1, 1)
state_machine.travel("Animate")
accum_echelle += animation_tree.get_root_motion_scale()
set_scale(echelle_actuelle * accum_echelle)
Vector3 get_root_motion_scale_accumulator() const 🔗
Récupère la valeur du mélange des pistes d'échelle avec le root_motion_track en tant que Vector3 qui peut être utilisé ailleurs.
Par exemple, si une animation avec une seule clé Vector3(1, 1, 1) est jouée dans la trame précédente, puis une animation avec une seule clé Vector3(2, 2, 2) est jouée dans la trame suivante, la différence peut être calculée comme suit :
var accumulateur_echelle_mouvement_source_precedent
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var accumulateur_echelle_mouvement_source_actuel = animation_tree.get_root_motion_scale_accumulator()
var difference = accumulateur_echelle_mouvement_source_actuel- accumulateur_echelle_mouvement_source_precedent
accumulateur_echelle_mouvement_source_precedent = accumulateur_echelle_mouvement_source_actuel
transform.basis = transform.basis.scaled(difference)
Cependant, si l'animation boucle, un changement discret non intentionnel peut se produire, donc cela n'est utile que pour certains cas d'utilisation simples.
bool has_animation(name: StringName) const 🔗
Renvoie true si l'AnimationMixer stocke une Animation avec la clé name.
bool has_animation_library(name: StringName) const 🔗
Renvoie true si l'AnimationMixer stocke une AnimationLibrary avec la clé name.
void remove_animation_library(name: StringName) 🔗
Retire la AnimationLibrary associée à la clé name.
void rename_animation_library(name: StringName, newname: StringName) 🔗
Déplace le AnimationLibrary associée à la clé name vers la clé newname.