scene_tree.rst 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
  1. .. _doc_scene_tree:
  2. Using SceneTree
  3. ===============
  4. Introduction
  5. ------------
  6. In previous tutorials, everything revolved around the concept of
  7. nodes. Scenes are collections of nodes. They become active once
  8. they enter the *scene tree*.
  9. MainLoop
  10. --------
  11. The way Godot works internally is as follows. There is the
  12. :ref:`OS <class_OS>` class,
  13. which is the only instance that runs at the beginning. Afterwards, all
  14. drivers, servers, scripting languages, scene system, etc are loaded.
  15. When initialization is complete, :ref:`OS <class_OS>` needs to be
  16. supplied a :ref:`MainLoop <class_MainLoop>`
  17. to run. Up to this point, all this is internals working (you can check
  18. main/main.cpp file in the source code if you are ever interested to
  19. see how this works internally).
  20. The user program, or game, starts in the MainLoop. This class has a few
  21. methods, for initialization, idle (frame-synchronized callback), fixed
  22. (physics-synchronized callback), and input. Again, this is low
  23. level and when making games in Godot, writing your own MainLoop seldom makes sense.
  24. SceneTree
  25. ---------
  26. One of the ways to explain how Godot works is that it's a high level
  27. game engine over a low level middleware.
  28. The scene system is the game engine, while the :ref:`OS <class_OS>`
  29. and servers are the low level API.
  30. The scene system provides its own main loop to OS,
  31. :ref:`SceneTree <class_SceneTree>`.
  32. This is automatically instanced and set when running a scene, no need
  33. to do any extra work.
  34. It's important to know that this class exists because it has a few
  35. important uses:
  36. - It contains the root :ref:`Viewport <class_Viewport>`, to which a
  37. scene is added as a child when it's first opened to become
  38. part of the *Scene Tree* (more on that next).
  39. - It contains information about the groups and has the means to call all
  40. nodes in a group or get a list of them.
  41. - It contains some global state functionality, such as setting pause
  42. mode or quitting the process.
  43. When a node is part of the Scene Tree, the
  44. :ref:`SceneTree <class_SceneTree>`
  45. singleton can be obtained by calling
  46. :ref:`Node.get_tree() <class_Node_method_get_tree>`.
  47. Root viewport
  48. -------------
  49. The root :ref:`Viewport <class_Viewport>`
  50. is always at the top of the scene. From a node, it can be obtained in
  51. two different ways:
  52. .. tabs::
  53. .. code-tab:: gdscript GDScript
  54. get_tree().root # Access via scene main loop.
  55. get_node("/root") # Access via absolute path.
  56. .. code-tab:: csharp
  57. GetTree().Root // Access via scene main loop.
  58. GetNode("/root"); // Access via absolute path.
  59. This node contains the main viewport. Anything that is a child of a
  60. :ref:`Viewport <class_Viewport>`
  61. is drawn inside of it by default, so it makes sense that the top of all
  62. nodes is always a node of this type otherwise nothing would be seen.
  63. While other viewports can be created in the scene (for split-screen
  64. effects and such), this one is the only one that is never created by the
  65. user. It's created automatically inside SceneTree.
  66. Scene tree
  67. ----------
  68. When a node is connected, directly or indirectly, to the root
  69. viewport, it becomes part of the *scene tree*.
  70. This means that as explained in previous tutorials, it will get the
  71. ``_enter_tree()`` and ``_ready()`` callbacks (as well as ``_exit_tree()``).
  72. .. image:: img/activescene.webp
  73. When nodes enter the *Scene Tree*, they become active. They get access
  74. to everything they need to process, get input, display 2D and 3D visuals,
  75. receive and send notifications, play sounds, etc. When they are removed from the
  76. *scene tree*, they lose these abilities.
  77. Tree order
  78. ----------
  79. Most node operations in Godot, such as drawing 2D, processing, or getting
  80. notifications are done in *tree order*, or top to bottom as seen in the
  81. editor (also known as pre-order traversal):
  82. .. image:: img/toptobottom.webp
  83. For example, the top node in a scene has its ``_process()`` function
  84. called first, then the node below it has its ``_process()`` function called,
  85. then the node below that and so on.
  86. An important exception is the ``_ready()`` function: each parent node has its
  87. ``_ready()`` function called only after all its child nodes have their
  88. ``_ready()`` functions called, so that the parent knows its children are
  89. completely ready to be accessed. This is also known as post-order traversal.
  90. In the above image, ``NameLabel`` would be notified first (but only after its
  91. children, if it had any!), followed by ``Name``, etc., and ``Panel`` would be
  92. notified last.
  93. The order of operations can also be overridden using the ``process_priority``
  94. node property. Nodes with a lower number are called first. For example, nodes
  95. with the priorities "0, 1, 2, 3" would be called in that order from left to right.
  96. "Becoming active" by entering the *Scene Tree*
  97. ----------------------------------------------
  98. #. A scene is loaded from disk or created by scripting.
  99. #. The root node of that scene (only one root, remember?) is added as
  100. either a child of the "root" Viewport (from SceneTree), or to any
  101. of its descendants.
  102. #. Every node of the newly added scene will receive the "enter_tree"
  103. notification ( ``_enter_tree()`` callback in GDScript) in
  104. top-to-bottom order (pre-order traversal).
  105. #. Every node will receive the "ready" notification ( ``_ready()``
  106. callback in GDScript) for convenience, once all its children have
  107. received the "ready" notification (post-order traversal).
  108. #. When a scene (or part of it) is removed, they receive the "exit
  109. scene" notification ( ``_exit_tree()`` callback in GDScript) in
  110. bottom-to-top order (the exact reverse of top-to-bottom order).
  111. Changing current scene
  112. ----------------------
  113. After a scene is loaded, you may want to change this scene for
  114. another one. One way to do this is to use the
  115. :ref:`SceneTree.change_scene_to_file() <class_SceneTree_method_change_scene_to_file>`
  116. function:
  117. .. tabs::
  118. .. code-tab:: gdscript GDScript
  119. func _my_level_was_completed():
  120. get_tree().change_scene_to_file("res://levels/level2.tscn")
  121. .. code-tab:: csharp
  122. public void _MyLevelWasCompleted()
  123. {
  124. GetTree().ChangeSceneToFile("res://levels/level2.tscn");
  125. }
  126. Rather than using file paths, one can also use ready-made
  127. :ref:`PackedScene <class_PackedScene>` resources using the equivalent
  128. function
  129. :ref:`SceneTree.change_scene_to_packed(PackedScene scene) <class_SceneTree_method_change_scene_to_packed>`:
  130. .. tabs::
  131. .. code-tab:: gdscript GDScript
  132. var next_scene = preload("res://levels/level2.tscn")
  133. func _my_level_was_completed():
  134. get_tree().change_scene_to_packed(next_scene)
  135. .. code-tab:: csharp
  136. public void _MyLevelWasCompleted()
  137. {
  138. var nextScene = (PackedScene)ResourceLoader.Load("res://levels/level2.tscn");
  139. GetTree().ChangeSceneToPacked(nextScene);
  140. }
  141. These are quick and useful ways to switch scenes but have the drawback
  142. that the game will stall until the new scene is loaded and running. At
  143. some point in the development of your game, it may be preferable to create proper loading
  144. screens with progress bar, animated indicators or threaded (background)
  145. loading. This must be done manually using :ref:`doc_singletons_autoload`
  146. and :ref:`doc_background_loading`.