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

Передумови

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

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

В Visual Studio Code:

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

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

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

Примітка

If you are using Linux you need to install the Mono SDK for the C# tools plugin to work.

To configure a project for debugging open the Godot project folder in VS Code. Go to the Run tab and click on Add Configuration.... Select C# Godot from the dropdown menu. Open the tasks.json and launch.json files that were created. Change the executable setting in launch.json and command settings in tasks.json to your Godot executable path. Now, when you start the debugger in VS Code, your Godot project will run.

Visual Studio (тільки Windows)

Завантажте та встановіть останню версію Visual Studio. 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, ви повинні побачити наступну опцію при виборі 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 #