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#

На этой странице представлен обзор наиболее часто используемых функций C# и Godot, а также того, как они используются вместе.

Преобразование и приведение типов

C# - это статически типизированный язык. Следовательно, вы не можете сделать следующее:

var mySprite = GetNode("MySprite");
mySprite.SetFrame(0);

Метод GetNode() возвращает экземпляр Node. Необходимо явно преобразовать его в нужный производный тип, в данном случае Sprite2D.

Для этого в C# имеются различные опции.

Приведение и проверка типа

Выдаёт исключение InvalidCastException, если возвращённый узел не может быть приведён к типу Sprite2D. Используйте его вместо оператора as, если вы уверены, что это не приведёт к ошибке.

Sprite2D mySprite = (Sprite2D)GetNode("MySprite");
mySprite.SetFrame(0);

** Использование оператора AS **

Оператор as возвращает null, если узел не может быть преобразован в Sprite2D, и по этой причине его нельзя использовать с типами значений.

Sprite2D mySprite = GetNode("MySprite") as Sprite2D;
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

** Использование универсальных методов **

Общие методы также предоставляются, чтобы сделать это преобразование типов прозрачным.

GetNode<T>() преобразует узел перед его возвратом. Он выдаст InvalidCastException, если узел не может быть приведен к нужному типу.

Sprite2D mySprite = GetNode<Sprite2D>("MySprite");
mySprite.SetFrame(0);

GetNodeOrNull<T>() использует оператор as и вернет null, если узел не может быть приведен к нужному типу.

Sprite2D mySprite = GetNodeOrNull<Sprite2D>("MySprite");
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

** Проверка типа с использованием оператора IS **

Чтобы проверить, можно ли преобразовать узел в Sprite2D, можно использовать оператор is. Оператор is возвращает false, если узел невозможно преобразовать в Sprite2D, в противном случае он возвращает true. Обратите внимание, что при использовании оператора is с null результат всегда будет false.

if (GetNode("MySprite") is Sprite2D)
{
    // Yup, it's a Sprite2D!
}

if (null is Sprite2D)
{
    // This block can never happen.
}

Вы также можете объявить новую переменную для условного сохранения результата приведения, если оператор is возвращает true.

if (GetNode("MySprite") is Sprite2D mySprite)
{
    // The mySprite variable only exists inside this block, and it's never null.
    mySprite.SetFrame(0);
}

Для более сложной проверки типов вы можете посмотреть в Сопоставление шаблонов.

Препроцессорные определения

Godot имеет набор определений, которые позволяют изменять код C# в зависимости от среды, в которую вы компилируете.

Примеры

Например, вы можете изменять код в зависимости от платформы:

    public override void _Ready()
    {
#if (GODOT_MOBILE || GODOT_WEB)
        // Use simple objects when running on less powerful systems.
        SpawnSimpleObjects();
#else
        SpawnComplexObjects();
#endif
    }

Или вы можете определить, в каком движке будет находиться ваш код, что полезно для создания кросс-движковых библиотек:

    public void MyPlatformPrinter()
    {
#if GODOT
        GD.Print("This is Godot.");
#elif UNITY_5_3_OR_NEWER
        print("This is Unity.");
#else
        throw new NotSupportedException("Only Godot and Unity are supported.");
#endif
    }

Или вы можете написать скрипты, ориентированные на несколько версий Godot, и воспользоваться функциями, которые доступны только в некоторых из этих версий:

    public void UseCoolFeature()
    {
#if GODOT4_3_OR_GREATER || GODOT4_2_2_OR_GREATER
        // Use CoolFeature, that was added to Godot in 4.3 and cherry-picked into 4.2.2, here.
#else
        // Use a workaround for the absence of CoolFeature here.
#endif
    }

Полный список определений

  • GODOT всегда объявлен в проектах Godot.

  • TOOLS определяется при сборке с конфигурацией отладки (редактор и проигрыватель редактора).

  • GODOT_REAL_T_IS_DOUBLE определяется, когда свойство GodotFloat64 установлено в значение true.

  • Один из GODOT_LINUXBSD, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_WEB в зависимости от ОС. В будущем эти названия могут измениться. Они создаются с помощью метода get_name() синглтона OS, но не каждая возможная ОС, возвращаемая методом, является ОС, на которой работает Godot с .NET.

  • GODOTX, GODOTX_Y, GODOTX_Y_Z, GODOTx_OR_GREATER, GODOTX_y_OR_GREATER и GODOTX_Y_z_OR_GREATER, где X, Y и Z заменяются текущими основными, второстепенными и патч-версиями Godot. x, y и z заменяются всеми значениями от 0 до текущего номера версии для этого компонента.

    Примечание

    Эти определения были впервые добавлены в Godot 4.0.4 и 4.1. Определения версий для предыдущих версий отсутствуют, независимо от текущей версии Godot.

    Например: Godot 4.0.5 определяет GODOT4, GODOT4_OR_GREATER, GODOT4_0, GODOT4_0_OR_GREATER, GODOT4_0_5, GODOT4_0_4_OR_GREATER и GODOT4_0_5_OR_GREATER. Godot 4.3.2 определяет GODOT4, GODOT4_OR_GREATER, GODOT4_3, GODOT4_0_OR_GREATER, GODOT4_1_OR_GREATER, GODOT4_2_OR_GREATER, GODOT4_3_OR_GREATER, GODOT4_3_2, GODOT4_3_0_OR_GREATER, GODOT4_3_1_OR_GREATER и GODOT4_3_2_OR_GREATER.

При экспорте также могут быть определены следующие параметры в зависимости от особенностей экспорта:

  • Один из GODOT_PC, GODOT_MOBILE, или GODOT_WEB в зависимости от типа платформы.

  • Один из GODOT_WINDOWS, GODOT_LINUXBSD, GODOT_MACOS, GODOT_ANDROID, GODOT_IOS или GODOT_WEB в зависимости от платформы.

Чтобы увидеть пример проекта, см. демонстрационную версию тестирования ОС: https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test