diff --git a/tutorials/scripting/gdscript/gdscript_exports.rst b/tutorials/scripting/gdscript/gdscript_exports.rst index d36b8cfd4..297deb0ba 100644 --- a/tutorials/scripting/gdscript/gdscript_exports.rst +++ b/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 `) 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 `. + .. 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.