mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-05 22:09:56 +03:00
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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user