Skip to content

Clarify rules around which scripts require @tool in Running code in the editor #10888

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions tutorials/plugins/running_code_in_the_editor.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is onto instead of on here what is commonly used in the docs?

this are :ref:`static variables <doc_gdscript_basics_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 <doc_version_control_systems>` to avoid losing work in
case you make a mistake.

Try ``@tool`` out
-----------------
Expand Down
9 changes: 9 additions & 0 deletions tutorials/scripting/gdscript/gdscript_basics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -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 <doc_running_code_in_the_editor_important_information>`
for details.

``@static_unload`` annotation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
Loading