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# и 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.