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

Installieren Sie die neueste stabile Version von .NET Core SDK (3.1 zum Zeitpunkt der Erstellung).

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

Godot bündelt die Teile von Mono, die benötigt werden, um bereits kompilierte Spiele auszuführen. Godot enthält jedoch nicht die Tools, die zum Erstellen und Kompilieren von Spielen benötigt werden, wie z. B. MSBuild. Diese Tools müssen separat installiert werden. Die erforderlichen Tools sind im .NET Core SDK enthalten. MSBuild ist auch im Mono-SDK enthalten, aber es kann keine C#-Projekte mit dem neuen csproj-Format erstellen, daher ist das .NET Core SDK für Godot 3.2.3+ erforderlich.

Zusammenfassend müssen Visual Studio oder Mono (abhängig von Ihrem Betriebssystem) und die Mono-fähige Version von Godot installiert sein.

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.

Visual Studio Code:

Um ein Projekt für das Debugging zu konfigurieren, öffnen Sie den Godot-Projektordner in VS Code. Gehen Sie auf die Registerkarte "Run" und klicken Sie auf create a launch.json file. Wählen Sie C# Godot aus dem Dropdown-Menü. Wenn Sie nun den Debugger in VS Code starten, wird Ihr Godot-Projekt ausgeführt.

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.

Als nächstes müssen Sie die Godot Visual Studio-Erweiterung von github hier herunterladen. Doppelklicken Sie auf die heruntergeladene Datei und folgen Sie dem Installationsprozess.

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:

../../../_images/attachcsharpscript.png

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