pausing_games.rst 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119
  1. .. _doc_pausing_games:
  2. Pausing games
  3. =============
  4. Pause?
  5. ------
  6. In most games it is desirable to, at some point, interrupt the
  7. game to do something else, such as taking a break or changing options.
  8. However this is not as simple as it seems. The game might be stopped,
  9. but it might be desirable that some menus and animations continue
  10. working.
  11. Implementing a fine-grained control for what can be paused (and what can
  12. not) is a lot of work, so a simple framework for pausing is provided in
  13. Godot.
  14. How pausing works
  15. -----------------
  16. To set pause mode, the pause state must be set. This is done by assigning
  17. "true" to the :ref:`SceneTree.paused <class_SceneTree_paused>` member
  18. variable:
  19. .. tabs::
  20. .. code-tab:: gdscript GDScript
  21. get_tree().paused = true
  22. .. code-tab:: csharp
  23. GetTree().Paused = true;
  24. Doing so will have the following behavior:
  25. - 2D and 3D physics will be stopped.
  26. - _process and _physics_process will not be called anymore in nodes.
  27. - _input and _input_event will not be called anymore either.
  28. This effectively stops the whole game. Calling this function from a
  29. script, by default, will result in an unrecoverable state (nothing will
  30. work anymore!).
  31. White-listing nodes
  32. -------------------
  33. Before enabling pause, make sure that nodes that must keep working
  34. during pause are white-listed. This is done by editing the "Pause Mode"
  35. property in a node:
  36. .. image:: img/pausemode.png
  37. By default all nodes have this property in the "Inherit" state. This
  38. means, that they will only process (or not) depending on what this same
  39. property is set on the parent node. If the parent is set to "Inherit" ,
  40. then the grandparent will be checked and so on. Ultimately, if a state
  41. can't be found in any of the grandparents, the pause state in SceneTree
  42. is used. This means that, by default, when the game is paused every node
  43. will be paused.
  44. So the three possible states for a node are:
  45. - **Inherit**: Process depending on the state of the parent,
  46. grandparent, etc. The first parent that has a non-Inherit state.
  47. - **Stop**: Stop the node no matter what (and children in Inherit
  48. mode). When paused this node will not process.
  49. - **Process**: Process the node no matter what (and children in Inherit
  50. mode). Paused or not this node will process.
  51. Example
  52. -------
  53. An example of this is creating a popup or panel with controls inside,
  54. and set its pause mode to "Process" then hide it:
  55. .. image:: img/pause_popup.png
  56. Just by setting the root of the pause popup to "Process", all children
  57. and grandchildren will inherit that state. This way, this branch of the
  58. scene tree will continue working when paused.
  59. Finally, make it so when a pause button is pressed (any button will do),
  60. enable the pause and show the pause screen.
  61. .. tabs::
  62. .. code-tab:: gdscript GDScript
  63. func _on_pause_button_pressed():
  64. get_tree().paused = true
  65. $pause_popup.show()
  66. .. code-tab:: csharp
  67. public void _on_pause_button_pressed()
  68. {
  69. GetTree().Paused = true;
  70. ((Control)GetNode("pause_popup")).Show();
  71. }
  72. To remove the pause, do the opposite when the pause screen is
  73. closed:
  74. .. tabs::
  75. .. code-tab:: gdscript GDScript
  76. func _on_pause_popup_close_pressed():
  77. $pause_popup.hide()
  78. get_tree().paused = false
  79. .. code-tab:: csharp
  80. public void _on_pause_popup_close_pressed()
  81. {
  82. ((Control)GetNode("pause_popup")).Hide();
  83. GetTree().Paused = false;
  84. }
  85. And that should be all!