Основы C#

Введение

Эта страница содержит краткое введение в C# — что это такое и как использовать его в Godot. После прочтения вы можете изучить как использовать определённые возможности, прочитать о различиях между C# и GDScript API и (пере)посетить раздел Скриптинг в пошаговом руководстве.

C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with the modern .NET runtime.

Внимание

Проекты, написанные на C# с использованием Godot 4, в настоящее время не могут быть экспортированы на веб-платформу. Для использования C# на веб-платформе рассмотрите Godot 3. Поддержка платформ Android и iOS доступна, начиная с Godot 4.2, но является экспериментальной и имеет некоторые ограничения some limitations apply.

Примечание

Это не полномасштабное руководство по целому языку C#. Если вы не знакомы с его синтаксисом или возможностями, посмотрите Microsoft C# руководство или поищите подходящее введение где-нибудь ещё.

Требования

Godot bundles the parts of .NET needed to run already-compiled games. However, Godot does not bundle the tools required to build and compile games, such as MSBuild and the C# compiler. These are included in the .NET SDK, and need to be installed separately.

Таким образом, у вас должны быть установлены .NET SDK и версия Godot с поддержкой .NET.

Download and install the latest stable version of the SDK from the .NET download page. Godot 4.5 requires .NET 8 or later, but exporting to Android requires .NET 9 or later.

Важно

Обязательно установите 64-битную версию SDK, если вы используете 64-битную версию Godot.

Если вы собираете Godot из исходного кода, обязательно выполните шаги по включению поддержки .NET в вашей сборке, как описано на странице Компиляция с помощью .NET.

Настройка внешнего редактора

Поддержка C# во встроенном редакторе скриптов Godot минимальна. Рассмотрите возможность использования внешней IDE или редактора, например, Visual Studio Code или Visual Studio. Они обеспечивают автодополнение, отладку и другие полезные функции для C#. Чтобы выбрать внешний редактор в Godot, нажмите Editor → Editor Settings и прокрутите вниз до Dotnet. В разделе Dotnet нажмите Editor и выберите нужный внешний редактор. В настоящее время Godot поддерживает следующие внешние редакторы:

  • Visual Studio 2022

  • Visuаl Studio Code

  • MonоDevelop

  • Visual Studio для MacOS

  • JetBrains rider

См. cледующие разделы, чтобы узнать, как настроить внешний редактор:

JetBrains rider

Прочитав раздел «Предварительные требования», вы можете загрузить и установить JetBrains Rider.

В меню Редактор→ Настройки редактора Godot:

  • Установите Dotnet -> Editor -> External Editor на JetBrains Rider.

В Rider:

  • Установите MSBuild version на .NET Core.

  • Если вы используете Rider версии ниже 2024.2, установите плагин Godot support. Эта функция теперь встроена в Rider.

Visuаl Studio Code

После прочтения раздела "Предварительные условия" вы можете загрузить и установить ` Visual Studio Code <https://code.visualstudio.com/download>`__ (он же VS Code).

В меню Редактор→ Настройки редактора Godot:

  • Установите Dotnet -> Editor -> External Editor на Visual Studio Code.

В Visual Studio Code:

  • Установите расширение C# .

Чтобы настроить проект для отладки, вам понадобятся файлы tasks.json и launch.json в папке .vscode с необходимой конфигурацией.

Вот пример launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Play",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${env:GODOT4}",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
        }
    ]
}

Чтобы эта конфигурация запуска работала, вам необходимо либо настроить переменную среды GODOT4, указывающую на исполняемый файл Godot, либо заменить параметр program на путь к исполняемому файлу Godot.

Вот пример tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": [
                "build"
            ],
            "problemMatcher": "$msCompile"
        }
    ]
}

Теперь при запуске отладчика в Visual Studio Code ваш проект Godot будет запущен.

Visual Studio (Только windows)

Загрузите и установите последнюю версию Visual Studio <https://visualstudio.microsoft.com/downloads/>`__. Visual Studio будет включать необходимые SDK, если у вас выбраны правильные рабочие нагрузки, поэтому вам не нужно вручную устанавливать вещи, перечисленные в разделе "Предварительные условия".

При установке Visual Studio выберите следующую рабочую нагрузку:

  • Разработка настольных приложений .NET

В меню Редактор→ Настройки редактора Godot:

  • Установите Dotnet -> Editor -> External Editor на Visual Studio.

Примечание

Если вы видите ошибку типа "Не удалось найти пакет Godot.NET.Sdk", возможно, ваша конфигурация NuGet неверна и ее необходимо исправить.

Простой способ исправить файл конфигурации NuGet - его восстановление. На вашем проводнике, перейдите к директорию %AppData%\NuGet. Переименуйте или удалите файл NuGet.Config`. При повторной сборки проекта Godot, файл будет автоматически создан с стардартными значениями.

Чтобы отладить ваши C# скрипты с использованием Visual Studio, откройте файл .sln, который создается после открытия первого C# скрипта в редакторе. В меню Отладка перейдите к элементу меню Свойства отладки для вашего проекта. Нажмите кнопку Создать новый профиль и выберите Исполняемый файл. В поле Исполняемый файл укажите путь к версии редактора Godot для C#, или введите %GODOT4%, если вы создали переменную среды для пути к исполняемому файлу Godot. Это должен быть путь к основному исполняемому файлу Godot, а не к 'консольной' версии. В поле Рабочая директория введите одну точку, ., что означает текущую директорию. Также отметьте чекбокс Включить отладку нативного кода. Теперь вы можете закрыть это окно, нажать на стрелку вниз в выпадающем списке профилей отладки и выбрать ваш новый профиль запуска. Нажмите на зеленую кнопку старт, и ваша игра начнет запускаться в режиме отладки.

Создание C# скрипта

После успешной настройки C# в Godot, вы должны увидеть новую опцию выбора — из контекстного меню прикрепляемого к сцене скрипта:

../../../_images/attachcsharpscript.webp

Обратите внимание, что, несмотря на некоторые изменения в деталях, большинство концепций остаются неизменными при использовании C# для написания скриптов. Если вы новичок в Godot, на данном этапе вам могут быть интересны руководства по Скриптовые языки. Хотя на некоторых страницах документации всё ещё отсутствуют примеры на C#, большинство концепций можно перенести из GDScript.

Настройка проекта и рабочего процесса

При создании первого скрипта C# Godot инициализирует файлы проекта C# для вашего проекта Godot. Это включает в себя генерацию решения C# (.sln) и файла проекта (.csproj), а также некоторых служебных файлов и папок (.godot/mono). Все эти файлы, кроме .godot/mono, важны и должны быть сохранены в вашей системе контроля версий. Все файлы в папке .godot можно безопасно добавить в список игнорируемых вашей системы контроля версий (VCS). При устранении неполадок иногда может помочь удаление папки .godot/mono и её повторная сгенерация.

Пример

Это пустой C# скрипт с некоторыми комментариями, чтобы продемонстрировать, как он работает.

using Godot;

public partial class YourCustomClass : Node
{
    // Member variables here, example:
    private int _a = 2;
    private string _b = "textvar";

    public override void _Ready()
    {
        // Called every time the node is added to the scene.
        // Initialization here.
        GD.Print("Hello from C# to Godot :)");
    }

    public override void _Process(double delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

Как видите, функции, обычно находящиеся в глобальной области видимости в GDScript, такие как функция print в Godot, доступны в статическом классе GD, который является частью пространства имён Godot. Полный список методов класса GD см. на страницах с описанием классов @GDScript и @GlobalScope.

Примечание

Имейте в виду, что класс, который вы хотите прикрепить к своему узлу, должен иметь то же имя, что и файл .cs. В противном случае вы получите следующую ошибку:

"Не удалось найти класс XXX для скрипта res://XXX.cs"

Основные различия между C# и GDScript

В языке C# всё API использует стиль записи PascalCase вместо snake_case, принятого в GDScript/C++. Поля и getters/setters представленны в виде свойств, там где это допустимо. В целом, Godot API на C# стримится быть наиболее наглядным, насколько это возможно.

За дополнительно информацией, обратитесь к странице: API различия C# и GDScript.

Предупреждение

Вам необходимо (пере)собрать сборки проекта, чтобы увидеть новые экспортированные переменные или сигналы в редакторе. Эту сборку можно запустить вручную, нажав кнопку Build в правом верхнем углу редактора.

../../../_images/build_dotnet.webp

Вам также потребуется перестроить сборки проекта, чтобы применить изменения в скриптовых "инструментах".

Текущие ограничения и известные проблемы

Поскольку поддержка C# в Godot появилась сравнительно недавно, существуют некоторые трудности и проблемы, требующие решения. Ниже представлен список наиболее важных проблем, о которых следует знать при освоении C# в Godot. Если же у вас есть сомнения, ознакомьтесь с официальным трекером проблем .NET.

  • Написание плагинов для редактора возможно, но в настоящее время это довольно затруднительно.

  • В данный момент, при выполнении горячей-перезагруки, состояние не сохраняется и не восстанавливается, за исключением экспортируемых переменных.

  • Прикрепленные C# скрипты должны относиться к классу, который имеет имя класса, соответствующее имени файла.

  • Некоторые методы, такие как Get()/Set(), Call()/CallDeferred() и метод подключения сигнала Connect(), основаны на соглашениях об именовании API Godot snake_case. Поэтому при использовании, например, CallDeferred("AddChild"), AddChild не будет работать, поскольку API ожидает исходную версию snake_case add_child. Однако вы можете использовать любые пользовательские свойства или методы без этого ограничения. Предпочтительнее использовать открытое StringName в PropertyName, MethodName и SignalName, чтобы избежать лишних выделений StringName и беспокойства об именовании в стиле snake_case.

Начиная с Godot 4.0, экспорт проектов .NET поддерживается для настольных платформ (Linux, Windows и macOS). Поддержка других платформ появится в будущих версиях 4.x.

Распространенные ошибки

При попытке изменить некоторые значения в объектах Godot, например, при попытке изменить координату X Node2D, вы можете столкнуться со следующей ошибкой:

public partial class MyNode2D : Node2D
{
    public override void _Ready()
    {
        Position.X = 100.0f;
        // CS1612: Cannot modify the return value of 'Node2D.Position' because
        // it is not a variable.
    }
}

Это совершенно нормально. Структуры (в данном примере Vector2) в C# копируются при присваивании, то есть при извлечении такого объекта из свойства или индексатора вы получаете его копию, а не сам объект. Изменение этой копии без последующего переприсваивания ни к чему не приведёт.

Обходной путь прост: извлеките всю структуру, измените значение, которое вы хотите изменить, и переназначьте свойство.

var newPosition = Position;
newPosition.X = 100.0f;
Position = newPosition;

Начиная с C# 10, можно также использовать with выражения в структурах, что позволяет делать то же самое в одной строке.

Position = Position with { X = 100.0f };

Подробнее об этой ошибке можно прочитать в Справочнике по языку C#.

Производительность C# в Godot

См. также

Сравнение производительности языков, поддерживаемых Godot, см. в разделе Какой язык программирования самый быстрый?.

Большинство свойств объектов Godot C#, основанных на GodotObject (например, любой Node, например Control, или Node3D, например Camera3D), требуют собственных (interop) вызовов при взаимодействии с ядром Godot C++. Рассмотрите возможность присвоения значений таких свойств локальной переменной, если вам нужно изменять или считывать их несколько раз в одном месте кода:

using Godot;

public partial class YourCustomClass : Node3D
{
    private void ExpensiveReposition()
    {
        for (var i = 0; i < 10; i++)
        {
            // Position is read and set 10 times which incurs native interop.
            // Furthermore the object is repositioned 10 times in 3D space which
            // takes additional time.
            Position += new Vector3(i, i);
        }
    }

    private void Reposition()
    {
        // A variable is used to avoid native interop for Position on every loop.
        var newPosition = Position;
        for (var i = 0; i < 10; i++)
        {
            newPosition += new Vector3(i, i);
        }
        // Setting Position only once avoids native interop and repositioning in 3D space.
        Position = newPosition;
    }
}

Передача необработанных массивов (таких как byte[]) или string в C# API Godot требует маршалинга, который является сравнительно затратным.

Неявное преобразование из string в NodePath или StringName влечет за собой затраты как на собственное взаимодействие, так и на маршалинг, поскольку string необходимо маршалировать и передавать соответствующему собственному конструктору.

Использование пакетов NuGet в Godot

NuGet пакеты могут быть установлены и использованы вместе с Godot, как и в любом другом C# проекте. Множество IDE способны добавлять пакеты напрямую. Если необходимо, вы можете добавить их вручную, добавив ссылку на пакет в .csproj файл, который расположен в корне проекта:

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
    </ItemGroup>
    ...
</Project>

Godot automatically downloads and sets up newly added NuGet packages the next time it builds the project.

Профилирование вашего C# кода

Для профилирования производительности и памяти управляемого кода можно использовать следующие инструменты:

  • JetBrains Rider с плагином dotTrace/dotMemory.

  • Автономный JetBrains dotTrace/dotMemory.

  • Visual Studio.

Одновременное профилирование управляемого и неуправляемого кода возможно как с помощью инструментов JetBrains, так и с помощью Visual Studio, но ограничено Windows.