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 ** kein ** umfassendes Tutorial 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

Windows (Visual Studio)

Laden Sie die neueste Version von Visual Studio (nicht Visual Studio Code) herunter und installieren sie. Sie enthält Dienstprogramme, die für die Verwendung von C# in Godot erforderlich sind. Wenn Sie die Visual Studio-IDE nicht verwenden möchten, können Sie stattdessen nur die Visual Studio Build Tools herunterladen. Stellen Sie sicher, dass mindestens das .NET Framework 4.5-Targeting-Pack installiert ist. Sie können es mit einem der oben auf der Registerkarte "individuelle Komponenten" genannten Installationsprogramme herunterladen.

Windows (JetBrains Rider)

JetBrains Rider kommt zusammen mit MSBuild, somit ist nichts weiteres erforderlich. Stelle sicher die folgenden Einstellungen zu verwenden:

  • In den Editor-Einstellungen von Godot:

    • Setzen Sie Mono External Editor auf JetBrains Rider.
    • Setzen Sie Mono Build Tool auf JetBrains Mono.
  • In Rider:

    • Stellen Sie MSBuild-Version entweder auf Mit Rider gebündelt oder .NET Core ein.
    • Installiere Godot Support Plugin.

MacOS und Linux

Laden Sie die neueste Version des Mono SDK herunter und installieren sie. Ab Godot 3.1 Beta 3 spielt die Versionsnummer keine Rolle, da Godot seine eigene Mono 5.18-Installation bereitstellt. Wir benötigen nur die Mono-Installation für NuGet und MSBuild, die für die Verwendung von C# in Godot erforderlich sind.

Bemerkung

Um Mono unter MacOS herunterzuladen, verwenden Sie den Link "Stable Channel" von der Seite Mono Download. Der Visual Studio-Kanal ist eine frühere Version von Mono und funktioniert nicht.

Zusätzliche Anmerkungen

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: ref: doc_compiling_with_mono beschrieben.

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

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 Sie 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

Bemerkung

Wenn Sie Visual Studio Code verwenden stellen Sie sicher, dass Sie die C# -Erweiterung <https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp>_ herunterladen und installieren, um Funktionen wie Syntaxhervorhebung und IntelliSense zu aktivieren.

Bemerkung

Wenn Sie Visual Studio 2019 verwenden, müssen Sie die Anweisungen im Abschnitt :ref:doc_c_sharp_configuring_vs_2019_for_debugging unten befolgen.

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.

Ab Godot 3.2.2 wird das Exportieren von Mono-Projekten 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 packages can be installed and used with Godot, as with any C# project. Many IDEs are able to add packages directly. They can also be added manually by adding the package reference in the .csproj file located in the project root:

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

Bemerkung

By default, tools like NuGet put Version as an attribute of the `PackageReference` Node. You must manually create a Version node as shown above. This is because the version of MSBuild used requires this. (This will be fixed in Godot 4.0.)

Whenever packages are added or modified, run nuget restore (not dotnet restore) in the root of the project directory. To ensure that NuGet packages will be available for msbuild to use, run:

msbuild /t:restore

Einen C# Code in Form bringen

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. Ensure that you do not have Xamarin installed. Do not choose the Mobile development with .NET workload. Xamarin changes the DLLs used by MonoDebugger, which breaks debugging.
  3. Installieren Sie VSMonoDebugger extension.
  4. In VS 2019 --> Extensions --> Mono --> Settings:
    • 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

To configure debugging, open Visual Studio Code and download the Mono Debug extension from Microsoft and the Godot extension by Ignacio. Then open the Godot project folder in VS Code. Go to the Run tab and click on create a launch.json file. Select C# Godot from the dropdown menu. Now, when you start the debugger in VS Code your Godot project will run.