godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-05 22:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

update gdscript export docs

Browse Source
This commit is contained in:
Hana
2022-12-11 21:06:10 +01:00
parent d84c5ae6e0
commit 74804eb8e9
2 changed files with 94 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
tutorials/scripting/gdscript/gdscript_basics.rst
View File

@@ -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:
`@onready` annotation
~~~~~~~~~~~~~~~~~~~~~
+------------------------------+---------------------------------------------------------------------------------------------------+
| **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`` | |
+------------------------------+---------------------------------------------------------------------------------------------------+
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
~~~~~~~~~~~~~~

92
tutorials/scripting/gdscript/gdscript_exports.rst
View File

@@ -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.
::
@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:
Resources and nodes can be exported.
::
@export var resource: Resource
@export var node: Node
Integers and strings hint enumerated values.
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.
::
# Editor will enumerate as 0, 1 and 2.
@export_enum("Warrior", "Magician", "Thief") var character_class
@export_group("My Properties")
@export var number = 3
If type is String, editor will enumerate with string names.
The second argument of the annotation can be used to only group properties
with the specified prefix.
Groups cannot be nested, use :ref:`@export_subgroup <class_@GDScript_annotation_@export_subgroup>`
to create subgroups within a group.
::
@export_enum("Rebecca", "Mary", "Leah") var character_name: String
@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false
Named enum values
-----------------
Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
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.
::
enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum
@export_category("Main Category")
@export var number = 3
@export var string = ""
@export_category("Extra Category")
@export var flag = false
.. note::
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
----------------