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# — це мова програмування високого рівня, розроблена компанією Microsoft. У Godot вона реалізована за допомогою сучасного середовища виконання .NET.

Увага

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

Примітка

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

Передумови

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

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

Завантажте та встановіть останню стабільну версію SDK зі сторінки завантаження .NET. Для Godot 4.5 потрібен .NET 8 або пізнішої версії, але для експорту в Android потрібен .NET 9 або пізнішої версії.

Важливо

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

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

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

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

  • Visual Studio 2022

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio для Mac

  • JetBrains Райдер

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

JetBrains Райдер

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

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

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

В Rider:

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

  • Якщо ви використовуєте версію Rider нижче 2024.2, установіть плагін підтримка Godot. Ця функція тепер вбудована в Rider.

Visual Studio 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_dotnet.webp

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

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

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

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

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

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

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

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

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

Ви можете зіткнутися з такою помилкою під час спроби змінити деякі значення в об’єктах Godot, напр. під час спроби змінити координату 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

Дивись також

Для порівняння продуктивності мов, які підтримує Godot, див. Яка мова програмування найшвидша?.

Більшість властивостей об’єктів 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 автоматично завантажує та налаштовує щойно додані пакети NuGet під час наступної збірки проєкту.

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

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

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

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

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

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