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

변종

일반적인 Variant에 대한 자세한 설명은 Variant 설명서 페이지를 참조하세요.

``Godot.Variant``는 Godot의 기본 Variant 유형을 나타내는 데 사용됩니다. 모든 :ref:`Variant 호환 유형 <c_sharp_variant_ Compatible_types>`을 변환할 수 있습니다. 형식화되지 않은 엔진 API와 상호작용해야 하는 경우가 아니면 ``Godot.Variant``를 사용하지 않는 것이 좋습니다. 가능하면 C#의 형식 안전성을 활용하세요.

암시적 변환을 사용하여 Variant 호환 C# 유형에서 Godot.Variant``로 변환할 수 있습니다. ``CreateFrom 메서드 오버로드와 일반 Variant.From<T> 메서드도 있습니다. 구문만 다를 뿐 동작은 동일합니다.

int x = 42;
Variant numberVariant = x;
Variant helloVariant = "Hello, World!";

Variant numberVariant2 = Variant.CreateFrom(x);
Variant numberVariant3 = Variant.From(x);

``Godot.Variant``로의 암시적 변환을 사용하면 변형을 메서드 인수로 매우 편리하게 전달할 수 있습니다. 예를 들어, 트윈의 최종 색상을 지정하는 :ref:`tween_property<class_Tween_method_tween_property>`의 세 번째 인수는 ``Godot.Variant``입니다.

Tween tween = CreateTween();
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);

명시적 변환을 사용하면 Godot.Variant``에서 C# 형식으로 변환할 수 있습니다. ``Variant.As{TYPE} 방법과 일반 Variant.As<T> 방법도 있습니다. 이들 모두는 동일하게 동작합니다.

int number = (int)numberVariant;
string hello = (string)helloVariant;

int number2 = numberVariant.As<int>();
int number3 = numberVariant.AsInt32();

참고

Variant.As{TYPE} 메서드는 일반적으로 C# 키워드(int)가 아닌 C# 유형(Int32)의 이름을 따서 명명됩니다.

변형 유형이 변환 대상 유형과 일치하지 않는 경우 소스 및 대상 값에 따라 결과가 달라집니다.

변환은 값을 검사하고 유사하지만 잠재적으로 예상치 못한 대상 유형 값을 반환할 수 있습니다. 예를 들어, 문자열 ``"42a"``는 정수 ``42``로 변환될 수 있습니다.
대상 유형의 기본값이 반환될 수 있습니다.
빈 배열이 반환될 수 있습니다.
예외가 발생할 수 있습니다.

올바른 유형으로 변환하면 복잡한 동작을 피할 수 있으므로 선호됩니다.

Variant.Obj 속성은 모든 변형에 대해 올바른 값이 포함된 C# ``object``를 반환합니다. 이는 Variant 유형을 완전히 알 수 없는 경우에 유용할 수 있습니다. 그러나 가능하다면 보다 구체적인 변환을 선호하세요. ``Variant.Obj``는 ``Variant.VariantType``에서 ``switch``를 평가하며 필요하지 않을 수도 있습니다. 또한 결과가 값 유형인 경우 boxing됩니다.

예를 들어 Variant.As<MyNode>()``가 잘못된 캐스트 예외를 throw할 가능성이 허용되지 않는 경우 대신 ``Variant.As<GodotObject>() is MyNode n 유형 패턴을 사용하는 것이 좋습니다.

참고

C#의 Variant 형식은 구조체이므로 null일 수 없습니다. "null" 변형을 만들려면 default 키워드 또는 매개 변수가 없는 Godot.Variant 생성자를 사용하세요.

커스텀 변수 타입

Variant 호환 유형은 ``Godot.Variant``로 변환될 수 있습니다. 다음 C# 형식은 Variant와 호환됩니다.

decimal, nint 및 ``nuint``를 제외한 모든 기본 제공 값 유형.
: String
Object
Godot.Collections 네임스페이스에 정의된 컬렉션 유형입니다.

Variant 유형 및 해당 C# 유형의 전체 목록:

변종	타입
`Nil`	`null` (타입 아님)
`Bool`	bool
`: int`	`long` (Godot는 Variant에 64비트 정수를 저장합니다)
`: float`	`double` (Godot는 Variant에 64비트 부동소수점을 저장합니다)
`String[]`	`: String`
`Vector2[]`	`Vector2[]`
`Vector2[]`	`Vector2[]`
Rect2	`Godot.Collections.Array`
Rect2	`Godot.Collections.Array`
`Vector3[]`	`Vector3[]`
`Vector3[]`	`Vector3[]`
'변형'	'변형'
`Vector2[]`	`Godot.Collections.Array`
`Vector2[]`	`Godot.Collections.Array`
평면	`Godot.Plane`
`Rotation`	`Rotation`
`Aabb`	`Godot.Aabb`
`is`	`Godot.Basis`
'변형'	'변형'
연결(Connections)	`Godot.Collections.Array`
`Color8`	`Color.Color8`
`String[]`	`PoolStringArray`
`$NodePath`	`$NodePath`
`-> void`	`Godot.Rid`
`{project}`	`Godot.GodotObject` 또는 파생된 유형입니다.
`end`	`Godot.Collections.Array`
시그널	`Godot.Collections.Array`
딕셔너리	`Godot.Collections.Dictionary` 를 사용합니다.
`Array`	`Godot.Collections.Array`
`PoolByteArray`	`byte[]`
`PoolIntArray`	`int[]`
`PoolIntArray`	`float[]`
`PoolFloatArray`	`float[]`
`PoolFloatArray`	`byte[]`
`PoolStringArray`	`String[]`
`PoolVector2Array`	`Vector2[]`
`PoolVector3Array`	`Vector3[]`
`PoolVector2Array`	`Vector2[]`
`PoolColorArray`	`Color[]`

경고

Godot는 Variant에서 64비트 정수와 부동소수점을 사용합니다. int, short 및 ``float``와 같은 더 작은 정수 및 부동 소수점 유형은 더 큰 유형에 적합하므로 지원됩니다. 변환을 수행할 때 잘못된 유형을 사용하면 정밀도가 손실될 수 있다는 점에 유의하세요.

경고

열거형은 기본 유형이 모두 호환되는 정수 유형이므로 Godot.Variant``에서 지원됩니다. 그러나 암시적 변환은 존재하지 않습니다. 열거형을 ``Godot.Variant``로/에서 변환하거나 일반 ``Variant.As<T> 및 Variant.From<T> 메서드를 사용하여 변환하기 전에 열거형을 기본 정수 유형으로 수동으로 변환해야 합니다.

enum MyEnum { A, B, C }

Variant variant1 = (int)MyEnum.A;
MyEnum enum1 = (MyEnum)(int)variant1;

Variant variant2 = Variant.From(MyEnum.A);
MyEnum enum2 = variant2.As<MyEnum>();

일반 컨텍스트에서 Variant 사용

제네릭을 사용할 때 제네릭 T 유형을 Variant 호환 유형 중 하나로 제한하는 데 관심이 있을 수 있습니다. 이는 [MustBeVariant] 속성을 사용하여 달성할 수 있습니다.

public void MethodThatOnlySupportsVariants<[MustBeVariant] T>(T onlyVariant)
{
    // Do something with the Variant-compatible value.
}

일반 Variant.From<T>``와 결합하면 일반 ``T 유형의 인스턴스에서 Godot.Variant 인스턴스를 얻을 수 있습니다. 그런 다음 Godot.Variant 구조체만 지원하는 모든 API에서 사용할 수 있습니다.

public void Method1<[MustBeVariant] T>(T variantCompatible)
{
    Variant variant = Variant.From(variantCompatible);
    Method2(variant);
}

public void Method2(Variant variant)
{
    // Do something with variant.
}

[MustBeVariant] 속성으로 주석이 달린 일반 매개변수가 있는 메서드를 호출하려면 값이 Variant 호환 유형이거나 [MustBeVariant] 속성으로 주석이 달린 일반 T 유형이어야 합니다.

public class ObjectDerivedClass : GodotObject { }

public class NonObjectDerivedClass { }

public void Main<[MustBeVariant] T1, T2>(T1 someGeneric1, T2 someGeneric2)
{
    MyMethod(42); // Works because `int` is a Variant-compatible type.
    MyMethod(new ObjectDerivedClass()); // Works because any type that derives from `GodotObject` is a Variant-compatible type.
    MyMethod(new NonObjectDerivedClass()); // Does NOT work because the type is not Variant-compatible.
    MyMethod(someGeneric1); // Works because `T1` is annotated with the `[MustBeVariant]` attribute.
    MyMethod(someGeneric2); // Does NOT work because `T2` is NOT annotated with the `[MustBeVariant]` attribute.
}

public void MyMethod<[MustBeVariant] T>(T variant)
{
    // Do something with variant.
}