Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions tutorials/scripting/gdscript/gdscript_exports.rst
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,18 @@ to create subgroups within a group.
@export var string = ""
@export var flag = false

Both groups and subgroups can optionally specify a property prefix, which will hide it from the property names. This is useful to shorten long property names:

::

@export_group("Group", "group_")
# Will appear as "Example Number" in the inspector instead of "Group Example Number".
@export var group_example_number = 3

@export_subgroup("Subgroup", "group_subgroup_")
# Will appear as "Example String" in the inspector instead of "Group Subgroup Example String".
@export var group_subgroup_example_string = ""

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.
Expand All @@ -96,12 +108,47 @@ annotation.
@export_category("Extra Category")
@export var flag = false

If you have a boolean property that toggles a behavior, you can move its
checkbox from the list of properties to the group heading as follows:

::

@export_group("Group", "group_")
@export_custom(PROPERTY_HINT_GROUP_ENABLE, "") var group_enabled = false
@export var group_example_string = ""
Comment thread
Calinou marked this conversation as resolved.

When the group is enabled, its properties are shown:

.. figure:: img/gdscript_exports_group_enable.webp
:alt: Group enabled (with checkbox in the group heading).

Group enabled (with checkbox in the group heading).

Properties are automatically hidden when the group is disabled. Their value is
still saved and can be modified from code, but they won't be visible in the
inspector until the group is enabled again.

.. 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.

The engine applies several conventions to its own property names.
While not strictly required, consider following this style for consistency:

- Properties that are part of groups all start with the same prefix (``group_*``).
- Properties that are part of subgroups all start with the same prefix,
which is an extension of the parent group prefix (``group_subgroup_*``).
- Properties that toggle a group are booleans whose name ends with ``_enabled``.

For example, :ref:`class_BaseMaterial3D` has ``refraction_enabled``,
``refraction_scale``, and ``refraction_texture`` properties, all part of the
``Refraction`` group (using ``refraction_`` as a prefix). The
``refraction_enabled`` boolean property makes use of the
``PROPERTY_HINT_GROUP_ENABLE`` hint to move its checkbox to the group
heading.

Strings as paths
----------------

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading