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#-Grundlagen

Einführung

Diese Seite bietet eine kurze Einführung in C#, sowohl was es ist, als auch wie man es in Godot verwendet. Danach sollten Sie sich Wie man bestimmte Features verwendet ansehen, etwas über die Unterschiede zwischen der C#- und der GDScript-API lesen und den Skripting-Abschnitt des Schritt-für-Schritt-Tutorials (erneut) besuchen.

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

Achtung

Projekte, die in C# mit Godot 4 geschrieben wurden, können derzeit nicht auf die Web-Plattform exportiert werden. Um C# auf der Webplattform zu verwenden, sollten Sie stattdessen Godot 3 verwenden. Unterstützung für die Plattformen Android und iOS ist ab Godot 4.2 verfügbar, aber experimentell und Es gelten einige Einschränkungen.

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 das Microsoft C#-Handbuch oder suchen Sie an anderer Stelle nach einer geeigneten Einführung.

Voraussetzungen

Godot bringt die Teile von .NET, die zum Ausführen bereits kompilierter Spiele benötigt werden mit. Allerdings bringt Godot nicht die Tools mit, die zum Erstellen und Kompilieren von Spielen erforderlich sind, wie MSBuild und den C#-Compiler. Diese sind im .NET SDK enthalten und müssen separat installiert werden.

Zusammenfassend lässt sich sagen, dass Sie das .NET SDK und die .NET-fähige Version von Godot installiert haben müssen.

Laden Sie die neueste stabile Version des SDK von der .NET Download-Seite herunter und installieren Sie sie.

Wichtig

Stellen Sie sicher, dass Sie die 64-Bit-Version des SDK(s) installieren, wenn Sie die 64-Bit-Version von Godot verwenden.

Wenn Sie Godot aus dem Quellcode bauen, stellen Sie sicher, dass Sie die Schritte zur Aktivierung der .NET-Unterstützung in Ihrem Build befolgen, wie auf der Seite Kompilieren mit .NET beschrieben wird.

Einen externen Editor konfigurieren

Die C#-Unterstützung im integrierten Skript-Editor von Godot ist minimal. Ziehen Sie die Verwendung einer externen IDE oder eines Editors in Betracht, 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 Sie nach unten zu Dotnet. Klicken Sie unter Dotnet auf Editor, und wählen Sie den externen Editor Ihrer Wahl aus. Godot unterstützt derzeit die folgenden externen Editoren:

  • Visual Studio 2022

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio für Mac

  • JetBrains Rider

In den folgenden Abschnitten erfahren Sie, wie Sie einen externen Editor konfigurieren:

JetBrains Rider

Nachdem Sie den Abschnitt "Voraussetzungen" gelesen haben, können Sie JetBrains Rider herunterladen und installieren.

In Godots Editor → Editoreinstellungen Menü:

  • Setzen Sie Dotnet -> Editor -> Externer Editor auf JetBrains Rider.

In Rider:

  • Setzen Sie MSBuild-Version auf .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 Code

Nachdem Sie den Abschnitt "Voraussetzungen" gelesen haben, können Sie Visual Studio Code (auch bekannt als VS Code) herunterladen und installieren.

In Godots Editor → Editoreinstellungen Menü:

  • Stellen Sie Dotnet -> Editor -> Externer Editor auf Visual Studio Code.

In Visual Studio Code:

  • Installieren Sie die C#-Erweiterung.

Um ein Projekt für das Debugging zu konfigurieren, benötigen Sie eine tasks.json und eine launch.json Datei im .vscode-Ordner mit der notwendigen Konfiguration.

Hier ist ein Beispiel-launch.json:

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

Damit diese Startkonfiguration funktioniert, müssen Sie entweder eine GODOT4-Umgebungsvariable einrichten, die auf die ausführbare Godot-Datei verweist, oder den Parameter program durch den Pfad zur ausführbaren Godot-Datei ersetzen.

Hier ist ein Beispiel-tasks.json:

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

Wenn Sie nun den Debugger in Visual Studio 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.

Wählen Sie bei der Installation von Visual Studio diesen Workload aus:

  • .NET-Desktop-Entwicklung

In Godots Editor → Editoreinstellungen Menü:

  • Setzen Sie Dotnet -> Editor -> Externer Editor auf Visual Studio.

Bemerkung

Wenn Sie eine Fehlermeldung wie "Unable to find package Godot.NET.Sdk" sehen, ist Ihre NuGet-Konfiguration möglicherweise falsch und muss korrigiert werden.

Eine einfache Möglichkeit, die NuGet-Konfigurationsdatei zu reparieren, besteht darin, sie neu zu generieren. Gehen Sie in einem Datei-Explorer-Fenster zu %AppData%\NuGet. Benennen Sie die Datei NuGet.Config um oder löschen Sie sie. Wenn Sie Ihr Godot-Projekt erneut erstellen, wird die Datei automatisch mit Defaultwerten erstellt.

Um Ihre C#-Skripte mit Visual Studio zu debuggen, öffnen Sie die .sln-Datei, die nach dem Öffnen des ersten C#-Skripts im Editor erzeugt wird. Gehen Sie im Menü Debug auf den Menüpunkt Debug-Propertys für Ihr Projekt. Klicken Sie auf den Button Ein neues Profil erstellen und wählen Sie Ausführbar. Suchen Sie im Feld Ausführbar den Pfad zur C#-Version des Godot-Editors, oder geben Sie %GODOT4% ein, wenn Sie eine Umgebungsvariable für den Godot-Ausführungspfad erstellt haben. Es muss der Pfad zur ausführbaren Godot-Hauptdatei sein, nicht die 'Kommandozeilen'-Version. Für das Arbeitsverzeichnis geben Sie einen einzelnen Punkt ein, ., was für das aktuelle Verzeichnis steht. Aktivieren Sie auch die Checkbox Natives Code-Debugging aktivieren. Schließen Sie nun dieses Fenster, klicken Sie auf den Abwärtspfeil in der Dropdown-Liste der Debug-Profile und wählen Sie Ihr neues Startprofil aus. Klicken Sie auf den grünen Startknopf, und Ihr Spiel beginnt im Debug-Modus zu laufen.

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

Beachten Sie, dass sich zwar einige Besonderheiten ändern, die meisten Konzepte aber gleich funktionieren, wenn Sie C# für die Skripterstellung verwenden. Wenn Sie neu in Godot sind, sollten Sie an dieser Stelle die Tutorials unter Skriptsprachen verfolgen. Auf einigen Dokumentationsseiten fehlen zwar noch C#-Beispiele, aber die meisten Begriffe können von GDScript übernommen werden.

Projekteinrichtung und Workflow

Wenn Sie das erste C#-Skript erstellen, initialisiert Godot die C#-Projektdateien für Ihr Godot-Projekt. Dazu gehört die Erzeugung einer C#-Solution (.sln) und einer Projektdatei (.csproj) sowie einiger Dienstprogrammdateien und -ordner (.godot/mono). Alle diese Dateien außer .godot/mono sind wichtig und sollten in Ihr Versionsverwaltungssystem übertragen werden. Alles unter .godot kann getrost in die ignore-Liste Ihres VCS aufgenommen werden. Bei der Fehlersuche kann es manchmal helfen, den .godot/mono-Ordner zu löschen und ihn neu generieren zu lassen.

Beispiel

Hier ist ein leeres C# Skript mit einigen Kommentaren, um zu zeigen, wie es funktioniert.

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

Wie Sie sehen können, sind Funktionen, die in GDScript normalerweise global sind, wie z.B. Godots print-Funktion, in der statischen Klasse GD verfügbar, die Teil des Godot-Namespace ist. Eine vollständige Liste der Methoden in der Klasse GD finden Sie auf den Klassenreferenzseiten für @GDScript und @GlobalScope.

Bemerkung

Beachten Sie, dass die Klasse, die Sie an Ihren Node anhängen möchten, den gleichen Namen wie die .cs-Datei haben sollte. Andernfalls erhalten Sie die folgende Fehlermeldung:

"Cannot find class XXX for script res://XXX.cs "

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 Propertys konvertiert. Im Allgemeinen ist die C#-Godot API bestrebt, so idiomatisch wie möglich zu sein.

Für mehr Informationen siehe die Seite C# API-Unterschiede zu GDScript.

Warnung

Sie müssen die Projekt-Assemblys (neu) erstellen, wenn Sie neue exportierte Variablen oder Signale im Editor sehen möchten. Dieser Build kann manuell ausgelöst werden, indem Sie auf den Build-Button in der oberen rechten Ecke des Editors klicken.

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

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

Aktuelle Fallstricke und bekannte Probleme

Da die C#-Unterstützung in Godot noch recht neu ist, gibt es noch einige Anlaufschwierigkeiten und Dinge, die ausgebügelt werden müssen. Im Folgenden finden Sie eine Liste der wichtigsten Probleme, die Sie beachten sollten, wenn Sie sich mit C# in Godot befassen. Im Zweifelsfall sollten Sie aber auch einen Blick auf den offiziellen issue tracker for .NET issues werfen.

  • Editor-Plugins zu schreiben ist möglich, aber zur Zeit ziemlich unübersichtlich.

  • 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 verlassen. Wenn Sie also z.B. CallDeferred("AddChild") verwenden, wird AddChild nicht funktionieren, da die API die ursprüngliche snake_case-Version add_child erwartet. Sie können jedoch alle benutzerdefinierten Propertys oder Methoden ohne diese Einschränkung verwenden. Bevorzugen Sie die Verwendung des zugreifbaren StringName im PropertyName, MethodName und SignalName, um zusätzliche StringName-Zuweisungen und die Sorge um die snake_case-Benennung zu vermeiden.

Ab Godot 4.0 wird der Export von .NET-Projekten für Desktop-Plattformen (Linux, Windows und macOS) unterstützt. Andere Plattformen werden in zukünftigen 4.x-Versionen unterstützt.

Häufige Fallstricke

Der folgende Fehler kann auftreten, wenn Sie versuchen, einige Werte in Godot-Objekten zu ändern, z.B. wenn Sie versuchen, die X-Koordinate eines Node2D zu ändern:

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

Das ist völlig normal. Strukturen (in diesem Beispiel ein Vector2) werden in C# bei der Zuweisung kopiert, d.h. wenn Sie ein solches Objekt von einer Property oder einem Indexer abrufen, erhalten Sie eine Kopie davon, nicht das Objekt selbst. Diese Kopie zu ändern, ohne sie anschließend neu zuzuweisen, bringt nichts.

Die Abhilfe ist einfach: Rufen Sie die gesamte Struktur ab, ändern Sie den Wert, den Sie ändern möchten, und weisen Sie die Property erneut zu.

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

Seit C# 10 ist es auch möglich, with-Ausdrücke auf Strukturen zu verwenden, wodurch Sie das Gleiche in einer einzigen Zeile tun können.

Position = Position with { X = 100.0f };

Sie können mehr über diesen Fehler in der C#-Sprachreferenz lesen.

Die Performance von C# in Godot

Siehe auch

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

Die meisten Propertys von Godot-C#-Objekten, die auf GodotObject basieren (z.B. jeder Node wie Control oder jeder Node3D wie Camera3D), erfordern native (Interop-) Aufrufe, da sie mit dem C++-Kern von Godot kommunizieren. Ziehen Sie in Erwägung, die Werte solcher Propertys einer lokalen Variable zuzuweisen, wenn Sie sie mehrfach an einer einzigen Codestelle ändern oder lesen müssen:

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

Die Übergabe von rohen Arrays (wie z.B. Byte[]) oder Strings an Godots C#-API erfordert Marshalling, das vergleichsweise kostspielig ist.

Die implizite Konvertierung von String in NodePath oder StringName verursacht sowohl native Interop- als auch Marshalling-Kosten, da der String gemarshallt und an den entsprechenden nativen Konstruktor übergeben werden muss.

Verwendung von NuGet-Paketen in Godot

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 im Projekt-Root 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.

Profilieren Ihres C#-Codes

Die folgenden Tools können für die Performance- und Speicherprofilierung Ihres verwalteten Codes verwendet werden:

  • JetBrains Rider mit dotTrace/DotMemory-Plugin.

  • Das eigenständige JetBrains dotTrace/dotMemory.

  • Visual Studio.

Das gleichzeitige Profiling von managed und unmanaged Code ist sowohl mit JetBrains-Tools als auch mit Visual Studio möglich, jedoch auf Windows beschränkt.