C# Grundlagen¶

Einführung¶

Warnung

C# Unterstützung ist eine neue Funktion, die seit Godot 3.0 verfügbar ist. Daher können immer noch Probleme auftreten oder Stellen gefunden werden, an denen die Dokumentation verbessert werden könnte. Bitte melden Sie Probleme mit C# in Godot auf engine GitHub page, und alle Dokumentations Probleme auf documentation GitHub page.

Diese Seite bietet eine kurze Einführung in C#, sowohl was es ist als auch wie man es in Godot benutzt. Danach möchten Sie vielleicht etwas über die Verwendung bestimmter Funktionen lesen und über die Unterschiede zwischen der C# und der GDScript API, sowie auf die Seite Scripting section der Schritt-für-Schritt-Anleitung schauen.

C# ist eine von Microsoft entwickelte High-Level Programmiersprache. In Godot wird es mit dem Mono 6.x .NET-Framework implementiert, einschließlich der vollständigen Unterstützung für C# 8.0. Mono ist eine Open Source-Implementierung von Microsoft .NET Framework, die auf den ECMA-Standards für C# und der Common Language Runtime basiert. Ein guter Ausgangspunkt für die Überprüfung der Funktionen ist die Seite Compatibility in der Mono-Dokumentation.

Bemerkung

Dies ist keine umfassende Anleitung zur Sprache C# im Ganzen. Wenn Sie mit der Syntax oder den Funktionen von C# noch nicht vertraut sind, lesen Sie den Microsoft C# Ratgeber oder suchen Sie an anderer Stelle nach einer geeigneten Einführung.

C# für Godot einrichten¶

Voraussetzungen¶

Install the latest stable version of the .NET SDK, previously known as the .NET Core SDK.

Ab Godot 3.2.3 ist die Installation des Mono SDK keine Voraussetzung mehr, außer wenn Sie die Engine selbst kompilieren.

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.

Zusätzliche Anmerkungen¶

Stellen Sie sicher, dass Sie die 64-Bit-Version des SDKs installieren, wenn Sie die 64-Bit-Version von Godot verwenden.

In Ihrer Godot-Version muss die Mono-Unterstützung aktiviert sein. Laden Sie daher unbedingt die Mono-Version von Godot herunter. Wenn Sie Godot aus dem Quellcode erstellen, befolgen Sie die Schritte, um die Mono-Unterstützung in Ihrem Build zu aktivieren, wie auf der Seite Kompilieren mit Mono beschrieben.

Einen externen Editor konfigurieren¶

Die C# Unterstützung in Godots Skripteditor ist minimal. Verwenden Sie eine externe IDE oder einen externen Editor, z.B. Visual Studio Code oder MonoDevelop. Diese bieten Autovervollständigung, Debugging und andere nützliche Funktionen für C#. Um einen externen Editor in Godot auszuwählen, klicken Sie auf Editor → Editoreinstellungen und scrollen nach unten zu Mono. Klicken Sie unter Mono auf Editor und wählen Sie den gewünschten externen Editor aus. Godot unterstützt derzeit die folgenden externen Editoren:

Visual Studio 2019
Visual Studio Code
MonoDevelop
Visual Studio für Mac
JetBrains Rider

In den folgenden Abschnitten erfährt man, wie man einen externen Editor konfiguriert:

JetBrains Rider¶

Nachdem der Abschnitt "Voraussetzungen" gelesen wurde, können man JetBrains Rider herunterladen und installieren.

In Godots Editor → Editoreinstellungen Menü:

Setzen Sie Mono -> Editor -> Externer Editor auf JetBrains Rider.
Stellen Sie Mono -> Builds -> Build Tool auf dotnet CLI.

In Rider:

Setzen Sie MSBuild-Version auf .NET Core.
Installiere Godot Support Plugin.

Visual Studio Code¶

Nachdem der Abschnitt "Voraussetzungen" gelesen wurde, kann man Visual Studio Code (alias VS Code) herunterladen und installieren.

In Godots Editor → Editoreinstellungen Menü:

Stellen Sie Mono -> Editor -> Externer Editor auf Visual Studio Code.
Stellen Sie Mono -> Builds -> Build Tool auf dotnet CLI.

Visual Studio Code:

Installieren Sie die Erweiterung C#.
Installieren Sie die Erweiterung Mono Debug.
Installieren Sie die Erweiterung C# Tools for Godot.

Bemerkung

Wenn Sie Linux benutzen, müssen Sie das Mono SDK <https://www.mono-project.com/download/stable/#download-lin> installieren, damit die C# Tools funktionieren.

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 (nur Windows)¶

Laden Sie die neueste Version von Visual Studio herunter und installieren Sie sie. Visual Studio enthält die erforderlichen SDKs, wenn Sie die richtigen Workloads ausgewählt haben, sodass Sie die im Abschnitt "Voraussetzungen" aufgeführten Dinge nicht manuell installieren müssen.

Einschränkungen beim Installieren von Visual Studio:

Mobile Entwicklung mit .NET
Plattformübergreifende .NET Core-Entwicklung

In Godots Editor → Editoreinstellungen Menü:

Stellen Sie Mono -> Editor -> Externer Editor auf Visual Studio.
Stellen Sie Mono -> Builds -> Build Tool auf 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.

Bemerkung

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.

Bemerkung

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.

Erstellen eines C# Skripts¶

Nachdem Sie C# für Godot erfolgreich eingerichtet haben, sollte die folgende Option angezeigt werden, wenn Sie im Kontextmenü eines Nodes in Ihrer Szene Skript anhängen auswählen:

Beachten Sie, dass sich einige Details ändern, die meisten Konzepte jedoch bei Verwendung von C# für die Skripterstellung gleich funktionieren. Wenn Sie Godot noch nicht kennen, wäre diese Anleitungen interessant Skriptsprachen. Während an einigen Stellen in der Dokumentation noch C# Beispiele fehlen, können die meisten Konzepte problemlos aus GDScript übertragen werden.

Projekt Aufbau und Ablauf¶

Wenn Sie das erste C# Skript erstellen, initialisiert Godot die C# Projektdateien für Ihr Godot-Projekt. Dies umfasst das Generieren einer C# Lösung (.sln) und einer Projektdatei (.csproj) sowie einiger Dienstprogrammdateien und Ordner (.mono und Properties/AssemblyInfo.cs ``). Alle diese außer ``.mono sind wichtig und sollten Ihrem Versionskontrollsystem zugewiesen werden. .mono kann sicher zur Ignorierliste Ihres VCS hinzugefügt werden. Bei der Fehlerbehebung kann es manchmal hilfreich sein den Ordner .mono zu löschen und neu generieren zu lassen.

Beispiel¶

Hier ist ein leeres C# Skript mit einigen Kommentaren um die Arbeitsweise zu zeigen.

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.
    }
}

Wie Sie sehen können, sind Funktionen, die normalerweise in GDScript im globalen Geltungsbereich liegen (wie Godots Funktion print) in der Klasse GD verfügbar, die Teil des Namenraums Godot ist. Eine Liste der Methoden in der Klasse GD finden Sie auf den Klassenreferenzseiten für @GDScript und @GlobalScope.

Bemerkung

Beachten Sie, dass die an Ihren Node anzuhängende Klasse denselben Namen wie die Datei .cs haben sollte. Andernfalls wird der folgende Fehler angezeigt und die Szene kann nicht ausgeführt werden: "Klasse XXX für Skript res://XXX.cs kann nicht gefunden werden"

Allgemeine Unterschiede zwischen C# und GDScript¶

Die C# API verwendet in GDScript und C++ PascalCase anstelle von snake_case. Nach Möglichkeit wurden Felder und Getter/Setter in Eigenschaften konvertiert. Im Allgemeinen ist die C# Godot API bestrebt, so idiomatisch wie möglich zu sein.

Für mehr Informationen über Events, siehe die Seite Verwendung von InputEvent.

Warnung

Sie müssen die Projekt-Assemblies (neu) bauen, wenn Sie neue exportierte Variablen oder Signale im Editor sehen möchten. Dieser Build kann manuell ausgelöst werden, indem Sie auf das Wort Build in der oberen rechten Ecke des Editors klicken. Sie können auch unten im Editor-Fenster auf Mono klicken, um das Mono-Panel einzublenden, und dann auf die Schaltfläche Projekt bauen klicken.

Sie müssen auch die Projektzusammenschnitte neu erstellen, um Änderungen in "Tool" -Skripten anzuwenden.

Aktuelle Fehler und bekannte Probleme¶

Da die C# Unterstützung in Godot ziemlich neu ist, gibt es noch einige Dinge die beseitigt werden müssen. Nachstehend finden Sie eine Liste dieser wichtigsten Probleme, die Sie beim Eintauchen in C# in Godot beachten sollten. Im Zweifelsfall sollten Sie sich jedoch auch den offiziellen Mono Problem-Tracker ansehen. <https://github.com/godotengine/godot/labels/topic%3Amono>`_.

Editor Plugins zu schreiben ist möglich, aber zur Zeit ziemlich verworren.
Der Status wird derzeit beim Hot-Reloading nicht gespeichert und wiederhergestellt, mit Ausnahme der exportierten Variablen.
Angehängte C# Skripte sollten sich auf eine Klasse beziehen, deren Klassenname mit dem Dateinamen übereinstimmt.
Es gibt einige Methoden wie Get()/Set(), Call()/CallDeferred() und die Signalverbindungsmethode Connect() die sich auf Godots snake_case API-Namenskonventionen stützen. Wenn also z.B. CallDeferred("AddChild") genutzt wird, funktioniert AddChild nicht, da die API die ursprüngliche snake_case-Version von add_child erwartet. Sie können jedoch alle benutzerdefinierten Eigenschaften oder Methoden ohne diese Einschränkung verwenden.

Das Exportieren von Mono-Projekten wird für Desktop-Plattformen (Linux, Windows und macOS), Android, HTML5 und iOS unterstützt. Die einzige noch nicht unterstützte Plattform ist UWP.

Die Leistung von C# in Godot¶

Nach einigen vorläufigen Leistungstests ist die Leistung von C# in Godot - obwohl im Allgemeinen in der gleichen Größenordnung - ungefähr ~4× so hoch wie von GDScript in einigen Fällen. C++ ist immer noch etwas schneller; Die Einzelheiten variieren je nach Anwendungsfall. GDScript ist wahrscheinlich schnell genug für die meisten allgemeinen Arbeitsbelastungen eines Skripts. C# ist schneller, erfordert jedoch teures Marshalling, wenn Sie mit Godot sprechen.

NuGet Pakete in Godot nutzen¶

NuGet Pakete können wie jedes C# Projekt mit Godot installiert und verwendet werden. Viele IDEs können Pakete direkt hinzufügen. Sie können auch manuell hinzugefügt werden, indem die Paketreferenz in die Datei .csproj in der Projekt-Wurzel eingefügt wird:

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

Ab Godot 3.2.3 lädt Godot automatisch neu hinzugefügte NuGet-Pakete herunter und richtet sie ein, wenn das Projekt das nächste Mal kompiliert wird.

Einen C# Code in Form bringen¶

Der Mono log profiler <https://www.mono-project.com/docs/debug+profile/profile/profiler/> ist für Linux und macOS verfügbar. Wegen einer Mono Änderung funktioniert das Programm für Windows im Moment nicht.
Externe Mono Profiler wie JetBrains dotTrace können wie hier beschrieben benutzt werden.