From 74804eb8e9e6383bbd40c52b64f99b33f7fd1593 Mon Sep 17 00:00:00 2001 From: Hana <48352564+Piralein@users.noreply.github.com> Date: Sun, 11 Dec 2022 21:06:10 +0100 Subject: [PATCH] update gdscript export docs --- .../scripting/gdscript/gdscript_basics.rst | 102 +++++------------- .../scripting/gdscript/gdscript_exports.rst | 92 +++++++++++----- 2 files changed, 94 insertions(+), 100 deletions(-) diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 264751a49..f09b7e22d 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/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 `. -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 ` +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 `. | -+------------------------------+---------------------------------------------------------------------------------------------------+ -| ``@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 ~~~~~~~~~~~~~~ diff --git a/tutorials/scripting/gdscript/gdscript_exports.rst b/tutorials/scripting/gdscript/gdscript_exports.rst index 840eaabb4..3eb1870d5 100644 --- a/tutorials/scripting/gdscript/gdscript_exports.rst +++ b/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 `) 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 `. - .. 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 ` +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 ` +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 ` +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 ` 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 ----------------