Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

C#-Variant

Für eine detaillierte Beschreibung von Variant im Allgemeinen, siehe die Variant-Dokumentationsseite.

Godot.Variant wird verwendet, um Godots nativen Typ Variant zu repräsentieren. Jeder Variant-kompatible Typ kann von/zu ihm konvertiert werden. Wir empfehlen, Godot.Variant zu vermeiden, es sei denn, es ist notwendig, mit nicht typisierten Engine-APIs zu interagieren. Nutzen Sie, wenn möglich, die Vorteile der Typsicherheit von C#.

Jede der Methoden Variant.As{TYPE} oder die generische Methode Variant.As<T> kann verwendet werden, um eine Godot.Variant in einen C#-Typ zu konvertieren. Da der Godot.Variant-Typ implizite Konvertierungen enthält, die für alle unterstützten Typen definiert sind, ist der direkte Aufruf dieser Methoden normalerweise nicht notwendig.

Verwenden Sie CreateFrom-Methodenüberladungen oder die generische Methode Variant.From<T>, um einen C#-Typ in eine Godot.Variant zu konvertieren.

Bemerkung

Da der Variant-Typ in C# ein Struct ist, kann er nicht null sein. Um eine "null"-Variante zu erzeugen, verwenden Sie das default-Schlüsselwort oder den parameterlosen Konstruktor.

Variantenkompatible Typen

• Alle Built-in-Werttypen außer decimal, nint und nuint.

• string.

• Von GodotObject abgeleitete Klassen.

• Collections-Typen, die im Godot.Collections-Namespace definiert sind.

Vollständige Liste der Variantentypen und ihres entsprechenden C#-Typs:

Variant.Type	C#-Typ
Nil	null (kein Typ)
Bool	bool
Int	long (Godot speichert 64-Bit-Integer in Variant)
Float	double (Godot speichert 64-Bit-Floats in Variant)
String	string
Vector2	Godot.Vector2
Vector2I	Godot.Vector2I
Rect2	Godot.Rect2
Rect2I	Godot.Rect2I
Vector3	Godot.Vector3
Vector3I	Godot.Vector3I
Transform2D	Godot.Transform2D
Vector4	Godot.Vector4
Vector4I	Godot.Vector4I
Plane	Godot.Plane
Quaternion	Godot.Quaternion
Aabb	Godot.Aabb
Basis	Godot.Basis
Transform3D	Godot.Transform3D
Projection	Godot.Projection
Color	Godot.Color
StringName	Godot.StringName
NodePath	Godot.NodePath
Rid	Godot.Rid
Object	Godot.GodotObject oder ein abgeleiteter Typ.
Callable	Godot.Callable
Signal	Godot.Signal
Dictionary	Godot.Collections.Dictionary
Array	Godot.Collections.Array
PackedByteArray	byte[]
PackedInt32Array	int[]
PackedInt64Array	long[]
PackedFloat32Array	float[]
PackedFloat64Array	double[]
PackedStringArray	string[]
PackedVector2Array	Godot.Vector2[]
PackedVector3Array	Godot.Vector3[]
PackedColorArray	Godot.Color[]

Warnung

Godot verwendet 64-Bit-Integer und -Floats in Variant. Kleinere Integer- und Float-Typen wie int, short und float werden unterstützt, da sie in den größeren Typ passen. Beachten Sie, dass eine implizite Konvertierung durchgeführt wird, so dass die Verwendung des falschen Typs zu einem möglichen Präzisionsverlust führt.

Warnung

Enums werden von Godot.Variant unterstützt, da ihr zugrundeliegender Typ ein Integer-Typ ist, die alle kompatibel sind. Allerdings gibt es keine impliziten Konvertierungen. Enums müssen manuell in ihren zugrundeliegenden Integer-Typ konvertiert werden, bevor sie in/aus Godot.Variant konvertiert werden können oder die generischen Methoden Variant.As<T> und Variant.From<T> verwenden, um sie zu konvertieren.

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>();

Verwendung von Variant in einem generischen Kontext

Bei der Verwendung von Generics kann es von Interesse sein, den generischen T-Typ darauf zu beschränken, dass er nur einer der Variant-kompatiblen Typen ist. Dies kann mit dem Attribut [MustBeVariant] erreicht werden.

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

Kombiniert mit dem generischen Variant.From<T> erlaubt es Ihnen, eine Instanz von Godot.Variant aus einer Instanz eines generischen T-Typs zu erhalten. Dann kann es in jeder API verwendet werden, die nur die Godot.Variant-Struktur unterstützt.

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

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

Um eine Methode mit einem generischen Parameter aufzurufen, der mit dem Attribut [MustBeVariant] versehen ist, muss der Wert ein Variant-kompatibler Typ oder ein generischer T-Typ sein, der ebenfalls mit dem Attribut [MustBeVariant] versehen ist.

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