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

Recursos da linguagem C#

Esta página fornece uma visão geral sobre os recursos comumente usados no C# e no Godot e como eles são usados juntos.

Conversão de Tipos e Casting

C# é uma linguagem estaticamente tipada. Portanto, você não pode fazer o seguinte:

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

O método GetNode() retorna uma instância de Node. Você deve convertê-la explicitamente para o tipo derivado desejado, Sprite2D neste caso.

Para isso, você tem várias opções em C#.

Casting e Verificação de Tipo

Lança uma InvalidCastException se o nó retornado não puder ser convertido para Sprite2D. Você usaria isso em vez do operador as se tiver certeza de que não vai falhar.

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

Usando o operador AS

O operador as retorna null se o nó não puder ser convertido para Sprite2D e, por esse motivo, não pode ser usado com tipos de valor.

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

Usando os métodos genéricos

Métodos genéricos também são providenciados para fazer esse tipo de conversão transparente.

GetNode<T>() faz a conversão do nó antes de retorná-lo. Um erro do tipo InvalidCastException será retornado caso o nó não possa ser convertido para o tipo desejado.

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

GetNodeOrNull<T>() usa o operador as e retornará null se o código não puder ser convertido para o tipo desejado.

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

Verificação de tipo usando o 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.
}

Você também pode declarar uma nova variável para armazenar condicionalmente o resultado da conversão se o operador is retornar true.

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

Para uma verificação de tipos mais avançada, você pode procurar em Correspondência de Padrões.

Definições de pré-processamento

Godot tem um conjunto de definições que permite a você mudar seu código C# dependendo do ambiente para o qual está compilando.

Exemplos

Por exemplo, você pode alterar o código baseado na plataforma:

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

Ou você pode detectar em qual engine seu código está, útil para fazer bibliotecas cross-engine:

    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
    }

Ou você pode escrever scripts direcionados a múltiplas versões do Godot e aproveitar recursos que estão disponíveis apenas em algumas dessas versões:

    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
    }

Lista completa de definições

  • GODOT é sempre definido para projetos Godot.

  • TOOLS é definido ao compilar com a configuração Debug (editor e reprodutor do editor).

  • GODOT_REAL_T_IS_DOUBLE é definido quando a propriedade GodotFloat64 está definida como true.

  • Um dentre GODOT_LINUXBSD, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_WEB dependendo do SO. Esses nomes podem mudar no futuro. Eles são criados a partir do método get_name() do singleton OS, mas nem todo SO possível que o método retorna é um SO no qual o Godot com .NET é executado.

  • GODOTX, GODOTX_Y, GODOTX_Y_Z, GODOTx_OR_GREATER, GODOTX_y_OR_GREATER e GODOTX_Y_z_OR_GREATER, onde X, Y e Z são substituídos pela versão major, minor e patch atual do Godot. x, y e z são substituídos por todos os valores de 0 até o número da versão atual para esse componente.

    Nota

    Essas definições foram adicionadas pela primeira vez no Godot 4.0.4 e 4.1. Definições de versão para versões anteriores não existem, independentemente da versão atual do Godot.

    Por exemplo: O Godot 4.0.5 define GODOT4, GODOT4_OR_GREATER, GODOT4_0, GODOT4_0_OR_GREATER, GODOT4_0_5, GODOT4_0_4_OR_GREATER e GODOT4_0_5_OR_GREATER. O Godot 4.3.2 define 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 e GODOT4_3_2_OR_GREATER.

Ao exportar, o seguinte também pode ser definido dependendo das características de exportação:

  • Um dos GODOT_PC, GODOT_MOBILE, ou GODOT_WEB, dependendo do tipo de plataforma.

  • Um dentre GODOT_WINDOWS, GODOT_LINUXBSD, GODOT_MACOS, GODOT_ANDROID, GODOT_IOS ou GODOT_WEB dependendo da plataforma.

Para ver um exemplo de projeto, veja um teste de demo de OS: https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test