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

Требования

Install the latest stable version of the .NET SDK, previously known as the .NET Core SDK.

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

Godot bundles the parts of Mono 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, which needs to be installed separately.

In summary, you must have installed the .NET SDK and the Mono-enabled version of Godot.

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

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

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

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

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

  • Visuаl Studio 2019

  • Visuаl Studio Code

  • MonоDevelop

  • 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).

Visuаl Studio Code

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

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

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

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

В Visual Studio Code:

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

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

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

Примечание

Если вы используете Linux, вам необходимо установить `Mono SDK <https://www.mono-project.com/download/stable/#download-lin> `__ для работы плагина инструментов C#.

Чтобы сконфигурировать проект для отладки, откройте папку проекта Godot в VS Code. Перейдите на вкладку Run и нажмите на Add Configuration.... Выберите C# Godot из выпадающего меню. Откройте созданные файлы tasks.json и launch.json. Измените настройки исполняемого файла в launch.json и команды в tasks.json на путь к исполняемому файлу 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.

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

Next, you can download the Godot Visual Studio extension from github here. Double click on the downloaded file and follow the installation process.

Примечание

The option to debug your game in Visual Studio may not appear after installing the extension. To enable debugging, there is a workaround for Visual Studio 2019. There is a separate issue about this problem in Visual Studio 2022.

Примечание

If you see an error like "Unable to find package Godot.NET.Sdk", your NuGet configuration may be incorrect and need to be fixed.

A simple way to fix the NuGet configuration file is to regenerate it. In a file explorer window, go to %AppData%\NuGet. Rename or delete the NuGet.Config file. When you build your Godot project again, the file will be automatically created with default values.

Создание 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, такие как функция Godot 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# кода