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...

노드 속성

Godot에서는 클래스 멤버는 내보낼 수 있습니다. 즉, 해당 값은 (scene과 같이) 붙여진 리소스와 함께 저장됩니다. 또한 속성 편집기에서 편집할 수 있습니다. 내보내기는 [Export] 특성을 사용하여 수행됩니다.

using Godot;

public partial class ExportExample : Node3D
{
    [Export]
    public int Number { get; set; } = 5;
}

이 예에서는 5 값이 저장되고 현재 프로젝트를 빌드한 후 속성 편집기에 표시됩니다.

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

내보내기는 :ref:`c_sharp_variant_compatible_types`로만 가능합니다.

참고

속성 내보내기는 GDScript에서도 수행할 수 있습니다. 자세한 내용은 :ref:`doc_gdscript_exports`를 참조하세요.

기초 사용법

패키지, 패치, 모드 내보내기

[Export]
private int _number;

[Export]
public int Number { get; set; }

내보낸 멤버는 기본값을 지정할 수 있습니다. 그렇지 않으면 `유형의 기본값 <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/default-values>`_가 대신 사용됩니다.

``Number``와 같은 ``int``의 기본값은 ``0``입니다. ``string``는 참조 유형이므로 ``Text``의 기본값은 null입니다.

[Export]
public int Number { get; set; }

[Export]
public string Text { get; set; }

필드 및 속성에 대해 기본값을 지정할 수 있습니다.

[Export]
private string _greeting = "Hello World";

[Export]
public string Greeting { get; set; } = "Hello World";

지원 필드가 있는 속성은 지원 필드의 기본값을 사용합니다.

private int _number = 2;

[Export]
public int NumberWithBackingField
{
    get => _number;
    set => _number = value;
}

참고

속성의 ``get``는 기본값을 결정하기 위해 실제로 실행되지 않습니다. 대신 Godot는 C# 소스 코드를 분석합니다. 이는 이 페이지의 예제와 같은 대부분의 경우에 잘 작동합니다. 그러나 일부 속성은 분석기가 이해하기에는 너무 복잡합니다.

예를 들어 다음 속성은 수학을 사용하여 속성 편집기에서 기본값을 ``5``로 표시하려고 시도하지만 작동하지 않습니다.

[Export]
public int NumberWithBackingField
{
    get => _number + 3;
    set => _number = value - 3;
}

private int _number = 2;

분석기는 이 코드를 이해하지 못하고 int, ``0``의 기본값으로 대체됩니다. 그러나 씬을 실행하거나 연결된 도구 스크립트를 사용하여 노드를 검사하면 ``_number``는 ``2``가 되고 ``NumberWithBackingField``는 ``5``를 반환합니다. 이 차이로 인해 혼란스러운 동작이 발생할 수 있습니다. 이를 방지하려면 복잡한 속성을 사용하지 마세요. 또는 기본값을 명시적으로 지정할 수 있는 경우 _PropertyCanRevert() 및 _PropertyGetRevert() 메서드를 사용하여 재정의할 수 있습니다.

모든 유형의 Resource 또는 Node``를 내보낼 수 있습니다. 속성 편집기는 이러한 유형에 대해 사용자에게 친숙한 할당 대화 상자를 표시합니다. 이는 ``GD.Load 및 GetNode 대신 사용할 수 있습니다. :ref:`노드 및 리소스 <doc_c_sharp_exports_nodes>`을 참조하세요.

[Export]
public PackedScene PackedScene { get; set; }

[Export]
public RigidBody2D RigidBody2D { get; set; }

속성 그루핑(Grouping)

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

[ExportGroup("My Properties")]
[Export]
public int Number { get; set; } = 3;

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

그룹은 중첩될 수 없습니다. ``[ExportSubgroup]``를 사용하여 그룹 내에 하위 그룹을 생성하세요.

[ExportSubgroup("Extra Properties")]
[Export]
public string Text { get; set; } = "";
[Export]
public bool Flag { get; set; } = false;

또한 기본 카테고리의 이름을 변경하거나 [ExportCategory] 속성을 사용하여 속성 목록에 추가 카테고리를 생성할 수도 있습니다.

[ExportCategory("Main Category")]
[Export]
public int Number { get; set; } = 3;
[Export]
public string Text { get; set; } = "";

[ExportCategory("Extra Category")]
[Export]
public bool Flag { get; set; } = false;

참고

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

줄 길이

속성 힌트를 사용하여 문자열을 경로로 내보낼 수 있습니다.

타일맵 사용하기

[Export(PropertyHint.File)]
public string GameFile { get; set; }

디렉터리에 대한 경로인 문자열입니다.

[Export(PropertyHint.Dir)]
public string GameDirectory { get; set; }

파일 경로인 문자열, 힌트로 제공되는 사용자 정의 필터.

[Export(PropertyHint.File, "*.txt,")]
public string GameFile { get; set; }

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

전역 파일 시스템의 PNG 파일에 대한 경로인 문자열입니다.

[Export(PropertyHint.GlobalFile, "*.png")]
public string ToolImage { get; set; }

전역 파일 시스템의 디렉터리에 대한 경로인 문자열입니다.

[Export(PropertyHint.GlobalDir)]
public string ToolDir { get; set; }

여러 줄 주석은 여러 줄을 편집하기 위한 큰 입력 필드를 표시하도록 편집기에 지시합니다.

[Export(PropertyHint.MultilineText)]
public string Text { get; set; }

인스턴스 편집하기

범위 속성 힌트를 사용하면 편집기를 사용하여 값으로 입력할 수 있는 항목을 제한할 수 있습니다.

0에서 20 사이의 정수 값을 허용합니다.

[Export(PropertyHint.Range, "0,20,")]
public int Number { get; set; }

-10에서 20 사이의 정수 값을 허용합니다.

[Export(PropertyHint.Range, "-10,20,")]
public int Number { get; set; }

-10에서 20까지의 부동 소수점을 허용하고 값을 0.2의 배수로 맞춥니다.

[Export(PropertyHint.Range, "-10,20,0.2")]
public float Number { get; set; }

"or_greater" 및/또는 "or_less" 힌트를 추가하면 슬라이더를 사용하는 대신 값을 입력하여 값을 조정할 때 제한을 초과하거나 미만으로 이동할 수 있습니다.

[Export(PropertyHint.Range, "0,100,1,or_greater,or_less")]
public int Number { get; set; }

완화 힌트가 포함된 부동

편집 시 ease 기능의 시각적 표현을 표시합니다.

[Export(PropertyHint.ExpEasing)]
public float TransitionSpeed { get; set; }

접미사 힌트로 내보내기

내보낸 변수에 대한 단위 힌트 접미사를 표시합니다. 부동 소수점 또는 벡터와 같은 숫자 유형과 함께 작동합니다.

[Export(PropertyHint.None, "suffix:m/s\u00b2")]
public float Gravity { get; set; } = 9.8f;
[Export(PropertyHint.None, "suffix:m/s")]
public Vector3 Velocity { get; set; }

위의 예에서 \u00b2``는 "제곱" 문자(``²)를 쓰는 데 사용됩니다.

색상

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

[Export]
public Color Color { get; set; }

빨간색-녹색-파란색 값으로 지정된 색상(알파는 항상 1임)

[Export(PropertyHint.ColorNoAlpha)]
public Color Color { get; set; }

노드

노드는 NodePath를 사용하지 않고도 직접 내보낼 수도 있습니다.

[Export]
public Node Node { get; set; }

특정 유형의 노드를 직접 내보낼 수도 있습니다. 인스펙터에서 "Assign"을 누른 후 표시되는 노드 목록은 지정된 유형으로 필터링되며 올바른 노드만 할당할 수 있습니다.

[Export]
public Sprite2D Sprite2D { get; set; }

사용자 정의 노드 클래스를 직접 내보낼 수도 있습니다. 필터링 동작은 사용자 정의 클래스가 :ref:`global class <doc_c_sharp_global_classes>`인지 여부에 따라 달라집니다.

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

[Export]
public NodePath NodePath { get; set; }

public override void _Ready()
{
    var node = GetNode(NodePath);
}

리소스

[Export]
public Resource Resource { get; set; }

인스펙터에서는 FileSystem 도크의 리소스 파일을 변수 슬롯으로 끌어다 놓을 수 있습니다.

그러나 검사기 드롭다운을 열면 만들 수 있는 클래스 목록이 매우 길어질 수 있습니다. 따라서 다음과 같이 Resource에서 파생된 유형을 지정하는 경우:

[Export]
public AnimationNode AnimationNode { get; set; }

드롭다운 메뉴는 AnimationNode 및 모든 파생 클래스로 제한됩니다. 사용자 정의 리소스 클래스도 사용할 수 있습니다. :ref:`doc_c_sharp_global_classes`를 참조하세요.

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

비트 플래그 내보내기

유형이 [Flags] 속성이 있는 열거형인 멤버를 내보낼 수 있으며 해당 값은 열거형 유형의 멤버로 제한됩니다. 편집기는 인스펙터에 위젯을 생성하여 열거형 멤버를 선택하지 않거나, 하나 또는 여러 개 선택할 수 있도록 합니다. 값은 정수로 저장됩니다.

플래그 열거형은 열거형 멤버의 값에 대해 2의 거듭제곱을 사용합니다. 논리 OR(|)를 사용하여 여러 플래그를 결합하는 멤버도 가능합니다.

[Flags]
public enum SpellElements
{
    Fire = 1 << 1,
    Water = 1 << 2,
    Earth = 1 << 3,
    Wind = 1 << 4,

    FireAndWater = Fire | Water,
}

[Export]
public SpellElements MySpellElements { get; set; }

비트 플래그로 사용되는 정수는 하나의 속성에 여러 true/false(불리언) 값을 저장할 수 있습니다. 다음과 같이 내보내기 힌트 Flags를 사용해 편집기에서 설정할 수 있습니다.

[Export(PropertyHint.Flags, "Fire,Water,Earth,Wind")]
public int SpellElements { get; set; } = 0;

각 플래그에 대한 문자열 설명을 제공해야 합니다. 이 예제에서 Fire는 값 1, Water는 값 2, Earth는 값 4, Wind는 값 8에 해당합니다. 일반적으로 상수는 이에 따라 정의되어야 합니다(예: const ELEMENT_WIND = 8 등등).

콜론을 사용하여 명시적인 값을 추가할 수 있습니다.

[Export(PropertyHint.Flags, "Self:4,Allies:8,Foes:16")]
public int SpellTargets { get; set; } = 0;

2의 거듭제곱 값만 비트 플래그 옵션으로 유효합니다. 허용되는 가장 낮은 값은 1입니다. 0은 아무것도 선택되지 않았음을 의미합니다. 다른 플래그를 조합한 옵션을 추가할 수도 있습니다.

[Export(PropertyHint.Flags, "Self:4,Allies:8,Self and Allies:12,Foes:16")]
public int SpellTargets { get; set; } = 0;

프로젝트 설정에 정의된 물리 및 렌더 레이어에 대한 내보내기 힌트도 제공됩니다:

[Export(PropertyHint.Layers2DPhysics)]
public uint Layers2DPhysics { get; set; }
[Export(PropertyHint.Layers2DRender)]
public uint Layers2DRender { get; set; }
[Export(PropertyHint.Layers3DPhysics)]
public uint Layers3DPhysics { get; set; }
[Export(PropertyHint.Layers3DRender)]
public uint Layers3DRender { get; set; }

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

내보내기 메뉴

유형이 열거형인 멤버는 내보낼 수 있으며 해당 값은 열거형 유형의 멤버로 제한됩니다. 편집기는 인스펙터에 위젯을 생성하여 다음을 "Thing 1", "Thing 2", "Another Thing"으로 열거합니다. 값은 정수로 저장됩니다.

public enum MyEnum
{
    Thing1,
    Thing2,
    AnotherThing = -1,
}

[Export]
public MyEnum MyEnumCurrent { get; set; }

정수 및 문자열 멤버는 PropertyHint.Enum 힌트와 함께 [Export] 주석을 사용하여 특정 값 목록으로 제한될 수도 있습니다. 편집기는 인스펙터에 위젯을 생성하여 다음을 Warrior, Magician, Thief로 열거합니다. 값은 선택한 옵션(예: 0, 1 또는 2)의 인덱스에 해당하는 정수로 저장됩니다.

[Export(PropertyHint.Enum, "Warrior,Magician,Thief")]
public int CharacterClass { get; set; }

콜론을 사용하여 명시적인 값을 추가할 수 있습니다.

[Export(PropertyHint.Enum, "Slow:30,Average:60,Very Fast:200")]
public int CharacterSpeed { get; set; }

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

[Export(PropertyHint.Enum, "Rebecca,Mary,Leah")]
public string CharacterName { get; set; }

초기값을 설정하려면 명시적으로 지정해야 합니다.

[Export(PropertyHint.Enum, "Rebecca,Mary,Leah")]
public string CharacterName { get; set; } = "Rebecca";

``[ExportToolButton]``를 사용하여 검사기 버튼 내보내기

인스펙터에서 클릭 가능한 버튼을 생성하려면 [ExportToolButton] 속성을 사용할 수 있습니다. 호출 가능 속성 또는 필드를 클릭 가능한 버튼으로 내보냅니다. 이는 편집기에서 실행되므로 [Tool] 속성을 사용해야 합니다. 버튼을 누르면 호출 가능 항목이 호출됩니다.

[Tool]
public partial class MyNode : Node
{
    [ExportToolButton("Click me!")]
    public Callable ClickMeButton => Callable.From(ClickMe);

    public void ClickMe()
    {
        GD.Print("Hello world!");
    }
}

두 번째 인수를 사용하여 버튼의 아이콘을 설정할 수도 있습니다. 지정된 경우 "EditorIcons" 테마 유형에서 :ref:`GetThemeIcon() <class_Control_method_get_theme_icon>`을 통해 아이콘을 가져옵니다.

[ExportToolButton("Click me!", Icon = "CharacterBody2D")]
public Callable ClickMeButton => Callable.From(ClickMe);

내보내기 고려 사항

C# Variant 설명서에 설명된 대로 특정 C# 배열과 Godot.Collections 네임스페이스에 정의된 컬렉션 유형만 Variant와 호환되므로 해당 유형만 내보낼 수 있습니다.

배열 내보내기

[Export]
public Godot.Collections.Array Array { get; set; }

일반 ``Godot.Collections.Array<T>``를 사용하면 배열 요소의 유형을 지정할 수 있으며 이는 편집기에 대한 힌트로 사용됩니다. 인스펙터는 요소를 지정된 유형으로 제한합니다.

[Export]
public Godot.Collections.Array<string> Array { get; set; }

Godot 배열의 기본값은 null입니다. 다른 기본값을 지정할 수 있습니다.

[Export]
public Godot.Collections.Array<string> CharacterNames { get; set; } =
[
    "Rebecca",
    "Mary",
    "Leah",
];

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

[Export]
public Godot.Collections.Array<Texture> Textures { get; set; }

[Export]
public Godot.Collections.Array<PackedScene> Scenes { get; set; }

내보내기 고려 사항

[Export]
public Godot.Collections.Dictionary Dictionary { get; set; }

일반 ``Godot.Collections.Dictionary<TKey, TValue>``를 사용하면 사전의 키 및 값 요소 유형을 지정할 수 있습니다.

[Export]
public Godot.Collections.Dictionary<string, int> Dictionary { get; set; }

Godot 사전의 기본값은 null입니다. 다른 기본값을 지정할 수 있습니다.

[Export]
public Godot.Collections.Dictionary<string, int> CharacterLives { get; set; } = new Godot.Collections.Dictionary<string, int>
{
    ["Rebecca"] = 10,
    ["Mary"] = 42,
    ["Leah"] = 0,
};

배열 내보내기

요소 유형이 :ref:`Variant 호환 유형 <c_sharp_variant_ Compatible_types>`인 경우 C# 배열을 내보낼 수 있습니다.

[Export]
public Vector3[] Vectors { get; set; }

[Export]
public NodePath[] NodePaths { get; set; }

C# 배열의 기본값은 null입니다. 다른 기본값을 지정할 수 있습니다.

[Export]
public Vector3[] Vectors { get; set; } =
[
    new Vector3(1, 2, 3),
    new Vector3(3, 2, 1),
];

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

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

고급 내보내기

불필요한 디자인 복잡성을 피하기 위해 모든 유형의 내보내기를 언어 자체 수준에서 제공할 수 있는 것은 아닙니다. 다음은 저수준 API로 구현할 수 있는 다소 일반적인 내보내기 기능에 대해 설명합니다.

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

더 보기

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

경고

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