C# Merkmale

This page provides an overview of the commonly used features of both C# and Godot and how they are used together.

Type conversion and casting

C# ist eine statische Programmiersprache, daher ist dies hier nicht möglich:

var mySprite = GetNode("MySprite");
mySprite.SetFrame(0);

Die Methode GetNode() liefert eine Node Instance. Diese muss nun in den gewünschten abgeleiteten Typ konvertiert werden , Sprite in diesem Fall.

Hierfür gibt es verschiedene Möglichkeiten in C#.

Casting und Typprüfung

Throws InvalidCastException if the returned node cannot be cast to Sprite. You would use it instead of the as operator if you are pretty sure it won't fail.

Sprite mySprite = (Sprite)GetNode("MySprite");
mySprite.SetFrame(0);

Nutzen des AS Operators

Der as Operator liefert null falls der Node nicht als Sprite genutzt werden kann, daher kann es nicht mit Wert Typen genutzt werden.

Sprite mySprite = GetNode("MySprite") as Sprite;
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

Nutzen der allgemeinen Methoden

Generic methods are also provided to make this type conversion transparent.

GetNode<T>() casts the node before returning it. It will throw an InvalidCastException if the node cannot be cast to the desired type.

Sprite mySprite = GetNode<Sprite>("MySprite");
mySprite.SetFrame(0);

GetNodeOrNull<T>() uses the as operator and will return null if the node cannot be cast to the desired type.

Sprite mySprite = GetNodeOrNull<Sprite>("MySprite");
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

Typprüfung mit dem IS-Operator

To check if the node can be cast to Sprite, you can use the is operator. The is operator returns false if the node cannot be cast to Sprite, otherwise it returns true.

if (GetNode("MySprite") is Sprite)
{
    // Yup, it's a sprite!
}

Weitere Informationen zur Typprüfung finden Sie unter Pattern Matching.

C# Signale

Ein vollständiges C# Beispiel finden Sie im Abschnitt Behandeln eines Signals in der Schritt-für-Schritt-Anleitung Skripten.

Das Deklarieren eines Signals in C# erfolgt mit dem Attribut [Signal] eines Beauftragten.

[Signal]
delegate void MySignal();

[Signal]
delegate void MySignalWithArguments(string foo, int bar);

These signals can then be connected either in the editor or from code with Connect. If you want to connect a signal in the editor, you need to (re)build the project assemblies to see the new signal. This build can be manually triggered by clicking the “Build” button at the top right corner of the editor window.

public void MyCallback()
{
    GD.Print("My callback!");
}

public void MyCallbackWithArguments(string foo, int bar)
{
    GD.Print("My callback with: ", foo, " and ", bar, "!");
}

public void SomeFunction()
{
    instance.Connect("MySignal", this, "MyCallback");
    instance.Connect(nameof(MySignalWithArguments), this, "MyCallbackWithArguments");
}

Das Senden von Signalen erfolgt mit der Methode EmitSignal.

public void SomeFunction()
{
    EmitSignal(nameof(MySignal));
    EmitSignal("MySignalWithArguments", "hello there", 28);
}

Beachten Sie, dass Sie einen Signalnamen immer mit dem Schlüsselwort nameof referenzieren können (angewendet auf den Beauftragten selbst).

Es ist möglich Werte beim Herstellen einer Verbindung durch Übergeben eines Objektarrays zu binden.

public int Value { get; private set; } = 0;

private void ModifyValue(int modifier)
{
    Value += modifier;
}

public void SomeFunction()
{
    var plusButton = (Button)GetNode("PlusButton");
    var minusButton = (Button)GetNode("MinusButton");

    plusButton.Connect("pressed", this, "ModifyValue", new object[] { 1 });
    minusButton.Connect("pressed", this, "ModifyValue", new object[] { -1 });
}

Signals support parameters and bound values of all the built-in types and Classes derived from Godot.Object. Consequently, any Node or Reference will be compatible automatically, but custom data objects will need to extend from Godot.Object or one of its subclasses.

public class DataObject : Godot.Object
{
    public string Field1 { get; set; }
    public string Field2 { get; set; }
}

Abschließend, Signale können durchs aufrufen von AddUserSignal erstellt werden, jedoch seien sie vorsichtig, dass dies durchgeführt, bevor das betroffene Signal benutzt wird (durch Connect oder EmitSignal).

public void SomeFunction()
{
    AddUserSignal("MyOtherSignal");
    EmitSignal("MyOtherSignal");
}

Präprozessor Festlegungen

Godot verfügt über eine Reihe von Definitionen, mit denen Sie Ihren C# Code abhängig von der Umgebung in die Sie kompilieren ändern können.

Bemerkung

Wenn Sie Ihr Projekt vor Godot 3.2 erstellt haben, müssen Sie Ihre csproj Datei ändern oder neu generieren, um diese Funktion zu verwenden (vergleichen Sie <DefineConstants> mit einem neuen 3.2+ -Projekt).

Beispiele

Sie können beispielsweise den Code basierend auf der Plattform ändern:

    public override void _Ready()
    {
#if GODOT_SERVER
        // Don't try to load meshes or anything, this is a server!
        LaunchServer();
#elif GODOT_32 || GODOT_MOBILE || GODOT_WEB
        // Use simple objects when running on less powerful systems.
        SpawnSimpleObjects();
#else
        SpawnComplexObjects();
#endif
    }

Oder Sie können erkennen in welcher Engine sich Ihr Code befindet, was für die Erstellung von Cross-Engine-Bibliotheken hilfreich ist:

    public void MyPlatformPrinter()
    {
#if GODOT
        GD.Print("This is Godot.");
#elif UNITY_5_3_OR_NEWER
        print("This is Unity.");
#else
        throw new InvalidWorkflowException("Only Godot and Unity are supported.");
#endif
    }

Vollständige Liste von Definitionen

  • GODOT wird immer in den Godot Einstellungen definiert.
  • Ob GODOT_64 oder GODOT_32 definiert wird, ist abhängig von der Architektur 64-bit oder 32-bit.
  • One of GODOT_X11, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_HTML5, or GODOT_SERVER depending on the OS. These names may change in the future. These are created from the get_name() method of the :ref:OS <class_OS> singleton, but not every possible OS the method returns is an OS that Godot with Mono runs on.

When exporting, the following may also be defined depending on the export features:

  • Je nach Plattformtyp eine von GODOT_PC, GODOT_MOBILE oder GODOT_WEB.
  • Eine von GODOT_ARM64_V8A oder GODOT_ARMEABI_V7A auf Android je nach Architektur.
  • Einer von GODOT_ARM64 oder GODOT_ARMV7 unter iOS abhängig von der Architektur.
  • Je nach Texturkomprimierungstyp GODOT_S3TC, GODOT_ETC und GODOT_ETC2.
  • Alle benutzerdefinierten Funktionen, die im Exportmenü hinzugefügt werden, werden großgeschrieben und mit dem Präfix foo -> GODOT_FOO versehen.

Zusätzlich zu dieser Dokumentation möchtest Du vielleicht auch einen Blick auf die verschieden Godot Demoprojekte werfen.