Document node configuration warnings in Running code in the editor

tutorials/plugins/running_code_in_the_editor.rst

@@ -6,13 +6,22 @@ Running code in the editor
 What is ``tool``?
 -----------------
 
-``tool`` is a powerful line of code that, when added at the top of your script, makes it execute in the editor. You can also decide which parts of the script execute in the editor, which in game, and which in both.
-
-You can use it for doing many things, but it is mostly useful in level design for visually presenting things that are hard to predict ourselves. Here are some use cases:
-
-- If you have a cannon that shoots cannonballs affected by physics (gravity), you can draw the cannonball's trajectory in the editor, making level design a lot easier.
-- If you have jumppads with varying jump heights, you can draw the maximum jump height a player would reach if it jumped on one, also making level design easier.
-- If your player doesn't use a sprite, but draws itself using code, you can make that drawing code execute in the editor to see your player.
+``tool`` is a powerful line of code that, when added at the top of your script,
+makes it execute in the editor. You can also decide which parts of the script
+execute in the editor, which in game, and which in both.
+
+You can use it for doing many things, but it is mostly useful in level design
+for visually presenting things that are hard to predict ourselves. Here are some
+use cases:
+
+- If you have a cannon that shoots cannonballs affected by physics (gravity),
+  you can draw the cannonball's trajectory in the editor, making level design a
+  lot easier.
+- If you have jumppads with varying jump heights, you can draw the maximum jump
+  height a player would reach if it jumped on one, also making level design
+  easier.
+- If your player doesn't use a sprite, but draws itself using code, you can make
+  that drawing code execute in the editor to see your player.
 
 .. DANGER::
 
@@ -46,7 +55,8 @@ For example, if you want to execute some code only in the editor, use:
         // Code to execute when in editor.
     }
 
-On the other hand, if you want to execute code only in game, simply negate the same statement:
+On the other hand, if you want to execute code only in game, simply negate the
+same statement:
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -61,7 +71,8 @@ On the other hand, if you want to execute code only in game, simply negate the s
         // Code to execute when in game.
     }
 
-Pieces of code do not have either of the 2 conditions above will run both in-editor and in-game.
+Pieces of code do not have either of the 2 conditions above will run both
+in-editor and in-game.
 
 Here is how a ``_process()`` function might look for you:
 
@@ -94,12 +105,17 @@ Here is how a ``_process()`` function might look for you:
         // Code to execute both in editor and in game.
     }
 
-.. note:: Modifications in editor are permanent. For example, in the following case, when we remove the script, the node will keep its rotation. Be careful to avoid making unwanted modifications.
+.. note::
+
+    Modifications in the editor are permanent. For example, in the following
+    case, when we remove the script, the node will keep its rotation. Be careful
+    to avoid making unwanted modifications.
 
 Try it out
 -----------
 
-Add a ``Sprite`` node to your scene and set the texture to Godot icon. Attach and open a script, and change it to this:
+Add a ``Sprite`` node to your scene and set the texture to Godot icon. Attach
+and open a script, and change it to this:
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -124,13 +140,17 @@ Add a ``Sprite`` node to your scene and set the texture to Godot icon. Attach an
         }
     }
 
-Save the script and return to the editor. You should now see your object rotate. If you run the game, it will also rotate.
+Save the script and return to the editor. You should now see your object rotate.
+If you run the game, it will also rotate.
 
 .. image:: img/rotating_in_editor.gif
 
-.. note:: If you don't see the changes, reload the scene (close it and open it again).
+.. note::
 
-Now let's choose which code runs when. Modify your ``_process()`` function to look like this:
+    If you don't see the changes, reload the scene (close it and open it again).
+
+Now let's choose which code runs when. Modify your ``_process()`` function to
+look like this:
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -155,12 +175,15 @@ Now let's choose which code runs when. Modify your ``_process()`` function to lo
         }
     }
 
-Save the script. Now the object will spin clockwise in the editor, but if you run the game, it will spin counter-clockwise.
+Save the script. Now the object will spin clockwise in the editor, but if you
+run the game, it will spin counter-clockwise.
 
 Editing variables
 -----------------
-Add and export a variable speed to the script. The function set_speed after "setget" is executed with your input to change the variable.
-Modify  ``_process()`` to include the rotation speed.
+
+Add and export a variable speed to the script. The function set_speed after
+``setget`` is executed with your input to change the variable. Modify
+``_process()`` to include the rotation speed.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -210,12 +233,68 @@ Modify  ``_process()`` to include the rotation speed.
         }
     }
 
-.. note:: Code from other nodes doesn't run in the editor. Your access to other nodes is limited. You can access the tree and nodes, and their default properties, but you can't access user variables. If you want to do so, other nodes have to run in the editor too. AutoLoad nodes cannot be accessed in the editor at all.
+.. note::
+
+    Code from other nodes doesn't run in the editor. Your access to other nodes
+    is limited. You can access the tree and nodes, and their default properties,
+    but you can't access user variables. If you want to do so, other nodes have
+    to run in the editor too. AutoLoad nodes cannot be accessed in the editor at
+    all.
+
+Reporting node configuration warnings
+-------------------------------------
+
+Godot uses a *node configuration warning* system to warn users about incorrectly
+configured nodes. It's materialized by a yellow triangle with an exclamation
+mark next to the node name in the Scene tree dock. When the user hovers or
+clicks the triangle, they can see a warning message. You can use this feature in
+your scripts to help yourself (and your team) avoid mistakes when setting up
+scenes.
+
+When using node configuration warnings, make sure to call
+:ref:`class_Node_method_update_configuration_warning` when the value of any
+"dependencies" changes so the warning is updated. Otherwise, the user will have
+to close and reopen the scene for the warning to be updated.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    # Use setters to update the configuration warning automatically.
+    export var title = "" setget set_title
+    export var description = "" setget set_description
+
+
+    func set_title(p_title):
+        if p_title != title:
+            title = p_title
+            update_configuration_warning()
+
+
+    func set_description(p_description):
+        if p_description != description:
+            description = p_description
+            update_configuration_warning()
+
+
+    func _get_configuration_warning():
+        var warning = ""
+        if title == "":
+            warning += "Please set `title` to a non-empty value."
+        if description.size() >= 100:
+            # Add a blank line between each warning to distinguish them individually.
+            if warning != "":
+                warning += "\n"
+            warning += "`description` should be less than 100 characters long."
+
+        # Returning an empty string means "no warning".
+        return warning
 
 Instancing scenes
 -----------------
 
-You can instantiate packed scenes normally and add them to the scene currently opened in the editor. Be sure to set the scene root as the owner of all the nodes created this way or the nodes won't be visible in the editor.
+You can instantiate packed scenes normally and add them to the scene currently
+opened in the editor. Be sure to set the scene root as the owner of all the
+nodes created this way or the nodes won't be visible in the editor.
 
 If you are using ``tool``:
 
@@ -242,7 +321,8 @@ If you are using :ref:`EditorScript<class_EditorScript>`:
  .. code-tab:: gdscript GDScript
 
     func _run():
-        var parent = get_scene().find_node("Parent") # Parent could be any node in the scene
+        # `parent` could be any node in the scene.
+        var parent = get_scene().find_node("Parent")
         var node = Spatial.new()
         parent.add_child(node)
         node.set_owner(get_scene())
@@ -251,10 +331,16 @@ If you are using :ref:`EditorScript<class_EditorScript>`:
 
     public override void _Run()
     {
-        var parent = GetScene().FindNode("Parent"); // Parent could be any node in the scene
+        // `parent` could be any node in the scene.
+        var parent = GetScene().FindNode("Parent");
         var node = new Spatial();
         parent.AddChild(node);
         node.Owner = GetScene();
     }
 
-.. warning:: Using ``tool`` improperly can yield many errors. It is advised to first write the code how you want it, and only then add the ``tool`` keyword to the top. Also, make sure to separate code that runs in-editor from code that runs in-game. This way, you can find bugs more easily.
+.. warning::
+
+    Using ``tool`` improperly can yield many errors. It is advised to first
+    write the code how you want it, and only then add the ``tool`` keyword to
+    the top. Also, make sure to separate code that runs in-editor from code that
+    runs in-game. This way, you can find bugs more easily.