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.

This page provides a brief introduction to C#, both what it is and how to use it in Godot. Afterwards, you may want to look at how to use specific features, read about the differences between the C# and the GDScript API and (re)visit the Scripting section of the step-by-step tutorial.

C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with the Mono 6.x .NET framework, including full support for C# 8.0. Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime. A good starting point for checking its capabilities is the Compatibility page in the Mono documentation.

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)

Download and install the latest version of Visual Studio (not Visual Studio Code), which contains utilities required to use C# in Godot. If you don't plan on using the Visual Studio IDE, you can download just the Visual Studio Build Tools instead. Make sure you at least have the .NET Framework 4.5 targeting pack installed, you can get it using any of the installers mentioned above inside the "Individual components" tab.

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

Download and install the latest version of the Mono SDK. As of Godot 3.1 beta 3, the version number doesn't matter since Godot bundles its own Mono 5.18 installation. We only need the Mono installation for NuGet and MSBuild which are required to use C# in Godot.

Bemerkung

To download Mono on macOS, use the "Stable Channel" link from the Mono Downloads Page. The Visual Studio channel is an earlier version of Mono and will not work.

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.

In summary, you must have installed Visual Studio or Mono (depending on your operating system) and the Mono-enabled version of Godot.

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

If you are using Visual Studio Code, ensure you download and install the C# extension to enable features like syntax highlighting and IntelliSense.

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

When you create the first C# script, Godot initializes the C# project files for your Godot project. This includes generating a C# solution (.sln) and a project file (.csproj), as well as some utility files and folders (.mono and Properties/AssemblyInfo.cs). All of these but .mono are important and should be committed to your version control system. .mono can be safely added to the ignore list of your VCS. When troubleshooting, it can sometimes help to delete the .mono folder and let it regenerate.

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

As you can see, functions normally in global scope in GDScript like Godot's print function are available in the GD class which is part of the Godot namespace. For a list of methods in the GD class, see the class reference pages for @GDScript and @GlobalScope.

Bemerkung

Keep in mind that the class you wish to attach to your node should have the same name as the .cs file. Otherwise, you will get the following error and won't be able to run the scene: "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 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

You need to (re)build the project assemblies whenever you want to see new exported variables or signals in the editor. This build can be manually triggered by clicking the word Mono at the bottom of the editor window to reveal the Mono panel, then clicking the Build Project button.

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

Aktuelle Fehler und bekannte Probleme

As C# support is quite new in Godot, there are some growing pains and things that need to be ironed out. Below is a list of the most important issues you should be aware of when diving into C# in Godot, but if in doubt, also take a look over the official issue tracker for Mono issues.

  • 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.
  • There are some methods such as Get()/Set(), Call()/CallDeferred() and signal connection method Connect() that rely on Godot's snake_case API naming conventions. So when using e.g. CallDeferred("AddChild"), AddChild will not work because the API is expecting the original snake_case version add_child. However, you can use any custom properties or methods without this limitation.

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

According to some preliminary benchmarks, the performance of C# in Godot — while generally in the same order of magnitude — is roughly ~4× that of GDScript in some naive cases. C++ is still a little faster; the specifics are going to vary according to your use case. GDScript is likely fast enough for most general scripting workloads. C# is faster, but requires some expensive marshalling when talking to Godot.

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

Deinen C# Code in Form bringen

VS 2019 zum Debuggen konfigurieren

Bemerkung

Godot has built-in support for workflows involving several popular C# IDEs. Built-in support for Visual Studio will be including in future versions, but in the meantime, the steps below can let you configure VS 2019 for use with Godot C# projects.

  1. Install VS 2019 with .NET desktop development and Desktop development with C++ workloads selected.
  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. Install the VSMonoDebugger extension.
  4. In VS 2019 --> Extensions --> Mono --> Settings:
    • Select Debug/Deploy to local Windows.
    • Leave Local Deploy Path blank.
    • Set the Mono Debug Port to the port in Godot --> Project --> Project Settings --> Mono --> Debugger Agent.
    • Also select Wait for Debugger in the Godot Mono options. This Godot Addon may be helpful.
  5. Run the game in Godot. It should hang at the Godot splash screen while it waits for your debugger to attach.
  6. In VS 2019, open your project and choose Extensions --> Mono --> Attach to Mono Debugger.

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.