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.

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 avec trop 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.

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 :

Connexions

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

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.

Ç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 :

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

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.

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 la mise en file d'attente d'un nœud pour suppression, ce qui se fait en appelant la méthode queue_free.

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 :

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

Si à la place, vous voulez lire cette valeur, glissez à nouveau le nœud mais pressez la touche Ctrl (ou Cmd sur macOS). Cela créera un getter :

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 :

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

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.

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

De même, maintenez Ctrl (ou Cmd sur macOS) pour déposer un setter :

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, mais cette fois avec Signals :

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

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 :

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

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 :

En appuyant sur Ctrl + F (ou Cmd + F sur macOS), vous pouvez effectuer une recherche 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.

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.

Le premier est "Constant" 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.

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.

Engine Singleton

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.

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 :

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.

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

Scene Node

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.

ArbreDesScènes

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 timers 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 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.

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.

Condition

C'est un simple nœud qui vérifie un port bool. Si true, il passera par le port de séquence "true". Si false, le second. Après avoir choisi l'un ou l'autre, il passe par le port "done". Laisser les ports de séquence déconnectés est acceptable si tous ne sont pas utilisés.

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.

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

Switch

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

While

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

Il y a une liste d'aides intégrées. La liste est presque identique à celle de GDScript). La plupart d'entre elles sont des fonctions mathématiques, mais d'autres peuvent être des aides très utiles. Assurez-vous de jeter un coup d’œil à la liste à l'occasion.

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.

Call

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é.

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.

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.

Attente/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.

Nœud 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) :

• Accédez aux variables ou propriétés locales :

• 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, z), Rect2(...), etc. :

• Appeler les fonctions de l'API :

• Utilisez le mode séquencé, ce qui a plus de sens en cas de respect de l'ordre de traitement :