Merge pull request #4247 from NathanLovato/gdscript-2.0

First pass on GDScript 2.0 docs

tutorials/scripting/gdscript/gdscript_exports.rst

@@ -9,14 +9,14 @@ 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`` keyword::
+Exporting is done by using the ``@export`` annotation::
 
     extends Button
 
-    export var number = 5 # Value will be saved and visible in the property editor.
+    @export var number = 5 # Value will be saved and visible in the property editor.
 
-An exported variable must be initialized to a constant expression or have an
-export hint in the form of an argument to the ``export`` keyword (see the
+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
 *Examples* section below).
 
 One of the fundamental benefits of exporting member variables is to have
@@ -24,6 +24,8 @@ 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#.
@@ -37,99 +39,102 @@ Examples
     # If the exported value assigns a constant or constant expression,
     # the type will be inferred and used in the editor.
 
-    export var number = 5
+    @export var number = 5
 
-    # Export can take a basic data type as an argument, which will be
-    # used in the editor.
+    # If there's no default value, you can add a type to the variable.
 
-    export(int) var number
+    @export var number: int
 
-    # Export can also take a resource type to use as a hint.
+    # Export works with resource types.
 
-    export(Texture) var character_face
-    export(PackedScene) var scene_file
+    @export var character_face: Texture
+    @export var scene_file: PackedScene
     # There are many resource types that can be used this way, try e.g.
     # the following to list them:
-    export(Resource) var resource
+    @export var resource: Resource
 
     # Integers and strings hint enumerated values.
 
     # Editor will enumerate as 0, 1 and 2.
-    export(int, "Warrior", "Magician", "Thief") var character_class
-    # Editor will enumerate with string names.
-    export(String, "Rebecca", "Mary", "Leah") var character_name
+    @export_enum("Warrior", "Magician", "Thief") var character_class
+    # If type is String, editor will enumerate with string names.
+    @export_enum("Rebecca", "Mary", "Leah") var character_name: String
 
     # Named enum values
 
     # Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
     enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
-    export(NamedEnum) var x
+    @export var x: NamedEnum
 
     # Strings as paths
 
     # String is a path to a file.
-    export(String, FILE) var f
+    @export_file var f
     # String is a path to a directory.
-    export(String, DIR) var f
+    @export_dir var f
     # String is a path to a file, custom filter provided as hint.
-    export(String, FILE, "*.txt") var f
+    @export_file("*.txt") var f
 
     # Using paths in the global filesystem is also possible,
-    # but only in scripts in "tool" mode.
+    # but only in scripts in tool mode.
 
     # String is a path to a PNG file in the global filesystem.
-    export(String, FILE, GLOBAL, "*.png") var tool_image
+    @export_global_file("*.png") var tool_image
     # String is a path to a directory in the global filesystem.
-    export(String, DIR, GLOBAL) var tool_dir
+    @export_global_dir var tool_dir
 
-    # The MULTILINE setting tells the editor to show a large input
+    # The multiline annotation tells the editor to show a large input
     # field for editing over multiple lines.
-    export(String, MULTILINE) var text
+    @export_multiline var text
 
     # Limiting editor input ranges
 
     # Allow integer values from 0 to 20.
-    export(int, 20) var i
+    @export_range(0, 20) var i
     # Allow integer values from -10 to 20.
-    export(int, -10, 20) var j
+    @export_range(-10, 20) var j
     # Allow floats from -10 to 20 and snap the value to multiples of 0.2.
-    export(float, -10, 20, 0.2) var k
+    @export_range(-10, 20, 0.2) var k: float
+    # The limits can be only for the slider if you add the hints "or_greater" and/or "or_lesser".
+    @export_range(0, 100, 1, "or_greater", "or_lesser")
     # Allow values 'y = exp(x)' where 'y' varies between 100 and 1000
     # while snapping to steps of 20. The editor will present a
     # slider for easily editing the value.
-    export(float, EXP, 100, 1000, 20) var l
+    @export_exp_range(100, 1000, 20) var l
 
     # Floats with easing hint
 
     # Display a visual representation of the 'ease()' function
     # when editing.
-    export(float, EASE) var transition_speed
+    @export_exp_easing var transition_speed
 
     # Colors
 
+    # Regular color given as red-green-blue-alpha value.
+    @export var col: Color
     # Color given as red-green-blue value (alpha will always be 1).
-    export(Color, RGB) var col
-    # Color given as red-green-blue-alpha value.
-    export(Color, RGBA) var col
+    @export_color_no_alpha var col: Color
 
     # Nodes
 
     # Another node in the scene can be exported as a NodePath.
-    export(NodePath) var node_path
+    @export var node_path: NodePath
     # Do take note that the node itself isn't being exported -
     # there is one more step to call the true node:
     var node = get_node(node_path)
+    # If you want to limit the types of nodes, you can use the @export_node_path annotation.
+    @export_node_path(Button, TouchScreenButton) var some_button
 
     # Resources
 
-    export(Resource) var resource
+    @export var resource: Resource
     # In the Inspector, you can then drag and drop a resource file
     # from the FileSystem dock into the variable slot.
 
     # Opening the inspector dropdown may result in an
     # extremely long list of possible classes to create, however.
     # Therefore, if you specify an extension of Resource such as:
-    export(AnimationNode) var resource
+    @export var resource: AnimationNode
     # The drop-down menu will be limited to AnimationNode and all
     # its inherited classes.
 
@@ -141,23 +146,23 @@ Exporting bit flags
 -------------------
 
 Integers used as bit flags can store multiple ``true``/``false`` (boolean)
-values in one property. By using the export hint ``int, FLAGS, ...``, they
+values in one property. By using the ``@export_flags`` annotation, they
 can be set from the editor::
 
     # Set any of the given flags from the editor.
-    export(int, FLAGS, "Fire", "Water", "Earth", "Wind") var spell_elements = 0
+    @export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0
 
 You must provide a string description for each flag. In this example, ``Fire``
 has value 1, ``Water`` has value 2, ``Earth`` has value 4 and ``Wind``
 corresponds to value 8. Usually, constants should be defined accordingly (e.g.
 ``const ELEMENT_WIND = 8`` and so on).
 
-Export hints are also provided for the physics and render layers defined in the project settings::
+Export annotations are also provided for the physics and render layers defined in the project settings::
 
-    export(int, LAYERS_2D_PHYSICS) var layers_2d_physics
-    export(int, LAYERS_2D_RENDER) var layers_2d_render
-    export(int, LAYERS_3D_PHYSICS) var layers_3d_physics
-    export(int, LAYERS_3D_RENDER) var layers_3d_render
+    @export_flags_2d_physics var layers_2d_physics
+    @export_flags_2d_render var layers_2d_render
+    @export_flags_3d_physics var layers_3d_physics
+    @export_flags_3d_render var layers_3d_render
 
 Using bit flags requires some understanding of bitwise operations.
 If in doubt, use boolean variables instead.
@@ -232,57 +237,3 @@ described in :ref:`doc_accessing_data_or_logic_from_object`.
 
 .. warning:: The script must operate in the ``tool`` mode so the above methods
              can work from within the editor.
-
-Adding script categories
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-For better visual distinguishing of properties, a special script category can be
-embedded into the inspector to act as a separator. ``Script Variables`` is one
-example of a built-in category.
-
-::
-
-    func _get_property_list():
-        var properties = []
-        properties.append(
-            {
-                name = "Debug",
-                type = TYPE_NIL,
-                usage = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SCRIPT_VARIABLE
-            }
-        )
-        return properties
-
-* ``name`` is the name of a category to be added to the inspector;
-
-* ``PROPERTY_USAGE_CATEGORY`` indicates that the property should be treated as a
-  script category specifically, so the type ``TYPE_NIL`` can be ignored as it
-  won't be actually used for the scripting logic, yet it must be defined anyway.
-
-Grouping properties
-~~~~~~~~~~~~~~~~~~~
-
-A list of properties with similar names can be grouped.
-
-::
-
-    func _get_property_list():
-        var properties = []
-        properties.append({
-                name = "Rotate",
-                type = TYPE_NIL,
-                hint_string = "rotate_",
-                usage = PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SCRIPT_VARIABLE
-        })
-        return properties
-
-* ``name`` is the name of a group which is going to be displayed as collapsible
-  list of properties;
-
-* every successive property added after the group property will be collapsed and
-  shortened as determined by the prefix defined via the ``hint_string`` key. For
-  instance, ``rotate_speed`` is going to be shortened to ``speed`` in this case.
-
-* ``PROPERTY_USAGE_GROUP`` indicates that the property should be treated as a
-  script group specifically, so the type ``TYPE_NIL`` can be ignored as it
-  won't be actually used for the scripting logic, yet it must be defined anyway.