GDScript 내보내기(Export)

내보내기 소개

Godot에서 클래스 멤버는 내보낼 수 있습니다. 즉, 멤버의 값은 (처럼) 붙어있는 리소스와 함께 저장됩니다. 그리고 속성(Property) 편집기에서 편집할 수 있습니다. 내보내려면 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.

스크립트가 편집기에서 실행하지 않는다면, 내보낸 속성은 편집할 수 있다는 것은 꼭 알아두세요. 왜냐하면 "Tool(도구) 모드에서 스크립트를 사용할 수 있기 때문입니다.

비트 플래그(bit flags) 내보내기

비트 플래그로 사용되는 정수는 한 속성에 여러 /거짓 (불리언) 값을 저장할 수 있습니다. 편집기에서 설정하도록 하려면 int, FLAGS 내보내기 힌트를 사용합니다:

# Individually edit the bits of an integer.
export(int, FLAGS) var spell_elements = ELEMENT_WIND | ELEMENT_WATER

플래그를 특정 개수의 이름있는 플래그로 제한하는 것도 가능합니다. 문법은 열거형 문법과 유사합니다:

# 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 hints are also provided for the physics and render layers defined in the project settings:

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

비트 플래그를 사용하려면 비트 연산에 대한 이해가 필요합니다. 의심스럽다면, 불리언 변수를 대신 내보내어야 합니다.

배열 내보내기

배열을 내보낼 수 있지만 중요한 주의 사항이 있습니다: 정규 배열은 모든 클래스 인스턴스에 지역(Local)으로 만들어지지만, 내보낸 배열은 모든 인스턴스 간에 공유됩니다. 즉, 한 인스턴스에서 배열을 편집하면 다른 인스턴스에서도 영향을 줍니다. 내보낸 배열은 이니셜라이저(Initializer)를 갖지만, 반드시 상수 표현식이 되어야 합니다.

If the exported array specifies a type which inherits from Resource, the array values can be set in the inspector by dragging and dropping multiple files from the FileSystem dock at once.

# Exported array, shared between all instances.
# 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()

# Regular array, created local for every instance.
# Default value can include run-time values, but can't
# be exported.

var c = [a, 2, 3]

Setting exported variables from a tool script

When changing an exported variable's value from a script in Tool mode(도구 모드), the value in the inspector won't be updated automatically. To update it, call property_list_changed_notify() after setting the exported variable's value.

Advanced exports

Not every type of export can be provided on the level of the language itself to avoid unnecessary design complexity. The following describes some more or less common exporting features which can be implemented with a low-level API.

Before reading further, you should get familiar with the way properties are handled and how they can be customized with _set(), _get(), and _get_property_list() methods as described in Accessing data or logic from an object.

더 보기

For binding properties using the above methods in C++, see Binding properties using _set/_get/_get_property_list.


The script must operate in the tool mode so the above methods can work from within the editor.

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 = []
            name = "Debug",
            type = TYPE_NIL,
    return properties
  • name is the name of a category to be added to the inspector;
  • 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.

Grouping properties

A list of properties with similar names can be grouped.

func _get_property_list():
    var properties = []
            name = "Rotate",
            type = TYPE_NIL,
            hint_string = "rotate_",
    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.
  • 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 won't be actually used for the scripting logic, yet it must be defined anyway.