C# basics

Вступ

Попередження

Підтримка C# - це нова функція, доступна з Godot 3.0. Таким чином, ви все ще можете зіткнутися з деякими проблемами, або знайти місця, де можна було б удосконалити документацію. Будь ласка, повідомте про проблеми з C# у Godot на сторінці движка GitHub, та про будь-які проблеми з документацією на `сторінці документації GitHub<https://github.com/godotengine/godot-docs/issues>`_.

На цій сторінці подано короткий вступ до C#, що це таке, та як його використовувати в Godot. Після цього, можливо, ви захочете ознайомитись із використанням конкретних функцій, прочитати про відмінності між C# та API GDScript та (повторно) переглянути розділ створення скриптів покрокового підручника.

C# - мова програмування високого рівня, розроблена Microsoft. У Godot вона реалізована за допомогою Mono 6.x .NET, включаючи повну підтримку C# 8.0. Mono - це реалізація .NET Framework від Microsoft з відкритим кодом, яка базується на стандартах ECMA для C# та Common Language Runtime (Загальномовне Виконуюче Середовище). Гарною відправною точкою для перевірки його можливостей є сторінка `сумісності<http://www.mono-project.com/docs/about-mono/compatibility/>`_ в документації Mono.

Примітка

Це не повномасштабний підручник з мови C#. Якщо ви ще не знайомі з її синтаксисом, або можливостями, перегляньте посібник Microsoft C# або знайдіть відповідний вступ у іншому місці.

Налаштування C# для Godot

Prerequisites

Install the latest stable version of .NET Core SDK (3.1 as of writing).

From Godot 3.2.3 onwards, installing Mono SDK is not a requirement anymore, except it is required if you are building the engine from source.

Godot bundles the parts of Mono needed to run already compiled games, however Godot does not include the tools required to build and compile games, such as MSBuild. These tools need to be installed separately. The required tools are included in the .NET Core SDK. MSBuild is also included in the Mono SDK, but it can't build C# projects with the new csproj format, therefore .NET Core SDK is required for Godot 3.2.3+.

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

Додаткові примітки

Be sure to install the 64-bit version of the SDK(s) if you are using the 64-bit version of Godot.

If you are building Godot from source, install the latest stable version of Mono, and make sure to follow the steps to enable Mono support in your build as outlined in the Compiling with Mono page.

Налаштування зовнішнього редактора

C# support in Godot's built-in 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. Godot currently supports the following external editors:

  • Visual Studio 2019

  • Visual Studio або VS Code

  • MonoDevelop

  • Visual Studio для Mac

  • JetBrains Rider

See the following sections for how to configure an external editor:

JetBrains Rider

After reading the "Prerequisites" section, you can download and install JetBrains Rider.

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to JetBrains Rider.

  • Set Mono -> Builds -> Build Tool to dotnet CLI.

In Rider:

  • Set MSBuild version to .NET Core.

  • Install the Godot support plugin.

Visual Studio або VS Code

After reading the "Prerequisites" section, you can download and install Visual Studio Code (aka VS Code).

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio Code.

In Visual Studio Code:

Next, follow the instructions found in the Configuring Visual Studio Code for debugging section below.

Visual Studio (Windows only)

Download and install the latest version of Visual Studio. Visual Studio will include the required SDKs if you have the correct workloads selected, so you don't need to manually install the things listed in the "Prerequisites" section.

While installing Visual Studio, select these workloads:

  • Mobile development with .NET

  • .NET Core cross-platform development

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio.

Next, follow the instructions found in the Налаштування VS 2019 для налагодження section below.

Створення скрипту C#

After you successfully set up C# for Godot, you should see the following option when selecting Attach Script in the context menu of a node in your scene:

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

Зауважте, що хоча деякі специфіки змінилися, більшість концепцій, при використанні C# для скриптів, залишаються тими самими. Якщо ви новачок у Godot, ви, можливо, захочете познайомитися із уроками Скриптинґ. Хоча в деяких місцях документації ще не вистачає прикладів C#, більшість концепцій можна легко перенести з GDScript.

Налаштування проєкту та робочий процес

Під час створення першого скрипту C# Godot ініціалізує файли проєкту C# для вашого проєкту Godot. Сюди входить генерація рішення 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. В іншому випадку ви отримаєте таку помилку, і не зможете запустити сцену: "Cannot find class XXX for script res://XXX.cs" ("Неможливо знайти клас XXX для скрипту res://XXX.cs")

Основні відмінності між C# і GDScript

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

Для отримання додаткової інформації дивіться сторінку C# API differences to GDScript.

Попередження

You need to (re)build the project assemblies whenever you want to see new exported variables or signals in the editor. This build can be manually triggered by clicking the word Mono at the bottom of the editor window to reveal the Mono panel, then clicking the Build Project button.

You will also need to rebuild the project assemblies to apply changes in "tool" scripts.

Поточні обмеження та відомі проблеми

Оскільки підтримка C# є абсолютно новою у Godot, є деякі дитячі болячки та речі, які потрібно випрасувати. Нижче наведено перелік найважливіших проблем, про які слід пам'ятати при використанні C# в Godot, але якщо ви сумніваєтесь, перегляньте офіційний випуск трекера для випусків Mono.

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

  • Наразі стан не зберігається та не відновлюється під час гарячого перезавантаження, за винятком експортованих змінних.

  • Вкладені скрипти C# повинні стосуватися класу, який має ім'я класу, яке відповідає імені файлу.

  • Існують деякі методи, такі як Get()/Set(), Call()/CallDeferred() і метод з'єднання сигналів Connect(), які покладаються на умови іменування API Godot snake_case. Тому при використанні, наприклад CallDeferred("AddChild"), AddChild не буде працювати, оскільки API очікує версію snake_case, тобто add_child. Однак ви можете використовувати будь-які власні властивості, або методи, без цього обмеження.

Exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not supported yet is UWP.

Продуктивність C# у Godot

Згідно з деякими попередніми benchmarks, ефективність C# в Godot - хоча в цілому тої самої величини - в деяких наївних випадках приблизно в 4-ри рази вище, ніж у GDScript. C++ все ще трохи швидший; характеристики залежать від Вашого випадку використання. GDScript, ймовірно, досить швидкий для більшості загальних скриптів. C# швидше, але вимагає дорогого марширування в діалозі з Godot.

Використання пакетів Nuget у Godot

Пакети `NuGet<https://www.nuget.org/>`_ можна встановлювати та використовувати з Godot, як і будь-який проєкт C#. Багато IDE можуть додавати пакети безпосередньо. Їх також можна додати вручну, додавши посилання на пакет у файл .csproj, що знаходиться в корені проєкту:

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

Примітка

За замовчуванням такі інструменти, як NuGet, ставлять Version як атрибут Вузла```PackageReference```. Ви повинні створити Version вузла вручну, як показано вище. Це тому, що використовувана версія MSBuild вимагає цього. (Це буде виправлено в Godot 4.0.)

Кожного разу, коли пакети додаються, чи змінюються, запустіть nuget restore (не dotnet restore) у корені каталогу проєкту. Щоб переконатися, що пакети NuGet будуть доступні для msbuild для використання, запустіть:

msbuild /t:restore

Профілювання коду C #

Налаштування 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 змінює DLL, використовувані MonoDebugger, що порушує налагодження.

  3. Встановіть розширення VSMonoDebugger.

  4. У VS 2019 --> Extensions --> Mono --> Settings (VS 2019 -> Розширення -> Моно -> Налаштування):

    • Виберіть Debug/Deploy to local Windows.

    • Залиште порожнім Local Deploy Path.

    • Встановіть Mono Debug Port порт у Godot --> Проєкт --> Параметри проєкту --> Mono --> Debugger Agent.

    • Виберіть також Wait for Debugger в параметрах Godot Mono. Цей Godot Addon може бути корисним.

  5. Запустіть гру в Godot. Він повинен висіти на екрані привітання Godot, поки він чекає, коли ваш налагоджувач прикріпиться.

  6. У VS 2019 відкрийте проєкт та виберіть Extensions --> Mono --> Attach to Mono Debugger (Розширення -> Моно -> Приєднати до Mono Debugger).

Configuring Visual Studio Code for debugging

To configure debugging, open Visual Studio Code and download the Mono Debug extension from Microsoft and the Godot extension by Ignacio. Then open the Godot project folder in VS Code. Go to the Run tab and click on create a launch.json file. Select C# Godot from the dropdown menu. Now, when you start the debugger in VS Code your Godot project will run.