Skip to content

Commit 3ad2eaa

Browse files
committed
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.
1 parent c5da624 commit 3ad2eaa

File tree

2 files changed

+28
-6
lines changed

2 files changed

+28
-6
lines changed

tutorials/plugins/running_code_in_the_editor.rst

+19-6
Original file line numberDiff line numberDiff line change
@@ -105,20 +105,33 @@ Here is how a ``_process()`` function might look for you:
105105
// Code to execute both in editor and in game.
106106
}
107107

108+
.. _doc_running_code_in_the_editor_important_information:
109+
108110
Important information
109111
---------------------
110112

111-
Any other GDScript that your tool script uses must *also* be a tool. Any
112-
GDScript without ``@tool`` used by the editor will act like an empty file!
113+
The general rule is that **any other GDScript that your tool script uses must
114+
*also* be a tool**. The editor is not able to construct instances from GDScript
115+
files without ``@tool``, which means you cannot call methods or reference member
116+
variables from them otherwise. However, since static methods, constants and
117+
enums can be used without creating an instance, it is possible to call them or
118+
reference them from a ``@tool`` script onto other non-tool scripts. One exception to
119+
this are :ref:`static variables <doc_gdscript_basics_static_variables>`.
120+
If you try to read a static variable's value in a script that does not have
121+
``@tool``, it will always return ``null`` but won't print a warning or error
122+
when doing so. This restriction does not apply to static methods, which can be
123+
called regardless of whether the target script is in tool mode.
113124

114125
Extending a ``@tool`` script does not automatically make the extending script
115126
a ``@tool``. Omitting ``@tool`` from the extending script will disable tool
116-
behavior from the super class. Therefore the extending script should also
127+
behavior from the super class. Therefore, the extending script should also
117128
specify the ``@tool`` annotation.
118129

119-
Modifications in the editor are permanent. For example, in the next
120-
section when we remove the script, the node will keep its rotation. Be careful
121-
to avoid making unwanted modifications.
130+
Modifications in the editor are permanent, with no undo/redo possible. For
131+
example, in the next section when we remove the script, the node will keep its
132+
rotation. Be careful to avoid making unwanted modifications. Consider setting up
133+
:ref:`version control <doc_version_control_systems>` to avoid losing work in
134+
case you make a mistake.
122135

123136
Try ``@tool`` out
124137
-----------------

tutorials/scripting/gdscript/gdscript_basics.rst

+9
Original file line numberDiff line numberDiff line change
@@ -1099,6 +1099,8 @@ Member variables are initialized in the following order:
10991099
To fix this, move the ``_data`` variable definition above the ``a`` definition
11001100
or remove the empty dictionary assignment (``= {}``).
11011101

1102+
.. _doc_gdscript_basics_static_variables:
1103+
11021104
Static variables
11031105
~~~~~~~~~~~~~~~~
11041106

@@ -1181,6 +1183,13 @@ A base class static variable can also be accessed via a child class::
11811183
B.x = 3
11821184
prints(A.x, B.x) # 3 3
11831185

1186+
.. note::
1187+
1188+
When referencing a static variable from a tool script, the other script
1189+
containing the static variable **must** also be a tool script.
1190+
See :ref:`Running code in the editor <running_code_in_the_editor_important_information>`
1191+
for details.
1192+
11841193
``@static_unload`` annotation
11851194
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
11861195

0 commit comments

Comments
 (0)