mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-03 05:48:42 +03:00
Update export docs to use annotations
This commit is contained in:
George Marques
committed by
Nathan Lovato
Nathan Lovato
parent
7f28694a94
commit
ec48a04a85
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user