Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Експортовані властивості GDScript

У Godot члени класу можна експортувати. Це означає, що їхнє значення зберігається разом із ресурсом (наприклад, scene), до якого вони приєднані, та передаються під час використання RPCs. Вони також будуть доступні для редагування в редакторі властивостей. Експорт здійснюється за допомогою анотації @export.

@export var number: int = 5

У цьому прикладі значення 5 буде збережено та видиме в редакторі властивостей.

Експортована змінна має бути ініціалізована постійним виразом або мати специфікатор типу в змінній. Деякі анотації експорту мають певний тип і не потребують введення змінної (див. розділ Приклади нижче).

Одна з фундаментальних переваг експорту змінних-членів полягає в тому, що вони видимі та доступні для редагування в редакторі. Таким чином, художники та розробники ігор можуть змінювати значення, які згодом впливають на роботу програми. Для цього передбачено спеціальний синтаксис експорту. Крім того, documentation comments можна використовувати для описів підказок, які відображаються при наведенні курсора миші.

Примітка

Експорт властивостей також можна виконати іншими мовами, такими як 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

Strings as input actions

String as an input action defined in the project's input map.

@export_custom(PROPERTY_HINT_INPUT_NAME) var my_input

String as an input action defined in the project's input map, plus default built-in values such as ui_accept and ui_cancel.

@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin") var my_input

String as an input action defined in the project's input map, plus arbitrary values that can manually be entered.

@export_custom(PROPERTY_HINT_INPUT_NAME, "loose_mode") var my_input

String as an input action defined in the project's input map, plus default built-in values such as ui_accept and ui_cancel and arbitrary values that can manually be entered.

@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin,loose_mode") var my_input

Обмеження діапазонів введення редактора

Перегляньте @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

On the other hand, the "prefer_slider" hint can be used to show a horizontal bar below int properties instead of up/down arrows:

@export_range(0, 100, 1, "prefer_slider") var with_slider: int

Додавання суфіксів і обробка градусів/радіанів

Також можна визначити суфікс, щоб зробити значення більш зрозумілим в інспекторі. Наприклад, щоб визначити значення, яке користувач має налаштувати як «метри» (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 в усьому редакторі.

Якщо натомість кут зберігається в градусах, скористайтеся підказкою «градуси», щоб відобразити символ градуса, вимкнувши автоматичне перетворення градусів у радіани, коли значення змінюється з інспектора.

Linking vector values together

It is possible to link vector values together. When the user adjusts one of the vector's components, the other components are automatically adjusted proportionally. For example, this is useful to maintain the aspect ratio of a 2D sprite when adjusting its scale. This feature can be temporarily disabled by the user by clicking the link icon to the right of the property.

# Leave the hint string empty if you don't want to add a suffix.
@export_custom(PROPERTY_HINT_LINK, "suffix:px") var vector2_linked: Vector2 = Vector2(16, 16)

Результати в:

Linked Vector2i property with the "px" suffix

This hint is effective on Vector2, Vector2i, Vector3, Vector3i, Vector4, and Vector4i. It can be used at the same time as a property suffix, as seen in the example above.

Плаває з натяком на полегшення

Відображати візуальне представлення функції 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

Вузли

Вузли також можна експортувати безпосередньо як властивості у скрипті без використання 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 у слот для змінних.

Однак відкриття спадного меню інспектора може призвести до надзвичайно довгого списку можливих класів для створення. Тому, якщо ви вкажете таке розширення ресурсу, як:

@export var resource: AnimationNode

Випадаюче меню буде обмежено AnimationNode і всіма похідними від нього класами.

Примітка

Using @export variables for Resource objects makes them a dependency of the instance, meaning that all the resources referenced by @export variables are loaded when the scene containing the script is loaded. If you want to reference a Resource object but load it manually when you need it (which, for example, is often the case for PackedScenes containing a whole level), use @export_file or @export_file_path instead.

Експорт бітових прапорців

Див. @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

Лише значення потужності 2 дійсні як параметри бітових прапорів. Найменше допустиме значення — 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

Використання бітових значень вимагає певного розуміння побітових операцій. Якщо ви сумніваєтесь, використовуйте замість них логічні змінні.

Експорт переліків

Див. @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"

Експорт масивів

Експортовані масиви можуть мати ініціалізатори, але вони повинні бути постійними виразами.

Якщо експортований масив задає тип, який успадковується від Ресурса, значення масиву можна встановити в інспекторі, перетягуючи одночасно кілька файлів із панелі Файлова система.

Значення за замовчуванням має бути постійним виразом.

@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]

Масиви з указаними типами, які успадковуються від ресурсу, можна встановити шляхом перетягування кількох файлів із док-станції FileSystem.

@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() після встановлення значення експортованої змінної.

Зчитування значення експортованої змінної на ранній стадії

Якщо ви зчитуєте значення експортованої змінної у _init(), вона поверне значення за замовчуванням, вказане в анотації експорту, замість значення, яке було встановлено в інспекторі. Це тому, що призначення значень зі збереженого файлу сцени/ресурсів відбувається після ініціалізації об'єкта; до того часу використовується значення за замовчуванням.

Щоб отримати значення, яке було встановлено в інспекторі (і, отже, збережено у файлі сцени/ресурсів), вам потрібно прочитати його після створення об'єкта, наприклад, у Node._ready(). Ви також можете прочитати значення в сеттері, визначеному для експортованої властивості, що корисно в користувацьких ресурсах, де _ready() недоступне:

# Set this property to 3 in the inspector.
@export var exported_variable = 2:
    set(value):
        exported_variable = value
        print("Inspector-set value: ", exported_variable)

func _init():
    print("Initial value: ", exported_variable)

Результати в:

Initial value: 2
Inspector-set value: 3

Розширений експорт

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

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

Дивись також

Для прив'язки властивостей, що використовуються в вищезгаданих методах в C++, дивіться Властивості прив’язки за допомогою _set/_get/_get_property_list.

Попередження

Скрипт має працювати в режимі @tool, щоб наведені вище методи могли працювати з редактора.