Основи C#

Вступ

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

Підтримка 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

Передумови

Встановіть останню стабільну версію .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 у вашій збірці, як зазначено на сторінці Compiling with Mono.

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

Підтримка C# в редакторі скриптів Godot мінімальна. Подумайте про використання зовнішнього IDE, або редактора, наприклад `Visual Studio Code<https://code.visualstudio.com/>`_ або MonoDevelop. Вони забезпечують автоматичне завершення, налагодження та інші корисні функції для C#. Щоб вибрати зовнішній редактор у Godot, натисніть Редактор → Параметри редактора та прогорніть униз до Mono. У розділі Mono натисніть на **Editor**(Редактор) та виберіть зовнішній редактор на вибір. На даний момент Godot підтримує такі зовнішні редактори:

  • Visual Studio 2019

  • Visual Studio або VS Code

  • MonoDevelop

  • Visual Studio для Mac

  • JetBrains Rider

Перегляньте наступні розділи, щоб дізнатися, як налаштувати зовнішній редактор:

JetBrains Rider

Прочитавши розділ "Передумови", ви можете завантажити та встановити JetBrains Rider.

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

  • Встановіть Mono -> Editor -> External Editor на JetBrains Rider.

  • Встановіть Mono -> Builds -> Build Tool на dotnet CLI.

В Rider:

  • Встановіть MSBuild version на .NET Core.

  • Встановіть плагін Godot support.

Visual Studio або VS Code

Прочитавши розділ "Передумови", ви можете завантажити та встановити Visual Studio Code (він же VS Code).

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

  • Встановіть Mono -> Editor -> External Editor**на **Visual Studio Code.

В Visual Studio Code:

  • Встановіть розширення C#.

  • Встановіть розширення Mono Debug.

  • Встановіть розширення C# Tools for Godot.

Щоб налаштувати проєкт для налагодження, відкрийте папку проєкту Godot у VS Code. Перейдіть на вкладку Виконати і натисніть на створити файл launch.json. Виберіть C# Godot з спливаючого меню. Тепер ваш проєкт Godot буде запущений, коли ви запускаєте налагоджувач у VS Code.

Visual Studio (тільки Windows)

Завантажте та встановіть останню версію Visual Studio. Visual Studio включатиме необхідні пакети SDK, якщо ви вибрали правильні робочі навантаження, тому вам не потрібно вручну встановлювати речі, перелічені в розділі "Передумови".

Під час встановлення Visual Studio виберіть такі робочі навантаження:

  • Мобільна розробка за допомогою .NET

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

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

  • Встановіть Mono -> Editor -> External Editor на Visual Studio.

Далі вам потрібно завантажити розширення Godot Visual Studio з github тут. Двічі клацніть на завантажений файл і виконайте процес встановлення.

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

Після того, як ви успішно налаштували C# для Godot, ви повинні побачити наступну опцію при виборі Attach Script у контекстному меню вузла на вашій сцені:

../../../_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 прагне бути максимально ідіоматичним, наскільки це можливо.

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

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

Вам потрібно (пере)збирувати збірки проєктів кожен раз, коли ви хочете бачити нові змінні експорту, чи сигнали в редакторі. Цю збірку можна вручну запустити, натиснувши слово Build у верхньому правому куті редактора. Ви також можете натиснути Mono внизу вікна редактора, щоб відкрити панель Mono, а потім натиснути кнопку Build Project.

Вам також потрібно буде перезбирувати збірки проєктів, щоб застосувати зміни в скриптах "інструментів".

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

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

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

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

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

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

Експорт проєктів Mono підтримується лише для настільних платформ (Linux, Windows та macOS), Android, HTML5 та iOS. Тільки 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" />
    </ItemGroup>
    ...
</Project>

Від Godot 3.2.3, Godot автоматично завантажує та налаштовує нещодавно додані пакети NuGet під час наступного створення проєкту.

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