Написание скриптов в Godot на C#. Введение

Введение

Поддержка 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. Хорошей отправной точкой для проверки его возможностей является страница «Совместимость» в документации Mono.

ПРИМЕЧАНИЕ: Это не полномасштабное руководство по языку C# в целом. Если вы еще не знакомы с его синтаксисом или функциями, обратитесь к руководству по Microsoft C# или найдите подходящее введение в другом месте.

Установка C# в Godot

Скачайте и установите Mono SDK

Если вы используете Godot 3.0.2, вы должны будете скачать Mono 5.4.

Godot 3.0.3+ требует Mono 5.12 (на любой платформе)

ПРИМЕЧАНИЕ: Чтобы скачать Mono v5.12+ на Mac, найдите ссылку «Стабильный канал» на странице загрузок Mono. Канал Visual Studio является более ранней версией Mono и не будет работать с Godot 3.0.3+.

Вам также будет нужен MSBuild (по крайней мере, версия 15.0), который должен поставляться с Mono.

ПРИМЕЧАНИЕ: Инструкции по установке более старых версий Mono в Linux см. на этой странице. Более старые версии Mono для macOS и Windows можно найти здесь.

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

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

Таким образом, вы должны установить 1) правильную версию Mono SDK для вашей версии Godot и 2) версию Godot Mono.

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

Хотя у Godot есть собственный редактор скриптов, его поддержка C# поддерживается на минимальном уровне, и рекомендуется использовать внешнюю IDE или редактор, например Microsoft Visual Studio Code или MonoDevelop, которые предоставляют автозаполнение, отладку и другие полезные функции при работе с C#. Чтобы настроить его, в Godot нажмите «Редактор», затем «Настройки редактора». Прокрутите вниз до настроек «Mono». Под Mono нажмите «Редактор», и на этой странице выберите свой внешний редактор.

ПРИМЕЧАНИЕ: Если вы используете Visual Studio Code, убедитесь, что вы загрузили и установили расширение .NET tools. Без этого Godot получит ошибку при попытке создать новый проект или отредактировать скрипт на C#.

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

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

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

Создание проекта и процесс работы

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

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

Пример: если вы создали сценарий (например, Test.cs) и удалили его в Godot, компиляция завершится неудачно, поскольку теперь ожидается, что отсутствующий файл все еще будет находиться в проекте CS. Сейчас вы можете просто открыть файл .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.
    }
}

Как вы видите, вещи, которые обычно находятся в Global Scope в GDScript, такие как Godot функция print, доступны в пространстве имен GD. Список их см. на справочных страницах классов для @GDScript и @GlobalScope.

ПРИМЕЧАНИЕ: Имейте в виду, что класс, который вы хотите присоединить к вашему узлу, должен называться как файл .cs. В противном случае вы получите следующую ошибку и не сможете запустить сцену: «Cannot find class XXX for script res://XXX.cs.».

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

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

Для подробностей см. страницу API differences to GDScript

Текущие ошибки и известные проблемы

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

Как объяснялось выше, проект C # не всегда автоматически синхронизируется при удалении, переименовании или перемещении объектов в Godot (#12917)
Написание плагинов редактора и инструментальных скриптов на C# пока не поддерживается
Экспорт Mono проектов поддерживается только для настольных платформ (Linux, Windows и macOS). HTML5, Android, iOS и UWP в настоящее время не поддерживаются (#18364 comment)
Присоединенные сценарии C# должны ссылаться на класс, имя которого соответствует имени файла и является уникальным в сборке проекта. (#7402 comment) (от автора перевода: ну, для шарповцев это не новинка)

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

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

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

Пакеты Nuget можно устанавливать и использовать с Godot, как и в любом проекте. Многие IDE (такие как VS Code) могут добавлять пакеты напрямую. Их также можно добавить вручную, добавив ссылку на пакет в файле .csproj, расположенном в корне проекта:

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2"/> <— Вот так
    </ItemGroup>
    ...
</Project>

Всякий раз, когда пакеты добавляются или изменяются, запускайте восстановление NuGet в корне каталога проекта, и чтобы убедиться, что пакеты NuGet будут доступны для использования MSBuild, запустите:

$ msbuild /t:restore

Оригинал

Помочь в переводе официальной документации