From ab7c43c899d26b18839a673461f015fb634b64af Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 22 Apr 2025 14:30:30 +0200 Subject: [PATCH] Clarify rules around which scripts require `@tool` in Running code in the editor - Mention that static methods work, but not static variables. - Emphasize the use of version control due to the lack of undo/redo. --- .../plugins/running_code_in_the_editor.rst | 25 ++++++++++++++----- .../scripting/gdscript/gdscript_basics.rst | 9 +++++++ 2 files changed, 28 insertions(+), 6 deletions(-) diff --git a/tutorials/plugins/running_code_in_the_editor.rst b/tutorials/plugins/running_code_in_the_editor.rst index e9b8825aa40..d52da181b09 100644 --- a/tutorials/plugins/running_code_in_the_editor.rst +++ b/tutorials/plugins/running_code_in_the_editor.rst @@ -105,20 +105,33 @@ Here is how a ``_process()`` function might look for you: // Code to execute both in editor and in game. } +.. _doc_running_code_in_the_editor_important_information: + Important information --------------------- -Any other GDScript that your tool script uses must *also* be a tool. Any -GDScript without ``@tool`` used by the editor will act like an empty file! +The general rule is that **any other GDScript that your tool script uses must +*also* be a tool**. The editor is not able to construct instances from GDScript +files without ``@tool``, which means you cannot call methods or reference member +variables from them otherwise. However, since static methods, constants and +enums can be used without creating an instance, it is possible to call them or +reference them from a ``@tool`` script onto other non-tool scripts. One exception to +this are :ref:`static variables `. +If you try to read a static variable's value in a script that does not have +``@tool``, it will always return ``null`` but won't print a warning or error +when doing so. This restriction does not apply to static methods, which can be +called regardless of whether the target script is in tool mode. Extending a ``@tool`` script does not automatically make the extending script a ``@tool``. Omitting ``@tool`` from the extending script will disable tool -behavior from the super class. Therefore the extending script should also +behavior from the super class. Therefore, the extending script should also specify the ``@tool`` annotation. -Modifications in the editor are permanent. For example, in the next -section when we remove the script, the node will keep its rotation. Be careful -to avoid making unwanted modifications. +Modifications in the editor are permanent, with no undo/redo possible. For +example, in the next section when we remove the script, the node will keep its +rotation. Be careful to avoid making unwanted modifications. Consider setting up +:ref:`version control ` to avoid losing work in +case you make a mistake. Try ``@tool`` out ----------------- diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 72ffc6ce91e..fcc9b85f9ee 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -1099,6 +1099,8 @@ Member variables are initialized in the following order: To fix this, move the ``_data`` variable definition above the ``a`` definition or remove the empty dictionary assignment (``= {}``). +.. _doc_gdscript_basics_static_variables: + Static variables ~~~~~~~~~~~~~~~~ @@ -1181,6 +1183,13 @@ A base class static variable can also be accessed via a child class:: B.x = 3 prints(A.x, B.x) # 3 3 +.. note:: + + When referencing a static variable from a tool script, the other script + containing the static variable **must** also be a tool script. + See :ref:`Running code in the editor ` + for details. + ``@static_unload`` annotation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~