signals.rst 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530
  1. .. Intention: give the user a first taste of signals. We should write more
  2. documentation in the scripting/ section.
  3. .. Note: GDScript snippets use one line return instead of two because they're
  4. really short.
  5. .. meta::
  6. :keywords: Signal
  7. .. _doc_signals:
  8. Using signals
  9. =============
  10. In this lesson, we will look at signals. They are messages that nodes emit when
  11. something specific happens to them, like a button being pressed. Other nodes can
  12. connect to that signal and call a function when the event occurs.
  13. Signals are a delegation mechanism built into Godot that allows one game object to
  14. react to a change in another without them referencing one another. Using signals
  15. limits `coupling
  16. <https://en.wikipedia.org/wiki/Coupling_(computer_programming)>`_ and keeps your
  17. code flexible.
  18. For example, you might have a life bar on the screen that represents the
  19. player’s health. When the player takes damage or uses a healing potion, you want
  20. the bar to reflect the change. To do so, in Godot, you would use signals.
  21. .. note:: As mentioned in the introduction, signals are Godot's version of the
  22. observer pattern. You can learn more about it here:
  23. https://gameprogrammingpatterns.com/observer.html
  24. We will now use a signal to make our Godot icon from the previous lesson
  25. (:ref:`doc_scripting_player_input`) move and stop by pressing a button.
  26. .. Example
  27. Scene setup
  28. -----------
  29. To add a button to our game, we will create a new "main" scene which will
  30. include both a button and the ``Sprite.tscn`` scene that we scripted in previous
  31. lessons.
  32. Create a new scene by going to the menu Scene -> New Scene.
  33. .. image:: img/signals_01_new_scene.png
  34. In the Scene dock, click the 2D Scene button. This will add a Node2D as our
  35. root.
  36. .. image:: img/signals_02_2d_scene.png
  37. In the FileSystem dock, click and drag the ``Sprite.tscn`` file you saved
  38. previously onto the Node2D to instantiate it.
  39. .. image:: img/signals_03_dragging_scene.png
  40. We want to add another node as a sibling of the Sprite. To do so, right-click on
  41. Node2D and select Add Child Node.
  42. .. image:: img/signals_04_add_child_node.png
  43. Search for the Button node type and add it.
  44. .. image:: img/signals_05_add_button.png
  45. The node is small by default. Click and drag on the bottom-right handle of the
  46. Button in the viewport to resize it.
  47. .. image:: img/signals_06_drag_button.png
  48. If you don't see the handles, ensure the select tool is active in the toolbar.
  49. .. image:: img/signals_07_select_tool.png
  50. Click and drag on the button itself to move it closer to the sprite.
  51. You can also write a label on the Button by editing its Text property in the
  52. Inspector. Enter "Toggle motion".
  53. .. image:: img/signals_08_toggle_motion_text.png
  54. Your scene tree and viewport should look like this.
  55. .. image:: img/signals_09_scene_setup.png
  56. Save your newly created scene. You can then run it with :kbd:`F6`.
  57. At the moment, the button will be visible, but nothing will happen if you
  58. press it.
  59. Connecting a signal in the editor
  60. ---------------------------------
  61. Here, we want to connect the Button's "pressed" signal to our Sprite, and we
  62. want to call a new function that will toggle its motion on and off. We need to
  63. have a script attached to the Sprite node, which we do from the previous lesson.
  64. You can connect signals in the Node dock. Select the Button node and, on the
  65. right side of the editor, click on the tab named "Node" next to the Inspector.
  66. .. image:: img/signals_10_node_dock.png
  67. The dock displays a list of signals available on the selected node.
  68. .. image:: img/signals_11_pressed_signals.png
  69. Double-click the "pressed" signal to open the node connection window.
  70. .. image:: img/signals_12_node_connection.png
  71. There, you can connect the signal to the Sprite node. The node needs a receiver
  72. method, a function that Godot will call when the Button emits the signal. The
  73. editor generates one for you. By convention, we name these callback methods
  74. "_on_NodeName_signal_name". Here, it'll be "_on_Button_pressed".
  75. .. note::
  76. When connecting signals via the editor's Node dock, you can use two
  77. modes. The simple one only allows you to connect to nodes that have a
  78. script attached to them and creates a new callback function on them.
  79. .. image:: img/signals_advanced_connection_window.png
  80. The advanced view lets you connect to any node and any built-in
  81. function, add arguments to the callback, and set options. You can
  82. toggle the mode in the window's bottom-right by clicking the Advanced
  83. button.
  84. Click the Connect button to complete the signal connection and jump to the
  85. Script workspace. You should see the new method with a connection icon in the
  86. left margin.
  87. .. image:: img/signals_13_signals_connection_icon.png
  88. If you click the icon, a window pops up and displays information about the
  89. connection. This feature is only available when connecting nodes in the editor.
  90. .. image:: img/signals_14_signals_connection_info.png
  91. Let's replace the line with the ``pass`` keyword with code that'll toggle the
  92. node's motion.
  93. Our Sprite moves thanks to code in the ``_process()`` function. Godot provides a
  94. method to toggle processing on and off: :ref:`Node.set_process()
  95. <class_Node_method_set_process>`. Another method of the Node class,
  96. ``is_processing()``, returns ``true`` if idle processing is active. We can use
  97. the ``not`` keyword to invert the value.
  98. .. tabs::
  99. .. code-tab:: gdscript GDScript
  100. func _on_Button_pressed():
  101. set_process(not is_processing())
  102. .. code-tab:: csharp C#
  103. private void OnButtonPressed()
  104. {
  105. SetProcess(!IsProcessing());
  106. }
  107. This function will toggle processing and, in turn, the icon's motion on and off
  108. upon pressing the button.
  109. Before trying the game, we need to simplify our ``_process()`` function to move
  110. the node automatically and not wait for user input. Replace it with the
  111. following code, which we saw two lessons ago:
  112. .. tabs::
  113. .. code-tab:: gdscript GDScript
  114. func _process(delta):
  115. rotation += angular_speed * delta
  116. var velocity = Vector2.UP.rotated(rotation) * speed
  117. position += velocity * delta
  118. .. code-tab:: csharp C#
  119. public override void _Process(float delta)
  120. {
  121. Rotation += _angularSpeed * delta;
  122. var velocity = Vector2.Up.Rotated(Rotation) * _speed;
  123. Position += velocity * delta;
  124. }
  125. Your complete ``Sprite.gd`` code should look like the following.
  126. .. tabs::
  127. .. code-tab:: gdscript GDScript
  128. extends Sprite
  129. var speed = 400
  130. var angular_speed = PI
  131. func _process(delta):
  132. rotation += angular_speed * delta
  133. var velocity = Vector2.UP.rotated(rotation) * speed
  134. position += velocity * delta
  135. func _on_Button_pressed():
  136. set_process(not is_processing())
  137. .. code-tab:: csharp C#
  138. using Godot;
  139. public partial class MySprite2D : Sprite2D
  140. {
  141. private float _speed = 400;
  142. private float _angularSpeed = Mathf.Pi;
  143. public override void _Process(float delta)
  144. {
  145. Rotation += _angularSpeed * (float)delta;
  146. var velocity = Vector2.Up.Rotated(Rotation) * _speed;
  147. Position += velocity * (float)delta;
  148. }
  149. private void OnButtonPressed()
  150. {
  151. SetProcess(!IsProcessing());
  152. }
  153. }
  154. Run the scene now and click the button to see the sprite start and stop.
  155. Connecting a signal via code
  156. ----------------------------
  157. You can connect signals via code instead of using the editor. This is necessary
  158. when you create nodes or instantiate scenes inside of a script.
  159. Let's use a different node here. Godot has a :ref:`Timer <class_Timer>` node
  160. that's useful to implement skill cooldown times, weapon reloading, and more.
  161. Head back to the 2D workspace. You can either click the "2D" text at the top of
  162. the window or press :kbd:`Ctrl + F1` (:kbd:`Alt + 1` on macOS).
  163. In the Scene dock, right-click on the Sprite node and add a new child node.
  164. Search for Timer and add the corresponding node. Your scene should now look like
  165. this.
  166. .. image:: img/signals_15_scene_tree.png
  167. With the Timer node selected, go to the Inspector and check the **Autostart**
  168. property.
  169. .. image:: img/signals_18_timer_autostart.png
  170. Click the script icon next to Sprite to jump back to the scripting workspace.
  171. .. image:: img/signals_16_click_script.png
  172. We need to do two operations to connect the nodes via code:
  173. 1. Get a reference to the Timer from the Sprite.
  174. 2. Call the Timer's ``connect()`` method.
  175. .. note:: To connect to a signal via code, you need to call the ``connect()``
  176. method of the node you want to listen to. In this case, we want to
  177. listen to the Timer's "timeout" signal.
  178. We want to connect the signal when the scene is instantiated, and we can do that
  179. using the :ref:`Node._ready() <class_Node_method__ready>` built-in function,
  180. which is called automatically by the engine when a node is fully instantiated.
  181. To get a reference to a node relative to the current one, we use the method
  182. :ref:`Node.get_node() <class_Node_method_get_node>`. We can store the reference
  183. in a variable.
  184. .. tabs::
  185. .. code-tab:: gdscript GDScript
  186. func _ready():
  187. var timer = get_node("Timer")
  188. .. code-tab:: csharp C#
  189. public override void _Ready()
  190. {
  191. var timer = GetNode<Timer>("Timer");
  192. }
  193. The function ``get_node()`` looks at the Sprite's children and gets nodes by
  194. their name. For example, if you renamed the Timer node to "BlinkingTimer" in the
  195. editor, you would have to change the call to ``get_node("BlinkingTimer")``.
  196. .. add seealso to a page that explains node features.
  197. We can now connect the Timer to the Sprite in the ``_ready()`` function.
  198. .. tabs::
  199. .. code-tab:: gdscript GDScript
  200. func _ready():
  201. var timer = get_node("Timer")
  202. timer.connect("timeout", self, "_on_Timer_timeout")
  203. .. code-tab:: csharp C#
  204. public override void _Ready()
  205. {
  206. var timer = GetNode<Timer>("Timer");
  207. timer.Connect("timeout", this, nameof(OnTimerTimeout));
  208. }
  209. The line reads like so: we connect the Timer's "timeout" signal to the node to
  210. which the script is attached (``self``). When the Timer emits "timeout", we want
  211. to call the function "_on_Timer_timeout", that we need to define. Let's add it
  212. at the bottom of our script and use it to toggle our sprite's visibility.
  213. .. tabs::
  214. .. code-tab:: gdscript GDScript
  215. func _on_Timer_timeout():
  216. visible = not visible
  217. .. code-tab:: csharp C#
  218. private void OnTimerTimeout()
  219. {
  220. Visible = !Visible;
  221. }
  222. The ``visible`` property is a boolean that controls the visibility of our node.
  223. The line ``visible = not visible`` toggles the value. If ``visible`` is
  224. ``true``, it becomes ``false``, and vice-versa.
  225. If you run the scene now, you will see that the sprite blinks on and off, at one
  226. second intervals.
  227. Complete script
  228. ---------------
  229. That's it for our little moving and blinking Godot icon demo!
  230. Here is the complete ``Sprite.gd`` file for reference.
  231. .. tabs::
  232. .. code-tab:: gdscript GDScript
  233. extends Sprite
  234. var speed = 400
  235. var angular_speed = PI
  236. func _ready():
  237. var timer = get_node("Timer")
  238. timer.connect("timeout", self, "_on_Timer_timeout")
  239. func _process(delta):
  240. rotation += angular_speed * delta
  241. var velocity = Vector2.UP.rotated(rotation) * speed
  242. position += velocity * delta
  243. func _on_Button_pressed():
  244. set_process(not is_processing())
  245. func _on_Timer_timeout():
  246. visible = not visible
  247. .. code-tab:: csharp C#
  248. using Godot;
  249. public partial class MySprite2D : Sprite2D
  250. {
  251. private float _speed = 400;
  252. private float _angularSpeed = Mathf.Pi;
  253. public override void _Ready()
  254. {
  255. var timer = GetNode<Timer>("Timer");
  256. timer.Connect("timeout", this, nameof(OnTimerTimeout));
  257. }
  258. public override void _Process(float delta)
  259. {
  260. Rotation += _angularSpeed * delta;
  261. var velocity = Vector2.Up.Rotated(Rotation) * _speed;
  262. Position += velocity * delta;
  263. }
  264. private void OnButtonPressed()
  265. {
  266. SetProcess(!IsProcessing());
  267. }
  268. private void OnTimerTimeout()
  269. {
  270. Visible = !Visible;
  271. }
  272. }
  273. Custom signals
  274. --------------
  275. .. note:: This section is a reference on how to define and use your own signals,
  276. and does not build upon the project created in previous lessons.
  277. You can define custom signals in a script. Say, for example, that you want to
  278. show a game over screen when the player's health reaches zero. To do so, you
  279. could define a signal named "died" or "health_depleted" when their health
  280. reaches 0.
  281. .. tabs::
  282. .. code-tab:: gdscript GDScript
  283. extends Node2D
  284. signal health_depleted
  285. var health = 10
  286. .. code-tab:: csharp C#
  287. using Godot;
  288. public partial class MyNode2D : Node2D
  289. {
  290. [Signal]
  291. public delegate void HealthDepleted();
  292. private int _health = 10;
  293. }
  294. .. note:: As signals represent events that just occurred, we generally use an
  295. action verb in the past tense in their names.
  296. Your signals work the same way as built-in ones: they appear in the Node tab and
  297. you can connect to them like any other.
  298. .. image:: img/signals_17_custom_signal.png
  299. To emit a signal in your scripts, call ``emit_signal()``.
  300. .. tabs::
  301. .. code-tab:: gdscript GDScript
  302. func take_damage(amount):
  303. health -= amount
  304. if health <= 0:
  305. emit_signal("health_depleted")
  306. .. code-tab:: csharp C#
  307. public void TakeDamage(int amount)
  308. {
  309. _health -= amount;
  310. if (_health <= 0)
  311. {
  312. EmitSignal(nameof(HealthDepleted));
  313. }
  314. }
  315. A signal can optionally declare one or more arguments. Specify the argument
  316. names between parentheses:
  317. .. tabs::
  318. .. code-tab:: gdscript GDScript
  319. extends Node
  320. signal health_changed(old_value, new_value)
  321. .. code-tab:: csharp C#
  322. using Godot;
  323. public partial class MyNode : Node
  324. {
  325. [Signal]
  326. public delegate void HealthChanged(int oldValue, int newValue);
  327. private int _health = 10;
  328. }
  329. .. note::
  330. The signal arguments show up in the editor's node dock, and Godot can use
  331. them to generate callback functions for you. However, you can still emit any
  332. number of arguments when you emit signals. So it's up to you to emit the
  333. correct values.
  334. To emit values along with the signal, add them as extra arguments to the
  335. ``emit_signal()`` function:
  336. .. tabs::
  337. .. code-tab:: gdscript GDScript
  338. func take_damage(amount):
  339. var old_health = health
  340. health -= amount
  341. emit_signal("health_changed", old_health, health)
  342. .. code-tab:: csharp C#
  343. public void TakeDamage(int amount)
  344. {
  345. int oldHealth = _health;
  346. _health -= amount;
  347. EmitSignal(nameof(HealthChanged), oldHealth, _health);
  348. }
  349. Summary
  350. -------
  351. Any node in Godot emits signals when something specific happens to them, like a
  352. button being pressed. Other nodes can connect to individual signals and react to
  353. selected events.
  354. Signals have many uses. With them, you can react to a node entering or exiting
  355. the game world, to a collision, to a character entering or leaving an area, to
  356. an element of the interface changing size, and much more.
  357. For example, an :ref:`Area2D <class_Area2D>` representing a coin emits a
  358. ``body_entered`` signal whenever the player's physics body enters its collision
  359. shape, allowing you to know when the player collected it.
  360. In the next section, :ref:`doc_your_first_2d_game`, you'll create a complete 2D
  361. game and put everything you learned so far into practice.