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

@export var number: int = 5

이 예에서는 5 값이 저장되고 속성 편집기에 표시됩니다.

내보낸 변수는 상수 표현식으로 초기화되거나 export 키워드에 대한 인수 형식의 내보내기 힌트가 있어야 합니다 (아래 예제 섹션 참조).

멤버 변수 내보내기의 기본적인 장점 중 하나는 편집기에서 멤버 변수를 보고 편집할 수 있다는 점입니다. 이런 식으로 아티스트와 게임 디자이너는 나중에 프로그램 실행 방식에 영향을 주는 값을 수정할 수 있습니다. 이를 위해 특별한 내보내기 구문이 제공됩니다.

참고

속성 내보내기는 C#과 같은 다른 언어에서도 가능합니다. 구문은 언어에 따라 다릅니다. C# 내보내기에 대한 정보는 노드 속성를 참고하세요.

기초 사용법

내보낸 값이 상수 또는 상수 표현식을 할당하는 경우 해당 유형이 추론되어 편집기에서 사용됩니다.

@export var number = 5

기본값이 없으면 변수에 유형을 추가할 수 있습니다.

@export var number: int

Shadermaterials는 내보낼 수 없습니다.

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

편집기에서 스크립트가 실행되지 않더라도 내보낸 속성은 계속 편집할 수 있습니다. 속성은 "툴" 모드의 스크립트와 함께 사용할 수 있습니다.

속성 그루핑(Grouping)

@export_group 주석을 사용하여 인스펙터 내에서 내보낸 속성을 그룹화할 수 있습니다. 이 주석 이후에 내보낸 모든 속성은 그룹에 추가됩니다. 새 그룹을 시작하거나 ``@export_group("")``를 사용하여 탈퇴하세요.

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

주석의 두 번째 인수는 지정된 접두사가 있는 그룹 속성에만 사용할 수 있습니다.

그룹은 중첩될 수 없습니다. :ref:`@export_subgroup <class_@GDScript_annotation_@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

참고

속성 목록은 클래스 상속을 기반으로 구성되며 새로운 범주는 이러한 기대를 깨뜨립니다. 특히 공용 프로젝트를 만들 때 주의해서 사용하세요.

줄 길이

Sprite

@export_file var f

Sprite

@export_dir var f

파일 경로인 문자열, 힌트로 제공되는 사용자 정의 필터. :ref:`@export_file <class_@GDScript_annotation_@export_file>`을 다시 참조하세요.

@export_file("*.txt") var f

전역 파일 시스템에서 경로를 사용하는 것도 가능하지만 도구 모드의 스크립트에서만 가능합니다.

전역 파일 시스템의 PNG 파일에 대한 경로인 문자열입니다. :ref:`@export_global_file <class_@GDScript_annotation_@export_global_file>`을 참조하세요.

@export_global_file("*.png") var tool_image

전역 파일 시스템의 디렉터리에 대한 경로인 문자열입니다. :ref:`@export_global_dir <class_@GDScript_annotation_@export_global_dir>`을 참조하세요.

@export_global_dir var tool_dir

여러 줄 주석은 여러 줄을 편집하기 위한 큰 입력 필드를 표시하도록 편집기에 지시합니다. :ref:`@export_multiline <class_@GDScript_annotation_@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

인스턴스 편집하기

Sprite

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

여유 요소를 나타내기 위한 값의 경우 대신 :ref:`doc_gdscript_exports_floats_with_easing_hint`를 사용하세요.

"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의 자체 rotation 속성에 의해 사용됩니다.

각도가 도 단위로 저장된 경우 "degrees" 힌트를 사용하여 도 기호를 표시하는 동시에 검사기에서 값이 수정될 때 자동 도-라디안 변환을 비활성화합니다.

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

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() 기능의 시각적 표현을 표시합니다. :ref:`@export_exp_easing <class_@GDScript_annotation_@export_exp_easing>`을 참조하세요.

@export_exp_easing var transition_speed

색상

빨간색-녹색-파란색-알파 값으로 제공되는 일반 색상입니다.

@export var col: Color

빨간색-녹색-파란색 값으로 지정된 색상(알파는 항상 1임) :ref:`@export_color_no_alpha <class_@GDScript_annotation_@export_color_no_alpha>`을 참조하세요.

@export_color_no_alpha var col: Color

노드

NodePath를 사용하지 않고도 노드를 스크립트의 속성으로 직접 내보낼 수도 있습니다.

# 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

필요한 경우 Godot 3.x에서와 같이 NodePath를 내보내는 것이 여전히 가능합니다:

@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 및 모든 파생 클래스로 제한됩니다.

참고

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.

비트 플래그 내보내기

Sprite

비트 플래그로 사용되는 정수는 하나의 속성에 여러 true/false(불리언) 값을 저장할 수 있습니다. 다음과 같이 내보내기 힌트 int, 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

비트 플래그를 사용하려면 비트 연산에 대한 이해가 필요합니다. 확실하지 않은 경우 대신 boolean 변수를 사용하세요.

내보내기 메뉴

Sprite

열거형을 참조하는 유형 힌트를 사용하여 속성을 내보내 해당 값을 열거형 값으로 제한할 수 있습니다. 편집기는 인스펙터에 위젯을 생성하여 다음을 "Thing 1", "Thing 2", "Another Thing"으로 열거합니다. 값은 정수로 저장됩니다.

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

정수 및 문자열 속성은 @export_enum 주석을 사용하여 특정 값 목록으로 제한될 수도 있습니다. 편집기는 인스펙터에 위젯을 생성하여 다음을 Warrior, Magician, Thief로 열거합니다. 값은 선택한 옵션(예: 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

유형이 문자열인 경우 값은 문자열로 저장됩니다.

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

내보낸 배열이 리소스를 상속받는 타입을 지정하는 경우 파일시스템 독에서 여러 파일을 한 번에 끌어다 놓으면 인스펙터에서 배열 값을 설정할 수 있습니다.

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

Android (시험용)

Sprite

기본적으로 속성을 내보내면 다음 두 가지 효과가 있습니다.

  1. 씬/resource 파일(PROPERTY_USAGE_STORAGE)에 속성을 저장합니다.

  2. 인스펙터(PROPERTY_USAGE_EDITOR)에 필드를 추가합니다.

그러나 때로는 속성을 직렬화할 수 있지만 의도하지 않은 변경과 인터페이스가 복잡해지는 것을 방지하기 위해 편집기에 표시하지 않을 수도 있습니다.

이렇게 하려면 @export_storage 스크립트에 유용할 수 있습니다. 또한 내보내지 않은 변수와 달리 Resource.duplicate() 또는 :ref:`노드.duplicate() <class_Node_method_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.

Android (시험용)

내장된 @export 주석으로 노출되는 것보다 더 많은 제어가 필요한 경우 대신 ``@export_custom``를 사용할 수 있습니다. 이를 통해 내장 노드에 대해 편집기에서 사용하는 것과 유사한 구문을 사용하여 속성 힌트, 힌트 문자열 및 사용 플래그를 정의할 수 있습니다.

예를 들어, 다음은 범위 제한이 없지만 m``(미터) 접미사가 정의된 ``altitude 속성을 노출합니다.

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

위의 내용은 범위 정의가 필요하기 때문에 일반적으로 표준 @export_range 구문으로는 실행 가능하지 않습니다.

매개변수 목록과 허용되는 값은 :ref:`class reference <class_@GDScript_annotation_@export_custom>`을 참조하세요.

경고

``@export_custom``를 사용할 때 GDScript는 구문에 대한 유효성 검사를 수행하지 않습니다. 잘못된 구문으로 인해 검사기에서 예기치 않은 동작이 발생할 수 있습니다.

Android (시험용)

클릭 가능한 검사기 버튼을 생성해야 하는 경우 @export_tool_button``를 사용할 수 있습니다. 그러면 ``Callable 속성이 클릭 가능한 버튼으로 내보내집니다. 버튼을 누르면 콜러블이 호출됩니다.

Godot 소스 저장소의 editor/icons 폴더에 있는 아이콘 파일 이름 중 하나와 일치해야 하는 사용자 정의 아이콘 이름을 지정할 수 있습니다(대소문자 구분). Godot 편집기 아이콘 웹사이트를 사용하여 편집기 아이콘을 찾아볼 수도 있습니다.

예를 들어, 해당 폴더에서 ``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!")

툴 스크립트에서 내보낸 변수 설정

툴 모드 스크립트에서 내보낸 변수의 값을 변경할 때 인스펙터의 값은 자동으로 업데이트되지 않습니다. 업데이트하려면 내보낸 변수의 값을 설정한 후 property_list_changed_notify()를 호출하세요.

툴 스크립트에서 내보낸 변수 설정

:ref:`_init() <class_Object_private_method__init>`에서 내보낸 변수의 값을 읽으면 검사기에 설정된 값 대신 내보내기 주석에 지정된 기본값이 반환됩니다. 이는 저장된 씬/리소스 파일의 값 할당이 개체 초기화 후에 발생하기 때문입니다. 그때까지는 기본값이 사용됩니다.

검사기에서 설정된 값(따라서 씬/resource 파일에 저장됨)을 얻으려면 :ref:`노드._ready() <class_Node_private_method__ready>`와 같이 객체가 생성된 후 읽어야 합니다. 내보낸 속성에 정의된 setter에서 값을 읽을 수도 있습니다. 이는 ``_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로 구현할 수 있는 다소 일반적인 내보내기 기능에 대해 설명합니다.

더 읽기 전에 속성이 처리되는 방식과 doc_accessing_data_or_logic_from_object`에 설명된 대로 :ref:`_set(), _get(), _get_property_list() 메서드를 동해 속성을 커스텀하는 방법에 대해 알고 있어야 합니다.

더 보기

C++에서 위의 방법을 사용해 속성을 바인딩하려면 _set/_get/``_get_property_list``를 사용하는 바인딩 속성를 참고하세요.

경고

위의 방법이 편집기 안에서 작동할 수 있도록 스크립트는 툴(tool) 모드에서 작동해야 합니다.