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
Ereditato da: AnimationPlayer, AnimationTree
Classe di base per AnimationPlayer e AnimationTree.
Descrizione
Classe di base per AnimationPlayer e AnimationTree per gestire le liste di animazione. Ha anche proprietà e metodi generali per la riproduzione e la fusione.
Dopo aver istanziato i dati di riproduzione all'interno di una classe che la estende, la fusione è viene elaborata dall'AnimationMixer.
Tutorial
Proprietà
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Metodi
_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) |
Segnali
animation_finished(anim_name: StringName) 🔗
Informa quando un'animazione ha terminato la riproduzione.
Nota: Questo segnale non viene emesso se un'animazione è in ripetizione.
animation_libraries_updated() 🔗
Informa quando le librerie di animazione sono cambiate.
animation_list_changed() 🔗
Informa quando viene modificata una lista di animazione.
animation_started(anim_name: StringName) 🔗
Notifica quando inizia la riproduzione di un'animazione.
Nota: Questo segnale non viene emesso se un'animazione è in ripetizione.
caches_cleared() 🔗
Informa quando le memorie cache sono state pulite, automaticamente o manualmente tramite clear_caches().
mixer_applied() 🔗
Informa quando il risultato di fusione correlato è stato applicato agli oggetti di destinazione.
mixer_updated() 🔗
Informa quando il processo relativo alla proprietà è stato aggiornato.
Enumerazioni
enum AnimationCallbackModeProcess: 🔗
AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS = 0
Elabora l'animazione durante i frame di fisica (vedi Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS). Ciò è particolarmente utile per animare i corpi fisici.
AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_IDLE = 1
Elabora l'animazione durante i frame di processo (vedi Node.NOTIFICATION_INTERNAL_PROCESS).
AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_MANUAL = 2
Non elaborare l'animazione. Utilizza advance() per elaborare l'animazione manualmente.
enum AnimationCallbackModeMethod: 🔗
AnimationCallbackModeMethod ANIMATION_CALLBACK_MODE_METHOD_DEFERRED = 0
Raggruppa le chiamate di metodi durante il processo di animazione, quindi esegue le chiamate dopo che gli eventi sono elaborati. Questo evita bug che coinvolgono l'eliminazione di nodi o la modifica di AnimationPlayer durante la riproduzione.
AnimationCallbackModeMethod ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE = 1
Esegue le chiamate di metodi immediatamente quando sono raggiunte nell'animazione.
enum AnimationCallbackModeDiscrete: 🔗
AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT = 0
Un valore di una traccia con Animation.UPDATE_DISCRETE ha la precedenza quando si esegue la fusione tra i valori di una traccia Animation.UPDATE_CONTINUOUS o Animation.UPDATE_CAPTURE e i valori di una traccia Animation.UPDATE_DISCRETE.
AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE = 1
Un valore di una traccia con Animation.UPDATE_CONTINUOUS o Animation.UPDATE_CAPTURE ha la precedenza quando si esegue la fusione tra i valori di una traccia Animation.UPDATE_CONTINUOUS o Animation.UPDATE_CAPTURE e i valori di una traccia Animation.UPDATE_DISCRETE. Questo è il comportamento predefinito per AnimationPlayer.
AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS = 2
Tratta sempre il valore della traccia Animation.UPDATE_DISCRETE come Animation.UPDATE_CONTINUOUS con Animation.INTERPOLATION_NEAREST. Questo è il comportamento predefinito per AnimationTree.
Se una traccia di valore ha valori di chiave di tipo non interpolabili, viene convertita internamente per usare ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE con Animation.UPDATE_DISCRETE.
@GlobalScope.TYPE_BOOL e @GlobalScope.TYPE_INT vengono trattati come @GlobalScope.TYPE_FLOAT durante la fusione e arrotondati quando il risultato viene recuperato.
Lista di tipi che non si possono interpolare:
Lo stesso vale per array e vettori, come @GlobalScope.TYPE_PACKED_INT32_ARRAY o @GlobalScope.TYPE_VECTOR2I, vengono trattati come @GlobalScope.TYPE_PACKED_FLOAT32_ARRAY o @GlobalScope.TYPE_VECTOR2. Nota inoltre che per gli array, anche la dimensione viene interpolata.
@GlobalScope.TYPE_STRING e @GlobalScope.TYPE_STRING_NAME vengono interpolate tra codici carattere e lunghezze, ma si noti che esiste una differenza nell'algoritmo tra l'interpolazione tra chiavi e l'interpolazione tramite fusione.
Descrizioni delle proprietà
Se true, l'AnimationMixer verrà eseguito.
int audio_max_polyphony = 32 🔗
Il numero di suoni simultanei possibili per ciascuno degli AudioStreamPlayer assegnati.
Ad esempio, se questo valore è 32 e l'animazione ha due tracce audio, i due AudioStreamPlayer assegnati possono riprodurre audio simultaneamente fino a 32 suoni ciascuno.
AnimationCallbackModeDiscrete callback_mode_discrete = 1 🔗
void set_callback_mode_discrete(value: AnimationCallbackModeDiscrete)
AnimationCallbackModeDiscrete get_callback_mode_discrete()
Normalmente, le tracce possono essere impostate su Animation.UPDATE_DISCRETE per aggiornare raramente, di solito quando si utilizza l'interpolazione più vicino.
Tuttavia, quando si esegue la fusione con Animation.UPDATE_CONTINUOUS diversi risultati sono considerati. callback_mode_discrete lo specifica esplicitamente. Vedi anche AnimationCallbackModeDiscrete.
Per abbellire i risultati fusi, si consiglia di impostare questo a ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS per aggiornare ogni frame durante la fusione. Altri valori esistono per compatibilità e vanno bene se non è presente una fusione, ma se non è così, potrebbe produrre artefatti.
AnimationCallbackModeMethod callback_mode_method = 0 🔗
void set_callback_mode_method(value: AnimationCallbackModeMethod)
AnimationCallbackModeMethod get_callback_mode_method()
La modalità di chiamata utilizzata per le tracce "Chiamata di metodi".
AnimationCallbackModeProcess callback_mode_process = 1 🔗
void set_callback_mode_process(value: AnimationCallbackModeProcess)
AnimationCallbackModeProcess get_callback_mode_process()
La notifica di processo nella quale si aggiornano le animazioni.
Se true, la fusione usa l'algoritmo deterministico. Il peso totale non è normalizzato e il risultato è accumulato con un valore iniziale (0 o una animazione "RESET" se presente).
Ciò significa che se la quantità totale della fusione è 0.0, il risultato è uguale all'animazione "RESET".
Se il numero di tracce tra le animazioni fuse è diverso, l'animazione con la traccia mancante è trattata come se avesse il valore iniziale.
Se false, la fusione non usa l'algoritmo deterministico. Il peso totale è normalizzato e sempre 1.0. Se il numero di tracce tra le animazioni fuse è diverso, non si fa nulla sull'animazione a cui manca una traccia.
Nota: In AnimationTree, la fusione con AnimationNodeAdd2, AnimationNodeAdd3, AnimationNodeSub2 o il peso maggiore di 1.0 potrebbe produrre risultati inaspettati.
Ad esempio, se AnimationNodeAdd2 fonde due nodi con il numero 1.0, allora il peso totale sarà 2.0 ma sarà normalizzato per rendere il numero totale 1.0 e il risultato sarà uguale a AnimationNodeBlend2 con la il numero 0.5.
Questo è utilizzato dall'editor. Se impostato su true, la scena verrà salvata con gli effetti dell'animazione di reset (l'animazione con la chiave "RESET") applicata come se fosse stata cercata al tempo 0, con l'editor che mantiene i valori che la scena aveva prima di salvare.
Questo rende più conveniente visualizzare in anteprima e modificare le animazioni nell'editor, in quanto le modifiche alla scena non saranno salvate finché sono impostate nell'animazione di reset.
bool root_motion_local = false 🔗
Se true, il valore da get_root_motion_position() viene estratto come valore di traslazione locale prima della fusione. In altre parole, viene trattato come se la traslazione fosse stata effettuata dopo la rotazione.
NodePath root_motion_track = NodePath("") 🔗
Il percorso della traccia di animazione utilizzata per il movimento di radice. I percorsi devono essere validi percorsi di albero di scene a un nodo, e devono essere specificati a partire dal nodo genitore del nodo che riprodurrà l'animazione. root_motion_track utilizza lo stesso formato di Animation.track_set_path(), ma si noti che un osso deve essere specificato.
Se la traccia è di tipo Animation.TYPE_POSITION_3D, Animation.TYPE_ROTATION_3D, o Animation.TYPE_SCALE_3D la trasformazione sarà annullata visivamente, e l'animazione sembrerà rimanere sul posto. Vedi anche get_root_motion_position(), get_root_motion_rotation(), get_root_motion_scale(), e RootMotionView.
NodePath root_node = NodePath("..") 🔗
Il nodo da cui i riferimenti dei percorsi di nodo iniziano.
Descrizioni dei metodi
Variant _post_process_key_value(animation: Animation, track: int, value: Variant, object_id: int, object_sub_idx: int) virtual const 🔗
Una funzione virtuale per l'elaborazione dopo aver ricevuto una chiave durante la riproduzione.
Error add_animation_library(name: StringName, library: AnimationLibrary) 🔗
Aggiunge la libreria library al riproduttore di animazioni, sotto la chiave name.
AnimationMixer ha una libreria globale predefinita con una stringa vuota come chiave. Per aggiungere un'animazione alla libreria globale:
var global_library = mixer.get_animation_library("")
global_library.add_animation("animation_name", animation_resource)
Avanza manualmente le animazioni al tempo specificato (in secondi).
void capture(name: StringName, duration: float, trans_type: TransitionType = 0, ease_type: EaseType = 0) 🔗
Se la traccia di animazione specificata da name ha un'opzione Animation.UPDATE_CAPTURE, memorizza i valori attuali degli oggetti indicati dal percorso della traccia come cache. Se c'è già una cache catturata, la vecchia cache viene scartata.
Dopodiché, interpolerà con il risultato attuale della fusione dell'animazione durante il processo di riproduzione per il tempo specificato da duration, funzionando come una dissolvenza incrociata.
È possibile specificare trans_type come la curva per l'interpolazione. Per ottenere migliori risultati, potrebbe essere opportuno specificare Tween.TRANS_LINEAR per i casi in cui la prima chiave della traccia inizia con un valore non zero o dove il valore chiave non cambia, e Tween.TRANS_QUAD per i casi in cui il valore chiave cambia linearmente.
void clear_caches() 🔗
AnimationMixer memorizza i nodi animati nella cache. Potrebbe non notare se un nodo scompare; clear_caches() lo costringe ad aggiornare nuovamente la cache.
StringName find_animation(animation: Animation) const 🔗
Restituisce la chiave dell'animazione animation o un StringName vuoto se non trovata.
StringName find_animation_library(animation: Animation) const 🔗
Restituisce la chiave per l'AnimationLibrary che contiene l'animazione animation o un StringName vuoto se non trovata.
Animation get_animation(name: StringName) const 🔗
Restituisce l'Animation con la chiave name. Se l'animazione non esiste, null è restituito ed è generato un errore.
AnimationLibrary get_animation_library(name: StringName) const 🔗
Restituisce il primo AnimationLibrary con la chiave name o null se non trovato.
Per ottenere la libreria globale di animazioni dell'AnimationMixer, usa get_animation_library("").
Array[StringName] get_animation_library_list() const 🔗
Restituisce la lista di chiavi memorizzate di libreria.
PackedStringArray get_animation_list() const 🔗
Restituisce la lista di chiavi memorizzate di animazione.
Vector3 get_root_motion_position() const 🔗
Recupera il delta di movimento della posizione con la root_motion_track come Vector3 che può essere utilizzato altrove.
Se root_motion_track non è un percorso verso una traccia di tipo Animation.TYPE_POSITION_3D, restituisce Vector3(0, 0, 0).
Vedi anche root_motion_track e RootMotionView.
L'esempio più basilare è l'applicazione della posizione a CharacterBody3D:
var current_rotation
func _process(delta):
if Input.is_action_just_pressed("animate"):
current_rotation = get_quaternion()
state_machine.travel("Animate")
var velocity = current_rotation * animation_tree.get_root_motion_position() / delta
set_velocity(velocity)
move_and_slide()
Utilizzando questo in combinazione con get_root_motion_rotation_accumulator(), puoi applicare la posizione del movimento della radice più correttamente per tenere conto della rotazione del nodo.
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 velocity = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta
set_velocity(velocity)
move_and_slide()
Se root_motion_local è true, restituisce il valore di traslazione pre-moltiplicato con la rotazione invertita.
In questo caso, il codice può essere scritto come segue:
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 velocity = get_quaternion() * animation_tree.get_root_motion_position() / delta
set_velocity(velocity)
move_and_slide()
Vector3 get_root_motion_position_accumulator() const 🔗
Recupera il valore combinato delle tracce di posizione con root_motion_track come Vector3 che può essere utilizzato altrove.
Ciò è utile nei casi in cui si desidera rispettare i valori della chiave iniziale dell'animazione.
Ad esempio, se un'animazione con una sola chiave Vector3(0, 0, 0) viene riprodotta nel frame precedente e poi un'animazione con una sola chiave Vector3(1, 0, 1) viene riprodotta nel frame successivo, la differenza può essere calcolata come segue:
var prev_root_motion_position_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var current_root_motion_position_accumulator = animation_tree.get_root_motion_position_accumulator()
var difference = current_root_motion_position_accumulator - prev_root_motion_position_accumulator
prev_root_motion_position_accumulator = current_root_motion_position_accumulator
transform.origin += difference
Tuttavia, se l'animazione si ripete, potrebbe verificarsi un cambiamento discreto indesiderato, quindi questa funzionalità è utile solo per alcuni casi d'uso semplici.
Quaternion get_root_motion_rotation() const 🔗
Recupera il delta del movimento di rotazione con root_motion_track come Quaternion che può essere utilizzato altrove.
Se root_motion_track non è un percorso verso una traccia di tipo Animation.TYPE_ROTATION_3D, restituisce Quaternion(0, 0, 0, 1).
Vedi anche root_motion_track e RootMotionView.
L'esempio più basilare è per applicare la rotazione a 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 🔗
Recupera il valore combinato delle tracce di rotazione con root_motion_track come Quaternion che può essere utilizzato altrove.
Ciò è necessario per applicare correttamente la posizione del movimento radice, tenendo conto della rotazione. Vedi anche get_root_motion_position().
Inoltre, ciò è utile nei casi in cui si desidera rispettare i valori della chiave iniziale dell'animazione.
Ad esempio, se un'animazione con una sola chiave Quaternion(0, 0, 0, 1) viene riprodotta nel frame precedente e poi un'animazione con una sola chiave Quaternion(0, 0.707, 0, 0.707) viene riprodotta nel frame successivo, la differenza può essere calcolata come segue:
var prev_root_motion_rotation_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var current_root_motion_rotation_accumulator = animation_tree.get_root_motion_rotation_accumulator()
var difference = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator
prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator
transform.basis *= Basis(difference)
Tuttavia, se l'animazione si ripete, potrebbe verificarsi un cambiamento discreto indesiderato, quindi questa funzionalità è utile solo per alcuni casi d'uso semplici.
Vector3 get_root_motion_scale() const 🔗
Recupera il delta di movimento della scala con la root_motion_track come Vector3 che può essere utilizzato altrove.
Se root_motion_track non è un percorso verso una traccia di tipo Animation.TYPE_POSITION_3D, restituisce Vector3(0, 0, 0).
Vedi anche root_motion_track e RootMotionView.
L'esempio più basilare è l'applicazione della posizione a CharacterBody3D:
var current_scale = Vector3(1, 1, 1)
var scale_accum = Vector3(1, 1, 1)
func _process(delta):
if Input.is_action_just_pressed("animate"):
current_scale = get_scale()
scale_accum = Vector3(1, 1, 1)
state_machine.travel("Animate")
scale_accum += animation_tree.get_root_motion_scale()
set_scale(current_scale * scale_accum)
Vector3 get_root_motion_scale_accumulator() const 🔗
Recupera il valore combinato delle tracce di scala con root_motion_track come Vector3 che può essere utilizzato altrove.
Ad esempio, se un'animazione con una sola chiave Vector3(1, 1, 1) viene riprodotta nel frame precedente e poi un'animazione con una sola chiave Vector3(2, 2, 2) viene riprodotta nel frame successivo, la differenza può essere calcolata come segue:
var prev_root_motion_scale_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var current_root_motion_scale_accumulator = animation_tree.get_root_motion_scale_accumulator()
var difference = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator
prev_root_motion_scale_accumulator = current_root_motion_scale_accumulator
transform.basis = transform.basis.scaled(difference)
Tuttavia, se l'animazione si ripete, potrebbe verificarsi un cambiamento discreto indesiderato, quindi questa funzionalità è utile solo per alcuni casi d'uso semplici.
bool has_animation(name: StringName) const 🔗
Restituisce true se l'AnimationMixer memorizza un'animazione con la chiave name.
bool has_animation_library(name: StringName) const 🔗
Restituisce true se l'AnimationMixer memorizza una libreria di animazioni con la chiave name.
void remove_animation_library(name: StringName) 🔗
Rimuove l'AnimationLibrary associata alla chiave name.
void rename_animation_library(name: StringName, newname: StringName) 🔗
Sposta l'AnimationLibrary associata alla chiave name alla chiave newname.