diff --git a/img/visual_script1.png b/img/visual_script1.png new file mode 100644 index 000000000..82df1753b Binary files /dev/null and b/img/visual_script1.png differ diff --git a/img/visual_script10.png b/img/visual_script10.png new file mode 100644 index 000000000..dacfc0239 Binary files /dev/null and b/img/visual_script10.png differ diff --git a/img/visual_script11.png b/img/visual_script11.png new file mode 100644 index 000000000..52660bd9e Binary files /dev/null and b/img/visual_script11.png differ diff --git a/img/visual_script12.png b/img/visual_script12.png new file mode 100644 index 000000000..b353f64c8 Binary files /dev/null and b/img/visual_script12.png differ diff --git a/img/visual_script13.png b/img/visual_script13.png new file mode 100644 index 000000000..25aef4317 Binary files /dev/null and b/img/visual_script13.png differ diff --git a/img/visual_script14.png b/img/visual_script14.png new file mode 100644 index 000000000..469c33462 Binary files /dev/null and b/img/visual_script14.png differ diff --git a/img/visual_script15.png b/img/visual_script15.png new file mode 100644 index 000000000..2f599beec Binary files /dev/null and b/img/visual_script15.png differ diff --git a/img/visual_script16.png b/img/visual_script16.png new file mode 100644 index 000000000..e3ba1c4cb Binary files /dev/null and b/img/visual_script16.png differ diff --git a/img/visual_script17.png b/img/visual_script17.png new file mode 100644 index 000000000..ce616db77 Binary files /dev/null and b/img/visual_script17.png differ diff --git a/img/visual_script18.png b/img/visual_script18.png new file mode 100644 index 000000000..18887df4e Binary files /dev/null and b/img/visual_script18.png differ diff --git a/img/visual_script19.png b/img/visual_script19.png new file mode 100644 index 000000000..556094926 Binary files /dev/null and b/img/visual_script19.png differ diff --git a/img/visual_script2.png b/img/visual_script2.png new file mode 100644 index 000000000..14463f5de Binary files /dev/null and b/img/visual_script2.png differ diff --git a/img/visual_script20.png b/img/visual_script20.png new file mode 100644 index 000000000..979521861 Binary files /dev/null and b/img/visual_script20.png differ diff --git a/img/visual_script21.png b/img/visual_script21.png new file mode 100644 index 000000000..44a2495ed Binary files /dev/null and b/img/visual_script21.png differ diff --git a/img/visual_script22.png b/img/visual_script22.png new file mode 100644 index 000000000..6d0e0dd34 Binary files /dev/null and b/img/visual_script22.png differ diff --git a/img/visual_script23.png b/img/visual_script23.png new file mode 100644 index 000000000..66cb45d71 Binary files /dev/null and b/img/visual_script23.png differ diff --git a/img/visual_script24.png b/img/visual_script24.png new file mode 100644 index 000000000..9e9683ca5 Binary files /dev/null and b/img/visual_script24.png differ diff --git a/img/visual_script25.png b/img/visual_script25.png new file mode 100644 index 000000000..c6b7fc109 Binary files /dev/null and b/img/visual_script25.png differ diff --git a/img/visual_script26.png b/img/visual_script26.png new file mode 100644 index 000000000..5401cfb80 Binary files /dev/null and b/img/visual_script26.png differ diff --git a/img/visual_script27.png b/img/visual_script27.png new file mode 100644 index 000000000..098604130 Binary files /dev/null and b/img/visual_script27.png differ diff --git a/img/visual_script28.png b/img/visual_script28.png new file mode 100644 index 000000000..36e83e51c Binary files /dev/null and b/img/visual_script28.png differ diff --git a/img/visual_script29.png b/img/visual_script29.png new file mode 100644 index 000000000..f99a981ce Binary files /dev/null and b/img/visual_script29.png differ diff --git a/img/visual_script3.png b/img/visual_script3.png new file mode 100644 index 000000000..a0912fca3 Binary files /dev/null and b/img/visual_script3.png differ diff --git a/img/visual_script30.png b/img/visual_script30.png new file mode 100644 index 000000000..81d9ab91b Binary files /dev/null and b/img/visual_script30.png differ diff --git a/img/visual_script31.png b/img/visual_script31.png new file mode 100644 index 000000000..6a9b29740 Binary files /dev/null and b/img/visual_script31.png differ diff --git a/img/visual_script32.png b/img/visual_script32.png new file mode 100644 index 000000000..94714b172 Binary files /dev/null and b/img/visual_script32.png differ diff --git a/img/visual_script33.png b/img/visual_script33.png new file mode 100644 index 000000000..b2977b145 Binary files /dev/null and b/img/visual_script33.png differ diff --git a/img/visual_script34.png b/img/visual_script34.png new file mode 100644 index 000000000..c34f0cb8e Binary files /dev/null and b/img/visual_script34.png differ diff --git a/img/visual_script35.png b/img/visual_script35.png new file mode 100644 index 000000000..3e6549324 Binary files /dev/null and b/img/visual_script35.png differ diff --git a/img/visual_script36.png b/img/visual_script36.png new file mode 100644 index 000000000..875b70503 Binary files /dev/null and b/img/visual_script36.png differ diff --git a/img/visual_script37.png b/img/visual_script37.png new file mode 100644 index 000000000..9e61d3191 Binary files /dev/null and b/img/visual_script37.png differ diff --git a/img/visual_script38.png b/img/visual_script38.png new file mode 100644 index 000000000..6483fd817 Binary files /dev/null and b/img/visual_script38.png differ diff --git a/img/visual_script39.png b/img/visual_script39.png new file mode 100644 index 000000000..1266397c1 Binary files /dev/null and b/img/visual_script39.png differ diff --git a/img/visual_script4.png b/img/visual_script4.png new file mode 100644 index 000000000..8aa6a5967 Binary files /dev/null and b/img/visual_script4.png differ diff --git a/img/visual_script40.png b/img/visual_script40.png new file mode 100644 index 000000000..ff18b250b Binary files /dev/null and b/img/visual_script40.png differ diff --git a/img/visual_script41.png b/img/visual_script41.png new file mode 100644 index 000000000..305b0b6bd Binary files /dev/null and b/img/visual_script41.png differ diff --git a/img/visual_script42.png b/img/visual_script42.png new file mode 100644 index 000000000..aef87bef3 Binary files /dev/null and b/img/visual_script42.png differ diff --git a/img/visual_script43.png b/img/visual_script43.png new file mode 100644 index 000000000..e7eec472e Binary files /dev/null and b/img/visual_script43.png differ diff --git a/img/visual_script44.png b/img/visual_script44.png new file mode 100644 index 000000000..ff6950fee Binary files /dev/null and b/img/visual_script44.png differ diff --git a/img/visual_script45.png b/img/visual_script45.png new file mode 100644 index 000000000..8da3b09a9 Binary files /dev/null and b/img/visual_script45.png differ diff --git a/img/visual_script46.png b/img/visual_script46.png new file mode 100644 index 000000000..ce0befae0 Binary files /dev/null and b/img/visual_script46.png differ diff --git a/img/visual_script47.png b/img/visual_script47.png new file mode 100644 index 000000000..9c627c9e7 Binary files /dev/null and b/img/visual_script47.png differ diff --git a/img/visual_script48.png b/img/visual_script48.png new file mode 100644 index 000000000..7a79dfffb Binary files /dev/null and b/img/visual_script48.png differ diff --git a/img/visual_script49.png b/img/visual_script49.png new file mode 100644 index 000000000..cfe11ff66 Binary files /dev/null and b/img/visual_script49.png differ diff --git a/img/visual_script5.png b/img/visual_script5.png new file mode 100644 index 000000000..ab586c721 Binary files /dev/null and b/img/visual_script5.png differ diff --git a/img/visual_script50.png b/img/visual_script50.png new file mode 100644 index 000000000..7d17945c9 Binary files /dev/null and b/img/visual_script50.png differ diff --git a/img/visual_script51.png b/img/visual_script51.png new file mode 100644 index 000000000..7b6f3ce6f Binary files /dev/null and b/img/visual_script51.png differ diff --git a/img/visual_script52.png b/img/visual_script52.png new file mode 100644 index 000000000..c521513ae Binary files /dev/null and b/img/visual_script52.png differ diff --git a/img/visual_script53.png b/img/visual_script53.png new file mode 100644 index 000000000..3507532be Binary files /dev/null and b/img/visual_script53.png differ diff --git a/img/visual_script54.png b/img/visual_script54.png new file mode 100644 index 000000000..c730da620 Binary files /dev/null and b/img/visual_script54.png differ diff --git a/img/visual_script55.png b/img/visual_script55.png new file mode 100644 index 000000000..3e973c4e3 Binary files /dev/null and b/img/visual_script55.png differ diff --git a/img/visual_script6.png b/img/visual_script6.png new file mode 100644 index 000000000..20fc64a7c Binary files /dev/null and b/img/visual_script6.png differ diff --git a/img/visual_script7.png b/img/visual_script7.png new file mode 100644 index 000000000..e09dcde88 Binary files /dev/null and b/img/visual_script7.png differ diff --git a/img/visual_script8.png b/img/visual_script8.png new file mode 100644 index 000000000..1fe687252 Binary files /dev/null and b/img/visual_script8.png differ diff --git a/img/visual_script9.png b/img/visual_script9.png new file mode 100644 index 000000000..27b198191 Binary files /dev/null and b/img/visual_script9.png differ diff --git a/img/visual_script_connect.gif b/img/visual_script_connect.gif new file mode 100644 index 000000000..2dff93eef Binary files /dev/null and b/img/visual_script_connect.gif differ diff --git a/img/visual_script_disconnect.gif b/img/visual_script_disconnect.gif new file mode 100644 index 000000000..08f9e799f Binary files /dev/null and b/img/visual_script_disconnect.gif differ diff --git a/learning/scripting/index.rst b/learning/scripting/index.rst index b549fce8d..99668c2a7 100644 --- a/learning/scripting/index.rst +++ b/learning/scripting/index.rst @@ -6,3 +6,4 @@ Scripting :name: toc-learn-scripting gdscript/index + visual_script/index diff --git a/learning/scripting/visual_script/.#index.rst b/learning/scripting/visual_script/.#index.rst new file mode 120000 index 000000000..e263d07a3 --- /dev/null +++ b/learning/scripting/visual_script/.#index.rst @@ -0,0 +1 @@ +red@here.12030 \ No newline at end of file diff --git a/learning/scripting/visual_script/index.rst b/learning/scripting/visual_script/index.rst new file mode 100644 index 000000000..a811898d0 --- /dev/null +++ b/learning/scripting/visual_script/index.rst @@ -0,0 +1,8 @@ +GDScript +======== + +.. toctree:: + :maxdepth: 1 + :name: toc-learn-scripting-visual_script + + visual_script_basics diff --git a/learning/scripting/visual_script/visual_script_basics.rst b/learning/scripting/visual_script/visual_script_basics.rst new file mode 100644 index 000000000..698a133a5 --- /dev/null +++ b/learning/scripting/visual_script/visual_script_basics.rst @@ -0,0 +1,633 @@ +.. _doc_visual_script: + +Visual Scripting +================ + +Introduction +------------ + +Visual Scripting is always a controversial topic, surronded by many misunderstandings. +Programmers often think the aim of it is replacing their beloved code, so they +act defensively against it. Artists and game designers think that, with it, +they can write any game they want with little effort without the need of programmers. + +This situation is the result of really bad marketing from many products over time +which, in their aim to capure the interest of artists and game designers, also +made programmers feel like they are being replaced by visual tools. + +Truth is mostly, somewhat, in the middle. First of all, programmers can rest +assured that Visual Scripting in no way makes code obsolete. Artists and game +designers can also rest assured that they will be able to do a lot of things +without programming. + +Visual Scripting is a tool designed to make the entry barrier to programming +much lower. As code is more visual, it needs less abstract thinking to be +understood. Any artist, animator, game designer, etc. can look at it and quickly +grasp the flow of logic. + +The reason it does not make existing programming obsolete is, simply, that it does not scale as well. +It takes considerably more time to create code with it, and it's often more difficult +to modify than just writing a few characters. + +With the misunderstanding cleared up, the question that remains is what are the practical +uses is for Visual Scripting. + +The most common use cases are are as follows: + +* Beginners into game development who want to learn an engine but have no programming experience yet. +* Artists and Game Designers who have no experience in programming and want to create quick prototypes or simple games. +* Programmers working in a team that want to make part of the game logic available to Artists or Game Designers in order to offload some of their work. + +These scenarios are far more common than one might think, so this is why Godot has added this feature. + +Visual Scripting in Godot +------------------------- + +As with everything in Godot, we prioritize a good experience over copying or integrating third party solutions +which might not fit nicely in the current workflow. This led us to write our own version of how we believe +this feature would work best with the engine. + +In Godot, a Visual Script fits smoothly together with regular scripts in the Editor tab + +.. image:: /img/visual_script1.png + +In fact, Visual Scripting integrates so well to Godot that It's hard to believe it was added only +in version 3.0. This is because, when editing, the rest of Godot panels and +docks act like a palette from where you can drag and drop all sorts of information to the script canvas: + +.. image:: /img/visual_script2.png + +Creating a Script +----------------- + +Creating scripts works the same as with other scripting languages: Just select any node in the scene +and push the "New Script" button at the top right corner of the Scene Tree dock: + +.. image:: /img/visual_script3.png + +Once it opens, the script type "Visual Script" must be selected from the drop down list. The script extension +must be ".vs" (for Visual Script!). + +.. image:: /img/visual_script4.png + +Finally, the script editor will open, allowing to start the editing of the visual script: + +.. image:: /img/visual_script5.png + + +Adding a Function +----------------- + +Unlike other visual scripting implementations, Visual Scripting in Godot is heavily based on functions. +This happens because it uses the same interface to communicate with the engine as other scripting engines. +In Godot, the scripting interface is universal and all implementations conform to it. + +A function is an individual canvas with nodes connected. + +A single script can contain many functions, each of which will have a canvas of it's own. This makes scripts +more organized. + +There are three main ways to add functions in a script: + +Overriding a Virtual Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most types of nodes and other types of objects in Godot contain virtual functions. These are functions that +will be called (run your code) when something happens and can be looked up in the reference. Virtual functions +are listed when pressing the "Override" icon in the member panel: + +.. image:: /img/visual_script6.png + + +In the following example, a function will be executed when the node is loaded and added to the running scene. +For this, the _ready() virtual method will be overriden: + +.. image:: /img/visual_script7.png + + +Finally, a canvas appears for this function, showing the override: + +.. image:: /img/visual_script8.png + +As some functions expect you to return a value, they will also add a return node where such value is supposed to be +provided + +.. image:: /img/visual_script9.png + +Connecting a Signal to a Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nodes in a tree emit signals when something happens. Godot uses signals for all sorts of things. +A typical example would be a button that emits a "pressed" signal when actually pressed. + +For this, a node must be selected and the Node tab opened. This will allow inspecting the signals. +Once they are displayed, connect the "pressed" signal: + +.. image:: /img/visual_script10.png + +This will open the connection dialog. In this dialog, we must select the node where the signal be +connected to, and the function that will receive the signal: + +.. image:: /img/visual_script11.png + +If this is done right, a new function will be created in our script and a signal will automatically be +connected to it: + + +.. image:: /img/visual_script12.png + +Creating a Function Manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The last way to create functions is to do it manualy. In general this is not as common unless you +really need it. Custom functions work when another (or the same) script calls them manually. +The main use case for this is to separate a function into more, or reusing your visual code. + +To create a function manually, push the big "Plus" button, and a new function will be added +with a default name: + +.. image:: /img/visual_script13.png + +This will add a new function, which can be renamed by simply double clicking it's name: + +.. image:: /img/visual_script14.png + +To edit the "arguments" this function can get (the values you pass to it when you call this function), +simply click the Function node and check the inspector: + +.. image:: /img/visual_script15.png + +More on that will be explained later in this document. + +Nodes and Terminology +---------------------- + +Before continuing, it must be noted that the *Node* termonology needs to be used with care. +When refering to *Visual Script Nodes* (or generally just *Nodes*) this text will refer to the little boxes you connect with lines, +which are part of a graph. When refering to just *Scene Nodes*, it is implied that the elements + that make up a Scene are being refered, which ar part of a tere. Their naming is similar, but their function is different. +When refering to *Node* here, it will be implied that a *Visual Script Node* is refered to unless indicated otherwise. + +.. image:: /img/visual_script16.png + + +Node Properties +--------------- + +Like in most visual scripting implementations, each node has editable properties. In Godot, though, we try to avoid +bloating the nodes with editable controls for the sake of readability. + +Nodes still display the required information as text, but editing is done via the *Inspector*. To edit them, just +select andy node and edit it's properties in the *Inspector*. + +Ports and Connections +-------------------- + +Programming in Godot Visual Scripting is done via *Nodes* and *Port Connections* inside each function. + +Ports +~~~~~ + +Nodes in Godot Visual Scripting have *Ports*. These are endpoints that appear to the +left and right of nodes and which can be used to make *Connnections*: +There are two types of *Ports*: *Sequence* and *Data*. + +.. image:: /img/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, it's easy to understand the logic within a function by just following the white lines. +Not every *Node* has *Sequence Ports*. In fact, most do not. + +*Data Ports* ports contain typed values. Types can be any regular Godot types, +such as a boolean, an integer, a string, a Vector3, an array, any Object or Scene Node, etc. +A *Data Port* on the right side of a node is considered an output, while, +a port on the left side is an input. Connecting them allows to transfer information from a node to the next. + +Not all *Data Port types are compatible and will allow connections, though. +Pay special attention to colors and icons, as each type has a different representation: + +.. image:: /img/visual_script18.png + + +Connections +~~~~~~~~~~~ + +Connecting is a relatively simple process. Just drag an *Output Port* towards an *Input Port*. + +.. image:: /img/visual_script_connect.gif + +Disconnecting takes a bit more practice. Disconnecting in *Data Ports* happens by +dragging the *Input* away, while for *Sequence Ports*, this happens by dragging the *Output* away. + +.. image:: /img/visual_script_disconnect.gif + +This may seem strange at the beginning, 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: + +.. image:: /img/visual_script52.png + +While, for data, a contextual set/get/call menu will open: + +.. image:: /img/visual_script53.png + + +Adding Nodes +------------ + +Finally! We got to the fun part! But, before explaining in more detail what each type of node does, +let's take a short look at how nodes are most commonly added and dealt with. + + +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, by default, will ask you to *call a method* (sometimes refered to as *member function*) on +this node. + +.. image:: /img/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. + +.. image:: /img/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 will be by far the most common way to *Scene Nodes* in Visual Scripting. Simply select a *Scene Node* from the *Scene Tree*, +go the the inspector, find *The Name* of the property you want to edit (hint, *not* the value!) and drag it to the canvas: + +.. image:: /img/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, just drag the node again but hold the *Control* key (or Command on Mac). This will create a getter: + +.. image:: /img/visual_script22.png + +In this case, the value can be read from a *Data Port*. + + +Variables +~~~~~~~~~ + +Variables are memory containers local the script, which can hold a value. This value can be read from any of the functions of the script, or +from other scripts via the method described in the previous step. + +Adding a Variable is simple, just push the "Plus" Button on the *Variables* section of the members panel. Afterwards, doubleclick the +new variable to rename it: + +.. image:: /img/visual_script23.png + +Right clicking the variable allows to configure the type, as well as other properties: + +.. image:: /img/visual_script24.png + +.. image:: /img/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 (@TODO, document this). +Ticking the "Export" options makes the variable visible in the property editor when selecting the node. This makes it available also to +othe scripts via the method described in the previous step. + +.. image:: /img/visual_script28.png + +To use the variable in the script, simply drag it to the canvas to create a getter: + +.. image:: /img/visual_script26.png + +Likewise, hold *Control* (*Command* on Mac) to drop a setter: + +.. image:: /img/visual_script27.png + + +Signals +~~~~~~~ + +In the *Connecting Signals to a Function* item we have already learned about *Signals*. It is also possible to create your own +signals in a script and use them. For this, just do the same steps you did for variables in the previous step, except for *Signals*: + +.. image:: /img/visual_script29.png + +Signal can also be edited via right click menu to customize arguments: + +.. image:: /img/visual_script30.png + +The signal you have just created will also show together with the other node signals, this allows to eventually connect to it from another script +from another *Scene Node*: + +.. image:: /img/visual_script31.png + +Finally, to emit the signal, simply drag it to the canvas: + +.. image:: /img/visual_script32.png + +Remember that emitting a signal is a sequenced operation, so it must come from a Sequence port. + + +Adding More Nodes +----------------- + +Now that the basics are covered, let's discuss the large amount of utilitary nodes available for your canvas! +Below the member panel, exists the list of all available node types: + +.. image:: /img/visual_script33.png + + +Any of them can be dragged to the scene. Remember that, unlike the nodes previously discussed (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. + +.. image:: /img/visual_script34.png + + +Remember that you can check the class reference for what each node does, as they are documented there. That mentioned, +a brief overview of node types follows: + +Constants +~~~~~~~~~ + +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. + +.. image:: /img/visual_script36.png + +Of interest here are mainly three nodes. The first one is "Constant" which allows 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. + +The second is the GlobalConstant node, which contains a long list of constants for global types in Godot. In there +you can find some useful constants to refer to key names, joystick or mouse buttons, etc. + +The third one is MathConstant, which provides typical mathematical constants such as PI, E, etc. + +Data +~~~~ + +Data nodes deal with all sorts of access to information. Any information in Godot is accessed via these nodes, so +they are some of the most important ones to use and pretty diverse. + +.. image:: /img/visual_script37.png + +There are many types of nodes of interest here, so a short attempt to describe them will follow: + +Action +^^^^^^ + +Action nodes are vital when dealing with input from a device. You can read more about actions in the (@TODO ACTION TUTE LINK). +In the following example below, the control is moved to the right when the "move_right" action is pressed. + +.. image:: /img/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. + +.. image:: /img/visual_script39.png + +Remember that dragging a connection to empty space will help you call functions or set/get properties on these: + +.. image:: /img/visual_script40.png + +Local Variables +^^^^^^^^^^^^^^^ + +These are nodes you can use as temporary storage for your graphs. Just make sure they all have the same name and type when using them +and they will reference the same piece of memory. + +.. image:: /img/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). + + +Scene Node +^^^^^^^^^^ + +This is just a reference to a node in the tree, but it's easier to use this node by just dragging the actual node +from the scene tree to the canvas (this will create it and configure it). + +Self +^^^^ + +In some rare ocassions, it may be desired to pass this Scene Node as argument. +It can be used to call functions and set/get properties, but it's easier to just +drag nodes (or event he 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 as 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. + +Preload +^^^^^^^ + +This does the same function as preload() in GDScript. It maintains this resource loaded and ready to use. Rather than +instancing the node, it's simpler to just drag the desired resource from the filesystem dock to the canvas. + +Resource Path +^^^^^^^^^^^^^ + +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. + +Comment +^^^^^^^ + +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 seleting it. It can also be used to write text on it. + +.. image:: /img/visual_script42.png + +Flow Control +~~~~~~~~~~~~ + +Flow control nodes are all sequenecd, and allow the execution take different branches, usually depending on a +given condition. + +.. image:: /img/visual_script43.png + +Condition +^^^^^^^^^ + +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 no 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. + +Return +^^^^^^ + +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. + +Sequence +^^^^^^^^ + +This node is useful mostly for organizing your graph. It calls it's sequence ports in order. + +TypeCast +^^^^^^^^ + +This is a very 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 obj output to get full completion. + +.. image:: /img/visual_script55.png + +It is also possible to cast to a script, which will allow to complete script properties and functions: + + +.. image:: /img/visual_script54.png + +Switch +^^^^^^ + +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. + +Functions +~~~~~~~~~ + +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 (@TODO, link to gdscript methods?) +Most of them are mathematical functions, but others can be very useful helpers. Just 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" intead of the Vector3 category. +In most cases just search the list of nodes, it should be faster. + +Call +^^^^ + +This is the generic calling node. It is rarely used directly but by dragging to empty space on an already cofigured node. + +Constructors +^^^^^^^^^^^^ + +These are all the functions needed to create godot basic datatypes. If you need to, for example, create a Vector3 out of 3 floats, a +constructor must be used. + +.. image:: /img/visual_script44.png + + +Destructor +^^^^^^^^^^ + +This is the opposite to Constructor, it allows to separate any basic type (ie, Vector3) into it's sub-elements. + +.. image:: /img/visual_script45.png + + +Emit Signal +^^^^^^^^^^^ + +Emits signals from any object. + + +Emit Signal +^^^^^^^^^^^ + +Emits signals from any object. In general not very useful, as dragging a signal to the canvas works better. + + +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 wil make the function return a value that can be used to resume execution. + + +Yield Signal +^^^^^^^^^^^^ + +Same as Yield, but will wait until a given signal is emitted. + + +Index +~~~~~ + +Generic indexing operator, not often used but it's good that exists just in case. + +Operators +~~~~~~~~~ + +These are mostly generic operators such as addition, multiplication, comparison, etc. +By default, these mostly accept any datatype (and will error in run-time if the types +feeded do not match for the operator). Is is always recommended to set the right +type for operators to catch errors faster and make the graph easier to read. + +.. image:: /img/visual_script46.png + + +Expression Node +^^^^^^^^^^^^^^^ + +Among the operators, the *Expression* node is the most powerful. If well used, it allows to enormously simplify +visual scripts that are math or logic heavy. Just type any expression on it and it will be executed in real-time. + +Expression nodes can: + +- Perform math and logic expressions based on custom inputs (eg: "a*5+b", where a and b are custom inputs): +.. image:: /img/visual_script47.png +- Access local variables or properties: +.. image:: /img/visual_script48.png +- Use most of the existing built-in functions and available to GDScript, such as sin(),cos(),print(), as well as constructors, such as Vector3(x,y,z),Rect2(..), etc.: +.. image:: /img/visual_script49.png +- Call API functions: +.. image:: /img/visual_script50.png +- Use sequenced mode, which makes more sense in case of respecting the processing order: +.. image:: /img/visual_script51.png + + + +