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

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.

Definizioni preprocessore

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