Merge pull request #6481 from Piralein/gd-export

Update GDScript Export Docs

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -322,9 +322,10 @@ Annotations
 
 There are some special tokens in GDScript that act like keywords but are not,
 they are *annotations* instead. Every annotation start with the ``@`` character
-and is specified by a name.
+and is specified by a name. A detailed description and example for each annotation
+can be found inside the :ref:`GDScript class reference <class_@GDScript>`.
 
-Those affect how the script is treated by external tools and usually don't
+Annotations affect how the script is treated by external tools and usually don't
 change the behavior.
 
 For instance, you can use it to export a value to the editor::
@@ -332,6 +333,9 @@ For instance, you can use it to export a value to the editor::
     @export_range(1, 100, 1, "or_greater")
     var ranged_var: int = 50
 
+For more information about exporting properties, read the :ref:`GDScript exports <doc_gdscript_exports>`
+article.
+
 Annotations can be specified one per line or all in the same line. They affect
 the next statement that isn't an annotation. Annotations can have arguments sent
 between parentheses and separated by commas.
@@ -344,55 +348,30 @@ Both of these are the same::
 
     @onready @export_node_path(TextEdit, LineEdit) var input_field
 
+.. _doc_gdscript_onready_annotation:
 
-Here's the list of available annotations:
-
-+------------------------------+---------------------------------------------------------------------------------------------------+
-| **Annotation**               | **Description**                                                                                   |
-+------------------------------+---------------------------------------------------------------------------------------------------+
-| ``@tool``                    | Enable the `Tool mode`_.                                                                          |
-+------------------------------+---------------------------------------------------------------------------------------------------+
-| ``@onready``                 | Defer initialization of variable until the node is in the tree. See                               |
-|                              | :ref:`doc_gdscript_onready_annotation`.                                                           |
-+------------------------------+---------------------------------------------------------------------------------------------------+
-| ``@icon(path)``              | Set the class icon to show in editor. To be used together with the ``class_name`` keyword.        |
-+------------------------------+---------------------------------------------------------------------------------------------------+
-| ``@rpc``                     | RPC modifiers. See :ref:`high-level multiplayer docs <doc_high_level_multiplayer>`.               |
-+------------------------------+---------------------------------------------------------------------------------------------------+
-| ``@export``                  | Export hints for the editor. See :ref:`doc_gdscript_exports`.                                     |
-|                              |                                                                                                   |
-| ``@export_enum``             |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_file``             |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_dir``              |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_global_file``      |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_global_dir``       |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_multiline``        |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_placeholder``      |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_range``            |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_exp_easing``       |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_color_no_alpha``   |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_node_path``        |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_flags``            |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_flags_2d_render``  |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_flags_2d_physics`` |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_flags_3d_render``  |                                                                                                   |
-|                              |                                                                                                   |
-| ``@export_flags_3d_physics`` |                                                                                                   |
-+------------------------------+---------------------------------------------------------------------------------------------------+
+`@onready` annotation
+~~~~~~~~~~~~~~~~~~~~~
+
+When using nodes, it's common to desire to keep references to parts
+of the scene in a variable. As scenes are only warranted to be
+configured when entering the active scene tree, the sub-nodes can only
+be obtained when a call to ``Node._ready()`` is made.
+
+::
+
+    var my_label
+
+
+    func _ready():
+        my_label = get_node("MyLabel")
+
+This can get a little cumbersome, especially when nodes and external
+references pile up. For this, GDScript has the ``@onready`` annotation, that
+defers initialization of a member variable until ``_ready()`` is called. It
+can replace the above code with a single line::
+
+    @onready var my_label = get_node("MyLabel")
 
 Comments
 ~~~~~~~~
@@ -1875,31 +1854,6 @@ This also means that returning a signal from a function that isn't a coroutine w
           With this type safety in place, a function cannot say that it returns an ``int`` while it actually returns a function state object
           during runtime.
 
-.. _doc_gdscript_onready_annotation:
-
-`@onready` annotation
-~~~~~~~~~~~~~~~~~~~~~
-
-When using nodes, it's common to desire to keep references to parts
-of the scene in a variable. As scenes are only warranted to be
-configured when entering the active scene tree, the sub-nodes can only
-be obtained when a call to ``Node._ready()`` is made.
-
-::
-
-    var my_label
-
-
-    func _ready():
-        my_label = get_node("MyLabel")
-
-This can get a little cumbersome, especially when nodes and external
-references pile up. For this, GDScript has the ``@onready`` annotation, that
-defers initialization of a member variable until ``_ready()`` is called. It
-can replace the above code with a single line::
-
-    @onready var my_label = get_node("MyLabel")
-
 Assert keyword
 ~~~~~~~~~~~~~~
 

tutorials/scripting/gdscript/gdscript_exports.rst

@@ -9,13 +9,13 @@ Introduction to exports
 In Godot, class members can be exported. This means their value gets saved along
 with the resource (such as the :ref:`scene <class_PackedScene>`) they're
 attached to. They will also be available for editing in the property editor.
-Exporting is done by using the ``@export`` annotation::
+Exporting is done by using the ``@export`` annotation.
 
-    extends Button
+::
 
-    @export var number = 5
+    @export var number: int = 5
 
-In that example the value `5` will be saved and visible in the property editor.
+In that example the value ``5`` will be saved and visible in the property editor.
 
 An exported variable must be initialized to a constant expression or have a type specifier
 in the variable. Some of the export annotations have a specific type and don't need the variable to be typed (see the
@@ -26,8 +26,6 @@ them visible and editable in the editor. This way, artists and game designers
 can modify values that later influence how the program runs. For this, a
 special export syntax is provided.
 
-Exporting can only be done with built-in types or objects derived from the :ref:`Resource class <class_Resource>`.
-
 .. note::
 
     Exporting properties can also be done in other languages such as C#.
@@ -50,42 +48,56 @@ If there's no default value, you can add a type to the variable.
 
     @export var number: int
 
-Export works with resource types.
+Resources and nodes can be exported.
 
 ::
 
-    @export var character_face: Texture
-    @export var scene_file: PackedScene
+    @export var resource: Resource
+    @export var node: Node
 
-There are many resource types that can be used this way, try e.g.
-the following to list them:
+Grouping Exports
+----------------
+
+It is possible to group your exported properties inside the Inspector
+with the :ref:`@export_group <class_@GDScript_annotation_@export_group>`
+annotation. Every exported property after this annotation will be added to
+the group. Start a new group or use ``@export_group("")`` to break out.
 
 ::
 
-    @export var resource: Resource
+    @export_group("My Properties")
+    @export var number = 3
+
+The second argument of the annotation can be used to only group properties
+with the specified prefix.
 
-Integers and strings hint enumerated values.
+Groups cannot be nested, use :ref:`@export_subgroup <class_@GDScript_annotation_@export_subgroup>`
+to create subgroups within a group.
 
 ::
 
-    # Editor will enumerate as 0, 1 and 2.
-    @export_enum("Warrior", "Magician", "Thief") var character_class
+    @export_subgroup("Extra Properties")
+    @export var string = ""
+    @export var flag = false
 
-If type is String, editor will enumerate with string names.
+You can also change the name of your main category, or create additional
+categories in the property list with the :ref:`@export_category <class_@GDScript_annotation_@export_category>`
+annotation.
 
 ::
 
-    @export_enum("Rebecca", "Mary", "Leah") var character_name: String
-
-Named enum values
------------------
-
-Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
+    @export_category("Main Category")
+    @export var number = 3
+    @export var string = ""
+    
+    @export_category("Extra Category")
+    @export var flag = false
 
-::
+.. note::
 
-    enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
-    @export var x: NamedEnum
+    The list of properties is organized based on the class inheritance and
+    new categories break that expectation. Use them carefully, especially
+    when creating projects for public use.
 
 Strings as paths
 ----------------
@@ -266,6 +278,34 @@ Export annotations are also provided for the physics, render, and navigation lay
 Using bit flags requires some understanding of bitwise operations.
 If in doubt, use boolean variables instead.
 
+Exporting enums
+---------------
+
+Properties can be exported with a type hint referencing an enum to limit their values
+to the values of the enumeration. The editor will create a widget in the Inspector, enumerating
+the following as THING_1, THING_2, ANOTHER_THING. The value will be stored as an integer.
+
+::
+
+    enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
+    @export var x: NamedEnum
+
+Integer and string properties can also be limited to a specific list of values using
+the :ref:`@export_enum <class_@GDScript_annotation_@export_enum>` annotation.
+The editor will create a widget in the Inspector, enumerating the following as Warrior,
+Magician, Thief. The value will be stored as an integer, corresponding to the index
+of the selected option (i.e. ``0``, ``1``,  or ``2``).
+
+::
+
+    @export_enum("Warrior", "Magician", "Thief") var character_class
+
+If the type is String, the value will be stored as a string.
+
+::
+
+    @export_enum("Rebecca", "Mary", "Leah") var character_name: String
+
 Exporting arrays
 ----------------