From 58647a8df77c95e3b232236c2bbca62497ee5a05 Mon Sep 17 00:00:00 2001 From: Michael Gundlach Date: Fri, 20 Oct 2023 13:25:38 -0400 Subject: [PATCH 1/4] 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. --- tutorials/scripting/scene_tree.rst | 38 ++++++++++++++++++------------ 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/tutorials/scripting/scene_tree.rst b/tutorials/scripting/scene_tree.rst index 6a30f0503b8..671e5e64646 100644 --- a/tutorials/scripting/scene_tree.rst +++ b/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. "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 ---------------------- From 43e3d56c7ad3c78ae0b30bfd4152d9315758a28c Mon Sep 17 00:00:00 2001 From: Michael Gundlach Date: Tue, 24 Oct 2023 11:07:31 -0400 Subject: [PATCH 2/4] Update tutorials/scripting/scene_tree.rst Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> --- tutorials/scripting/scene_tree.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/scripting/scene_tree.rst b/tutorials/scripting/scene_tree.rst index 671e5e64646..d1c6bd4b191 100644 --- a/tutorials/scripting/scene_tree.rst +++ b/tutorials/scripting/scene_tree.rst @@ -118,7 +118,7 @@ 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. +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. From 8ea2a1c727d708550b3d4baca6f62b93174d955c Mon Sep 17 00:00:00 2001 From: Michael Gundlach Date: Tue, 24 Oct 2023 11:07:38 -0400 Subject: [PATCH 3/4] Update tutorials/scripting/scene_tree.rst Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> --- tutorials/scripting/scene_tree.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/scripting/scene_tree.rst b/tutorials/scripting/scene_tree.rst index d1c6bd4b191..c2eb4d7c768 100644 --- a/tutorials/scripting/scene_tree.rst +++ b/tutorials/scripting/scene_tree.rst @@ -124,7 +124,7 @@ 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 +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. "Becoming active" by entering the *Scene Tree* From e48142e24c3dfbfdfb7679fb5e4b1eb073ec53bd Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Thu, 9 Nov 2023 12:15:58 +0100 Subject: [PATCH 4/4] Apply suggestions from code review --- tutorials/scripting/scene_tree.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/scripting/scene_tree.rst b/tutorials/scripting/scene_tree.rst index c2eb4d7c768..adeeb0d5e10 100644 --- a/tutorials/scripting/scene_tree.rst +++ b/tutorials/scripting/scene_tree.rst @@ -125,7 +125,7 @@ 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. +with the priorities "0, 1, 2, 3" would be called in that order from left to right. "Becoming active" by entering the *Scene Tree* ----------------------------------------------