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 .NET Core SDK (3.1 as of writing).

From Godot 3.2.3 onwards, installing Mono SDK is not a requirement anymore, except it is required if you are building the engine from source.

Godot bundles the parts of Mono needed to run already compiled games, however Godot does not include the tools required to build and compile games, such as MSBuild. These tools need to be installed separately. The required tools are included in the .NET Core SDK. MSBuild is also included in the Mono SDK, but it can't build C# projects with the new csproj format, therefore .NET Core SDK is required for Godot 3.2.3+.

In summary, you must have installed .NET Core SDK and the Mono-enabled version of Godot.

Zusätzliche Anmerkungen

Be sure to install the 64-bit version of the SDK(s) if you are using the 64-bit version of Godot.

If you are building Godot from source, install the latest stable version of Mono, and make sure to follow the steps to enable Mono support in your build as outlined in the Kompilieren mit Mono page.

Einen externen Editor konfigurieren

C# support in Godot's built-in script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or MonoDevelop. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Mono. Under Mono, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio für Mac

  • JetBrains Rider

See the following sections for how to configure an external editor:

JetBrains Rider

After reading the "Prerequisites" section, you can download and install JetBrains Rider.

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to JetBrains Rider.

  • Set Mono -> Builds -> Build Tool to dotnet CLI.

In Rider:

  • Set MSBuild version to .NET Core.

  • Installiere Godot Support Plugin.

Visual Studio Code

After reading the "Prerequisites" section, you can download and install Visual Studio Code (aka VS Code).

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio Code.

In Visual Studio Code:

Next, follow the instructions found in the Visual Studio Code zum Debuggen konfigurieren section below.

Visual Studio (Windows only)

Download and install the latest version of Visual Studio. Visual Studio will include the required SDKs if you have the correct workloads selected, so you don't need to manually install the things listed in the "Prerequisites" section.

While installing Visual Studio, select these workloads:

  • Mobile development with .NET

  • .NET Core cross-platform development

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio.

Next, follow the instructions found in the VS 2019 zum Debuggen konfigurieren section below.

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 Eingabe-Ereignisse.

Warnung

Wenn Sie C# verwenden, müssen Sie die Projekt-Bausteine neu übersetzen um neue Exportvariablen oder Signale sichtbar zu machen. Das kann manuell durch einen Klick auf das Wort "Mono" im unteren Fensterbereich geschehen, es wird das Mono-Panel eingeblendet und ein anschließender Klick auf "Build Project" führt die Aktion aus.

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.

Exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not supported yet is 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</Version>
        </PackageReference>
    </ItemGroup>
    ...
</Project>

Bemerkung

Standardmäßig setzen Tools wie NuGet Version als Attribut des PackageReference-Nodes. Sie müssen manuell einen Versions-Node wie oben gezeigt erstellen. Dies liegt daran, dass die verwendete Version von MSBuild dies erfordert. (Dies wird in Godot 4.0 behoben.)

Wenn Pakete hinzugefügt oder geändert werden, führen Sie nuget restore (nicht dotnet restore) im Wurzelverzeichnis des Projekts aus. Führen Sie Folgendes aus um sicherzustellen, dass NuGet-Pakete für MsBuild verfügbar sind:

msbuild /t:restore

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.

VS 2019 zum Debuggen konfigurieren

Bemerkung

Godot verfügt über eine integrierte Unterstützung für Arbeitsabläufe, an denen mehrere beliebte C# -IDEs beteiligt sind. Die integrierte Unterstützung für Visual Studio wird in zukünftigen Versionen enthalten sein. In der Zwischenzeit können Sie mit den folgenden Schritten VS 2019 für die Verwendung mit Godot C# Projekten konfigurieren.

  1. Installieren Sie VS 2019 mit .NET Desktop-Entwicklung und ``Desktop-Entwicklung mit C++``ausgewählten Auslastungen.

  2. Stellen Sie sicher, dass Xamarin nicht installiert ist. Wählen Sie nicht die Workload Mobile Entwicklung mit .NET. Xamarin ändert die von MonoDebugger verwendeten DLLs, wodurch das Debuggen unterbrochen wird.

  3. Installieren Sie VSMonoDebugger extension.

  4. In VS 2019 --> Erweiterungen --> Mono --> Einstellungen:

    • Wählen Sie Debug/Bereitstellung für lokales Windows.

    • Lassen Sie Local Deploy Path leer.

    • Setzen Sie Mono Debug Port auf den Port in Godot --> Projekt --> Projekteinstellungen --> Mono --> Debugger Agent.

    • Setzen Sie auch Warte auf Debugger in den Godot Mono Optionen. Diese Godot Erweiterung ist vielleicht hilfreich.

  5. Führen Sie das Spiel in Godot aus. Es sollte am Godot-Begrüßungsbildschirm hängen bleiben, während es auf das Hinzufügen Ihres Debuggers wartet.

  6. Öffnen Sie in VS 2019 Ihr Projekt und wählen Sie Erweiterungen -> Mono -> An Mono-Debugger anhängen.

Visual Studio Code zum Debuggen konfigurieren

Um das Debugging zu konfigurieren, öffnen Sie Visual Studio Code und laden die Mono Debug Erweiterung von Microsoft und die Godot Erweiterung von Ignacio herunter. Öffnen Sie nun den Godot Projektordner mit VS Code und wechseln zum Run Tab und klicken dort auf create a launch.json file. Wählen Sie C# Godot vom Dropdownmenü. Wenn Sie jetzt den Debugger in VS Code starten wird Ihr Godot Projekt ausgeführt.