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...
SceneTree
Gestisce il ciclo di gioco tramite una gerarchia di nodi.
Descrizione
Come una delle classi più importanti, SceneTree gestisce la gerarchia dei nodi in una scena, così come le scene stesse. I nodi possono essere aggiunti, recuperati e rimossi. L'intero albero di scena (e quindi la scena attuale) può essere messo in pausa. Le scene possono essere caricate, cambiate e ricaricate.
Puoi anche usare SceneTree per organizzare i tuoi nodi in gruppi: ogni nodo può essere aggiunto a tutti i gruppi che vuoi creare, ad esempio un gruppo "nemico". Puoi quindi iterare questi gruppi o persino chiamare metodi e impostare proprietà su tutti i nodi appartenenti a un dato gruppo.
SceneTree è l'implementazione di MainLoop predefinita utilizzata dal motore, ed è quindi responsabile del ciclo di gioco.
Tutorial
Proprietà
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Metodi
Segnali
Emesso quando il nodo node entra in questo albero.
node_configuration_warning_changed(node: Node) 🔗
Emesso quando viene chiamato Node.update_configuration_warnings() del nodo node. Emesso solo nell'editor.
Emesso quando il nodo node esce da questo albero.
Emesso quando il nome (Node.name) del nodo node cambia.
physics_frame() 🔗
Emesso subito prima che Node._physics_process() venga chiamato su ogni nodo in questo albero.
process_frame() 🔗
Emesso subito prima che Node._process() venga chiamato su ogni nodo in questo albero.
scene_changed() 🔗
Emesso dopo che la nuova scena è stata aggiunta all'albero di scene e inizializzata. È possibile utilizzarlo per accedere in modo sicuro a current_scene quando si cambia scena.
# Questo codice si dovrebbe trovare all'interno di un autoload.
get_tree().change_scene_to_file(other_scene_path)
await get_tree().scene_changed
print(get_tree().current_scene) # Stampa la nuova scena.
tree_changed() 🔗
Emesso ogni volta che cambia la gerarchia dell'albero (i nodi vengono spostati, rinominati, ecc.).
tree_process_mode_changed() 🔗
Emesso quando il Node.process_mode di un nodo qualsiasi all'interno dell'albero viene modificato. Emesso solo nell'editor, per aggiornare la visibilità dei nodi disattivati.
Enumerazioni
enum GroupCallFlags: 🔗
GroupCallFlags GROUP_CALL_DEFAULT = 0
Chiama i nodi all'interno di un gruppo senza alcun comportamento speciale (predefinito).
GroupCallFlags GROUP_CALL_REVERSE = 1
Chiama i nodi all'interno di un gruppo in ordine gerarchico ad albero inverso (tutti i nodi figlio innestati vengono chiamati prima dei rispettivi nodi genitore).
GroupCallFlags GROUP_CALL_DEFERRED = 2
Chiama i nodi all'interno di un gruppo alla fine del frame attuale (può essere un frame di processo o fisico), simile al Object.call_deferred().
GroupCallFlags GROUP_CALL_UNIQUE = 4
Chiama i nodi all'interno di un gruppo solo una volta, anche se la chiamata viene eseguita più volte nello stesso frame. Deve essere combinato con GROUP_CALL_DEFERRED per funzionare.
Nota: Gli argomenti diversi non sono presi in considerazione. Pertanto, quando la stessa chiamata viene eseguita con argomenti diversi, verrà eseguita solo la prima chiamata.
Descrizioni delle proprietà
bool auto_accept_quit = true 🔗
Se true, l'applicazione accetta automaticamente le richieste di uscita.
Per le piattaforme mobili, vedi quit_on_go_back.
Il nodo radice della scena principale attualmente caricata, solitamente come figlio diretto di root. Vedi anche change_scene_to_file(), change_scene_to_packed() e reload_current_scene().
Attenzione: L'impostazione diretta di questa proprietà potrebbe non funzionare come previsto, poiché nessun nodo è aggiunto o rimosso nodo da questo albero.
bool debug_collisions_hint = false 🔗
Se true, le forme di collisione saranno visibili durante l'esecuzione del gioco dall'editor a scopo di debug.
Nota: Questa proprietà non è progettata per essere modificata in fase di esecuzione. Modificare il valore di debug_collisions_hint mentre il progetto è in esecuzione non avrà l'effetto desiderato.
Se true, i poligoni di navigazione saranno visibili durante l'esecuzione del gioco dall'editor a scopo di debug.
Nota: Questa proprietà non è progettata per essere modificata in fase di esecuzione. Modificare il valore di debug_navigation_hint mentre il progetto è in esecuzione non avrà l'effetto desiderato.
bool debug_paths_hint = false 🔗
Se true, le curve dai nodi Path2D e Path3D saranno visibili durante l'esecuzione del gioco dall'editor a scopo di debug.
Nota: Questa proprietà non è progettata per essere modificata in fase di esecuzione. Modificare il valore di debug_paths_hint mentre il progetto è in esecuzione non avrà l'effetto desiderato.
La radice della scena attualmente in fase di modifica nell'editor. Di solito è un figlio diretto di root.
Nota: Questa proprietà non fa nulla nelle build di rilascio.
bool multiplayer_poll = true 🔗
Se true (valore predefinito), abilita il polling automatico di MultiplayerAPI per questo SceneTree durante process_frame.
Se false, devi chiamare manualmente MultiplayerAPI.poll() per elaborare i pacchetti di rete e inviare gli RPC. Ciò consente di eseguire gli RPC in un ciclo diverso (ad esempio fisica, thread, intervallo di tempo specifico) e per la protezione manuale con Mutex quando si accede alla MultiplayerAPI dai thread.
Se true, l'albero di scena è considerato in pausa. Ciò causa il seguente comportamento:
La fisica 2D e 3D sarà interrotta, così come il rilevamento delle collisioni e i segnali correlati.
A seconda di Node.process_mode di ciascun nodo, i loro metodi di callback Node._process(), Node._physics_process() e Node._input() potrebbero non essere più chiamati.
bool physics_interpolation = false 🔗
Se true, il renderer interpolerà le trasformazioni degli oggetti fisici tra le ultime due trasformazioni, in modo che un movimento fluido sia visualizzato anche quando i tick di fisica non coincidono con i frame renderizzati.
Il valore predefinito di questa proprietà è controllato da ProjectSettings.physics/common/physics_interpolation.
Nota: Sebbene questa sia un'impostazione globale, è possibile controllare più precisamente i singoli rami dello SceneTree usando Node.physics_interpolation_mode.
Se true, l'applicazione si chiude automaticamente quando si torna indietro (ad esempio, utilizzando il pulsante di sistema "Indietro" su Android).
Per gestire il pulsante "Torna indietro" quando questa opzione è disabilitata, usa DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST.
Window get_root()
La radice Window dell'albero. Questo è il Node più in alto dell'albero della scena ed è sempre presente. Un NodePath assoluto inizia sempre da questo nodo. I figli del nodo radice possono includere il current_scene caricato, così come qualsiasi AutoLoad configurato nelle Impostazioni del progetto.
Attenzione: Non eliminare questo nodo. Ciò risulterà in comportamento instabile, seguito da un crash.
Descrizioni dei metodi
void call_group(group: StringName, method: StringName, ...) vararg 🔗
Chiama il metodo method su ogni nodo all'interno di questo albero aggiunto al gruppo group. Puoi passare argomenti a method specificandoli alla fine di questa chiamata. I nodi che non possono chiamare method (perché il metodo non esiste o gli argomenti non corrispondono) sono ignorati. Vedi anche set_group() e notify_group().
Nota: Questo metodo agisce immediatamente su tutti i nodi selezionati allo stesso tempo, il che potrebbe causare scatti in alcune situazioni intense sulle prestazioni.
Nota: In C#, method deve essere in snake_case quando si fa riferimento ai metodi integrati di Godot. Preferisci usare i nomi esposti nella classe MethodName per evitare di allocare un nuovo StringName a ogni chiamata.
void call_group_flags(flags: int, group: StringName, method: StringName, ...) vararg 🔗
Chiama il metodo method su ogni nodo all'interno di questo albero aggiunto al gruppo group. Usa flags per personalizzare il comportamento di questo metodo (vedi GroupCallFlags). È possibile passare ulteriori argomenti a method alla fine di questo metodo. I nodi che non possono chiamare method (perché il metodo non esiste o gli argomenti non corrispondono) sono ignorati.
# Chiama "hide" su tutti i nodi del gruppo "enemies", alla fine del frame e in ordine inverso nell'albero.
get_tree().call_group_flags(
SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE,
"enemies", "hide")
Nota: In C#, method deve essere in snake_case quando si fa riferimento ai metodi integrati di Godot. Si preferisce utilizzare i nomi esposti nella classe MethodName per evitare di allocare un nuovo StringName a ogni chiamata.
Error change_scene_to_file(path: String) 🔗
Changes the running scene to the one at the given path, after loading it into a PackedScene and creating a new instance.
Returns @GlobalScope.OK on success, @GlobalScope.ERR_CANT_OPEN if the path cannot be loaded into a PackedScene, or @GlobalScope.ERR_CANT_CREATE if that scene cannot be instantiated.
Note: See change_scene_to_node() for details on the order of operations.
Error change_scene_to_node(node: Node) 🔗
Changes the running scene to the provided Node. Useful when you want to set up the new scene before changing.
Returns @GlobalScope.OK on success, @GlobalScope.ERR_INVALID_PARAMETER if the node is null, or @GlobalScope.ERR_UNCONFIGURED if the node is already inside the scene tree.
Note: Operations happen in the following order when change_scene_to_node() is called:
The current scene node is immediately removed from the tree. From that point, Node.get_tree() called on the current (outgoing) scene will return
null. current_scene will benulltoo, because the new scene is not available yet.At the end of the frame, the formerly current scene, already removed from the tree, will be deleted (freed from memory) and then the new scene node will be added to the tree. Node.get_tree() and current_scene will be back to working as usual.
This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to Node.queue_free().
If you want to reliably access the new scene, await the scene_changed signal.
Warning: After using this method, the SceneTree will take ownership of the node and will free it automatically when changing scene again. Any references you had to that node will become invalid.
Error change_scene_to_packed(packed_scene: PackedScene) 🔗
Changes the running scene to a new instance of the given PackedScene (which must be valid).
Returns @GlobalScope.OK on success, @GlobalScope.ERR_CANT_CREATE if the scene cannot be instantiated, or @GlobalScope.ERR_INVALID_PARAMETER if the scene is invalid.
Note: See change_scene_to_node() for details on the order of operations.
SceneTreeTimer create_timer(time_sec: float, process_always: bool = true, process_in_physics: bool = false, ignore_time_scale: bool = false) 🔗
Restituisce un nuovo SceneTreeTimer. Dopo che sono trascorsi time_sec in secondi, il timer emetterà SceneTreeTimer.timeout e sarà automaticamente liberato.
Se process_always è false, il timer sarà messo in pausa quando si imposta paused su true.
Se process_in_physics è true, il timer sarà aggiornato alla fine del frame di fisica, invece del frame di processo.
Se ignore_time_scale è true, il timer ignorerà Engine.time_scale e si aggiornerà con il tempo trascorso reale.
Questo metodo è comunemente usato per creare un timer di ritardo a colpo singolo, come nel seguente esempio:
func some_function():
print("start")
await get_tree().create_timer(1.0).timeout
print("end")
public async Task SomeFunction()
{
GD.Print("start");
await ToSignal(GetTree().CreateTimer(1.0f), SceneTreeTimer.SignalName.Timeout);
GD.Print("end");
}
Nota: il timer viene sempre elaborato dopo tutti i nodi nell'albero. Il metodo Node._process() di un nodo verrebbe chiamato prima dell'aggiornamento del timer (o Node._physics_process() se process_in_physics è impostato su true).
Crea e restituisce un nuovo Tween elaborato in questo albero. Il Tween sarà avviato automaticamente sul frame di processo o frame di fisica successivo (a seconda del suo TweenProcessMode).
Nota: Un Tween creato utilizzando questo metodo non è associato a nessun Node. Può continuare a funzionare finché non c'è più nulla da animare. Se vuoi che il Tween venga automaticamente eliminato quando il Node viene liberato, usa Node.create_tween() o Tween.bind_node().
Node get_first_node_in_group(group: StringName) 🔗
Restituisce il primo Node trovato all'interno dell'albero, che è stato aggiunto al gruppo group, in ordine di gerarchia della scena. Restituisce null se non viene trovata alcuna corrispondenza. Vedi anche get_nodes_in_group().
Restituisce il numero di passaggi del processo fisico elaborati, dall'avvio dell'applicazione. Questa non è una misura del tempo trascorso. Vedi anche physics_frame. Per il numero di frame renderizzati, vedi Engine.get_process_frames().
MultiplayerAPI get_multiplayer(for_path: NodePath = NodePath("")) const 🔗
Cerca la MultiplayerAPI configurata per il percorso specificato. Se non ne esiste una, cerca nei percorsi padre finché non ne trova una. Se il percorso è vuoto o nessuna ne viene trovata, viene restituito quella predefinita. Vedi set_multiplayer().
Restituisce il numero di nodi all'interno di questo albero.
int get_node_count_in_group(group: StringName) const 🔗
Restituisce il numero di nodi assegnati al gruppo fornito.
Array[Node] get_nodes_in_group(group: StringName) 🔗
Restituisce un Array contenente tutti i nodi all'interno di questo albero, che sono stati aggiunti al gruppo group, in ordine gerarchico della scena.
Array[Tween] get_processed_tweens() 🔗
Restituisce un Array di Tween attualmente esistenti nell'albero, inclusi i tween in pausa.
bool has_group(name: StringName) const 🔗
Restituisce true se un nodo aggiunto al gruppo con nome name esiste nell'albero.
bool is_accessibility_enabled() const 🔗
Restituisce true se le funzionalità di accessibilità sono abilitate e gli aggiornamenti delle informazioni di accessibilità sono elaborati attivamente.
bool is_accessibility_supported() const 🔗
Restituisce true se le funzionalità di accessibilità sono supportate dal sistema operativo e abilitate nelle impostazioni del progetto.
void notify_group(group: StringName, notification: int) 🔗
Chiama Object.notification() con la notifica notification su tutti i nodi all'interno di questo albero aggiunti al gruppo group. Vedi anche Godot notifications, call_group() e set_group().
Nota: Questo metodo agisce immediatamente su tutti i nodi selezionati allo stesso tempo, il che potrebbe causare scatti in alcune situazioni intense sulle prestazioni.
void notify_group_flags(call_flags: int, group: StringName, notification: int) 🔗
Chiama Object.notification() con la notifica notification su tutti i nodi all'interno di questo albero aggiunti al gruppo group. Usa call_flags per personalizzare il comportamento di questo metodo (vedi GroupCallFlags).
void queue_delete(obj: Object) 🔗
Mette in coda l'oggetto obj per essere eliminato, chiamando il suo Object.free() alla fine del frame attuale. Questo metodo è simile a Node.queue_free().
void quit(exit_code: int = 0) 🔗
Esce dall'applicazione alla fine dell'iterazione attuale, con il codice di uscita exit_code.
Per convenzione, un codice di uscita di 0 indica successo, mentre qualsiasi altro codice di uscita indica un errore. Per motivi di portabilità, dovrebbe essere compreso tra 0 e 125 (inclusi).
Nota: Su iOS questo metodo non funziona. Invece, come consigliato dalle linee guida di interfacce iOS, ci si aspetta che l'utente chiuda le app tramite il pulsante Home.
Error reload_current_scene() 🔗
Ricarica la scena attualmente attiva, sostituendo current_scene con una nuova istanza del suo PackedScene originale.
Restituisce @GlobalScope.OK in caso di successo, @GlobalScope.ERR_UNCONFIGURED se nessun current_scene è definito, @GlobalScope.ERR_CANT_OPEN se current_scene non può essere caricato in un PackedScene o @GlobalScope.ERR_CANT_CREATE se la scena non può essere istanziata.
void set_group(group: StringName, property: String, value: Variant) 🔗
Imposta la proprietà property su value su tutti i nodi all'interno di questo albero aggiunti al gruppo group. I nodi che non hanno property sono ignorati. Vedi anche call_group() e notify_group().
Nota: Questo metodo agisce immediatamente su tutti i nodi selezionati allo stesso tempo, il che potrebbe causare scatti in alcune situazioni intense sulle prestazioni.
Nota: In C#, property deve essere in snake_case quando si fa riferimento alle proprietà integrate di Godot. Preferisci usare i nomi esposti nella classe PropertyName per evitare di allocare un nuovo StringName a ogni chiamata.
void set_group_flags(call_flags: int, group: StringName, property: String, value: Variant) 🔗
Imposta la proprietà property su value su tutti i nodi all'interno di questo albero aggiunti al gruppo group. I nodi che non hanno property sono ignorati. Usa call_flags per personalizzare il comportamento di questo metodo (vedi GroupCallFlags).
Nota: In C#, property deve essere in snake_case quando si fa riferimento alle proprietà integrate di Godot. Preferisci usare i nomi esposti nella classe PropertyName per evitare di allocare un nuovo StringName a ogni chiamata.
void set_multiplayer(multiplayer: MultiplayerAPI, root_path: NodePath = NodePath("")) 🔗
Imposta una MultiplayerAPI personalizzata con il percorso root_path (che controlla anche i sotto-percorsi relativi), o sovrascrive quella predefinita se root_path è vuoto.
Nota: Nessuna MultiplayerAPI deve essere configurata per il sottopercorso contenente root_path, i multiplayer personalizzati innestati non sono consentiti. Ovvero, se ne è configurato uno per "/root/Foo" impostandone uno per "/root/Foo/Bar" si verificherà un errore.
Nota: il set_multiplayer() deve essere chiamato prima che i nodi figlio siano pronti al percorso root_path. Se nodi multiplayer come MultiplayerSpawner o MultiplayerSynchronizer vengono aggiunti all'albero prima che l'API multiplayer personalizzata sia impostata, non funzioneranno.
void unload_current_scene() 🔗
Se una scena attuale è caricata, chiamare questo metodo la libererà.