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

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.

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

C# support in Godot's built-in script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or Visual Studio. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Dotnet. Under Dotnet, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:

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

When you create the first C# script, Godot initializes the C# project files for your Godot project. This includes generating a C# solution (.sln) and a project file (.csproj), as well as some utility files and folders (.godot/mono). All of these but .godot/mono are important and should be committed to your version control system. Everything under .godot can be safely added to the ignore list of your VCS. When troubleshooting, it can sometimes help to delete the .godot/mono folder and let it regenerate.

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

You need to (re)build the project assemblies whenever you want to see new exported variables or signals in the editor. This build can be manually triggered by clicking the Build button in the top right corner of the 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

You might encounter the following error when trying to modify some values in Godot objects, e.g. when trying to change the X coordinate of a 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 struttura, 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 strutture, 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.

The implicit conversion from string to NodePath or StringName incur both the native interop and marshalling costs as the string has to be marshalled and passed to the respective native constructor.

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>

A partire dalla versione Godot 3.2.3, 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.

Profiling managed and unmanaged code at once is possible with both JetBrains tools and Visual Studio, but limited to Windows.