Основы 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

Windows (Visual Studio)

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.

Windows (JetBrains Rider)

JetBrains Rider поставляется в комплекте с MSBuild, так что ничего лишнего не требуется. Обязательно установите следующие настройки:

  • В настройках редактора Godot:

    • Установите Mono External Editor на JetBrains Rider.
    • выставьте Mono Build Tool на JetBrains Mono.
  • В Rider:

    • Установите MSBuild version либо в комплекте с Rider, либо с .NET Core.
    • Установите плагин Godot support**(**Поддержка Godot).

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.

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

В то время как 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

Примечание

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

Примечание

Если вы используете Visual Studio 2019, вам необходимо следовать инструкциям, приведенным в разделе`:ref: настройка C# в VS 2019 для дебаггинга doc_c_sharp_configuring_vs_2019_for_debugging` ниже.

Создание 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 различия С# и GDScript.

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

Чтобы видеть новые экспортируемые переменные и сигналы в редакторе, вам необходимо каждый раз (пере)собирать C#-проект. Эта сборка может быть запущена нажатием на Mono, в нижней части окна редактора; в открытой Mono Panel (Панели 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``. Однако вы можете использовать любые пользовательские свойства или методы без этого ограничения.

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

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

Согласно некоторым предварительным`бенчмарк-тестам <https://github.com/cart/godot3-bunnymark>`_, производительность 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</Version>
        </PackageReference>
    </ItemGroup>
    ...
</Project>

Примечание

По умолчанию, утилиты вроде NuGet в качестве атрибута для `PackageReference` используют Version. Вы должны создать узел Version вручную как показано выше. Это требуется используемой версией MSBuild. (Будет исправлено в Godot 4.0.)

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

msbuild /t:restore

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

  • Mono log profiler (Mono профайлер логов) <https://www.mono-project.com/docs/debug+profile/profile/profiler/> _ доступен для Linux и macOS. Из-за изменения Mono, он не работает на Windows на данный момент.
  • Внешний моно-профилировщик, такой как JetBrains dotTrace <https://www.jetbrains.com/profiler/> _, можно использовать, как описано здесь <https://github.com/godotengine/godot/pull/34382> _.

Настройка VS 2019 для отладки

Примечание

Godot имеет встроенную поддержку рабочих процессов с участием нескольких популярных C# IDE. Встроенная поддержка Visual Studio будет включена в будущие версии, но пока что приведенные ниже шаги могут позволить вам настроить VS 2019 для использования с проектами Godot C#.

  1. Установите VS 2019 с выбранными рабочими нагрузками .NET desktop development и Desktop development with C++.
  2. Убедитесь, что у вас не установлен Xamarin. Не выбирайте рабочую нагрузку Mobile development with .NET. Xamarin изменяет DLLs, используемые MonoDebugger, что нарушает отладку.
  3. Установите расширение VSMonoDebugger.
  4. В VS 2019 --> Extensions --> Mono --> Settings:
    • Выберите Debug/Deploy to local Windows.
    • Оставьте пустым Local Deploy Path.
    • Установите Mono Debug Port в порт в Godot --> Project --> Project Settings --> Mono --> Debugger Agent.
    • Также выберите Wait for Debugger в настройках Godot Mono. Этот аддон для Godot может быть полезен.
  5. Запустите игру в Godot. Она должна зависнуть на заставке Godot в ожидании подключения вашего отладчика.
  6. В VS 2019 откройте свой проект и выберите Extensions --> Mono --> Attach to Mono Debugger.

Настройка Visual Studio Code для отладки (дебаггинга)

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