Введение

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

Поддержка C# была введена в Godot 3.0. Из-за новизны, вы можете столкнуться с какими-то проблемами, или найти места где документация может быть улучшена. Пожалуйста сообщайте о проблемах с C# в Godot на странице движка на GitHub, а о проблемах с документацией на странице GitHub документации.

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

C# это высоко-уровневый язык программирования разработанный Microsoft. В Godot, он применён с использованием фреймворка Mono 5.x .NET, включающий поддержку C# 7.0. Mono - это реализация Microsoft .NET Framework с открытым исходным кодом, базирующаяся на стандартах ECMA для C# и Common Language Runtime(CLR). Для изучения его возможностей смотрите страницу Совместимость в документации Mono.

Примечание

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

Настройка C# для Godot

Windows

Download and install the latest version of Visual Studio (not Visual Studio Code), which contains utilities required to use C# in Godot. If you don’t plan on using the Visual Studio IDE, you can download just the Visual Studio Build Tools instead. Make sure you at least have the .NET Framework 4.5 targeting pack installed, you can get it using any of the installers mentioned above inside the «Individual components» tab.

macOS и Linux

Загрузите и установите последнюю версию Mono SDK. Начиная с Godot 3.1 beta 3, номер версии не играет роли, так как Godot поставляется с собственной сборкой Mono 5.18. Нам нужна Mono установка для NuGet и MSBuild которые нужны для использования C# в Godot.

Примечание

Для загрузки Mono на macOS, используйте ссылку на «Stable Channel» из Страницы Загрузок Mono. Канал Visual Studio это ранняя версия Mono которая не будет работать.

Дополнительные заметки

Ваша версия Godot должна иметь включенную поддержку Mono, так что убедитесь что скачали именно Mono версию Godot. Если вы собираете Godot из исходников, убедитесь что вы следовали инструкции по включению Mono в вашу сборку как описано на странице Compiling with Mono.

В итоге, вы должны иметь установленную Visual Studio или Mono (в зависимости от вашей операционной системы) и Mono-ориентированную версию Godot.

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

C# support in Godot’s script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or MonoDevelop. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Mono. Under Mono, click on Editor, and select your external editor of choice.

Примечание

Если вы используете Visual Studio Code, убедитесь что загрузили и установили C# расширение для включения подсветки синтаксиса и IntelliSense.

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

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

../../../_images/attachcsharpscript.png

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

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

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

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

Например, если вы создали скрипт (например, `` Test.cs``) и удалили его в Godot, компиляция завершится неудачно, поскольку ожидается, что отсутствующий файл все еще будет в файле проекта C #. На данный момент вы можете просто открыть файл `` .csproj`` и найти `` ItemGroup``, там должна быть строка, подобная следующей:

<ItemGroup>
    <Compile Include="Test.cs" />
    <Compile Include="AnotherTest.cs" />
</ItemGroup>

Просто удалите эту строку, и ваш проект должен снова компилироваться правильно. То же самое для переименования и перемещения, просто переименуйте и переместите их в файле проекта, если это необходимо.

Пример

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

using Godot;
using System;

public 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(float delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

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

Примечание

Keep in mind that the class you wish to attach to your node should have the same name as the .cs file. Otherwise, you will get the following error and won’t be able to run the scene: «Cannot find class XXX for script res://XXX.cs»

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

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

For more information, see the API differences to GDScript page.

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

Поскольку поддержка C# введена относительно недавно, в ней всё ещё присутствуют «детские болячки» и проблемы, которые необходимо устранить. Ниже вы найдёте список наиболее важных проблем, о существовании которых вам следовало бы знать, при использовании C# вместе с Godot. Если есть какие-то сомнения, вы также можете заглянуть на официальный трекер проблем/запросов Mono.

  • Как объяснялось выше, проект C# не всегда автоматически синхронизируется при удалении, переименовании или перемещении объектов в Godot (#12917).
  • Написание плагинов редактора возможно, но в настоящее время это довольно запутанно.
  • В данный момент, при выполнении горячей-перезагруки, состояние не сохраняется и не восстанавливается, за исключением экспортируемых переменных.
  • Экспорт Mono проектов доступен только для настольных платформ (Linux, Windows and macOS). Android, iOS, HTML5 и UWP в настоящий момент не поддерживаются (#20267, #20268 #20270 #20271).
  • Прикрепленные C# скрипты должны относиться к классу, который имеет имя класса, соответствующее имени файла.

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

According to some preliminary benchmarks, the performance of C# in Godot — while generally in the same order of magnitude — is roughly ~4× that of GDScript in some naive cases. C++ is still a little faster; the specifics are going to vary according to your use case. GDScript is likely fast enough for most general scripting workloads. C# is faster, but requires some expensive marshalling when talking to Godot.

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

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

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

Всякий раз, когда пакеты были добавлены или модифицированы, следует запусткать ``nuget restore``в корневой папке проекта. Чтобы убедиться, что пакеты NuGet будут доступны в msbuild, выполните:

msbuild /t:restore