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# сумісні з варіантами:

Повний список типів 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.
}