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

Windows (Visual Studio)

Завантажте та встановіть останню версію Visual Studio ( не Visual Studio Code), яка містить утиліти, необхідні для використання C# у Godot. Якщо ви не плануєте використовувати Visual Studio IDE, ви можете завантажити лише `інструменти Visual Studio<https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15>`_ . Переконайтеся, що ви, принаймні, маєте встановлений пакет орієнтації .NET Framework 4.5, ви можете отримати його за допомогою будь-якого із згаданих вище встановщиків на вкладці "Особисті компоненти".

Windows (JetBrains Rider)

JetBrains Rider comes with bundled MSBuild, so nothing extra is required. Make sure to set the following preferences:

  • In Godot's Editor Settings:

    • Set Mono External Editor to JetBrains Rider.
    • set Mono Build Tool to JetBrains Mono.
  • In Rider:

    • Set MSBuild version to either Bundled with Rider or .NET Core.
    • Install the Godot support plugin.

macOS і Linux

Завантажте та встановіть останню версію Mono SDK. Від Godot 3.1 beta 3, номер версії не має значення, оскільки Godot постачає власну установку Mono 5.18. Нам потрібна тільки установка Mono для NuGet і MSBuild, які необхідні для використання C# в Godot.

Примітка

Щоб завантажити Mono на macOS, скористайтеся посиланням "Стабільний канал" зі сторінки завантаження Mono. Канал Visual Studio - це більш рання версія Mono і не працюватиме.

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

У вашій версії Godot повинна бути включена підтримка Mono, тому обов'язково завантажте Mono версію Godot. Якщо ви створюєте Godot з джерела, не забудьте виконати кроки для увімкнення підтримки Mono у вашій збірці, як зазначено на сторінці Compiling with Mono.

В результаті, ви повинні встановити Visual Studio, або Mono, (залежно від вашої операційної системи) та придатну для Mono версію Godot.

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

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

Примітка

Якщо ви використовуєте Visual Studio Code, переконайтеся, що ви завантажили та встановили `розширення C#<https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp>`_ , щоб увімкнути такі функції, як підсвічування синтаксису та IntelliSense.

Примітка

If you are using Visual Studio 2019, you must follow the instructions found in the :ref:doc_c_sharp_configuring_vs_2019_for_debugging 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. Однак ви можете використовувати будь-які власні властивості, або методи, без цього обмеження.

As of Godot 3.2.2, 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.