visual_script_basics.rst 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669
  1. .. _doc_visual_script:
  2. Visual Scripting
  3. ================
  4. Introduction
  5. ------------
  6. Visual Scripting is a tool designed to make the entry barrier to programming
  7. much lower. As code is more visual, it needs less abstract thinking to be
  8. understood. Any artist, animator, game designer, etc. can look at it and quickly
  9. grasp the flow of logic.
  10. The reason it does not make existing programming obsolete is, simply, that it does not scale as well.
  11. It takes considerably more time to create code with it, and it's often more difficult
  12. to modify than just writing a few characters.
  13. With the misunderstanding cleared up, the question that remains is what are the practical
  14. uses for Visual Scripting.
  15. The most common use cases are are as follows:
  16. * Game development beginners who want to learn an engine but have no programming experience yet.
  17. * Artists and Game Designers who have no experience in programming and want to create quick prototypes or simple games.
  18. * 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.
  19. These scenarios are far more common than one might think, so this is why Godot has added this feature.
  20. Visual Scripting in Godot
  21. -------------------------
  22. As with everything in Godot, we prioritize a good experience over copying or integrating third party solutions
  23. which might not fit nicely in the current workflow. This led us to write our own version of how we believe
  24. this feature would work best with the engine.
  25. In Godot, a Visual Script fits smoothly together with regular scripts in the Editor tab
  26. .. image:: img/visual_script1.png
  27. In fact, Visual Scripting integrates so well to Godot that it's hard to believe it was added only
  28. in version 3.0. This is because, when editing, the rest of Godot panels and docks act like a
  29. palette from where you can drag and drop all sorts of information to the script canvas:
  30. .. image:: img/visual_script2.png
  31. Creating a Script
  32. -----------------
  33. Creating scripts works the same as with other scripting languages: Just select any node in the scene
  34. and push the "New Script" button at the top right corner of the Scene Tree dock:
  35. .. image:: img/visual_script3.png
  36. Once it opens, the script type "Visual Script" must be selected from the drop down list. The script extension
  37. must be ".vs" (for Visual Script!).
  38. .. image:: img/visual_script4.png
  39. Finally, the Script Editor will open, allowing to start the editing of the visual script:
  40. .. image:: img/visual_script5.png
  41. Adding a Function
  42. -----------------
  43. Unlike other visual scripting implementations, Visual Scripting in Godot is heavily based on functions.
  44. This happens because it uses the same interface to communicate with the engine as other scripting engines.
  45. In Godot, the scripting interface is universal and all implementations conform to it.
  46. A function is an individual canvas with nodes connected.
  47. A single script can contain many functions, each of which will have a canvas of its own, allowing for more organization.
  48. There are three main ways to add functions in a script:
  49. Overriding a Virtual Function
  50. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51. Most types of nodes and other types of objects in Godot contain virtual functions. These are functions that
  52. will be called (run your code) when something happens and can be looked up in the reference. Virtual functions
  53. are listed when pressing the "Override" icon in the member panel:
  54. .. image:: img/visual_script6.png
  55. In the following example, a function will be executed when the node is loaded and added to the running scene.
  56. For this, the _ready() virtual method will be overridden:
  57. .. image:: img/visual_script7.png
  58. Finally, a canvas appears for this function, showing the override:
  59. .. image:: img/visual_script8.png
  60. As some functions expect you to return a value, they will also add a return node where such value is supposed to be
  61. provided:
  62. .. image:: img/visual_script9.png
  63. Connecting a Signal to a Function
  64. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65. Nodes in a tree emit signals when something happens. Godot uses signals for all sorts of things.
  66. A typical example would be a button that emits a "pressed" signal when actually pressed.
  67. For this, a node must be selected and the Node tab opened. This will allow inspecting the signals.
  68. Once they are displayed, connect the "pressed" signal:
  69. .. image:: img/visual_script10.png
  70. This will open the connection dialog. In this dialog, you must select the node where the signal will be
  71. connected to, and the function that will receive the signal:
  72. .. image:: img/visual_script11.png
  73. If this is done right, a new function will be created in our script and a signal will automatically be
  74. connected to it:
  75. .. image:: img/visual_script12.png
  76. Creating a Function Manually
  77. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78. The last way to create functions is to do it manually. In general this is not as common unless you
  79. really need it. Custom functions work when another (or the same) script calls them manually.
  80. The main use case for this is to separate a function into more, or reusing your visual code.
  81. To create a function manually, push the big "Plus" button, and a new function will be added
  82. with a default name:
  83. .. image:: img/visual_script13.png
  84. This will add a new function, which can be renamed by simply double clicking its name:
  85. .. image:: img/visual_script14.png
  86. To edit the "arguments" this function can get (the values you pass to it when you call this function),
  87. simply click the Function node and check the inspector:
  88. .. image:: img/visual_script15.png
  89. More on that will be explained later in this document.
  90. Nodes and Terminology
  91. ----------------------
  92. Before continuing, it must be noted that the *Node* terminology needs to be used with care.
  93. When referring to *Visual Script Nodes* (or generally *Nodes*) this text will refer to the little boxes you connect with lines, which are part of a graph.
  94. When referring to *Scene Nodes*, it is implied that the elements that make up a Scene are being referred, which are part of a tree. Their naming is similar but their function is different.
  95. When referring to *Node* here, it will be implied that a *Visual Script Node* is referred to unless indicated otherwise.
  96. .. image:: img/visual_script16.png
  97. Node Properties
  98. ---------------
  99. Like in most visual scripting implementations, each node has editable properties. In Godot, though, we try to avoid
  100. bloating the nodes with editable controls for the sake of readability.
  101. Nodes still display the required information as text, but editing is done via the *Inspector*. To edit them, just
  102. select any node and edit its properties in the *Inspector*.
  103. Ports and Connections
  104. ---------------------
  105. Programming in Godot Visual Scripting is done via *Nodes* and *Port Connections* inside each function.
  106. Ports
  107. ~~~~~
  108. Nodes in Godot Visual Scripting have *Ports*. These are endpoints that appear to the
  109. left and right of nodes and which can be used to make *Connnections*:
  110. There are two types of *Ports*: *Sequence* and *Data*.
  111. .. image:: img/visual_script17.png
  112. *Sequence Ports* indicate the order in which operations are executed.
  113. Typically when a *Node* is done processing, it will go to the next node from one of the ports at the right.
  114. If nothing is connected the function may end, or another output *Sequence Port* might be tried (this depends on the node).
  115. Thanks to this, it's easy to understand the logic within a function by just following the white lines.
  116. Not every *Node* has *Sequence Ports*. In fact, most do not.
  117. *Data Ports* ports contain typed values. Types can be any regular Godot types,
  118. such as a boolean, an integer, a string, a Vector3, an array, any Object or Scene Node, etc.
  119. A *Data Port* on the right side of a node is considered an output, while,
  120. a port on the left side is an input. Connecting them allows information to flow to the next node.
  121. Not all *Data Port* types are compatible and will allow connections, though.
  122. Pay special attention to colors and icons, as each type has a different representation:
  123. .. image:: img/visual_script18.png
  124. Connections
  125. ~~~~~~~~~~~
  126. Connecting is a relatively simple process. Just drag an *Output Port* towards an *Input Port*.
  127. .. image:: img/visual_script_connect.gif
  128. Disconnecting takes a bit more practice. Disconnecting in *Data Ports* happens by
  129. dragging the *Input* away, while for *Sequence Ports*, this happens by dragging the *Output* away.
  130. .. image:: img/visual_script_disconnect.gif
  131. This may seem strange at the beginning, but it happens because *Data Ports* are 1:N
  132. (A single output port can connect to many inputs), while *Sequence Ports* are N:1
  133. (Many sequence outputs can be connected to a single input).
  134. Connecting to empty space (drag to connect but unpress over empty space) is also context sensitive, it will supply
  135. a list of most common operations. For sequences, it will be conditional nodes:
  136. .. image:: img/visual_script52.png
  137. While, for data, a contextual set/get/call menu will open:
  138. .. image:: img/visual_script53.png
  139. Adding Nodes
  140. ------------
  141. Finally! We got to the fun part! But, before explaining in more detail what each type of node does,
  142. let's take a short look at how nodes are most commonly added and dealt with.
  143. Accessing Scene Nodes
  144. ~~~~~~~~~~~~~~~~~~~~~
  145. One of the most common tasks is accessing Scene Tree Nodes (again, not to mistake with *Visual Script Nodes*).
  146. 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.
  147. .. image:: img/visual_script19.png
  148. While accessing properties is desired in most cases (more on that below), sometimes *calling methods* can be useful too.
  149. Methods execute specific actions on objects. In the above case, the mouse pointer can be warped to a position in local
  150. coordinates to the control. Another common use case is queueing a node for deletion, which is done with the *queue_free* method.
  151. .. image:: img/visual_script20.png
  152. 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.
  153. Accessing Scene Node Properties
  154. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  155. 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:
  156. .. image:: img/visual_script21.png
  157. The result is that this value can be changed from your script by writing to a *Data Port*.
  158. 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:
  159. .. image:: img/visual_script22.png
  160. In this case, the value can be read from a *Data Port*.
  161. Variables
  162. ~~~~~~~~~
  163. Variables are memory containers local to 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.
  164. To add a Variable, push the "+" button on the *Variables* section of the Members panel. Double-click the new variable to rename it:
  165. .. image:: img/visual_script23.png
  166. Right-clicking the variable allows you to configure its properties:
  167. .. image:: img/visual_script24.png
  168. .. image:: img/visual_script25.png
  169. 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).
  170. Ticking the "Export" options 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.
  171. .. image:: img/visual_script28.png
  172. To use the variable in the script, simply drag it to the canvas to create a getter:
  173. .. image:: img/visual_script26.png
  174. Likewise, hold *Control* (*Command* on Mac) to drop a setter:
  175. .. image:: img/visual_script27.png
  176. Signals
  177. ~~~~~~~
  178. 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*:
  179. .. image:: img/visual_script29.png
  180. A signal can also be edited via right-click menu to customize its arguments:
  181. .. image:: img/visual_script30.png
  182. The signal you have just 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*:
  183. .. image:: img/visual_script31.png
  184. Finally, to emit the signal, simply drag it to the canvas:
  185. .. image:: img/visual_script32.png
  186. Remember that emitting a signal is a sequenced operation, so it must come from a Sequence port.
  187. Adding More Nodes
  188. -----------------
  189. Now that the basics are covered, let's discuss the large amount of utility nodes available for your canvas!
  190. Below the member panel, exists the list of all available node types:
  191. .. image:: img/visual_script33.png
  192. Ctrl-F (Command-F on Mac) allows you to search the list.
  193. Any of them can be dragged to the scene. Unlike nodes (e.g. dragging a property
  194. 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.
  195. .. image:: img/visual_script34.png
  196. Remember that you can check the class reference for what each node does, as they are documented there. That mentioned,
  197. a brief overview of node types follows:
  198. Constants
  199. ~~~~~~~~~
  200. Constant nodes are nodes that provide values that, while not changing over time, can be useful as reference values.
  201. Most of the time they are integer or float.
  202. .. image:: img/visual_script36.png
  203. 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.
  204. The second is the GlobalConstant node, which contains a long list of constants for global types in Godot. In there
  205. you can find some useful constants to refer to key names, joystick or mouse buttons, etc.
  206. The third one is MathConstant, which provides typical mathematical constants such as PI, E, etc.
  207. Data
  208. ~~~~
  209. Data nodes deal with all sorts of access to information. Any information in Godot is accessed via these nodes, so
  210. they are some of the most important ones to use and pretty diverse.
  211. .. image:: img/visual_script37.png
  212. There are many types of nodes of interest here, so a short attempt to describe them will follow:
  213. Action
  214. ^^^^^^
  215. Action nodes are vital when dealing with input from a device. You can read more about actions in the (@TODO ACTION TUTE LINK).
  216. In the following example below, the control is moved to the right when the "move_right" action is pressed.
  217. .. image:: img/visual_script38.png
  218. Engine Singleton
  219. ^^^^^^^^^^^^^^^^
  220. Engine singletons are global interfaces (meaning they can be accessed without a reference, unlike Scene Nodes, they are always available).
  221. They have several purposes, but in general they are useful for low level access or OS-related access.
  222. .. image:: img/visual_script39.png
  223. Remember that dragging a connection to empty space will help you call functions or set/get properties on these:
  224. .. image:: img/visual_script40.png
  225. Local Variables
  226. ^^^^^^^^^^^^^^^
  227. 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.
  228. .. image:: img/visual_script41.png
  229. As it can be seen above, there are two nodes available: A simple getter, and a sequenced getter (setting requires a sequence port).
  230. Scene Node
  231. ^^^^^^^^^^
  232. 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
  233. from the scene tree to the canvas (this will create it and configure it).
  234. Self
  235. ^^^^
  236. In some rare ocassions, it may be desired to pass this Scene Node as argument.
  237. It can be used to call functions and set/get properties, or just drag nodes (or event the node itself that has the script) from the Scene Tree to the canvas for this.
  238. SceneTree
  239. ^^^^^^^^^
  240. This node is similar to the Singleton node because it references the SceneTree, which contains the active scene.
  241. SceneTree, however, only works when the node is sitting in the scene and active, otherwise accessing it will
  242. return as an error.
  243. SceneTree allows for many low level things, like setting stretch options, calling groups, make timers, or even
  244. load another scene. It's a good class to get familiar with.
  245. Preload
  246. ^^^^^^^
  247. This does the same function as preload() in GDScript. It maintains this resource loaded and ready to use. Rather than
  248. instancing the node, it's simpler to just drag the desired resource from the filesystem dock to the canvas.
  249. Resource Path
  250. ^^^^^^^^^^^^^
  251. 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
  252. load things from disk.
  253. Comment
  254. ^^^^^^^
  255. 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
  256. to top when selecting it. It can also be used to write text on it.
  257. .. image:: img/visual_script42.png
  258. Flow Control
  259. ~~~~~~~~~~~~
  260. Flow control nodes allow the execution to take different branches, usually depending on a
  261. given condition.
  262. .. image:: img/visual_script43.png
  263. Condition
  264. ^^^^^^^^^
  265. This is a simple node that checks a bool port. If true, it will go via the "true" sequence port. If false,
  266. the second. After going for either of them, it goes via the "done" port. Leaving sequence
  267. ports disconnected is fine if not all of them are used.
  268. Iterator
  269. ^^^^^^^^
  270. Some data types in Godot (ie, arrays, dictionaries) are iterable. This means that a bit of code can run
  271. for each element that it has.
  272. The Iterator node goes through all elements and, for each of them, it goes via the "each" sequence port,
  273. making the element available in the "elem" data port.
  274. When done, it goes via the "exit" sequence port.
  275. Return
  276. ^^^^^^
  277. Some functions can return values. In general for virtual ones, Godot will add the Return node for you.
  278. A return node forces the function to end.
  279. Sequence
  280. ^^^^^^^^
  281. This node is useful mostly for organizing your graph. It calls its sequence ports in order.
  282. TypeCast
  283. ^^^^^^^^
  284. This is a very useful and commonly used node. You can use it to cast arguments or other objects
  285. to the type you desire. Afterwards, you can even drag the object output to get full completion.
  286. .. image:: img/visual_script55.png
  287. It is also possible to cast to a script, which will allow complete script properties and functions:
  288. .. image:: img/visual_script54.png
  289. Switch
  290. ^^^^^^
  291. The Switch node is similar to the Condition node, but it matches many values at the same time.
  292. While
  293. ^^^^^
  294. This is a more primitive form of iteration. "repeat" sequence output will be called as long as
  295. the condition in the "cond" data port is met.
  296. Functions
  297. ~~~~~~~~~
  298. Functions are simple helpers, most of the time deterministic. They take some arguments as
  299. input and return an output. They are almost never sequenced.
  300. Built-In
  301. ^^^^^^^^
  302. There is a list of built in helpers. The list is almost identical to the one from GDScript (@TODO, link to gdscript methods?).
  303. Most of them are mathematical functions, but others can be very useful helpers. Just make sure to take a look at the list
  304. at some point.
  305. By Type
  306. ^^^^^^^
  307. 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.
  308. In most cases just search the list of nodes, it should be faster.
  309. Call
  310. ^^^^
  311. This is the generic calling node. It is rarely used directly but by dragging to empty space on an already configured node.
  312. Constructors
  313. ^^^^^^^^^^^^
  314. These are all the functions needed to create Godot basic datatypes. For example, If you need to create a Vector3 out of 3 floats, a constructor must be used.
  315. .. image:: img/visual_script44.png
  316. Destructor
  317. ^^^^^^^^^^
  318. This is the opposite to Constructor, it allows to separate any basic type (ie, Vector3) into its sub-elements.
  319. .. image:: img/visual_script45.png
  320. Emit Signal
  321. ^^^^^^^^^^^
  322. Emits signals from any object. In general it's not very useful, as dragging a signal to the canvas works better.
  323. Get/Set
  324. ^^^^^^^
  325. Generic Getter/Setter node. Dragging properties from the Inspector works better, as they appear properly configured on drop.
  326. Wait
  327. ^^^^
  328. The Wait nodes will suspend execution of the function until something happens (many frames can pass until resuming, in fact).
  329. Default nodes allow you to wait for a frame to pass, a fixed frame or a given amount of time until execution is resumed.
  330. Yield
  331. ^^^^^
  332. 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.
  333. Yield Signal
  334. ^^^^^^^^^^^^
  335. Same as Yield, but will wait until a given signal is emitted.
  336. Index
  337. ~~~~~
  338. Generic indexing operator, not often used but it's good that it exists just in case.
  339. Operators
  340. ~~~~~~~~~
  341. These are mostly generic operators such as addition, multiplication, comparison, etc.
  342. By default, these mostly accept any datatype (and will error in run-time if the types
  343. feeded do not match for the operator). It is always recommended to set the right
  344. type for operators to catch errors faster and make the graph easier to read.
  345. .. image:: img/visual_script46.png
  346. Expression Node
  347. ^^^^^^^^^^^^^^^
  348. Among the operators, the *Expression* node is the most powerful. If well used, it allows you to enormously simplify
  349. visual scripts that are math or logic heavy. Just type any expression on it and it will be executed in real-time.
  350. Expression nodes can:
  351. - Perform math and logic expressions based on custom inputs (eg: "a*5+b", where a and b are custom inputs):
  352. .. image:: img/visual_script47.png
  353. - Access local variables or properties:
  354. .. image:: img/visual_script48.png
  355. - Use most of the existing built-in functions that are available to GDScript, such as sin(),cos(),print(), as well as constructors, such as Vector3(x,y,z),Rect2(..), etc.:
  356. .. image:: img/visual_script49.png
  357. - Call API functions:
  358. .. image:: img/visual_script50.png
  359. - Use sequenced mode, which makes more sense in case of respecting the processing order:
  360. .. image:: img/visual_script51.png