Основы C#

Введение

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

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

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

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

Примечание

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

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

Требования

Установите последнюю стабильную версию .NET Core SDK (3.1 на момент написания).

Начиная с Godot 3.2.3 и далее, установка Mono SDK больше не является требованием, за исключением случаев, когда вы собираете движок из исходных текстов.

Godot объединяет части Mono, необходимые для запуска уже скомпилированных игр, однако Godot не включает инструменты, требуемые для сборки и компиляции игр, такие как MSBuild. Эти инструменты необходимо устанавливать отдельно. Требуемые инструменты включены в .NET Core SDK. MSBuild также включен в Mono SDK, но он не может создавать проекты C# с новым форматом csproj, поэтому для Godot 3.2.3+ требуется .NET Core SDK.

В итоге, у вас должны быть установлены .NET Core SDK и версия Godot с поддержкой Mono.

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

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

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

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

Godot имеет собственный редактор скриптов, его поддержка C# минимальна; вместо этого рекомендовано использовать отдельную IDE или редактор, такой как Visual Studio Code или MonoDevelop. Они поддерживают авто-завершение кода, отладку и другие возможности полезные при разработке на C#. Для установки их в Godot, кликните по Editor → Editor Settings и прокрутите вниз к настройкам Mono. Под Mono, кликните по Editor и выберите внешний редактор на выбор:

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio для MacOS

  • JetBrains rider

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

JetBrains rider

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

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

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

  • Установите Mono -> Builds -> Build Tool на dotnet CLI.

В Rider:

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

  • Установите плагин Godot support**(**Поддержка Godot).

Visual Studio Code

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

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

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

В Visual Studio Code:

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

  • Установите расширение Mono Debug .

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

Чтобы настроить проект для отладки, откройте папку Godot-проекта в Visual Studio Code. Перейдите на вкладку Run и нажмите create a launch.json file. В раскрывающемся меню выберите C# Godot. Теперь, когда вы запустите отладчик в VS Code, ваш проект Godot будет запущен.

Visual Studio (Только windows)

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

При установке Visual Studio, выберите эти нагрузки:

  • Мобильная разработка с .NET

  • Кросс-платформенная разработка .NET Core

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

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

Затем вам необходимо загрузить расширение Godot Visual Studio с github здесь. Дважды щелкните загруженный файл и следуйте процессу установки.

Создание 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 которая затем самовосстановится.

Пример

Это пустой 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.

Примечание

Помните, что класс, который вы хотите присоединить к вашему узлу, должен иметь то же имя, что и файл `` .cs``. В противном случае вы получите следующую ошибку и не сможете запустить сцену: «Не удается найти класс XXX для сценария res://XXX.cs»

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

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

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

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

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

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

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

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

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

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

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

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

Экспорт Mono проектов поддерживается для настольных платформ (Linux, Windows и macOS), Android, HTML5 и iOS. Единственная платформа, которая еще не поддерживается, - это UWP.

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

Согласно некоторым предварительным бенчмарк-тестам, производительность C# в Godot — пусть и находится в пределах одной величины — что приблизительно в ~4 раза выше, чем в GDScript в некоторых наивных случаях. Но C++ до сих пор немного быстрее; производительность будет зависеть от вашего варианта использования. Но помните, что быстродействия GDScript будет вполне достаточно для большинства основных задач по написанию сценариев. Хоть C# и производительнее, но он требует выполнение достаточно дорогостоящего маршалинга, когда речь заходит об использовании C# в Godot.

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

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

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

Начиная с Godot 3.2.3, Godot автоматически загружает и устанавливает недавно добавленные пакеты NuGet при следующей сборке проекта.

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