Better explain advanced exports, script categories and groups (#5622)

* Make better explanation of advanced exports

Make better explanation of advanced GDScript exports because It was hard for me the first time I tried to do it it.

* Apply suggestions from code review

Co-authored-by: Hugo Locurcio <hugo.locurcio@hugo.pro>
Co-authored-by: Max Hilbrunner <mhilbrunner@users.noreply.github.com>
This commit is contained in:
Dan-Gamin
2022-04-07 19:26:44 +03:00
committed by Hugo Locurcio
parent 086abfd939
commit 3213cf7e88

View File

@@ -236,28 +236,86 @@ 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.
Properties
~~~~~~~~~~
To understand how to better use the sections below, you should understand
how to make properties with advanced exports.
::
func _get_property_list():
var properties = []
# Same as "export(int) var my_property"
properties.append({
name = "my_property",
type = TYPE_INT
})
return properties
* The ``_get_property_list()`` function gets called by the inspector. You
can override it for more advanced exports. You must return an ``Array``
with the contents of the properties for the function to work.
* ``name`` is the name of the property
* ``type`` is the type of the property from ``Variant.Type``.
.. note:: The ``float`` type is called a real (``TYPE_REAL``) in the ``Variant.Type`` enum.
Attaching variables to properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To attach variables to properties (allowing the value of the property to be used
in scripts), you need to create a variable with the exact same name as the
property or else you may need to override the
:ref:`_set() <class_Object_method__get_property_list>` and
:ref:`_get() <class_Object_method__get_property_list>` methods. Attaching
a variable to to a property also gives you the ability to give it a default state.
::
# This variable is determined by the function below.
# This variable acts just like a regular gdscript export.
var my_property = 5
func _get_property_list():
var properties = []
# Same as "export(int) var my_property"
properties.append({
name = "my_property",
type = TYPE_INT
})
return properties
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
}
)
properties.append({
name = "Debug",
type = TYPE_NIL,
usage = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SCRIPT_VARIABLE
})
# Example of adding a property to the script category
properties.append({
name = "Logging_Enabled",
type = TYPE_BOOL
})
return properties
* ``name`` is the name of a category to be added to the inspector;
* Every following property added after the category definition will be a part
of the category.
* ``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.
@@ -266,25 +324,39 @@ 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
name = "Rotate",
type = TYPE_NIL,
hint_string = "rotate_",
usage = PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SCRIPT_VARIABLE
})
# Example of adding to the group
properties.append({
name = "rotate_speed",
type = TYPE_REAL
})
# This property won't get added to the group
# due to not having the "rotate_" prefix.
properties.append({
name = "trail_color",
type = TYPE_COLOR
})
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.
* Every following property added after the group property with the prefix
(which determined by ``hint_string``) will be shortened. For instance,
``rotate_speed`` is going to be shortened to ``speed`` in this case.
However, ``movement_speed`` won't be a part of the group and will not
be shortened.
* ``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