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

Le basi di C#

Introduzione

Questa pagina fornisce una breve introduzione a C#, sia per quanto riguarda la sua natura sia per come utilizzarlo in Godot. In seguito, potresti voler dare un'occhiata a come utilizzare funzionalità specifiche, leggere le differenze tra l'API di C# e di GDScript e (ri)vedere la sezione scripting del tutorial passo per passo.

C# è un linguaggio di programmazione di alto livello sviluppato da Microsoft. In Godot, è implementato con il runtime .NET moderno.

Attenzione

I progetti scritti in C# utilizzando Godot 4 al momento non possono essere esportati sulla piattaforma web. Per utilizzare C# sulla piattaforma web, si consiglia di utilizzare Godot 3. Il supporto per le piattaforme Android e iOS è disponibile a partire da Godot 4.2, ma è sperimentale e si applicano alcune limitazioni.

Nota

Questo non è un tutorial completo sul linguaggio C# nel suo complesso. Se non si ha familiarità con la sua sintassi o le sue funzionalità, consultare la Guida a C# di Microsoft o cercare un'introduzione adeguata altrove.

Prerequisiti

Godot include le parti di .NET necessarie per eseguire giochi già compilati. Tuttavia, Godot non include gli strumenti necessari per la creazione e la compilazione di giochi, come MSBuild e il compilatore C#. Questi sono inclusi nell'SDK di .NET e devono essere installati separatamente.

In sintesi, è necessario aver installato l'SDK di .NET e la versione di Godot abilitata per .NET.

Scaricare e installare l'ultima versione stabile dell'SDK dalla pagina di download .NET. Godot 4.5 richiede .NET 8 o superiore, ma l'esportazione per Android richiede .NET 9 o superiore.

Importante

Assicurarsi di installare la versione a 64 bit degli SDK se si sta utilizzando la versione a 64 bit di Godot.

Se si sta compilando Godot dal codice sorgente, assicurarsi di seguire i passaggi per abilitare il supporto per .NET nella propria build, come descritto nella pagina Compilare con .NET.

Configurare un editor esterno

Il supporto per C# nell'editor di script integrato di Godot è minimo. Si consiglia di utilizzare un IDE o un editor esterno, come Visual Studio Code o Visual Studio. Questi offrono completamento automatico, debug e altre utili funzionalità per C#. Per selezionare un editor esterno in Godot, cliccare su Editor → Impostazioni dell'editor e scorrere fino a Dotnet. In Dotnet, cliccare su Editor e selezionare l'editor esterno desiderato. Godot attualmente supporta i seguenti editor esterni:

Visual Studio 2022
Visual Studio Code
MonoDevelop
Visual Studio per Mac
JetBrains Rider

Per informazioni su come configurare un editor esterno, consultare le sezioni seguenti:

JetBrains Rider

Dopo aver letto la sezione "Prerequisiti", scaricare e installare JetBrains Rider.

Nel menu Editor -> impostazioni dell'editor di Godot:

Impostare Dotnet -> Editor -> Editor esterno su JetBrains Rider.

In Rider:

Imposta MSBuild version su .NET Core.
Se si utilizza una versione di Rider precedente alla 2024.2, installare l'estensione Godot support. Questa funzionalità è ora integrata in Rider.

Visual Studio Code

Dopo aver letto la sezione "Prerequisiti", scaricare e installare Visual Studio Code (noto anche come VS Code).

Nel menu Editor -> impostazioni dell'editor di Godot:

Impostare Dotnet -> Editor -> Editor esterno su Visual Studio Code.

In Visual Studio Code:

Installare l'estensione C#.

Per configurare un progetto per il debug, è necessario un file tasks.json e launch.json nella cartella .vscode con la configurazione necessaria.

Ecco un launch.json di esempio:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Play",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${env:GODOT4}",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
        }
    ]
}

Affinché questa configurazione di avvio funzioni, è necessario impostare una variabile d'ambiente GODOT4 che punti all'eseguibile Godot oppure sostituire il parametro program con il percorso all'eseguibile Godot.

Ecco un tasks.json di esempio:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": [
                "build"
            ],
            "problemMatcher": "$msCompile"
        }
    ]
}

Ora, quando il debugger viene avviato in Visual Studio Code, il progetto Godot verrà eseguito.

Visual Studio (solo per Windows)

Scaricare e installare la versione più recente di Visual Studio. Visual Studio includerà gli SDK necessari se sono stati selezionati i workload corretti, quindi non è necessario installare manualmente gli elementi elencati nella sezione "Prerequisiti".

Durante l'installazione di Visual Studio, selezionare questo workload:

Sviluppo desktop .NET

Nel menu Editor -> impostazioni dell'editor di Godot:

Impostare Dotnet -> Editor -> Editor esterno su Visual Studio.

Nota

Se appare un errore del tipo "Unable to find package Godot.NET.Sdk", la configurazione di NuGet potrebbe essere errata e deve essere corretta.

Un modo semplice per correggere il file di configurazione di NuGet è rigenerarlo. In una finestra di Esplora file, andare a %AppData%\NuGet. Rinominare o eliminare il file NuGet.Config. Quando il progetto Godot viene compilato, il file verrà creato automaticamente con i valori predefiniti.

To debug your C# scripts using Visual Studio, open the .sln file that is generated after opening the first C# script in the editor. In the Debug menu, go to the Debug Properties menu item for your project. Click the Create a new profile button and choose Executable. In the Executable field, browse to the path of the C# version of the Godot editor, or type %GODOT4% if you have created an environment variable for the Godot executable path. It must be the path to the main Godot executable, not the 'console' version. For the Working Directory, type a single period, ., meaning the current directory. Also check the Enable native code debugging checkbox. You may now close this window, click downward arrow on the debug profile dropdown, and select your new launch profile. Hit the green start button, and your game will begin playing in debug mode.

Creare uno script C#

Dopo aver configurato correttamente C# per Godot, dovrebbero apparire la seguente opzioni quando viene selezionato Allega script nel menu contestuale di un nodo nella scena:

../../../_images/attachcsharpscript.webp

Si noti che, sebbene alcuni dettagli cambino, la maggior parte dei concetti funziona allo stesso modo quando si usa C# per lo scripting. Se non si ha familiarità con Godot, a questo punto potrebbe essere utile seguire i tutorial su Linguaggi di scripting. Sebbene alcune pagine di documentazione siano ancora prive di esempi in C#, la maggior parte dei concetti può essere trasferita da GDScript.

Configurazione del progetto e flusso di lavoro

Quando si crea il primo script C#, Godot inizializza i file C# di progetto per il progetto Godot. Questo include la generazione di una soluzione C# (.sln) e di un file di progetto (.csproj), oltre ad alcuni file e cartelle di utilità (.godot/mono). Tutti questi file, tranne .godot/mono, sono importanti e si dovrebbero inserire nel proprio sistema di controllo versione. Tutto ciò che si trova in .godot si può tranquillamente aggiungere alla lista degli elementi ignorati del VCS. Durante la risoluzione dei problemi, a volte può essere utile eliminare la cartella .godot/mono e lasciarla rigenerare.

Esempio

Ecco uno script C# vuoto con alcuni commenti per dimostrarne il funzionamento.

using Godot;

public partial class YourCustomClass : Node
{
    // Member variables here, example:
    private int _a = 2;
    private string _b = "textvar";

    public override void _Ready()
    {
        // Called every time the node is added to the scene.
        // Initialization here.
        GD.Print("Hello from C# to Godot :)");
    }

    public override void _Process(double delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

Come si può vedere, le funzioni normalmente in ambito globale in GDScript, come la funzione print di Godot, sono disponibili nella classe statica GD, che fa parte dello spazio dei nomi Godot. Per un elenco completo dei metodi della classe GD, consultare le pagine di riferimento classi @GDScript e @GlobalScope.

Nota

Da tenere presente che la classe che si desidera associare al proprio nodo deve avere lo stesso nome del file .cs. Se no, verrà generato il seguente errore:

"Cannot find class XXX for script res://XXX.cs"

Differenze generali tra C# e GDScript

L'API di C# utilizza il PascalCase invece del snake_case in GDScript/C++. Ove possibile, campi e getter/setter sono stati convertiti in proprietà. In generale, l'API di C# in Godot si sforza di essere il più idiomatica possibile.

Per ulteriori informazioni, consultare la pagina Differenze dell'API C# rispetto a GDScript.

Avvertimento

È necessario (ri)compilare gli assembly del progetto ogni volta che si desidera visualizzare nuove variabili o segnali esportati nell'editor. È possibile attivare questa compilazione manualmente cliccando sul pulsante Compila nell'angolo in alto a destra dell'editor.

Sarà inoltre necessario ricostruire gli assembly del progetto per applicare le modifiche negli script strumento (tool).

Insidie attuali e problemi noti

Poiché il supporto per C# è piuttosto nuovo in Godot, ci sono alcune difficoltà di sviluppo e aspetti da risolvere. Di seguito è riportato un elenco dei problemi più importanti di cui è necessario essere a conoscenza quando ci si tuffa in C# in Godot. In caso di dubbi, è suggerito consultare anche il tracker ufficiale per i problemi di .NET.

È possibile creare estensioni per editor, ma al momento è piuttosto complicato.
Al momento, lo stato non viene salvato né ripristinato durante il ricaricamento a caldo, ad eccezione delle variabili esportate.
Gli script C# allegati devono fare riferimento a una classe il cui nome corrisponda al nome del file.
Esistono alcuni metodi come Get()/Set(), Call()/CallDeferred() e il metodo di connessione del segnale Connect() che si basano sulle convenzioni di denominazione in snake_case dell'API di Godot. Quindi, ad esempio, quando si utilizza CallDeferred("AddChild"), AddChild non funzionerà perché l'API si aspetta la versione originale di add_child in snake_case. Nonostante ciò, è possibile utilizzare qualsiasi proprietà o metodo personalizzato senza questa limitazione. Si consiglia di utilizzare StringName esposto in PropertyName, MethodName e SignalName per evitare di allocare StringName aggiuntivi e di preoccuparsi dei nomi in snake_case.

A partire da Godot 4.0, l'esportazione di progetti .NET è supportata per le piattaforme desktop (Linux, Windows e macOS). Altre piattaforme saranno supportate nelle future versioni 4.x.

Errori comuni

Si potrebbe riscontrare il seguente errore quando si prova a modificare alcuni valori negli oggetti di Godot, ad esempio quando si prova a cambiare la coordinata X di un Node2D:

public partial class MyNode2D : Node2D
{
    public override void _Ready()
    {
        Position.X = 100.0f;
        // CS1612: Cannot modify the return value of 'Node2D.Position' because
        // it is not a variable.
    }
}

Questo è perfettamente normale. Le strutture (in questo esempio, un Vector2) in C# vengono copiate all'assegnazione, il che significa che quando si recupera un oggetto di questo tipo da una proprietà o da un indicizzatore, si ottiene una sua copia, non l'oggetto stesso. Modificare tale copia senza riassegnarla in seguito non porterà a nulla.

La soluzione alternativa è semplice: recuperare l'intera struct, modificare il valore che si desidera modificare e riassegnare la proprietà.

var newPosition = Position;
newPosition.X = 100.0f;
Position = newPosition;

A partire da C# 10, è anche possibile utilizzare le espressioni with sulle struct, consentendo di fare la stessa cosa su una sola riga.

Position = Position with { X = 100.0f };

Per leggerne di più su questo errore, consultare la Guida di riferimento al linguaggio C#.

Prestazioni di C# in Godot

Vedi anche

Per un confronto delle prestazioni dei linguaggi supportati da Godot, consultare Quale linguaggio di programmazione è il più veloce?.

La maggior parte delle proprietà degli oggetti C# di Godot basati su GodotObject (ad esempio, qualsiasi Node come Control o Node3D come Camera3D) richiedono chiamate native (interop) per comunicare con il core C++ di Godot. Si consiglia di assegnare i valori di tali proprietà a una variabile locale se è necessario modificarle o leggerle più volte in un'unica sezione di codice:

using Godot;

public partial class YourCustomClass : Node3D
{
    private void ExpensiveReposition()
    {
        for (var i = 0; i < 10; i++)
        {
            // Position is read and set 10 times which incurs native interop.
            // Furthermore the object is repositioned 10 times in 3D space which
            // takes additional time.
            Position += new Vector3(i, i);
        }
    }

    private void Reposition()
    {
        // A variable is used to avoid native interop for Position on every loop.
        var newPosition = Position;
        for (var i = 0; i < 10; i++)
        {
            newPosition += new Vector3(i, i);
        }
        // Setting Position only once avoids native interop and repositioning in 3D space.
        Position = newPosition;
    }
}

Il passaggio di array grezzi (come byte[]) o string all'API di C# in Godot richiede il marshalling, che è relativamente costoso.

La conversione implicita da string a NodePath o StringName comporta sia costi di interoperabilità nativa sia di marshalling, poiché string deve essere sottoposta a marshalling e passata al rispettivo costruttore nativo.

Utilizzare i pacchetti NuGet in Godot

I pacchetti NuGet possono essere installati e utilizzati con Godot, come con qualsiasi progetto C#. Molti IDE sono in grado di aggiungere pacchetti direttamente. Si possono anche aggiungere manualmente inserendo il riferimento al pacchetto nel file .csproj situato nella radice del progetto:

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
    </ItemGroup>
    ...
</Project>

Godot scarica e installa automaticamente i nuovi pacchetti NuGet aggiunti la prossima volta che compila il progetto.

Profilazione del codice C#

Per la profilazione delle prestazioni e della memoria del codice gestito, è possibile utilizzare i seguenti strumenti:

JetBrains Rider con l'estensione dotTrace/dotMemory.
JetBrains dotTrace/dotMemory autonomo.
Visual Studio.

La profilazione simultanea del codice gestito e non gestito è possibile sia con gli strumenti JetBrains sia con Visual Studio, ma è limitata a Windows.