Browse Source

Correct the description of "tree order" (#8294)

* Update scene_tree.rst

Correct the description of "tree order".

The discussion conflated _ready()'s unusual traversal order (post-order traversal) with the usual "tree order" (preorder traversal) for most operations.  It seemed to imply that _ready and most other notifications were received in identical orders.

---------

Co-authored-by: A Thousand Ships <[email protected]>
Co-authored-by: Hugo Locurcio <[email protected]>
Michael Gundlach 1 year ago
parent
commit
042c415e25
1 changed files with 23 additions and 15 deletions
  1. 23 15
      tutorials/scripting/scene_tree.rst

+ 23 - 15
tutorials/scripting/scene_tree.rst

@@ -106,18 +106,26 @@ Tree order
 ----------
 
 Most node operations in Godot, such as drawing 2D, processing, or getting
-notifications are done in tree order, or top to bottom. For example, the
-top node in a scene has its ``_ready()`` function called first, then the
-node below it has its function called, then the node below that and so
-on. However, children of a node will get called before their parent, also
-in top to bottom order. So the top child node of the top node will get its
-``_ready()`` function called first.
+notifications are done in *tree order*, or top to bottom as seen in the 
+editor (also known as pre-order traversal):
 
 .. image:: img/toptobottom.webp
 
-This can also be overridden using the ``process_priority`` node property.
-Nodes with a lower number are called first. For example, nodes with the
-priorities "0, 1, 2, 3" would be called in that order (from left to right).
+For example, the top node in a scene has its ``_process()`` function 
+called first, then the node below it has its ``_process()`` function called, 
+then the node below that and so on.
+
+An important exception is the ``_ready()`` function: each parent node has its
+``_ready()`` function called only after all its child nodes have their 
+``_ready()`` functions called, so that the parent knows its children are 
+completely ready to be accessed. This is also known as post-order traversal.
+In the above image, ``NameLabel`` would be notified first (but only after its
+children, if it had any!), followed by ``Name``, etc., and ``Panel`` would be
+notified last.
+
+The order of operations can also be overridden using the ``process_priority``
+node property. Nodes with a lower number are called first. For example, nodes
+with the priorities "0, 1, 2, 3" would be called in that order from left to right.
 
 "Becoming active" by entering the *Scene Tree*
 ----------------------------------------------
@@ -126,15 +134,15 @@ priorities "0, 1, 2, 3" would be called in that order (from left to right).
 #. The root node of that scene (only one root, remember?) is added as
    either a child of the "root" Viewport (from SceneTree), or to any
    of its descendants.
-#. Every node of the newly added scene, will receive the "enter_tree"
+#. Every node of the newly added scene will receive the "enter_tree"
    notification ( ``_enter_tree()`` callback in GDScript) in
-   top-to-bottom order.
-#. An extra notification, "ready" ( ``_ready()`` callback in GDScript)
-   is provided for convenience, when a node and all its children are
-   inside the active scene.
+   top-to-bottom order (pre-order traversal).
+#. Every node will receive the "ready" notification ( ``_ready()`` 
+   callback in GDScript) for convenience, once all its children have
+   received the "ready" notification (post-order traversal).
 #. When a scene (or part of it) is removed, they receive the "exit
    scene" notification ( ``_exit_tree()`` callback in GDScript) in
-   bottom-to-top order
+   bottom-to-top order (the exact reverse of top-to-bottom order).
 
 Changing current scene
 ----------------------