Экспортирование в GDScript

Введение в экспорт

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

extends Button

export var number = 5 # Value will be saved and visible in the property editor.

Экспортируемая переменная должна быть инициализирована в постоянное выражение (Константу) или иметь подсказку на экспорт в виде аргумента к ключевому слову export (см. ниже секцию Примеры).

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

Примечание

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

Примеры

# If the exported value assigns a constant or constant expression,
# the type will be inferred and used in the editor.

export var number = 5

# Export can take a basic data type as an argument, which will be
# used in the editor.

export(int) var number

# Export can also take a resource type to use as a hint.

export(Texture) var character_face
export(PackedScene) var scene_file
# There are many resource types that can be used this way, try e.g.
# the following to list them:
export(Resource) var resource

# Integers and strings hint enumerated values.

# Editor will enumerate as 0, 1 and 2.
export(int, "Warrior", "Magician", "Thief") var character_class
# Editor will enumerate with string names.
export(String, "Rebecca", "Mary", "Leah") var character_name

# Named enum values

# Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
export(NamedEnum) var x

# Strings as paths

# String is a path to a file.
export(String, FILE) var f
# String is a path to a directory.
export(String, DIR) var f
# String is a path to a file, custom filter provided as hint.
export(String, FILE, "*.txt") var f

# Using paths in the global filesystem is also possible,
# but only in scripts in "tool" mode.

# String is a path to a PNG file in the global filesystem.
export(String, FILE, GLOBAL, "*.png") var tool_image
# String is a path to a directory in the global filesystem.
export(String, DIR, GLOBAL) var tool_dir

# The MULTILINE setting tells the editor to show a large input
# field for editing over multiple lines.
export(String, MULTILINE) var text

# Limiting editor input ranges

# Allow integer values from 0 to 20.
export(int, 20) var i
# Allow integer values from -10 to 20.
export(int, -10, 20) var j
# Allow floats from -10 to 20 and snap the value to multiples of 0.2.
export(float, -10, 20, 0.2) var k
# Allow values 'y = exp(x)' where 'y' varies between 100 and 1000
# while snapping to steps of 20. The editor will present a
# slider for easily editing the value.
export(float, EXP, 100, 1000, 20) var l

# Floats with easing hint

# Display a visual representation of the 'ease()' function
# when editing.
export(float, EASE) var transition_speed

# Colors

# Color given as red-green-blue value (alpha will always be 1).
export(Color, RGB) var col
# Color given as red-green-blue-alpha value.
export(Color, RGBA) var col

# Nodes

# Another node in the scene can be exported as a NodePath.
export(NodePath) var node_path
# Do take note that the node itself isn't being exported -
# there is one more step to call the true node:
var node = get_node(node_path)

# Resources

export(Resource) var resource
# In the Inspector, you can then drag and drop a resource file
# from the FileSystem dock into the variable slot.

# Opening the inspector dropdown may result in an
# extremely long list of possible classes to create, however.
# Therefore, if you specify an extension of Resource such as:
export(AnimationNode) var resource
# The drop-down menu will be limited to AnimationNode and all
# its inherited classes.

Следует отметить, что даже если во время работы в редакторе скрипт не выполняется, экспортируемые свойства все равно можно редактировать. Это можно использовать в сочетании с режимом "инструмента":.

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

Целые числа, используемые в качестве битовых флагов, могут хранить несколько true/false (булевых) значений в одном свойстве. Используя подсказку экспорта int, FLAGS, их можно настроить в редакторе:

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

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

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

export(int, LAYERS_2D_PHYSICS) var layers_2d_physics
export(int, LAYERS_2D_RENDER) var layers_2d_render
export(int, LAYERS_3D_PHYSICS) var layers_3d_physics
export(int, LAYERS_3D_RENDER) var layers_3d_render

Using bit flags requires some understanding of bitwise operations. If in doubt, use boolean variables instead.

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

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

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

# Default value must be a constant expression.

export var a = [1, 2, 3]

# Exported arrays can specify type (using the same hints as before).

export(Array, int) var ints = [1, 2, 3]
export(Array, int, "Red", "Green", "Blue") var enums = [2, 1, 0]
export(Array, Array, float) var two_dimensional = [[1.0, 2.0], [3.0, 4.0]]

# You can omit the default value, but then it would be null if not assigned.

export(Array) var b
export(Array, PackedScene) var scenes

# Arrays with specified types which inherit from resource can be set by
# drag-and-dropping multiple files from the FileSystem dock.

export(Array, Texture) var textures
export(Array, PackedScene) var scenes

# Typed arrays also work, only initialized empty:

export var vector3s = PoolVector3Array()
export var strings = PoolStringArray()

# Default value can include run-time values, but can't
# be exported.

var c = [a, 2, 3]

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

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

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

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

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

См.также

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

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

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

Добавление категорий скриптов

Для лучшего визуального различения свойств в Инспектор (Inspector) может быть встроена специальная категория скрипта, выполняющая роль разделителя. Script Variables - это один из примеров встроенной категории.

func _get_property_list():
    var properties = []
    properties.append(
        {
            name = "Debug",
            type = TYPE_NIL,
            usage = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SCRIPT_VARIABLE
        }
    )
    return properties
  • name это название категории, которая будет добавлена в инспектор;
  • PROPERTY_USAGE_CATEGORY указывает, что свойство должно рассматриваться именно как категория скрипта, поэтому тип TYPE_NIL можно игнорировать, поскольку он фактически не будет использоваться для логики скрипта, но все равно должен быть определен.

Свойства группировки

Список свойств с похожими именами можно сгруппировать.

func _get_property_list():
    var properties = []
    properties.append({
            name = "Rotate",
            type = TYPE_NIL,
            hint_string = "rotate_",
            usage = PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SCRIPT_VARIABLE
    })
    return properties
  • name - это имя группы, которая будет отображаться в виде складываемого списка свойств;
  • каждое последующее свойство, добавленное после свойства группы, будет свернуто и сокращено в соответствии с префиксом, определенным с помощью ключа hint_string. Например, в этом случае``rotate_speed`` будет сокращен до speed.
  • PROPERTY_USAGE_GROUP указывает, что свойство должно рассматриваться именно как группа сценариев, поэтому тип TYPE_NIL можно игнорировать, поскольку он фактически не будет использоваться для логики сценариев, но он все равно должен быть определен.