C# language features

Esta página provee un resumen acerca de las características comunmente utilizadas en C# y Godot y cómo son usadas.

Conversión de tipo y casting

C# es un lenguaje estáticamente tipado, por lo tanto, no puedes hacer lo siguiente:

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

The method GetNode() returns a Node instance. You must explicitly convert it to the desired derived type, Sprite2D in this case.

Para esto, hay varias opciones en C#.

Casting & Chequeo de Tipo

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

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

Utilizando el operador AS

The as operator returns null if the node cannot be cast to Sprite2D, and for that reason, it cannot be used with value types.

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

Utilizando métodos genéricos

Los métodos genéricos se proveen para hacer la conversión de tipo transparente.

GetNode<T>() realiza un casting del nodo antes de retornarlo. Lanzará una InvalidCastException si el nodo no puede ser convertido al tipo deseado.

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

GetNodeOrNull<T>() usa el operador as y retornará null si el nodo no puede ser convertido al tipo deseado.

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

Chequeo de tipo usando el operador IS

To check if the node can be cast to Sprite2D, you can use the is operator. The is operator returns false if the node cannot be cast to Sprite2D, otherwise it returns true. Note that when the is operator is used against null the result is always going to be false.

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

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

You can also declare a new variable to conditionally store the result of the cast if the is operator returns true.

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

Para tipos avanzados de comprobaciones, puedes mirar Pattern Matching.

Defines de preprocesador

Godot tiene un conjunto de definiciones que le permiten cambiar su código C# dependiendo del entorno en el que esté compilando.

Ejemplos

Por ejemplo, puedes cambiar el código basado en la plataforma:

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

O puedes detectar en qué motor está tu código, útil para hacer bibliotecas de motores cruzados:

    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
    }

Or you can write scripts that target multiple Godot versions and take advantage of features that are only available on some of those versions:

    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
    }

A continuación está la lista completa de hints

  • "GODOT" siempre está definido para los proyectos de Godot.

  • TOOLS is defined when building with the Debug configuration (editor and editor player).

  • GODOT_REAL_T_IS_DOUBLE is defined when the GodotFloat64 property is set to true.

  • 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, and GODOTX_Y_z_OR_GREATER, where X, Y, and Z are replaced by the current major, minor and patch version of Godot. x, y, and z are replaced by all values from 0 to the current version number for that component.

    Nota

    These defines were first added in Godot 4.0.4 and 4.1. Version defines for prior versions do not exist, regardless of the current Godot version.

    For example: Godot 4.0.5 defines GODOT4, GODOT4_OR_GREATER, GODOT4_0, GODOT4_0_OR_GREATER, GODOT4_0_5, GODOT4_0_4_OR_GREATER, and GODOT4_0_5_OR_GREATER. Godot 4.3.2 defines 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, and GODOT4_3_2_OR_GREATER.

Cuando se exporta, también se puede definir lo siguiente dependiendo de las características de la exportación:

  • Una de GODOT_PC, GODOT_MOBILE, o GODOT_WEB dependiendo del tipo de plataforma.

  • One of GODOT_WINDOWS, GODOT_LINUXBSD, GODOT_MACOS, GODOT_ANDROID, GODOT_IOS, or GODOT_WEB depending on the platform.

Para ver un proyecto de ejemplo, revisa la demo de pruebas de SO: https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test