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.

Godot.Variant використовується для представлення рідного типу Godot Variant. Будь-який Variant-compatible type можна конвертувати з/в нього. Ми рекомендуємо уникати Godot.Variant, якщо не потрібно взаємодіяти з нетиповими API механізму. Скористайтеся перевагами захисту типів 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 роблять передачу варіантів як аргументів методу дуже зручною. Наприклад, третій аргумент 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# (Int32), а не за ключовими словами C# (int).

Якщо тип варіанту не відповідає цільовому типу конверсії, наслідки залежать від вихідного та цільового значень.

Перетворення може перевіряти значення та повертати подібне, але потенційно неочікуване значення цільового типу. Наприклад, рядок "42a" можна перетворити на ціле число 42.
Може бути повернуто значення за замовчуванням цільового типу.
Може бути повернуто порожній масив.
Може бути виняток.

Перетворення на правильний тип дозволяє уникнути складної поведінки, тому йому слід надавати перевагу.

Властивість Variant.Obj повертає об’єкт C# з правильним значенням для будь-якого варіанту. Це може бути корисним, коли тип варіанту абсолютно невідомий. Однак, коли це можливо, віддайте перевагу більш конкретним перетворенням. Variant.Obj оцінює перемикач на Variant.VariantType, і це може не знадобитися. Крім того, якщо результат є типом значення, він поміщається в рамку.

Наприклад, якщо можливість Variant.As<MyNode>() викликати недійсний виняток приведення є неприйнятною, розгляньте можливість використання Variant.As<GodotObject>() є MyNode n шаблон типу замість цього.

Примітка

Оскільки тип Variant у C# є структурою, він не може бути нульовим. Щоб створити «нульовий» варіант, використовуйте ключове слово default або Godot.Variant конструктор без параметрів.

Типи, сумісні з варіантами

Тип, сумісний з Variant, можна конвертувати в Godot.Variant і з нього. Ці типи C# сумісні з варіантами:

Усі вбудовані типи значень, крім decimal , nint і nuint.
string.
Похідні класи GodotObject.
Типи колекцій, визначені в просторі імен Godot.Collections.

Повний список типів Variant і їх еквівалентного типу C#:

Варіант.Тип	Тип C#
`Nil`	`null` (Не тип)
`Bool`	`bool`
`Int`	`long` (Godot зберігає 64-розрядні цілі числа у Variant)
`Float`	`double` (Godot зберігає 64-бітні числа з плаваючою точкою у 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` або будь-який похідний тип.
`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[]`
`PackedVector4Array`	`Godot.Vector4[]`
`PackedColorArray`	`Godot.Color[]`

Попередження

Godot використовує 64-розрядні цілі числа та числа з плаваючою точкою у Variant. Підтримуються менші цілі числа та типи з плаваючою точкою, такі як 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 лише одним із типів, сумісних з варіантами. Цього можна досягти за допомогою атрибута [MustBeVariant].

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

У поєднанні з узагальненим Variant.From<T> дозволяє отримати екземпляр Godot.Variant з екземпляра узагальненого типу T. Потім його можна використовувати в будь-якому API, який підтримує лише структуру Godot.Variant.

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, або загальним типом T, анотованим [MustBeVariant] атрибут також.

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