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...
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 Typsicherheit von C#.
Die Konvertierung von einem Variant-kompatiblen C#-Typ nach Godot.Variant
kann durch implizite Konvertierungen erfolgen. Es gibt auch CreateFrom
Methodenüberladungen und die generischen Variant.From<T>
Methoden. Nur die Syntax ist anders: das Verhalten ist das gleiche.
int x = 42;
Variant numberVariant = x;
Variant helloVariant = "Hello, World!";
Variant numberVariant2 = Variant.CreateFrom(x);
Variant numberVariant3 = Variant.From(x);
Implizite Konvertierungen in Godot.Variant
machen die Übergabe von Varianten als Methodenargumente sehr bequem. Zum Beispiel ist das dritte Argument von tween_property, das die endgültige Farbe des Tweens angibt, eine Godot.Variant
.
Tween tween = CreateTween();
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
Die Konvertierung von Godot.Variant
in einen C#-Typ kann durch explizite Konvertierungen erfolgen. Es gibt auch Variant.As{TYPE}
Methoden und die generische Variant.As<T>
Methode. Alle diese Methoden verhalten sich gleich.
int number = (int)numberVariant;
string hello = (string)helloVariant;
int number2 = numberVariant.As<int>();
int number3 = numberVariant.AsInt32();
Bemerkung
Die Variant.As{TYPE}
-Methoden sind typischerweise nach C#-Typen benannt (Int32
), nicht nach C#-Schlüsselwörtern (int
).
Wenn der Typ der Variante nicht mit dem Typ des Konvertierungsziels übereinstimmt, hat dies je nach Quell- und Zielwert unterschiedliche Folgen.
Die Konvertierung kann den Wert untersuchen und einen ähnlichen, aber möglicherweise unerwarteten Wert des Zieltyps zurückgeben. Zum Beispiel kann der String
"42a"
in die Integer-Zahl42
konvertiert werden.Der Defaultwert des Zieltyps kann zurückgegeben werden.
Ein leeres Array kann zurückgegeben werden.
Eine Exception kann ausgelöst werden.
Die Konvertierung in den richtigen Typ vermeidet kompliziertes Verhalten und sollte bevorzugt werden.
Die Property Variant.Obj
gibt ein C# Objekt
mit dem korrekten Wert für jede Variante zurück. Dies kann nützlich sein, wenn der Typ der Variante völlig unbekannt ist. Wenn möglich, sollten Sie jedoch spezifischere Konvertierungen bevorzugen. Variant.Obj
führt einen Switch
auf Variant.VariantType
aus und das ist vielleicht nicht notwendig. Wenn das Ergebnis ein Wertetyp ist, wird es außerdem in einen Rahmen gesetzt.
Wenn zum Beispiel die Möglichkeit, dass Variant.As<MyNode>()
eine ungültige Cast-Ausnahme auslöst, nicht akzeptabel ist, sollten Sie stattdessen ein Pattern vom Typ Variant.As<GodotObject>() is MyNode n
verwenden.
Bemerkung
Da der Variant-Typ in C# ein Struct ist, kann er nicht null sein. Um eine "null"-Variante zu erzeugen, verwenden Sie das Schlüsselwort default
oder den parameterlosen Konstruktor Godot.Variant
.
Variantenkompatible Typen
Ein Variant-kompatibler Typ kann in und aus einer Godot.Variant
konvertiert werden. Diese C#-Typen sind Variant-kompatibel:
Alle Built-in-Werttypen außer
decimal
,nint
undnuint
.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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 wenn eine Konvertierung durchgeführt wird, 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.
}