Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Основи C#

Вступ

Ця сторінка містить короткий вступ до C#, як це таке, так і як його використовувати в Godot. Після цього ви можете переглянути how to use specific features, читати про differences between the C# and the GDScript API, і (знову) відвідайте Scripting section покрокового посібника.

C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with .NET 8.0.

Увага

Проекти, написані на C# з використанням Godot 4, наразі не можна експортувати на веб-платформу. Щоб використовувати C# на веб-платформі, розгляньте Godot 3. Підтримка платформ Android та iOS доступна з Godot 4.2, але є експериментальною та застосовуються деякі обмеження.

Примітка

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

Передумови

Godot об’єднує частини .NET, необхідні для запуску вже скомпільованих ігор. Однак Godot не містить інструментів, необхідних для створення та компіляції ігор, таких як MSBuild і компілятор C#. Вони входять до .NET SDK і їх потрібно інсталювати окремо.

Підсумовуючи, ви повинні інсталювати .NET SDK і версію Godot із підтримкою .NET.

Завантажте та встановіть останню стабільну версію SDK зі сторінки завантаження .NET.

Важливо

Обов’язково встановіть 64-бітну версію SDK, якщо ви використовуєте 64-бітну версію Godot.

Якщо ви створюєте Godot із вихідного коду, обов’язково виконайте кроки, щоб увімкнути підтримку .NET у своїй збірці, як описано на сторінці Компіляція з .NET.

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

Підтримка C# у вбудованому редакторі сценаріїв Godot мінімальна. Розгляньте можливість використання зовнішньої IDE або редактора, наприклад Visual Studio Code або MonoDevelop. Вони забезпечують автозавершення, налагодження та інші корисні функції для C#. Щоб вибрати зовнішній редактор у Godot, натисніть Редактор → Параметри редактора та прокрутіть униз до Dotnet. У розділі Dotnet натисніть Редактор і виберіть потрібний зовнішній редактор. Наразі Godot підтримує такі зовнішні редактори:

  • visual Studio 2022

  • Visual Studio або VS Code

  • МоноДевелопмент

  • Visual Studio для Mac

  • JetBrains Райдер

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

JetBrains Райдер

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

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

  • Установіть Dotnet -> Редактор -> Зовнішній редактор на JetBrains Rider.

В Rider:

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

  • If you are using a Rider version below 2024.2, install the Godot support plugin. This functionality is now built into Rider.

Visual Studio або VS Code

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

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

  • Установіть для Dotnet -> Редактор -> Зовнішній редактор значення Visual Studio Code.

В Visual Studio Code:

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

Щоб налаштувати проект для налагодження, вам знадобляться файли tasks.json і launch.json у папці .vscode з необхідною конфігурацією.

Ось приклад launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Play",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${env:GODOT4}",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
        }
    ]
}

Щоб ця конфігурація запуску працювала, вам потрібно або налаштувати змінну середовища GODOT4, яка вказує на виконуваний файл Godot, або замінити параметр program на шлях до виконуваного файлу Godot.

Ось приклад tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": [
                "build"
            ],
            "problemMatcher": "$msCompile"
        }
    ]
}

Тепер, коли ви запускаєте налагоджувач у Visual Studio Code, ваш проект Godot запускатиметься.

Visual Studio (тільки Windows)

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

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

  • Розробка робочого столу .NET

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

  • Установіть Dotnet -> Редактор -> Зовнішній редактор на Visual Studio.

Примітка

Якщо ви бачите помилку на зразок «Не вдається знайти пакет Godot.NET.Sdk», можливо, ваша конфігурація NuGet неправильна та її потрібно виправити.

Простий спосіб виправити файл конфігурації NuGet — це повторно створити його. У вікні провідника файлів перейдіть до %AppData%\NuGet. Перейменуйте або видаліть файл NuGet.Config. Коли ви знову створите свій проект Godot, файл буде автоматично створено зі значеннями за замовчуванням.

Щоб налагодити сценарії C# за допомогою Visual Studio, відкрийте файл .sln, який створюється після відкриття першого сценарію C# у редакторі. У меню Debug перейдіть до пункту меню Debug Properties для вашого проекту. Натисніть кнопку Створити новий профіль і виберіть Виконуваний файл. У полі Виконуваний файл знайдіть шлях до C# версії редактора Godot або введіть %GODOT4%, якщо ви створили змінну середовища для шляху до виконуваного файлу Godot. Це має бути шлях до основного виконуваного файлу Godot, а не «консольної» версії. Для Робочого каталогу введіть одну крапку, ., що означає поточний каталог. Також установіть прапорець Увімкнути налагодження рідного коду. Тепер ви можете закрити це вікно, клацнути стрілку вниз у спадному списку профілю налагодження та вибрати новий профіль запуску. Натисніть зелену кнопку «Пуск», і ваша гра почне грати в режимі налагодження.

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

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

../../../_images/attachcsharpscript.webp

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

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

Коли ви створюєте перший сценарій C#, Godot ініціалізує файли проекту C# для вашого проекту Godot. Це включає створення рішення C# (.sln) і файлу проекту (.csproj), а також деяких службових файлів і папок (.godot/mono). Усе це, крім .godot/mono, є важливим і має бути додано до вашої системи контролю версій. Усе, що міститься в .godot, можна безпечно додати до списку ігнорування вашого VCS. Під час усунення несправностей іноді може допомогти видалити папку .godot/mono і дати їй відновитися.

Приклад

Ось порожній скрипт C# з деякими коментарями, щоб продемонструвати, як він працює.

using Godot;

public partial 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(double delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

Як ви можете бачити, функції, які зазвичай знаходяться в глобальній області видимості в GDScript, як-от функція Godot print, доступні в статичному класі GD, який є частиною простору імен Godot. Щоб отримати повний список методів у класі GD, перегляньте довідкові сторінки класів для @GDScript і @GlobalScope.

Примітка

Майте на увазі, що клас, який ви хочете приєднати до вашого вузла, повинен мати ту саму назву, що й файл .cs. В іншому випадку ви отримаєте наступну помилку:

"Не вдається знайти клас XXX для сценарію res://XXX.cs"

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

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

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

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

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

../../../_images/build_dotnet1.webp

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

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

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

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

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

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

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

Починаючи з Godot 4.0, експорт проектів .NET підтримується для настільних платформ (Linux, Windows і macOS). Інші платформи отримають підтримку в майбутніх версіях 4.x.

Поширені підводні камені

Ви можете зіткнутися з такою помилкою під час спроби змінити деякі значення в об’єктах Годо, напр. під час спроби змінити координату X Node2D:

public partial class MyNode2D : Node2D
{
    public override void _Ready()
    {
        Position.X = 100.0f;
        // CS1612: Cannot modify the return value of 'Node2D.Position' because
        // it is not a variable.
    }
}

Це абсолютно нормально. Структури (у цьому прикладі Vector2) у C# копіюються під час призначення, тобто коли ви отримуєте такий об’єкт із властивості чи індексатора, ви отримуєте його копію, а не сам об’єкт. Зміна зазначеної копії без її повторного призначення згодом нічого не досягне.

Обхід простий: отримайте всю структуру, змініть значення, яке потрібно змінити, і повторно призначте властивість.

var newPosition = Position;
newPosition.X = 100.0f;
Position = newPosition;

Починаючи з C# 10, також можна використовувати with expressions на структурах, дозволяючи вам зробити те саме в одному рядку.

Position = Position with { X = 100.0f };

Ви можете прочитати більше про цю помилку в довіднику з мови C#.

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

Дивись також

For a performance comparison of the languages Godot supports, see Which programming language is fastest?.

Більшість властивостей об’єктів Godot C#, які базуються на GodotObject (наприклад, будь-який Node, як-от Control або Node3D, як-от Camera3D), потребують власних викликів (взаємодія), оскільки вони поговорити з ядром C++ Godot. Розгляньте можливість призначення значень таких властивостей локальній змінній, якщо вам потрібно змінити або прочитати їх кілька разів в одному місці коду:

using Godot;

public partial class YourCustomClass : Node3D
{
    private void ExpensiveReposition()
    {
        for (var i = 0; i < 10; i++)
        {
            // Position is read and set 10 times which incurs native interop.
            // Furthermore the object is repositioned 10 times in 3D space which
            // takes additional time.
            Position += new Vector3(i, i);
        }
    }

    private void Reposition()
    {
        // A variable is used to avoid native interop for Position on every loop.
        var newPosition = Position;
        for (var i = 0; i < 10; i++)
        {
            newPosition += new Vector3(i, i);
        }
        // Setting Position only once avoids native interop and repositioning in 3D space.
        Position = newPosition;
    }
}

Передача необроблених масивів (таких як byte[]) або string до C# API Godot вимагає маршалінгу, який є порівняно дорогим.

Неявне перетворення з string на NodePath або StringName спричиняє витрати як на власне взаємодія, так і на маршалінг, оскільки string потрібно маршалізувати та передати відповідному рідному конструктору.

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

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

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

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

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

Для профілювання продуктивності та пам’яті вашого керованого коду можна використовувати такі інструменти:

  • JetBrains Rider із плагіном dotTrace/dotMemory.

  • Автономний JetBrains dotTrace/dotMemory.

  • Візуальна Studio.

Профілювання керованого та некерованого коду одночасно можливе за допомогою інструментів JetBrains і Visual Studio, але обмежено Windows.