From 88ec4c294bc1ce36bc65f0910ef7793f92871253 Mon Sep 17 00:00:00 2001 From: Danil Alexeev Date: Wed, 28 Feb 2024 18:29:27 +0300 Subject: [PATCH] GDScript: Document `@export_storage` annotation --- .../scripting/gdscript/gdscript_exports.rst | 24 ++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/tutorials/scripting/gdscript/gdscript_exports.rst b/tutorials/scripting/gdscript/gdscript_exports.rst index d920dfa2080..05ec50b40a2 100644 --- a/tutorials/scripting/gdscript/gdscript_exports.rst +++ b/tutorials/scripting/gdscript/gdscript_exports.rst @@ -368,6 +368,28 @@ Packed type arrays also work, but only initialized empty: @export var vector3s = PackedVector3Array() @export var strings = PackedStringArray() +``@export_storage`` +------------------- + +By default, exporting a property has two effects: + +1. makes the property stored in the scene/resource file (:ref:`PROPERTY_USAGE_STORAGE `); +2. adds a field to the Inspector (:ref:`PROPERTY_USAGE_EDITOR `). + +However, sometimes you may want to make a property serializable, but not display it +in the editor to prevent unintentional changes and cluttering the interface. + +To do this you can use :ref:`@export_storage `. +This can be useful for :ref:`@tool ` scripts. +Also the property value is copied when :ref:`Resource.duplicate() ` +or :ref:`Node.duplicate() ` is called, unlike non-exported variables. + +:: + + var a # Not stored in the file, not displayed in the editor. + @export_storage var b # Stored in the file, not displayed in the editor. + @export var c: int # Stored in the file, displayed in the editor. + Setting exported variables from a tool script --------------------------------------------- @@ -394,5 +416,5 @@ described in :ref:`doc_accessing_data_or_logic_from_object`. .. seealso:: For binding properties using the above methods in C++, see :ref:`doc_binding_properties_using_set_get_property_list`. -.. warning:: The script must operate in the ``tool`` mode so the above methods +.. warning:: The script must operate in the ``@tool`` mode so the above methods can work from within the editor.