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¶

对于 Variant 的详细解释，请参阅 Variant 文档页面。

Godot.Variant is used to represent Godot's native Variant type. Any Variant-compatible type can be converted from/to it. We recommend avoiding Godot.Variant unless it is necessary to interact with untyped engine APIs. Take advantage of C#'s type safety when possible.

Converting from a Variant-compatible C# type to Godot.Variant can be done using implicit conversions. There are also CreateFrom method overloads and the generic Variant.From<T> methods. Only the syntax is different: the behavior is the same.

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

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

Implicit conversions to Godot.Variant make passing variants as method arguments very convenient. For example, the third argument of tween_property specifying the final color of the tween is a Godot.Variant.

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

Converting from Godot.Variant to a C# type can be done using explicit conversions. There are also Variant.As{TYPE} methods and the generic Variant.As<T> method. All of these behave the same.

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

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

备注

The Variant.As{TYPE} methods are typically named after C# types (Int32), not C# keywords (int).

If the Variant type doesn't match the conversion target type, the consequences vary depending on the source and target values.

The conversion may examine the value and return a similar but potentially unexpected value of the target type. For example, the string "42a" may be converted to the integer 42.
The default value of the target type may be returned.
An empty array may be returned.
An exception may be thrown.

Converting to the correct type avoids complicated behavior and should be preferred.

The Variant.Obj property returns a C# object with the correct value for any variant. This may be useful when the type of Variant is completely unknown. However, when possible, prefer more specific conversions. Variant.Obj evaluates a switch on Variant.VariantType and it may not be necessary. Also, if the result is a value type, it is boxed.

For example, if the potential for Variant.As<MyNode>() to throw an invalid cast exception isn't acceptable, consider using a Variant.As<GodotObject>() is MyNode n type pattern instead.

备注

Since the Variant type in C# is a struct, it can't be null. To create a "null" Variant, use the default keyword or the Godot.Variant parameterless constructor.

Variant 兼容类型¶

A Variant-compatible type can be converted to and from a Godot.Variant. These C# types are Variant-compatible:

除了 decimal 、 nint 和 nuint 之外，所有的内置值类型。
String 。
从 GodotObject 派生的类。
在 Godot.Collections 命名空间中定义的集合类型。

Variant 类型的完整列表及其对应的 C# 类型：

Variant.Type	C# 类型
`Nil`	`null` （不是类型）
`Bool`	`bool`
`Int`	`long` （Godot 在 Variant 中存储 64 位整数）
`Float`	`double` （Godot 在 Variant 中存储 64 位浮点数）
`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` 或其他派生类型。
`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[]`

警告

Godot uses 64-bit integers and floats in Variant. Smaller integer and float types such as int, short and float are supported since they can fit in the bigger type. Be aware that when a conversion is performed, using the wrong type will result in potential precision loss.

警告

枚举类型由于其底层类型是整数类型，因此都与 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.
}