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
Gère la boucle du jeu via une hiérarchie de nœuds.
Description
En tant qu'une des classes les plus importantes, le SceneTree gère la hiérarchie des nœuds dans une scène, ainsi que les scènes elles-mêmes. Les nœuds peuvent être ajoutés, récupérés et enlevés. L'arborescence de scène entière (et donc la scène actuelle) peut être mise pause. Les scènes peuvent être chargées, échangées et rechargées.
Vous pouvez également utiliser le SceneTree pour organiser vos nœuds en groupes : chaque nœud peut être ajouté à autant de groupes que vous voulez créer, par exemple un groupe "ennemi". Vous pouvez ensuite itérer sur ces groupes ou même appeler des méthodes et définir des propriétés sur tous les nœuds appartenant à un groupe donné.
SceneTree est l'implémentation de MainLoop par défaut utilisée par le moteur, et est donc en charge de la boucle du jeu.
Tutoriels
Propriétés
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Méthodes
Signaux
Émis lorsque le nœud node entre dans cet arbre.
node_configuration_warning_changed(node: Node) 🔗
Émis lorsque la méthode Node.update_configuration_warnings() du nœud node est appelée. Seulement émis dans l'éditeur.
Émis lorsque le nœud node sort de cet arbre.
Émis lorsque le nom Node.name du nœud node est changé.
physics_frame() 🔗
Émis immédiatement juste avant que Node._physics_process() soit appelée sur chaque nœud de cet arbre.
process_frame() 🔗
Émis immédiatement juste avant que Node._process() soit appelée sur chaque nœud de cet arbre.
scene_changed() 🔗
Émis après que la nouvelle scène soit ajoutée à l'arborescence de scène et initialisée. Peut être utilisé pour accéder de façon fiable à current_scene lorsque d'un changement de scènes.
# Ce code devrait être à l'intérieur d'un chargement automatique.
get_tree().change_scene_to_file(chemin_autre_scene)
await get_tree().scene_changed
print(get_tree().current_scene) # Affiche la nouvelle scène.
tree_changed() 🔗
Émis à chaque fois que la hiérarchie de l'arbre change (les nœuds sont déplacés, renommés, etc...).
tree_process_mode_changed() 🔗
Émis lorsque le Node.process_mode d'un nœud dans l’arborescence est changé. Seulement émis dans l'éditeur, pour mettre à jour la visibilité des nœuds désactivés.
Énumérations
enum GroupCallFlags: 🔗
GroupCallFlags GROUP_CALL_DEFAULT = 0
Appeler des nœuds dans un groupe sans comportement particulier (valeur par défaut).
GroupCallFlags GROUP_CALL_REVERSE = 1
Appeler les nœuds dans un groupe dans l'ordre inverse de la hiérarchie de l'arbre (tous les enfants imbriqués sont appelés avant leurs nœuds parents respectifs).
GroupCallFlags GROUP_CALL_DEFERRED = 2
Appeler des nœuds dans un groupe à la fin de la trame actuelle (peut être une trame de traitement ou de physique), semblable à Object.call_deferred().
GroupCallFlags GROUP_CALL_UNIQUE = 4
Appeler tous les nœuds dans un groupe seulement une fois, même si l'appel est exécuté plusieurs fois dans la même trame. Doit être combiné avec GROUP_CALL_DEFERRED pour fonctionner.
Note : Des arguments différents ne sont pas pris en compte. Par conséquent, lorsque le même appel est exécuté avec des arguments différents, seul le premier appel sera exécuté.
Descriptions des propriétés
bool auto_accept_quit = true 🔗
Si true, l'application accepte automatiquement les requêtes de fermeture.
Pour les plateformes mobiles, voir quit_on_go_back.
Le nœud racine de la scène principale actuellement chargée, habituellement comme un enfant direct de root. Voir aussi change_scene_to_file(), change_scene_to_packed(), et reload_current_scene().
Attention : Définir cette propriété peut ne pas fonctionner comme prévu, car elle n'ajoute ou ne retire pas de nœud de cet arbre.
bool debug_collisions_hint = false 🔗
Si true, les formes de collision seront visibles lors de l'exécution du jeu de l'éditeur à des fins de débogage.
Note : Cette propriété n'est pas conçue pour être changée durant l'exécution. Changer la valeur de debug_collisions_hint pendant que le projet est en cours d'exécution n'aura pas l'effet désiré.
Si true, les polygones de navigation seront visibles lors de l'exécution du jeu depuis l'éditeur à des fins de débogage.
Note : Cette propriété n'est pas conçue pour être changée durant l'exécution. Changer la valeur de debug_navigation_hint pendant que le projet est en cours d'exécution n'aura pas l'effet désiré.
bool debug_paths_hint = false 🔗
Si true, les courbes des nœuds Path2D et Path3D seront visibles lors de l'exécution du jeu depuis l'éditeur à des fins de débogage.
Note : Cette propriété n'est pas conçue pour être changée durant l'exécution. Changer la valeur de debug_paths_hint pendant que le projet est en cours d'exécution n'aura pas l'effet désiré.
La racine de la scène actuellement en cours d'édition dans l'éditeur. Il s'agit généralement d'un enfant direct de la racine root.
Note : Cette propriété ne fait rien dans les compilations de release.
bool multiplayer_poll = true 🔗
Si true (valeur par défaut), permet le polling automatique du MultiplayerAPI pour ce SceneTree pendant process_frame.
Si false, vous devez appeler manuellement MultiplayerAPI.poll() pour traiter les paquets réseau et délivrer les RPCs. Cela permet d'exécuter des RPCs dans une boucle différente (p. ex. physique, fil, pas de temps spécifique) et d'avoir une protection Mutex manuelle lors de l'accès au MultiplayerAPI depuis des threads.
Si true, l'arborescence de scène est considérée comme mise en pause. Cela provoque le comportement suivant :
La physique 2D et 3D sera arrêtée, ainsi que la détection des collisions et les signaux connexes.
Selon le Node.process_mode de chaque nœud, leurs méthodes de callback Node._process(), Node._physics_process() et Node._input() peuvent ne plus être appelées.
bool physics_interpolation = false 🔗
Si true, le moteur de rendu interpolera les transformations des objets (à la fois physique et non physique) entre les deux dernières transformations, de sorte à ce que le mouvement lisse soit vu même lorsque les tics de physique ne coïncident pas avec les trames rendues.
La valeur par défaut de cette propriété est contrôlée par ProjectSettings.physics/common/physics_interpolation.
Note : Bien qu'il s'agisse d'un paramètre global, un contrôle plus fin des branches individuelles du SceneTree est possible en utilisant Node.physics_interpolation_mode.
Si true, l'application s'arrête automatiquement lorsque vous naviguez en arrière (p. ex. en utilisant le bouton « Retour » du système sur Android).
Pour gérer le bouton 'Aller en arrière' lorsque cette option est désactivée, utilisez DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST.
Window get_root()
La racine de l'arbre. Il s'agit du Node le plus haut dans l'arborescence de scène, et il est toujours présent. Un NodePath absolu part toujours de ce nœud. Les enfants du nœud racine peuvent inclure la scène current_scene chargée, ainsi que tout Chargement automatique configuré dans les paramètres du projet.
Attention : Ne supprimez pas ce nœud. Cela résultera en un comportement instable, suivi d'un plantage.
Descriptions des méthodes
void call_group(group: StringName, method: StringName, ...) vararg 🔗
Appelle la méthode method sur chaque nœud à l'intérieur de cette arborescence ajouté au groupe group donné. Vous pouvez passer des arguments à method en les spécifiant à la fin de cet appel de méthode. Les nœuds qui ne peuvent pas appeler method (car la méthode n'existe pas ou que les arguments ne correspondent pas) sont ignorés. Voir aussi set_group() et notify_group().
Note : Cette méthode agit immédiatement sur tous les nœuds sélectionnés en une fois, ce qui peut provoquer des ralentissements dans certaines situations avec beaucoup de calculs.
Note : En C#, method doit être en snake_case lorsqu'il s'agit de méthodes Godot intégrées. Préférez utiliser les noms exposés dans la classe MethodName pour éviter d'attribuer un nouveau StringName à chaque appel.
void call_group_flags(flags: int, group: StringName, method: StringName, ...) vararg 🔗
Appelle la méthode method sur chaque nœud à l'intérieur de cette arborescence ajouté au groupe group donné. Utilisez flags pour personnaliser le comportement de cette méthode (voir GroupCallFlags). Des arguments supplémentaires pour method peuvent être passés à la fin de cette méthode. Les nœuds qui ne peuvent pas appeler method (que la méthode n'existe pas ou que les arguments ne correspondent pas) sont ignorés.
# Appelle "cacher" sur tous les nœuds du groupe "ennemis", à la fin de la trame et dans l'ordre inverse de l'arborescence.
get_tree().call_group_flags(
SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE,
"ennemis", "cacher")
Note : En C#, method doit être en snake_case lorsqu'il s'agit de méthodes Godot intégrées. Préférez utiliser les noms exposés dans la classe MethodName pour éviter d'attribuer un nouveau StringName à chaque appel.
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) 🔗
Change la scène en cours d'exécution sans le noeud utilisé. Utile lorsque vous voulez mettre en place une scène avant un changement.
Renvoie @GlobalScope.OK lors du succès, @GlobalScope.ERR_INVALID_PARAMETER si le node vaut null, ou @GlobalScope.ERR_UNCONFIGURED si le node est déjà dans l'arborescence de scène.
Note : Les opérations se déroulent dans l'ordre suivant quand change_scene_to_node() est appelée :
Le nœud de la scène actuelle est immédiatement retiré de l'arbre. À partir de ce point, appeler Node.get_tree() sur la scène courante (sortante) renverra
null. current_scene vaudra aussinull, car la nouvelle scène n'est pas encore disponible.A la fin de la trame, l'ancienne scène actuelle, déjà retirée de l'arbre, sera supprimée (libérée de mémoire) et la nouvelle scène sera instanciée et ajoutée à l'arbre. Node.get_tree() et current_scene recommenceront ainsi à fonctionner comme d'habitude.
Cela garantit que les deux scènes ne s'exécutent pas en même temps, tout en libérant quand même la scène précédente d'une manière sécurisée semblable à Node.queue_free().
Si vous voulez accéder de manière fiable à la nouvelle scène, attendez le scene_changed signal .
Attention : Après avoir utilisé cette méthode, le SceneTree prendra possession du nœud et le libérera automatiquement lors de la modification de la scène. Toute référence que vous avez eue à ce nœud deviendra invalide.
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) 🔗
Renvoie un nouveau SceneTreeTimer. Après que time_sec secondes sont passées, le minuteur émet le signal SceneTreeTimer.timeout et sera automatiquement libéré.
Si process_always vaut false, le minuteur sera interrompu lorsque paused passe à true.
Si process_in_physics vaut true, le minuteur mettra à jour à la fin de le trame de physique, au lieu de la trame de traitement.
Si ignore_time_scale vaut true, le minuteur ignore Engine.time_scale et se met à jour avec le temps réel écoulé.
Cette méthode est couramment utilisée pour créer un minuteur de délai à usage unique, comme dans l'exemple suivant :
func une_fonction():
print("début")
await get_tree().create_timer(1.0).timeout
print("fin")
public async Task UneFonction()
{
GD.Print("début");
await ToSignal(GetTree().CreateTimer(1.0f), SceneTreeTimer.SignalName.Timeout);
GD.Print("fin");
}
Note : Le minuteur est toujours mis à jour après tous les nœuds de l'arbre. La méthode Node._process() d'un nœud serait appelée avant que le minuteur se mette à jour (ou Node._physics_process() si process_in_physics est définie à true).
Crée et renvoie un nouveau Tween traité dans cette arboresence. Le Tween commencera automatiquement lors de la prochaine trame de traitement ou de physique (selon son TweenProcessMode).
Note : Un Tween créé à l'aide de cette méthode n'est lié à aucun Node. Il peut continuer à travailler jusqu'à ce qu'il ne reste rien à animer. Si vous voulez que le Tween soit automatiquement tué lorsque le Node est libéré, utilisez Node.create_tween() ou Tween.bind_node().
Node get_first_node_in_group(group: StringName) 🔗
Renvoie le premier Node trouvé à l'intérieur de l'arborescence, qui a été ajouté au groupe group donné, dans l'ordre de la hiérarchie de la scène. Renvoie null si aucun nœud correspondant n'est trouvé. Voir aussi get_nodes_in_group().
Renvoie combien de étapes de traitement de la physique ont été traitées depuis le début de l'application. Il ne s'agit pas d'une mesure du temps écoulé. Voir aussi physics_frame. Pour le nombre de trames rendues, voir Engine.get_process_frames().
MultiplayerAPI get_multiplayer(for_path: NodePath = NodePath("")) const 🔗
Cherche le MultiplayerAPI configuré pour le chemin donné, s'il n'existe pas, cherche les chemins parents jusqu'à ce qu'un soit trouvé. Si le chemin est vide, ou qu'aucun n'est trouvé, le chemin par défaut est renvoyé. Voir set_multiplayer().
Renvoie le nombre de nœuds dans cet arbre.
int get_node_count_in_group(group: StringName) const 🔗
Renvoie le nombre de nœuds assignés au groupe donné.
Array[Node] get_nodes_in_group(group: StringName) 🔗
Renvoie un Array contenant tous les nœuds à l'intérieur de cet arbre, qui ont été ajoutés au groupe group donné, dans l'ordre de la hiérarchie de la scène.
Array[Tween] get_processed_tweens() 🔗
Renvoie un Array des Tweens existant actuellement dans l'arbre, y compris les tweens en pause.
bool has_group(name: StringName) const 🔗
Renvoie true si un nœud ajouté au groupe avec le nom name donné existe dans l'arbre.
bool is_accessibility_enabled() const 🔗
Renvoie true si les fonctionnalités d'accessibilité sont activées, et les mises à jour d'information d'accessibilité sont traitées activement.
bool is_accessibility_supported() const 🔗
Renvoie true si les fonctionnalités d'accessibilité sont supportées par l'OS et activées dans les paramètres du projet.
void notify_group(group: StringName, notification: int) 🔗
Appelle Object.notification() avec la notification notification donnée sur tous les nœuds dans cet arbre ajoutés au groupe group. Voir aussi Notifications Godot et call_group() et set_group().
Note : Cette méthode agit immédiatement sur tous les nœuds sélectionnés en une fois, ce qui peut provoquer des ralentissements dans certaines situations avec beaucoup de calculs.
void notify_group_flags(call_flags: int, group: StringName, notification: int) 🔗
Appelle Object.notification() avec la notification notification donnée sur tous les nœuds dans cet arbre ajoutés au groupe group. Utilisez call_flags pour personnaliser le comportement de cette méthode (voir GroupCallFlags).
void queue_delete(obj: Object) 🔗
Met en file d'attente la suppression de l'objet obj donné, en appelant Object.free() à la fin de la trame actuelle. Cette méthode est similaire à Node.queue_free().
void quit(exit_code: int = 0) 🔗
Arrête l'application à la fin de l'itération actuelle, avec le code de sortie exit_code donné.
Par convention, un code de sortie de 0 indique un succès, alors que tout autre code de sortie indique une erreur. Pour des raisons de portabilité, il devrait être compris entre 0 et 125 (inclusifs).
Note : Sur iOS cette méthode ne fonctionne pas. Au lieu de cela, comme le recommande le iOS Human Interface Guidelines, on s'attend à ce que l'utilisateur ferme les applications avec le bouton Home.
Error reload_current_scene() 🔗
Recharge la scène actuellement active, en remplaçant current_scene par une nouvelle instance de sa PackedScene originale.
Renvoie @GlobalScope.OK lors du succès, @GlobalScope.ERR_UNCONFIGURED si aucune scène current_scene n'est définie, @GlobalScope.ERR_CANT_OPEN si current_scene ne peut être chargée dans une PackedScene, ou @GlobalScope.ERR_CANT_CREATE si la scène ne peut pas être instanciée.
void set_group(group: StringName, property: String, value: Variant) 🔗
Définit la propriété property donnée à la valeur value sur tous les nœuds à l'intérieur de cette arborescence ajoutés au groupe group donné. Les nœuds qui n'ont pas la propriété property sont ignorés. Voir aussi call_group() et notify_group().
Note : Cette méthode agit immédiatement sur tous les nœuds sélectionnés en une fois, ce qui peut provoquer des ralentissements dans certaines situations avec beaucoup de calculs.
Note : En C#, property doit être en snake_case lorsqu'il s'agit de méthodes Godot intégrées. Préférez utiliser les noms exposés dans la classe MethodName pour éviter d'attribuer un nouveau StringName à chaque appel.
void set_group_flags(call_flags: int, group: StringName, property: String, value: Variant) 🔗
Définit la propriété property donnée à la valeur value sur tous les nœuds à l'intérieur de cette arborescence ajoutés au groupe group donné. Les nœuds qui n'ont pas la propriété property sont ignorés. Utilisez call_flags pour personnaliser le comportement de cette méthode (voir GroupCallFlags).
Note : En C#, property doit être en snake_case lorsqu'il s'agit de méthodes Godot intégrées. Préférez utiliser les noms exposés dans la classe MethodName pour éviter d'attribuer un nouveau StringName à chaque appel.
void set_multiplayer(multiplayer: MultiplayerAPI, root_path: NodePath = NodePath("")) 🔗
Définit une MultiplayerAPI personnalisée avec le chemin racine root_path donné (contrôlant également les sous-chemins relatifs), ou redéfinit l'API par défaut si root_path est vide.
Note : Aucun MultiplayerAPI ne doit être configuré pour le sous-chemin contenant root_path, les API multijoueurs personnalisées ne sont pas autorisées. I.e. si l'une est configurée pour "/root/Foo", en définir une pour "/root/Foo/Bar" causera une erreur.
Note : set_multiplayer() doit être appelé avant que les nœuds enfants sont prêts au root_path donné. Si des nœuds multijoueur comme MultiplayerSpawner ou MultiplayerSynchronizer sont ajoutés à l'arborescence avant que l'API multijoueur personnalisée soit définie, ils ne fonctionneront pas.
void unload_current_scene() 🔗
Si une scène est actuellement chargée, appeler cette méthode la déchargera.