Funzionalità del linguaggio C#

Questa pagina fornisce una panoramica delle funzionalità più comunemente utilizzate sia di C# sia di Godot, e di come sono utilizzate insieme.

Conversione di tipo e casting

C# è un linguaggio staticamente tipizzato. Pertanto, non è possibile fare il seguente:

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

Il metodo GetNode() restituisce un'istanza di Node. È necessario convertirla esplicitamente nel tipo derivato desiderato, in questo caso Sprite2D.

Per farlo, in C# sono disponibili diverse opzioni.

Casting e verifica del tipo

Genera InvalidCastException se non è possibile convertire il nodo restituito in Sprite2D. Si potrebbe usare al posto dell'operatore as se si è abbastanza sicuri che non fallirà.

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

Utilizzo dell'operatore AS

L'operatore as restituisce null se non è possibile convertire il nodo in Sprite2D e, per tale motivo, non si può utilizzare con tipi di valore.

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

Utilizzo dei metodi generici

Sono forniti anche metodi generici per rendere trasparente questa conversione di tipo.

GetNode<T>() effettua un cast del nodo prima di restituirlo. Genererà una InvalidCastException se non è possibile effettuare il cast del nodo nel tipo desiderato.

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

GetNodeOrNull<T>() utilizza l'operatore as e restituirà null se non è possibile convertire il nodo nel tipo desiderato.

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

Verifica del tipo tramite l'operatore IS

Per verificare se è possibile convertire il nodo in Sprite2D, si può utilizzare l'operatore is. L'operatore is restituisce false se non è possibile convertire il nodo in Sprite2D, altrimenti restituisce true. Si noti che quando l'operatore is è utilizzato con null, il risultato sarà sempre false.

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

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

È anche possibile dichiarare una nuova variabile per memorizzare condizionalmente il risultato della conversione se l'operatore is restituisce true.

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

Per una verifica dei tipi più avanzata, si può consultare Pattern Matching.

Preprocessor defines

Godot ha una serie di definizioni che consentono di modificare il codice C# a seconda dell'ambiente su cui si sta compilando.

Esempi

Ad esempio, è possibile cambiare il codice in base alla piattaforma:

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

Oppure rilevare in quale motore si trova il codice, utile per creare librerie 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
    }

Oppure è possibile scrivere script che mirano a più versioni di Godot e sfruttare le funzionalità disponibili solo su alcune di queste versioni:

    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
    }

Elenco completo di definizioni

  • GODOT è sempre definito per i progetti Godot.

  • TOOLS è definito quando si compila con la configurazione Debug (editor e esecuzione dall'editor).

  • GODOT_REAL_T_IS_DOUBLE è definito quando la proprietà GodotFloat64 è impostata su true.

  • Uno tra GODOT_LINUXBSD, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_WEB a seconda del sistema operativo. Questi nomi potrebbero cambiare in futuro. Sono creati dal metodo get_name() del singleton OS, ma non tutti gli OS possibili restituiti dal metodo sono OS su cui funziona Godot con .NET.

  • GODOTX, GODOTX_Y, GODOTX_Y_Z, GODOTx_OR_GREATER, GODOTX_y_OR_GREATER e GODOTX_Y_z_OR_GREATER, dove X, Y e Z sono sostituiti dalla versione principale, secondaria e patch attuale di Godot. x, y e z sono sostituiti da tutti i valori da 0 al numero di versione attuale per quel componente.

    Nota

    Queste definizioni sono state aggiunte per la prima volta in Godot 4.0.4 e 4.1. Le definizioni di versione per le versioni precedenti non esistono, a prescindere dalla versione attuale di Godot.

    Ad esempio: Godot 4.0.5 definisce GODOT4, GODOT4_OR_GREATER, GODOT4_0, GODOT4_0_OR_GREATER, GODOT4_0_5, GODOT4_0_4_OR_GREATER e GODOT4_0_5_OR_GREATER. Godot 4.3.2 definisce 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.

All'esportazione, a seconda delle funzionalità di esportazione, è possibile definire anche quanto segue:

  • Uno tra GODOT_PC, GODOT_MOBILE o GODOT_WEB a seconda del tipo di piattaforma.

  • Uno tra GODOT_WINDOWS, GODOT_LINUXBSD, GODOT_MACOS, GODOT_ANDROID, GODOT_IOS o GODOT_WEB a seconda della piattaforma.

Per vedere un progetto d'esempio, vedi la demo di test del sistema operativo: https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test