131 lines
4.4 KiB
ReStructuredText
131 lines
4.4 KiB
ReStructuredText
.. _doc_getting_started_visual_script:
|
|
|
|
Getting started with Visual Scripting
|
|
=====================================
|
|
|
|
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: 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 you to start editing 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 its own, allowing for more organization.
|
|
|
|
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 overridden:
|
|
|
|
.. 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, you must select the node where the signal will 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 manually. 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 cases for this are breaking a larger function up into several manageable chunks and 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 its 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.
|