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

Diese Seite bietet einen Überblick über die häufig verwendeten Features von C# und Godot und wie sie zusammen verwendet werden.

Typumwandlung und Casting

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

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

Die Methode GetNode() gibt eine Node-Instanz zurück. Sie müssen sie explizit in den gewünschten abgeleiteten Typ konvertieren, in diesem Fall Sprite2D.

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

Casting und Typprüfung

Wirft InvalidCastException, wenn der zurückgegebene Node nicht in Sprite2D gecastet werden kann. Sie sollten ihn anstelle des as-Operators verwenden, wenn Sie ziemlich sicher sind, dass er nicht fehlschlagen wird.

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

Nutzen des AS-Operators

Der as-Operator gibt null zurück, wenn der Node nicht in Sprite2D gecastet werden kann, und aus diesem Grund kann er nicht mit Wertetypen verwendet werden.

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

Nutzen der generischen Methoden

Es werden auch generische Methoden bereitgestellt, um diese Typkonvertierung transparent zu machen.

GetNode<T>() castet den Node, bevor er zurückgegeben wird. Es wird eine InvalidCastException ausgelöst, wenn der Node nicht in den gewünschten Typ gecastet werden kann.

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

GetNodeOrNull<T>() verwendet den Operator as und gibt null zurück, wenn der Node nicht in den gewünschten Typ gecastet werden kann.

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

Typprüfung mit dem IS-Operator

Um zu prüfen, ob der Node in Sprite2D umgewandelt werden kann, können Sie den Operator is verwenden. Der is-Operator gibt false zurück, wenn der Node nicht in Sprite2D gecastet werden kann, andernfalls gibt er true zurück. Beachten Sie, dass das Ergebnis des Operators is immer false ist, wenn er gegen null verwendet wird.

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

if (null is Sprite2D)
{
    // This block can never happen.
}

Sie können auch eine neue Variable deklarieren, um das Ergebnis des Casts bedingt zu speichern, wenn der Operator is den Wert true liefert.

if (GetNode("MySprite") is Sprite2D mySprite)
{
    // The mySprite variable only exists inside this block, and it's never null.
    mySprite.SetFrame(0);
}

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

Präprozessor-Defines

Godot verfügt über eine Reihe von Defines, mit denen Sie Ihren C#-Code ändern können, je nach Umgebung, in die Sie kompilieren.

Beispiele

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

    public override void _Ready()
    {
#if (GODOT_MOBILE || GODOT_WEB)
        // Use simple objects when running on less powerful systems.
        SpawnSimpleObjects();
#else
        SpawnComplexObjects();
#endif
    }

Oder Sie können detektieren, 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 NotSupportedException("Only Godot and Unity are supported.");
#endif
    }

Oder Sie können Skripte schreiben, die auf mehrere Godot-Versionen abzielen und die Vorteile von Funktionen nutzen, die nur in einigen dieser Versionen verfügbar sind:

    public void UseCoolFeature()
    {
#if GODOT4_3_OR_GREATER || GODOT4_2_2_OR_GREATER
        // Use CoolFeature, that was added to Godot in 4.3 and cherry-picked into 4.2.2, here.
#else
        // Use a workaround for the absence of CoolFeature here.
#endif
    }

Vollständige Liste von Definitionen

  • GODOT ist immer für Godot-Projekte definiert.

  • TOOLS ist beim Build mit der Debug-Konfiguration (Editor und Editor-Player) definiert.

  • GODOT_REAL_T_IS_DOUBLE ist definiert, wenn die Property GodotFloat64 auf true gesetzt ist.

  • One of GODOT_LINUXBSD, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_WEB depending on the OS. These names may change in the future. These are created from the get_name() method of the OS singleton, but not every possible OS the method returns is an OS that Godot with .NET runs on.

  • GODOTX, GODOTX_Y, GODOTX_Y_Z, GODOTx_OR_GREATER, GODOTX_y_OR_GREATER und GODOTX_Y_z_OR_GREATER, wobei X, Y und Z durch die aktuelle Major-, Minor- und Patch-Version von Godot ersetzt werden. x, y und z werden durch alle Werte von 0 bis zur aktuellen Versionsnummer für diese Komponente ersetzt.

    Bemerkung

    Diese Defines wurden erstmals in Godot 4.0.4 und 4.1 hinzugefügt. Versions-Defines für frühere Versionen gibt es nicht, unabhängig von der aktuellen Godot-Version.

    Zum Beispiel: Godot 4.0.5 definiert GODOT4, GODOT4_OR_GREATER, GODOT4_0, GODOT4_0_OR_GREATER, GODOT4_0_5, GODOT4_0_4_OR_GREATER, und GODOT4_0_5_OR_GREATER. Godot 4.3. 2 definiert GODOT4, GODOT4_OR_GREATER, GODOT4_3, GODOT4_0_OR_GREATER, GODOT4_1_OR_GREATER, GODOT4_2_OR_GREATER, GODOT4_3_OR_GREATER, GODOT4_3_2, GODOT4_3_0_OR_GREATER, GODOT4_3_1_OR_GREATER, und GODOT4_3_2_OR_GREATER.

Beim Exportieren kann Folgendes auch abhängig von den Exportfunktionen definiert werden:

  • Eine von GODOT_PC, GODOT_MOBILE oder GODOT_WEB, abhängig vom Plattformtyp.

  • Eine von GODOT_WINDOWS, GODOT_LINUXBSD, GODOT_MACOS, GODOT_ANDROID, GODOT_IOS, oder GODOT_WEB, abhängig von der Plattform.

Ein Beispielprojekt finden Sie in der Betriebssystem-Testdemo: https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test