Nœuds et terminologie

Avant de continuer, il faut noter que la terminologie nœud doit être utilisé avec précaution. En mentionnant des nœuds Visual Script (ou généralement nœuds) ce texte désignera les petites boîtes que vous connectez avec des lignes, faisant partie d’un graphe. Lors de la mention de nœuds de scène, c’est implicitement les éléments de l’arbre d’une scène donnée dont il est question. Ce nommage est similaire mais pour des objets fonctionnellement différents. Ici, la mention de nœud désignera des nœuds Visual Script, sauf indication contraire.

../../../_images/visual_script16.png

Propriétés d’un nœud

Comme dans toute implémentation de script visuel, chaque nœud a des propriétés éditables. Dans Godot, cependant, nous évitons de bombarder les nœuds de contrôles éditables dans un but de lisibilité.

Les nœuds affichent toujours les informations requises sous forme de texte, mais l’édition se fait via l”Inspecteur. Pour les éditer, il suffit de sélectionner n’importe quel nœud et d’éditer ses propriétés dans l”Inspecteur.

Ports et connexions

La programmation dans le Visual Sciprt de Godot est fait par nœuds et connexions de ports à l’intérieur de chaque fonctions.

Ports

Les nœuds dans le Visual Scripting de Godot ont des Ports. Ce sont des points de terminaison qui apparaissent à gauche et à droite des nœuds et qui peuvent être utilisés pour faire des Connexions : il existe deux types de Ports : Sequence et Data.

../../../_images/visual_script17.png

Les ports de séquence indiquent l’ordre dans lequel les opérations sont exécutées. Typiquement, lorsqu’un nœud est traité, il ira au nœud suivant parmi les ports à droite. Si rien n’est connecté, la fonction peut se terminer, ou une autre sortie Port de séquence peut être essayée (cela dépend du nœud). Grâce à cela, il est facile de comprendre la logique au sein d’une fonction en suivant simplement les lignes blanches. Tous les nœud n’ont pas Ports de séquence. En fait, la plupart n’en n’ont pas.

Les ports de données contiennent des valeurs typées. Les types peuvent être de n’importe quel type Godot régulier, tel qu’un booléen, un entier, une chaîne de caractères, un Vector3, un tableau, n’importe quel objet ou nœud de scène, etc. Un Port de données sur le côté droit d’un nœud est considéré comme une sortie, tandis qu’un port sur le côté gauche est une entrée. Leur connexion permet à l’information de circuler jusqu’au nœud suivant.

Cependant, tous les types de port de données ne sont pas tous compatibles ou permettent des connexions. Faites attention aux couleurs et icônes, étant donné que chaque type a une représentation différente :

../../../_images/visual_script18.png

Connexions

Connecter est un processus relativement simple. Glissez un port de sortie vers un port d’entrée.

../../../_images/visual_script_connect.gif

Déconnecter requiert un peu plus de pratique. La déconnexion des ports de données s’effectue en glissant et éloignant l’entrée, alors que pour les ports de séquences, cela s’effectue en glissant la sortie.

../../../_images/visual_script_disconnect.gif

Ça peut sembler étrange au début, mais ça se passe ainsi car les ports de données sont 1:N (un port de sortie peut être connecté à plusieurs entrées), alors que les ports de séquence son N:1 (plusieurs ports de séquence peut être connectés à une seule entrée).

Connecter vers un emplacement vide (glisser un port pour le connecter mais le lâcher dans un espace vide) est aussi sensible au contexte, une liste d’opérations courantes sera proposée. Pour les séquences, ce seront des nœuds conditionnels :

../../../_images/visual_script52.png

Alors que pour les données, un menu contextuel de set/get/call s’ouvrira :

../../../_images/visual_script53.png

Ajouter des nœuds

Enfin ! On est arrivé à la partie amusante ! Mais, avant d’expliquer plus en détail ce que chaque type de nœuds fait, regardons vite fait comment on ajoute et on gère couramment un nœud.

Accéder aux nœuds de scène

L’une des tâches les plus courantes est d’accéder aux nœuds de l’arbre des scènes (encore une fois, à ne pas confondre avec les nœuds de script visuel). Glisser un nœud depuis l’arbre des scènes et le déposer dans le canevas vous demandera d”invoquer une méthode (parfois appelée fonction membre) sur ce nœud.

../../../_images/visual_script19.png

Quand bien même accéder à des propriétés est désiré dans la plupart des cas (plus d’information sur le sujet en bas), parfois appeler des méthodes peut aussi être utile. Les méthodes exécutent des actions spécifiques sur les objets. Dans le cas ci-dessus, la souris peut être déplacée vers une position en coordonnées locales par rapport au contrôle. Un autre cas d’utilisation commun est de dépêcher un nœud pour suppression, ce qui se fait en appelant la méthode queue_free.

../../../_images/visual_script20.png

Notez bien que ça ne marche que si la scène en cours d’édition contient votre Visual Script dans un des nœuds ! Autrement, un message d’erreur sera affiché.

Accès aux propriétés d’un nœud de scène

C’est la manière la plus courante de modifier les nœuds de scène en Visual Scripting. Sélectionnez un nœud de scène depuis la hiérarchie de scène, allez dans l’inspecteur, trouvez le nom de la propriété que vous voulez changer (pas la valeur !) et glissez la vers le canevas :

../../../_images/visual_script21.png

Le résultat est que cette valeur peut être changée de votre script en écrivant à un Port de données.

Si vous voulez lire cette valeur à la place, glissez à nouveau le nœud et pressez la touche Contrôle (ou Command sur Mac). Cela créera un getter :

../../../_images/visual_script22.png

Dans ce cas, la valeur peut être lue à partir d’un Port de données.

Variables

Les variables sont des conteneurs mémoire locaux au script qui peuvent contenir une valeur. Cette valeur peut être lue depuis n’importe laquelle des fonctions du script ou depuis d’autres scripts par les méthodes décrites précédemment.

Pour ajouter une variable, appuyez sur le bouton « + » dans la section Variables du panneau Membres. Double-cliquez sur la nouvelle variable pour la renommer :

../../../_images/visual_script23.png

Cliquer droit sur la variable vous permet de configurer ses propriétés :

../../../_images/visual_script24.png ../../../_images/visual_script25.png

Comme on peut le voir ci-dessus, le type et la valeur initiale de la variable peuvent être modifiés, ainsi que certains indices de propriété. En cochant l’option « Exporter », la variable devient visible dans l’inspecteur lors de la sélection du nœud. Ceci la rend également disponible à d’autres scripts via la méthode décrite dans l’étape précédente.

../../../_images/visual_script28.png

Pour utiliser la variable dans le script, il suffit de la faire glisser sur le canevas pour créer un getter :

../../../_images/visual_script26.png

De même, maintenez Contrôle (Command sur Mac) pour y déposer un setter :

../../../_images/visual_script27.png

Signaux

Il est également possible de créer vos propres signaux dans un script et de les utiliser. Pour cela, effectuez les mêmes étapes que pour les variables de l’étape précédente, à l’exception des signaux :

../../../_images/visual_script29.png

Un signal peut également être modifié via le menu clic-droit pour personnaliser ses arguments :

../../../_images/visual_script30.png

Le signal que vous venez de créer apparaîtra dans l’inspecteur avec les signaux intégrés au nœud. Ceci vous permet de le connecter à partir d’un autre script d’un autre Nœud de scène :

../../../_images/visual_script31.png

Enfin, pour émettre le signal, glissez le sur le canevas :

../../../_images/visual_script32.png

Rappelez-vous que l’émission d’un signal est une opération séquencée, elle doit donc provenir d’un port de séquence.

Ajouter d’autres nœuds

Maintenant que les bases sont vues, discutons de la grande quantité de nœuds utilitaires disponibles pour votre canevas ! Sous le panneau des membres, se trouve la liste de tous les types de nœuds disponibles :

../../../_images/visual_script33.png

Ctrl-F (Command-F sur Mac) vous permet de rechercher dans la liste.

N’importe lequel d’entre eux peut être glissé jusqu’à la scène. Contrairement aux nœuds (par exemple, faire glisser une propriété depuis l’inspecteur définit le contexte du nœud en cours d’édition automatique), ceux-ci sont ajoutés sans aucune information « contextuelle », cela doit donc être fait manuellement.

../../../_images/visual_script34.png

Rappelez-vous que vous pouvez vérifier la référence des classes pour ce que chaque nœud fait, car ils y sont documentés. Cela dit, voici un bref aperçu des types de nœuds :

Constantes

Les nœuds constants sont des nœuds qui fournissent des valeurs qui, bien qu’elles ne changent pas avec le temps, peuvent être utiles comme valeurs de référence. La plupart du temps, ce sont des entiers ou des flottants.

../../../_images/visual_script36.png

La première est « Constante » qui vous permet de sélectionner n’importe quelle valeur de n’importe quel type comme constante, d’un entier (42) à une chaîne (« Hello ! »). En général, ce nœud n’est pas souvent utilisé à cause des valeurs d’entrée par défaut dans les Ports de données, mais il est bon de savoir qu’il existe.

Le second est le nœud GlobalConstant, qui contient une longue liste de constantes pour les types globaux dans Godot. Vous y trouverez des constantes utiles pour faire référence à des noms de touches, des boutons de joystick ou de souris, etc.

Le troisième est MathConstant, qui fournit des constantes mathématiques typiques telles que PI, E, etc.

Données

Les nœuds de données traitent toutes sortes d’accès à l’information. Toute information dans Godot est accessible par l’intermédiaire de ces nœuds, de sorte qu’ils sont parmi les plus importants à utiliser et assez divers.

../../../_images/visual_script37.png

Il y a beaucoup de types de nœuds d’intérêt ici, en voici donc une brève description :

Action

Les nœuds d’action sont vitaux lorsqu’il s’agit des entrées d’un dispositif. Vous pouvez en savoir plus sur les actions dans le (@TODO LIEN VERS TUTO ACTION). Dans l’exemple ci-dessous, le contrôle est déplacé vers la droite lorsque l’action « move_right » est pressée.

../../../_images/visual_script38.png

Singleton moteur

Les singletons du moteur sont des interfaces globales (ce qui signifie qu’on peut y accéder sans référence, contrairement aux nœuds de scène, ils sont toujours disponibles). Ils ont plusieurs buts, mais en général ils sont utiles pour l’accès de bas niveau ou l’accès lié à l’OS.

../../../_images/visual_script39.png

Rappelez-vous que faire glisser une connexion vers un espace vide vous aidera à appeler des fonctions ou des propriétés set/get sur celles-ci :

../../../_images/visual_script40.png

Variables locales

Ce sont des nœuds que vous pouvez utiliser comme stockage temporaire pour vos graphes. Assurez-vous simplement qu’ils ont tous le même nom et le même type lors de leurs utilisations et ils feront référence aux mêmes emplacements en mémoire.

../../../_images/visual_script41.png

Comme on peut le voir ci-dessus, il y a deux nœuds disponibles : Un getter simple, et un getter séquencé (le setter requiert un port de séquence).

Nœud de scène

Ceci est seulement une référence à un nœud dans l’arbre, mais il est plus facile d’utiliser ce nœud en glissant le nœud actuel de l’arbre de scène vers le canevas (cela va le créer et le configurer).

Self

En quelques rares occasions, vous pouvez vouloir passer ce nœud de scène comme argument. Cela peut être utilisé pour appeler des fonctions et paramétrer/obtenir des propriétés, ou glisser simplement les nœuds (ou même le nœud lui-même qui a le script) à partir de l’arbre de scène vers le canevas pour cela.

L’arbre de scène

Ce nœud est similaire au nœud Singleton puisqu’il référence l’arbre des scènes SceneTree, qui contient la scène active. SceneTree, cependant, fonctionne seulement lorsque le nœud est dans la scène et actif, sinon y accéder résultera en une erreur.

SceneTree permet nombreuses choses de bas niveau, de régler des options d’étirement, d’appeler des groupes, de créer des minuteurs ou même de charger une autre scène. C’est une classe avec qui il est bon de se familiariser.

Précharger

Cela fait la même chose que la fonction preload() en GDScript. Cela maintient la ressource chargée et prête à être utilisée. Au lieu d’instancier ce nœud, il est plus simple de glisser la ressource désirée du dock de système de fichier vers le canevas.

Chemin de la ressource

Ce nœud est une simple aide pour obtenir une chaîne de caractères avec un chemin à une ressource que vous pouvez prendre. Cela est utile dans les fonctions qui charge les éléments à partir du disque.

Commentaire

Un nœud Commentaire est un nœud que vous pouvez redimensionner pour le placer autour d’autres nœuds. Il ne tentera pas d’obtenir le focus ou de se placer au dessus lorsqu’il est sélectionné. Il peut également être utilisé pour y écrire du texte.

../../../_images/visual_script42.png

Contrôle de flux

Les nœuds de contrôle de flux permettent à l’exécution de prendre différentes branches, généralement en fonction d’une condition donnée.

../../../_images/visual_script43.png

Condition

C’est simplement un nœud qui vérifie un port booléen. Si c’est vrai, l’exécution se poursuit via la séquence de port « vraie ». Sinon, la seconde. Après avoir passé au travers de l’une d’elles, l’exécution passe dans le port « terminé ». Laisser les séquences de ports déconnectées est correcte si elles ne sont pas toutes utilisées.

Itérateur

Certains types de données dans Godot (ex: tableaux, dictionnaires) sont itérables. Cela signifie qu’un peu de code peut s’exécuter pour chaque élément dont il dispose.

Le nœud Iterator passe par tous les éléments et, pour chacun d’entre eux, il passe par le port de séquence « each », rendant l’élément disponible dans le port de données « elem ».

Une fois terminé, il passe par le port de séquence « sortie ».

Retour

Certaines fonctions peuvent renvoyer des valeurs. En général pour celles virtuelles, Godot ajoutera le nœud Return pour vous. Un nœud de retour force la fonction à se terminer.

Séquence

Ce nœud est surtout utile pour organiser votre graphe. Il appelle ses ports de séquence dans l’ordre.

TypeCast

C’est un nœud très utile et couramment utilisé. Vous pouvez l’utiliser pour convertir des arguments ou d’autres objets au type que vous désirez. Ensuite, vous pouvez même faire glisser la sortie de l’objet pour en obtenir le résultat complet.

../../../_images/visual_script55.png

Il est également possible de caster un script, ce qui permettra d’obtenir des propriétés et des fonctions complètes de script :

../../../_images/visual_script54.png

Switch

Le nœud Switch est similaire au nœud Condition, mais il compare à plusieurs valeurs en même temps.

Tant que

C’est une forme plus primitive d’itération. La sortie de la séquence « repeat » sera appelée tant que la condition dans le port de données « cond » est remplie.

Fonctions

Les fonctions sont des aides simples, la plupart du temps déterministes. Ils prennent certains arguments en entrée et retournent une sortie. Ils ne sont presque jamais séquencés.

Built-In

There is a list of built-in helpers. The list is almost identical to the one from GDScript. Most of them are mathematical functions, but others can be useful helpers. Make sure to take a look at the list at some point.

Par type

Ce sont les méthodes disponibles pour les types de base. Par exemple, si vous voulez un produit scalaire (dot-product), vous pouvez rechercher « dot » au lieu de la catégorie Vector3. Dans la plupart des cas, recherchez simplement dans liste des nœuds, ça devrait être plus rapide.

Appel

Il s’agit du nœud d’appel générique. Il est rarement utilisé directement mais en faisant glisser un nœud déjà configuré, vers un emplacement vide.

Constructeurs

Ce sont toutes les fonctions nécessaires pour créer des types de données de base de Godot. Par exemple, si vous avez besoin de créer un Vector3 à partir de 3 flottants, un constructeur doit être utilisé.

../../../_images/visual_script44.png

Destructeur

C’est le contraire du constructeur, il permet de séparer n’importe quel type de base (i.e. Vector3) en ses sous-éléments.

../../../_images/visual_script45.png

Emettre un signal

Émet un signal depuis n’importe quel objet. En général ce n’est pas très utile, glisser/déposer le signal vers le canevas fonctionnera nettement mieux.

Get/Set

Nœud Getter/Setter générique. Glisser des propriétés à partir de l’inspecteur fonctionne mieux, car elles apparaissent correctement configurées au moment du dépôt.

Attendre

Les nœuds Wait suspendront l’exécution de la fonction jusqu’à ce que quelque chose se produise (de nombreuses trames peuvent passer jusqu’à la reprise, en fait). Les nœuds par défaut vous permettent d’attendre qu’une trame passe, une trame déterminée ou un intervalle de temps donné jusqu’à la reprise de l’exécution.

Yield

Ce nœud suspend complètement l’exécution du script, et fera retourner à la fonction une valeur qui peut être utilisée pour reprendre l’exécution.

Yield Signal

Identique à Yield, mais attendra jusqu’à ce qu’un signal donné soit émis.

Index

Opérateur d’indexation générique, pas souvent utilisé mais existe en cas de besoin.

Opérateurs

Il s’agit principalement d’opérateurs génériques tels que l’addition, la multiplication, la comparaison, etc. Par défaut, la plupart d’entre eux acceptent n’importe quel type de données (et généreront des erreurs pendant l’exécution si les types fournis ne correspondent pas à l’opérateur). Il est toujours recommandé de définir le bon type pour que les opérateurs captent les erreurs plus rapidement et rendent le graphe plus facile à lire.

../../../_images/visual_script46.png

Nœud d’expression

Parmi les opérateurs, le nœud Expression est le plus puissant. S’il est bien utilisé, il vous permet de simplifier énormément les scripts visuels qui sont lourds en mathématiques ou en logique. Il suffit de taper n’importe quelle expression et elle sera exécutée en temps réel.

Les nœuds d’expression peuvent :

  • Exécuter des expressions mathématiques et logiques basées sur des entrées personnalisées (ex : « a*5+b », où a et b sont des entrées personnalisées) :
../../../_images/visual_script47.png
  • Accédez aux variables ou propriétés locales :
../../../_images/visual_script48.png
  • Utilisez la plupart des fonctions intégrées existantes qui sont disponibles pour GDScript, telles que sin(), cos(), print(), ainsi que des constructeurs, tels que Vector3(x,y,y,z), Rect2(…), etc. :
../../../_images/visual_script49.png
  • Appeler les fonctions de l’API :
../../../_images/visual_script50.png
  • Utilisez le mode séquencé, ce qui a plus de sens en cas de respect de l’ordre de traitement :
../../../_images/visual_script51.png