Nodes and terminology

Przed kontynuowaniem należy pamiętać, że terminologia Węzła musi być używana ostrożnie. W przypadku Visual Script Nodes (lub ogólnie Węzłów) tekst ten będzie odnosił się do małych pól, które łączą się z liniami, które są częścią wykresu. Węzły sceny oznaczają, że elementy składające się na scenę, które są częścią drzewa. Ich nazwa jest podobna, ale ich funkcja jest inna. W przypadku odniesienia się tutaj do Węzła, co będzie oznaczało Visual Script Nodes, o ile nie wskazano inaczej.

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

Node properties

Podobnie jak w większości wizualnych implementacji skryptowych, każdy węzeł posiada edytowalne właściwości. Jednak w Godocie staramy się unikać zbytniego powiększania węzłów w celu zapewnienia czytelności.

Węzły nadal wyświetlają wymagane informacje jako tekst, ale ich edycja odbywa się za pomocą Inspektor. Aby je edytować, zaznacz dowolny węzeł i edytuj jego właściwości w Inspektorze.

Ports and connections

Programowanie w Godot Visual Scripting odbywa się poprzez Węzły i Połączenia portów wewnątrz każdej funkcji.

Porty

Węzły w Godot Visual Scripting mają Porty. Są to punkty końcowe, które pojawiają się po lewej i prawej stronie węzłów i mogą być użyte do utworzenia Połączeń: Istnieją dwa rodzaje Portów: Kolejność i Dane.

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

Sequence Ports indicate the order in which operations are executed. Typically when a Node is done processing, it will go to the next node from one of the ports at the right. If nothing is connected, the function may end, or another output Sequence Port might be tried (this depends on the node). Thanks to this, you can follow the logic flow within a function by following the white lines. Not every Node has Sequence Ports. In fact, most do not.

Porty Danych zawierają wpisane wartości. Typy mogą być dowolnymi typami Godota, takimi jak boolean, integer, string, Vector3, array, każdy obiekt lub węzeł sceny itp. Port danych po prawej stronie węzła jest uważany za wyjście, podczas gdy port po lewej stronie jest wejściem. Podłączenie ich umożliwia przepływ informacji do następnego węzła.

Nie wszystkie typy Data Port są kompatybilne i umożliwią nawiązanie połączeń. Zwróć szczególną uwagę na kolory i ikony, ponieważ każdy typ ma inną reprezentację:

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

Połączenia

Podłączenie jest stosunkowo prostym procesem. Przeciągnij Port wyjściowy w stronę Port wejściowy.

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

Odłączanie wymaga nieco więcej wysiłku. Odłączenie w Portach Danych następuje przez przeciągnięcie Wejścia, natomiast w Portach kolejności przez przeciągnięcie Wyjścia.

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

This may seem strange at first, but it happens because Data Ports are 1:N (A single output port can connect to many inputs), while Sequence Ports are N:1 (Many sequence outputs can be connected to a single input).

Connecting to empty space (drag to connect but unpress over empty space) is also context sensitive, it will supply a list of most common operations. For sequences, it will be conditional nodes:

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

While, for data, a contextual set/get/call menu will open:

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

Adding nodes

W końcu! Dotarliśmy do części rozrywkowej! Zanim jednak wyjaśnimy szczegółowo, co robi każdy typ węzła, przyjrzyjmy się, w jaki sposób węzły są najczęściej dodawane i obsługiwane.

Accessing scene nodes

One of the most common tasks is accessing Scene Tree Nodes (again, not to mistake with Visual Script Nodes). Dragging from the Scene Tree and dropping into the canvas will ask you to call a method (sometimes referred to as member function) on this node.

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

While accessing properties is desired in most cases (more on that below), sometimes calling methods can be useful too. Methods execute specific actions on objects. In the above case, the mouse pointer can be warped to a position in local coordinates to the control. Another common use case is queueing a node for deletion, which is done with the queue_free method.

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

Care must be taken that this only works if the scene being edited contains your Visual Script in one of the nodes! Otherwise, a warning will be shown.

Accessing scene node properties

This is the most common way to edit Scene Nodes in Visual Scripting. Select a Scene Node from the Scene Tree, go to the Inspector, find the Name of the property you want to edit (hint, not the value!) and drag it to the canvas:

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

The result is that this value can be changed from your script by writing to a Data Port.

If instead reading this value is desired, drag the node again but hold the Control key (or Command on Mac). This will create a getter:

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

W tym przypadku wartość można odczytać z Portu Danych.

Zmienne

Zmienne to miejsce pamięci dla skryptu, które mogą zawierać wartość. Wartość tę można odczytać z dowolnej funkcji skryptu lub z innych skryptów metodą opisaną w poprzednim kroku.

Aby dodać zmienną, naciśnij przycisk „+” w sekcji Zmienne panelu Członkowie. Kliknij dwukrotnie na nową zmienną, aby zmienić jej nazwę:

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

Kliknięcie zmiennej prawym przyciskiem myszy umożliwi skonfigurowanie jej właściwości:

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

As it can be seen above, the type and initial value of the variable can be changed, as well as some property hints. Ticking the „Export” option makes the variable visible in the Inspector when selecting the node. This also makes it available to other scripts via the method described in the previous step.

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

Aby użyć zmiennej w skrypcie, po prostu przeciągnij ją w ramkę, aby utworzyć odbiorcę:

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

Podobnie, przytrzymaj Control (Command na komputerze Mac), aby ustawić setter:

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

Sygnały

It is also possible to create your own signals in a script and use them. For this, do the same steps you did for variables in the previous step, except for Signals:

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

A signal can also be edited via the right-click menu to customize its arguments:

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

The signal you have created will appear in the Inspector, along with the built-in node signals. This allows you to connect it from another script from another Scene Node:

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

Na koniec, aby wyemitować sygnał, przeciągnij go na obszar roboczy:

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

Remember that emitting a signal is a sequenced operation, so it must come from a Sequence port.

Adding more nodes

Teraz, gdy podstawy są już wyjaśnione, omówmy dużą ilość użytecznych węzłów dla twojego projektu! Poniżej panelu Członkowie znajduje się lista wszystkich dostępnych typów węzłów:

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

Ctrl-F (Command-F on Mac) umożliwia przeszukiwanie listy.

Any of them can be dragged to the scene. Unlike nodes (e.g. dragging a property from the Inspector sets the context to the node being edited automatically), these are added without any „contextual” information, so this has to be done manually.

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

Pamiętaj, że możesz sprawdzić, co robi każdy z węzłów, ponieważ są one udokumentowane. Poniżej znajduje się krótki przegląd typów węzłów:

Stałe

Constant nodes are nodes that provide values that, while not changing over time, can be useful as reference values. Most of the time they are integer or float.

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

The first one is „Constant”, which allows you to select any value of any type as constant, from an integer (42) to a String („Hello!”). In general, this node is not used that often because of default input values in Data Ports, but it’s good to know it exists.

Drugim jest węzeł GlobalConstant, który zawiera długą listę stałych dla typów globalnych w Godot. W tym miejscu można znaleźć przydatne stałe, które odnoszą się do nazw klawiszy, dżojstika, przycisków myszy itp.

The third one is MathConstant, which provides typical mathematical constants, such as PI, E, etc.

Dane

Węzły danych zajmują się wszelkiego rodzaju dostępem do informacji. Wszelkie informacje w Godocie są dostępne za pośrednictwem tych węzłów, co czyni je jednymi z najważniejszych dostępnych węzłów oraz są bardzo różnorodne.

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

There are many types of nodes of interest here, so a short attempt to describe them will follow:

Akcja

Węzły funkcyjne są niezbędne w przypadku wprowadzania danych z urządzenia. Więcej informacji na temat akcji można znaleźć w (@TODO ACTION TUTE LINK). W poniższym przykładzie obiekt przesuwa się w prawo po uruchomieniu akcji „move_right”.

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

Engine Singleton

Engine singletons are global interfaces (meaning they can be accessed without a reference; unlike Scene Nodes, they are always available). They have several purposes, but in general, they are useful for low-level access or OS-related access.

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

Pamiętaj, że przeciągnięcie połączenia na puste miejsce pomoże ci wywołać funkcje lub ustawić/zapisać właściwości na nich:

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

Lokalne zmienne

Są to węzły, których można używać do tymczasowego zapisu wykresów. Upewnij się, że podczas korzystania z nich wszystkie mają tą samą nazwę i typ oraz że będą odnosić się do tego samego obszaru pamięci.

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

As it can be seen above, there are two nodes available: A simple getter, and a sequenced getter (setting requires a sequence port).

Węzeł sceny

This is just a reference to a node in the tree, but it’s easier to use this node by dragging the actual node from the scene tree to the canvas (this will create it and configure it).

Ten obiekt

In some rare occasions, it may be desired to pass this Scene Node as argument. It can be used to call functions and set/get properties, or drag nodes (or event the node itself that has the script) from the Scene Tree to the canvas for this.

SceneTree

This node is similar to the Singleton node because it references the SceneTree, which contains the active scene. SceneTree, however, only works when the node is sitting in the scene and active, otherwise accessing it will return an error.

SceneTree allows for many low-level things, like setting stretch options, calling groups, make timers, or even load another scene. It’s a good class to get familiar with.

Wstępne Ładowanie

Pełni to tę samą funkcję co preload() w GDScript. Utrzymuje on ten zasób w stanie załadowanym i gotowym do użycia. Zamiast uruchamiać węzeł, łatwiej jest przeciągnąć żądany zasób z panelu systemu plików na obszar roboczy.

Ścieżka zasobu

This node is a simple helper to get a string with a path to a resource you can pick. It’s useful in functions that load things from disk.

Komentarz

A Comment node works as a node you can resize to put around other nodes. It will not try to get focus or be brought to top when selecting it. It can also be used to write text on it.

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

Flow Control

Flow control nodes allow the execution to take different branches, usually depending on a given condition.

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

Warunek

This is a simple node that checks a bool port. If true, it will go via the „true” sequence port. If false, the second. After going for either of them, it goes via the „done” port. Leaving sequence ports disconnected is fine if not all of them are used.

Iterator

Some data types in Godot (ie, arrays, dictionaries) are iterable. This means that a bit of code can run for each element that it has.

The Iterator node goes through all elements and, for each of them, it goes via the „each” sequence port, making the element available in the „elem” data port.

When done, it goes via the „exit” sequence port.

Zwraca

Some functions can return values. In general for virtual ones, Godot will add the Return node for you. A return node forces the function to end.

Sekwencja

This node is useful mostly for organizing your graph. It calls its sequence ports in order.

TypeCast

This is a useful and commonly used node. You can use it to cast arguments or other objects to the type you desire. Afterwards, you can even drag the object output to get full completion.

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

It is also possible to cast to a script, which will allow complete script properties and functions:

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

Przełącznik

The Switch node is similar to the Condition node, but it matches many values at the same time.

While

This is a more primitive form of iteration. „repeat” sequence output will be called as long as the condition in the „cond” data port is met.

Funkcje

Functions are simple helpers, most of the time deterministic. They take some arguments as input and return an output. They are almost never sequenced.

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.

By Type

Those are the methods available to basic types. For example, if you want a dot-product, you can search for „dot” instead of the Vector3 category. In most cases just search the list of nodes, it should be faster.

Wywołanie

This is the generic calling node. It is rarely used directly but by dragging to empty space on an already configured node.

Konstruktory

Są to wszystkie funkcje, potrzebne do stworzenia podstawowych typów danych Godota. Na przykład, jeśli chcesz utworzyć Vector3 z 3 liczb zmiennoprzecinkowych, musisz użyć konstruktora.

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

Destruktor

Jest to przeciwieństwo Konstruktora, pozwala on na rozdzielenie dowolnego typu podstawowego (tj. Vector3) na jego podelementy.

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

Wyemituj sygnał

Emituje sygnały z dowolnego obiektu. Generalnie nie jest on aż tak przydatny, ponieważ przeciąganie sygnału na obszar roboczy działa lepiej.

Get/Set

Generic Getter/Setter node. Dragging properties from the Inspector works better, as they appear properly configured on drop.

Wait

The Wait nodes will suspend execution of the function until something happens (many frames can pass until resuming, in fact). Default nodes allow you to wait for a frame to pass, a fixed frame or a given amount of time until execution is resumed.

Yield

This node completely suspends the execution of the script, and it will make the function return a value that can be used to resume execution.

Yield Sygnał

Taki sam jak Yield, ale będzie czekać, aż dany sygnał zostanie wysłany.

Indeks

Generic indexing operator, not often used but it’s good that it exists just in case.

Operatory

These are mostly generic operators, such as addition, multiplication, comparison, etc. By default, these mostly accept any datatype (and will throw an error at run-time if the types fed do not match those expected by the operator). It is always recommended to set the right type for operators to catch errors faster and make the graph easier to read.

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

Expression Node

Among the operators, the Expression node is the most powerful. If well used, it allows you to enormously simplify visual scripts that are math or logic heavy. Type any expression on it and it will be executed in real-time.

Węzły ekspresji mogą:

  • Wykonuj wyrażenia matematyczne i logiczne w oparciu o niestandardowe wejścia (np. „a*5+b”, gdzie a i b są niestandardowymi wejściami):
../../../_images/visual_script47.png
  • Dostęp do lokalnych zmiennych lub właściwości:
../../../_images/visual_script48.png
  • Wykorzystaj większość istniejących funkcji wbudowanych, które są dostępne dla GDScript, takich jak sin(), cos(), print(), jak również konstruktory, takie jak Vector3(x,y,z), Rect2(…) itp:
../../../_images/visual_script49.png
  • Wywołanie funkcji API:
../../../_images/visual_script50.png
  • Use sequenced mode, which makes more sense in case of respecting the processing order:
../../../_images/visual_script51.png