Экспортируемые свойства GDScript

В Godot члены класса можно экспортировать. Это означает, что их значения сохраняются вместе с ресурсом (например, scene), к которому они прикреплены, и передаются при использовании RPCs. Они также будут доступны для редактирования в редакторе свойств. Экспорт осуществляется с помощью аннотации @export.

@export var number: int = 5

В этом примере значение 5 будет сохранено и будет видно в редакторе свойств.

Экспортируемая переменная должна быть инициализирована константным выражением или иметь спецификатор типа. Некоторые аннотации экспорта имеют определённый тип и не требуют типизации переменной (см. раздел Примеры ниже).

Одним из фундаментальных преимуществ экспорта переменных (членов класса) является то, что они видны и редактируются в редакторе. Таким образом, художники и гейм-дизайнеры могут изменять значения, которые впоследствии будут влиять на работу программы. Для этого предусмотрен специальный синтаксис экспорта.

Примечание

Экспорт свойств также возможен в других языках, например, C#. Синтаксис различается в зависимости от языка. Подробнее об экспорте в C# см. в документе Экспортированные свойства C#.

Основное применение

Если экспортируемое значение присваивает константу или константное выражение, тип будет выведен и использован в редакторе.

@export var number = 5

Если значения по умолчанию нет, вы можете добавить тип к переменной.

@export var number: int

Можно экспортировать ресурсы и узлы .

@export var resource: Resource
@export var node: Node

Даже если скрипт не выполняется в редакторе, экспортированные свойства всё равно можно редактировать. Однако геттеры и сеттеры будут использоваться только в том случае, если скрипт находится в режиме Режим Инструмента.

Группировка экспорта

Экспортированные свойства можно сгруппировать в Инспекторе с помощью аннотации @export_group. Каждое экспортированное свойство после этой аннотации будет добавлено в группу. Создайте новую группу или используйте @export_group("") для разбиения.

@export_group("My Properties")
@export var number = 3

Второй аргумент аннотации можно использовать только для группировки свойств с указанным префиксом.

Группы не могут быть вложенными, используйте @export_subgroup для создания подгрупп внутри группы.

@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false

Вы также можете изменить название основной категории или создать дополнительные категории в списке свойств с помощью аннотации @export_category.

@export_category("Main Category")
@export var number = 3
@export var string = ""

@export_category("Extra Category")
@export var flag = false

Примечание

Список свойств организован на основе наследования классов, и новые категории нарушают это ожидание. Используйте их с осторожностью, особенно при создании проектов для публичного использования.

Строки как пути

Строка как путь к файлу. См. @export_file.

@export_file var f

Строка как путь к каталогу. См. @export_dir.

@export_dir var f

Строка как путь к файлу, пользовательский фильтр предоставлен в качестве подсказки. См. также: @export_file.

@export_file("*.txt") var f

Использование путей в глобальной файловой системе также возможно, но только в скриптах в режиме инструмента.

Строка, указывающая путь к PNG-файлу в глобальной файловой системе. См. @export_global_file.

@export_global_file("*.png") var tool_image

Строка, указывающая путь к каталогу в глобальной файловой системе. См. @export_global_dir.

@export_global_dir var tool_dir

Многострочная аннотация указывает редактору на необходимость отображения большого поля ввода для редактирования нескольких строк. См. @export_multiline.

@export_multiline var text

Ограничение диапазонов ввода редактора

Смотрите все нижеперечисленное @export_range.

Допустимы целые значения от 0 до 20.

@export_range(0, 20) var i

Допустимы целые значения от -10 до 20.

@export_range(-10, 20) var j

Разрешить значения с плавающей точкой от -10 до 20 и привязать их к значениям, кратным 0,2.

@export_range(-10, 20, 0.2) var k: float

Ограничения можно задать так, чтобы они влияли только на ползунок, добавив подсказки "or_less" и/или "or_greater". При использовании любой из этих подсказок пользователь сможет ввести любое значение или перетащить его мышью, не используя ползунок, даже если значение выходит за пределы указанного диапазона.

@export_range(0, 100, 1, "or_less", "or_greater") var l: int

Подсказку "exp" можно использовать для того, чтобы значение отображалось с помощью экспоненциального ползунка вместо линейного. Это означает, что при перемещении ползунка вправо изменения будут происходить всё быстрее при перемещении мыши. Это полезно для упрощения редактирования значений, которые могут быть как очень маленькими, так и очень большими, но при этом менее интуитивно понятным.

@export_range(0, 100000, 0.01, "exp") var exponential: float

Для значений, которые должны представлять коэффициент замедления, вместо этого используйте Поплавки с подсказкой о смягчении.

Подсказку "hide_slider" можно использовать, чтобы скрыть горизонтальную полосу, которая отображается под свойствами float, или стрелки вверх/вниз, которые отображаются рядом со свойствами int:

@export_range(0, 1000, 0.01, "hide_slider") var no_slider: float

Добавление суффиксов и работа с градусами/радианами

Также можно определить суффикс, чтобы сделать значение более понятным в инспекторе. Например, чтобы определить значение, которое пользователь должен настроить как «метры» (m):

@export_range(0, 100, 1, "suffix:m") var m: int

Для углов, которые хранятся в радианах, но отображаются для пользователя в градусах, используйте подсказку "radians_as_degrees":

@export_range(0, 360, 0.1, "radians_as_degrees") var angle: float

Это автоматически преобразует значение при отображении или изменении в инспекторе, а также добавляет суффикс градуса (°). Этот подход используется в свойствах Godot rotation во всем редакторе.

Если угол хранится в градусах, используйте подсказку "degrees" для отображения символа градуса и отключения автоматического преобразования градусов в радианы при изменении значения в инспекторе.

Поплавки с подсказкой о смягчении

Отображает визуальное представление функции ease() при редактировании. См. @export_exp_easing.

@export_exp_easing var transition_speed

Цвета

Обычный цвет задается как значение красный-зеленый-синий-альфа.

@export var col: Color

Цвет задаётся как значение "красный-зелёный-синий" (альфа всегда будет равна 1). См. @export_color_no_alpha.

@export_color_no_alpha var col: Color

Узлы

Начиная с Godot 4.0 узлы можно напрямую экспортировать как свойства в скрипте без необходимости использования NodePaths:

# Allows any node.
@export var node: Node

# Allows any node that inherits from BaseButton.
# Custom classes declared with `class_name` can also be used.
@export var some_button: BaseButton

Экспорт NodePaths, как в Godot 3.x, по-прежнему возможен, если он вам нужен:

@export var node_path: NodePath
var node = get_node(node_path)

Если вы хотите ограничить типы узлов для NodePaths, вы можете использовать аннотацию @export_node_path:

@export_node_path("Button", "TouchScreenButton") var some_button

Ресурсы

@export var resource: Resource

Затем в Инспекторе можно перетащить файл ресурса из дока FileSystem в слот переменной.

Однако при открытии раскрывающегося списка Инспектора может появиться очень длинный список возможных классов для создания. Поэтому, если указать расширение Resource, например:

@export var resource: AnimationNode

Раскрывающееся меню будет ограничено AnimationNode и всеми его производными классами.

Экспорт битовых флагов

См. @export_flags.

Целые числа, используемые в качестве битовых флагов, могут хранить несколько логических значений true/false в одном свойстве. С помощью аннотации @export_flags их можно задать из редактора:

# Set any of the given flags from the editor.
@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0

Вы должны предоставить строчное описание каждому флагу. В этом примере у Fire значение 1, у Water - 2, у Earth - 4 и у Wind - 8. Обычно константы должны быть определены соответствующим образом (например, const ELEMENT_WIND = 8 и так далее).

Вы можете добавить явные значения, используя двоеточие:

@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0

В качестве битовых флагов допустимы только значения, являющиеся степенью двойки. Минимальное допустимое значение — 1, поскольку 0 означает, что ничего не выбрано. Вы также можете добавлять параметры, представляющие собой комбинацию других флагов:

@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0

Экспортные аннотации также предоставляются для слоев физики, рендеринга и навигации, определенных в настройках проекта:

@export_flags_2d_physics var layers_2d_physics
@export_flags_2d_render var layers_2d_render
@export_flags_2d_navigation var layers_2d_navigation
@export_flags_3d_physics var layers_3d_physics
@export_flags_3d_render var layers_3d_render
@export_flags_3d_navigation var layers_3d_navigation

Использование бинарных флагов требует некоторого понимания побитовых операций. Если вы сомневаетесь, вместо этого следует экспортировать логические переменные.

Exporting enums (Экспорт перечислений)

См. @export_enum.

Свойства можно экспортировать с указанием типа, ссылающегося на перечисление, чтобы ограничить их значения значениями этого перечисления. Редактор создаст виджет в Инспекторе, обозначив следующие элементы как "Thing 1", "Thing 2", "Another Thing". Значение будет сохранено как целое число.

enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum

Целочисленные и строковые свойства также можно ограничить определённым списком значений с помощью аннотации @export_enum. Редактор создаст виджет в Инспекторе, указав следующие типы: «Воин», «Маг», «Вор». Значение будет сохранено как целое число, соответствующее индексу выбранного варианта (например, 0, 1 или 2).

@export_enum("Warrior", "Magician", "Thief") var character_class: int

Вы можете добавить явные значения, используя двоеточие:

@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int

Если тип — String, значение будет сохранено как строка.

@export_enum("Rebecca", "Mary", "Leah") var character_name: String

Если вы хотите задать начальное значение, его необходимо указать явно:

@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"

Экспорт массивов

Экспортируемые массивы могут иметь инициализаторы, но они должны быть постоянными выражениями.

Если экспортируемый массив указывает тип, который наследуется от Ресурса, значения массива можно задать в инспекторе (Inspector), перетаскивая несколько файлов из файловой системы (FileSystem) одновременно.

Значение по умолчанию должно быть константным выражением.

@export var a = [1, 2, 3]

Для экспортируемых массивов можно указать тип (используя те же подсказки, что и раньше).

@export var ints: Array[int] = [1, 2, 3]

# Nested typed arrays such as `Array[Array[float]]` are not supported yet.
@export var two_dimensional: Array[Array] = [[1.0, 2.0], [3.0, 4.0]]

Вы можете опустить значение по умолчанию, но тогда оно будет равно null, если не назначено.

@export var b: Array
@export var scenes: Array[PackedScene]

Массивы с указанными типами, наследующими от ресурса, можно задать путем перетаскивания нескольких файлов из дока Файловой Системы.

@export var textures: Array[Texture] = []
@export var scenes: Array[PackedScene] = []

Массивы упакованного типа также работают, но только инициализируются пустыми:

@export var vector3s = PackedVector3Array()
@export var strings = PackedStringArray()

При экспорте массивов можно использовать и другие варианты экспорта:

@export_range(-360, 360, 0.001, "degrees") var laser_angles: Array[float] = []
@export_file("*.json") var skill_trees: Array[String] = []
@export_color_no_alpha var hair_colors = PackedColorArray()
@export_enum("Espresso", "Mocha", "Latte", "Capuccino") var barista_suggestions: Array[String] = []

@export_storage

См. @export_storage.

По умолчанию экспорт свойства имеет два эффекта:

  1. делает свойство сохраненным в файле сцены/ресурсов (PROPERTY_USAGE_STORAGE);

  2. добавляет поле в Инспектор (PROPERTY_USAGE_EDITOR).

Однако иногда может потребоваться сделать свойство сериализуемым, но не отображать его в редакторе, чтобы предотвратить непреднамеренные изменения и загромождение интерфейса.

Для этого можно использовать @export_storage. Это может быть полезно для скриптов @tool. Кроме того, значение свойства копируется при вызове Resource.duplicate() или Node.duplicate(), в отличие от неэкспортируемых переменных.

var a # Not stored in the file, not displayed in the editor.
@export_storage var b # Stored in the file, not displayed in the editor.
@export var c: int # Stored in the file, displayed in the editor.

@export_custom

Если вам требуется больше контроля, чем тот, который предоставляют встроенные аннотации @export, вы можете использовать @export_custom. Это позволяет определить любые подсказки свойств, строки подсказок и флаги использования с помощью синтаксиса, похожего на тот, который используется редактором для встроенных узлов.

Например, это раскрывает свойство altitude без ограничений диапазона, но с определенным суффиксом m (метр):

@export_custom(PROPERTY_HINT_NONE, "suffix:m") var altitude: float

Вышеуказанное обычно невозможно осуществить при использовании стандартного синтаксиса @export_range, поскольку он требует определения диапазона.

Список параметров и их допустимых значений см. в class reference.

Предупреждение

При использовании @export_custom GDScript не выполняет проверку синтаксиса. Неверный синтаксис может привести к неожиданному поведению в инспекторе.

@export_tool_button

Если вам нужно создать кнопку-инспектор, активируемую нажатием, используйте @export_tool_button. Это экспортирует свойство Callable как активируемую кнопку. При нажатии кнопки вызывается вызываемый объект.

Вы можете указать имя собственного значка, которое должно совпадать с одним из имён файлов значков из папки editor/icons в репозитории исходного кода Godot (с учётом регистра). Вы также можете просматривать значки редактора на сайте Godot editor icons.

Например, если вы хотите использовать Node2D.svg из этой папки, необходимо указать "Node2D" в качестве второго параметра @export_tool_button. В настоящее время использование пользовательских значков из папки проекта невозможно; можно использовать только встроенные значки редактора.

Это экспортирует кнопку с меткой "Hello" и значком "Callable" (который используется по умолчанию, если значок не указан). При нажатии на кнопку будет выведено "Hello world!".

@tool
extends Node

@export_tool_button("Hello", "Callable") var hello_action = hello

func hello():
    print("Hello world!")

Установка экспортированных переменных из скрипта инструмента

При изменении значения экспортированной переменной из скрипта в Режим Инструмента значение в инспекторе не будет обновлено автоматически. Чтобы обновить его, вызовите notify_property_list_changed() после установки значения экспортированной переменной.

Расширенный экспорт

Не каждый тип экспорта может быть предоставлен на уровне самого языка, чтобы избежать ненужной сложности проектирования. Далее описаны некоторые более или менее распространенные функции экспорта, которые могут быть реализованы с помощью низкоуровневого API.

Прежде чем читать дальше, вам следует ознакомиться со способом обработки свойств и тем, как их можно настраивать с помощью методов _set(), _get() и _get_property_list(), как описано в Доступ к данным или логике из объекта.

См. также

Свойства привязки, использующие описанные выше методы в C++, см. в разделе Связывание свойств через _set/_get/_get_property_list.

Предупреждение

Скрипт должен работать в режиме @tool, чтобы вышеуказанные методы могли работать из редактора.