Godot 4 per Android con C#: Creare il Primo Progetto 2D

Questa è la seconda bozza della serie su Godot 4 per Android usando esclusivamente C#. In questo articolo vedremo come creare il primo progetto 2D con supporto .NET, configurarlo per Android, aggiungere una semplice scena con codice C# e preparare una prima esportazione di prova. Il tono e la struttura seguono le guide Android Java già presenti sul sito: pratica, didattica e passo passo.

Obiettivo dell’articolo

Alla fine di questa guida avrai:

un progetto Godot 4 2D con supporto .NET/C# attivo;
la configurazione base per il deploy su Android;
una scena principale con nodi essenziali e uno script C# collegato;
un messaggio visualizzato sullo schermo via C#;
una prima esportazione di test su dispositivo Android o emulatore.

Prerequisiti

Prima di iniziare assicurati di avere:

Godot 4 .NET (Mono) installato (versione 4.x con supporto C#);
.NET SDK compatibile con la tua versione di Godot (di solito .NET 6.0 o superiore);
Android SDK installato (dal pacchetto Android Studio o da riga di comando);
Java Development Kit (JDK) installato (versione 11 o 17, in base alle raccomandazioni di Godot);
un dispositivo Android con debug USB abilitato oppure un emulatore configurato;
familiarità di base con C# o con la programmazione a oggetti (per i principianti, i passaggi saranno comunque spiegati).

In questa guida daremo per scontato che tu abbia già installato gli strumenti. Nel prossimo articolo entreremo più nel dettaglio su scene, nodi e segnali.

Creare un nuovo progetto 2D con supporto .NET/C#

Avvia Godot 4 .NET (l’eseguibile specifico per C#). Dalla schermata iniziale procedi così:

Clicca su New Project.
Scegli una cartella vuota per il tuo progetto (es. GodotAndroidCSharp2D).
Imposta un Project Name descrittivo, ad esempio GodotAndroidCSharp2D.
Assicurati che l’opzione .NET o C# support sia abilitata (in Godot 4 .NET è attiva per default).
Clicca su Create & Edit per aprire l’editor.

A questo punto Godot creerà la struttura base del progetto con il supporto C#. Nella cartella del progetto troverai un file .csproj che rappresenta il progetto .NET vero e proprio.

Impostare il progetto come 2D

Godot non obbliga a scegliere tra 2D e 3D al momento della creazione, ma l’editor può essere messo in modalità 2D:

Nella parte alta dell’editor seleziona la scheda 2D (accanto a 3D e Script).
Verifica che l’area principale mostri la griglia 2D: questa sarà la tua area di lavoro.

Questo non cambia impostazioni interne, ma ti aiuta a organizzare il lavoro come gioco/app 2D.

Configurare il progetto per Android

Prima di scrivere codice, è utile impostare subito la piattaforma Android, così eventuali errori di configurazione emergono presto.

1. Aprire le impostazioni di esportazione

In alto, vai su Project > Export….
Nella finestra di esportazione clicca su Add….
Seleziona Android dall’elenco dei template.

Se non hai ancora scaricato i template di esportazione, Godot ti chiederà di farlo. Segui la procedura guidata (richiede una connessione Internet).

2. Configurare SDK, JDK e adb

Godot deve sapere dove si trovano Android SDK, JDK e lo strumento adb. Impostali così:

Vai su Editor > Editor Settings….
Nella colonna a sinistra cerca Export > Android.
Imposta i percorsi per:
- Android Sdk Path (es. C:\Android\Sdk su Windows o /Users/<utente>/Library/Android/sdk su macOS);
- Jarsigner e Keytool (normalmente rilevati dal JDK);
- Adb (di solito si trova in platform-tools nella cartella dell’SDK).

Una volta salvate queste impostazioni, chiudi la finestra e torna alla scheda Project > Export….

3. Configurare il preset Android minimo

Nel preset Android puoi lasciare la maggior parte delle impostazioni di default, ma ci sono alcuni campi importanti:

Package name: usa un identificativo univoco, es. com.example.godotandroidcsharp2d.
Version name e Version code: puoi lasciare 1.0 e 1 per la prova.
Permissions: per questa prima app non servono permessi extra.

Per la firma dell’APK in fase di test puoi usare una chiave di debug generata da Godot oppure una chiave tua. Per ora è sufficiente la configurazione automatica suggerita dall’editor.

Creare la scena principale

In Godot tutto parte da una scena, cioè un albero di nodi. Creiamo una scena principale molto semplice che mostri un messaggio.

1. Creare una nuova scena

Nella barra in alto clicca su Scene > New Scene.
Nella colonna di destra (Scene) clicca su 2D Scene per creare un nodo root di tipo Node2D.
Rinomina il nodo root da Node2D a Main (tasto destro > Rename).

Questa sarà la nostra scena principale, di tipo 2D.

2. Aggiungere i nodi essenziali

Aggiungiamo un nodo per visualizzare testo sullo schermo.

Con il nodo Main selezionato, clicca sul pulsante + in alto per aggiungere un figlio.
Nella finestra di ricerca digita Label e seleziona il nodo Label.
Clicca su Create.

Seleziona il nodo Label e, nel pannello Inspector, imposta:

Text: ad esempio Caricamento... (verrà poi sovrascritto da C#);
Usa il pannello 2D per spostare il Label al centro dello schermo (puoi trascinarlo con il mouse).

3. Salvare la scena

Vai su Scene > Save oppure premi Ctrl+S/Cmd+S.
Scegli un nome file, ad esempio Main.tscn.
Salva nella cartella principale del progetto (root del progetto Godot).

Ora hai un file Main.tscn nella root del progetto, che rappresenta la scena principale.

Impostare la scena principale come scena di avvio

Per far sì che Godot carichi automaticamente questa scena all’avvio:

Vai su Project > Project Settings….
Nella sezione Application seleziona la categoria Run.
Nel campo Main Scene clicca sull’icona della cartella e scegli Main.tscn.
Salva le impostazioni e chiudi la finestra.

Da questo momento, quando eseguirai il progetto, Godot caricherà automaticamente Main.tscn.

Creare e collegare uno script C# a un nodo

Ora aggiungiamo uno script C# che, all’avvio della scena, aggiorna il testo del Label e stampa un log in console.

1. Creare il file C#

Seleziona il nodo Main nella gerarchia.
Clicca sull’icona Attach Script (foglio con il simbolo C#) in alto nella colonna dei nodi.
Verifica che il linguaggio sia C#.
Imposta il Path su res://Scripts/Main.cs (Godot creerà la cartella Scripts se non esiste).
Lascia il Template di default.
Clicca su Create.

Godot aprirà l’editor di script integrato (oppure il tuo IDE esterno, se configurato) con il file Main.cs già creato e collegato al nodo Main.

2. Codice C# per mostrare un messaggio a schermo

Sostituisci il contenuto del file Main.cs con il seguente codice:

using Godot;
using System;

public partial class Main : Node2D
{
    // Riferimento al nodo Label nella scena
    private Label _messageLabel;

    public override void _Ready()
    {
        // Ottiene il nodo Label (figlio di Main) per nome
        _messageLabel = GetNode<Label>("Label");

        if (_messageLabel != null)
        {
            _messageLabel.Text = "Godot 4 + C# su Android!";
        }
        else
        {
            GD.PrintErr("Label non trovata nella scena.");
        }

        GD.Print("Scena Main inizializzata.");
    }

    public override void _Process(double delta)
    {
        // Qui potrai aggiungere logica che viene eseguita a ogni frame
    }
}

3. Spiegazione del codice

public partial class Main : Node2D: definisce una classe C# che estende Node2D, in linea con il tipo del nodo root della scena.
private Label _messageLabel;: campo privato che conterrà il riferimento al nodo Label.
public override void _Ready(): metodo chiamato da Godot quando il nodo (e i suoi figli) è pronto nella scena.
_messageLabel = GetNode<Label>("Label");: cerca un nodo figlio di tipo Label con nome esatto "Label" nella gerarchia sotto Main.
Se il nodo viene trovato, il testo viene impostato a "Godot 4 + C# su Android!", altrimenti viene loggato un errore con GD.PrintErr.
GD.Print("Scena Main inizializzata.");: stampa un messaggio nella console dell’editor, utile per il debug.
_Process(double delta): metodo chiamato a ogni frame, utile per logica di gioco continua; per ora è vuoto.

La posizione del file Main.cs nel progetto è:

res://Scripts/Main.cs (sul disco: nella cartella Scripts che si trova all’interno della root del progetto Godot).

Eseguire il progetto in editor

Prima di provare su Android, è buona pratica verificare che tutto funzioni in editor.

Assicurati che la scena Main.tscn sia salvata e che lo script Main.cs sia compilato (Godot potrebbe impiegare qualche secondo).
Clicca sul pulsante Play (icona ▶ in alto a destra) per eseguire il progetto.
Dovrebbe aprirsi una finestra con il testo Godot 4 + C# su Android! al centro.
Nella finestra di output dell’editor dovresti vedere il messaggio Scena Main inizializzata..

Se il testo non appare o se vengono mostrati errori, consulta la sezione Errori comuni più avanti.

Preparare una prima esportazione di prova su Android

Ora che la scena funziona in editor, possiamo creare un APK di prova e installarlo sul dispositivo Android.

1. Collegare il dispositivo o avviare l’emulatore

Su dispositivo reale: abilita le Opzioni sviluppatore e attiva il Debug USB, quindi collega il telefono via cavo al PC.
Su emulatore: avvia un dispositivo virtuale Android da Android Studio o dallo strumento che preferisci.

Verifica da terminale che il dispositivo sia visibile tramite adb devices. Dovresti vedere almeno un device in lista.

2. Esportare e installare dall’editor

In Godot vai di nuovo su Project > Export….
Seleziona il preset Android che hai creato prima.
Per una prima prova, puoi cliccare su Export & Run (se disponibile nella tua versione) per esportare e installare direttamente sul device collegato.
In alternativa, clicca su Export Project, scegli un percorso (es. builds/Android/) e un nome file (es. godot-android-csharp-2d-debug.apk).

Se esporti manualmente l’APK, potrai installarlo sul dispositivo con:

adb install -r godot-android-csharp-2d-debug.apk

Una volta installata l’app, aprila dal dispositivo: dovresti vedere lo stesso messaggio Godot 4 + C# su Android! mostrato in editor.

Errori comuni e come risolverli

Errore: "The name 'Label' does not exist" o null reference

Se nel log vedi errori relativi a Label o a un oggetto nullo:

Verifica che il nodo figlio si chiami esattamente Label (nome del nodo nella gerarchia).
Assicurati che lo script Main.cs sia collegato al nodo Main (controlla l’icona a forma di foglio accanto al nodo).
Verifica che il file Main.cs sia stato compilato senza errori (vedi la scheda Errors o Output).

Errore di compilazione C#

Gli errori di compilazione tipici includono:

mancata corrispondenza tra il nome della classe e quello del file (in Godot 4 con partial class questo è più flessibile, ma è buona pratica mantenerli coerenti);
mancanza dei namespace using Godot; o using System;;
errori di sintassi (parentesi mancanti, punti e virgola, ecc.).

Controlla sempre la prima riga in cui appare l’errore: spesso la causa è poco sopra.

Problemi con Android SDK o firma dell’APK

Se Godot non riesce a esportare su Android:

Verifica i percorsi in Editor Settings > Export > Android (SDK, JDK, adb).
Assicurati di aver scaricato i Export Templates per Android (verifica nella finestra Export se ci sono avvisi).
Per le prime prove usa un keystore di debug generato automaticamente, senza complicare troppo la firma.

Controlla sempre il log di esportazione: è la fonte principale di informazioni sugli errori.

Riepilogo

In questa bozza di articolo abbiamo visto come creare un progetto 2D in Godot 4 con supporto .NET/C#, configurare la piattaforma Android, creare una scena principale con un nodo Label, collegare uno script C# e visualizzare un messaggio a schermo. Hai anche preparato un preset di esportazione Android e generato un primo APK di prova da installare su dispositivo o emulatore.

Questi passaggi costituiscono la base per gli articoli successivi, in cui costruiremo comportamenti più complessi e interattivi mantenendo sempre il target Android in mente.

FAQ

Posso usare lo stesso progetto per altre piattaforme oltre ad Android?

Sì. Godot è multipiattaforma: con lo stesso progetto 2D C# puoi esportare su desktop, Web e altre piattaforme mobile, purché tu configuri i rispettivi preset di esportazione. In questa serie ci concentreremo soprattutto su Android, ma i concetti di base restano gli stessi.

Serve per forza Godot 4 .NET o posso usare la versione standard?

Per usare C# è necessario Godot 4 .NET, che integra il runtime .NET e il supporto per i progetti C#. La versione standard (senza .NET) supporta solo GDScript e altri linguaggi via estensioni, ma non C#.

Posso aprire e modificare i file C# da un IDE esterno come Rider o Visual Studio?

Sì. Godot può generare i file di soluzione/ progetto e puoi configurare un IDE esterno per l’editing. Per questa bozza ci siamo concentrati sull’editor integrato, ma in produzione è consigliabile usare un IDE avanzato per il supporto a refactoring, debug e completamento del codice.

Il codice C# è diverso tra desktop e Android?

La logica di gioco C# è la stessa. Ciò che cambia tra desktop e Android sono soprattutto le API specifiche di piattaforma (es. permessi, integrazione con servizi nativi). In questa serie evidenzieremo quando sarà necessario scrivere codice specifico per Android.

Anticipazione del prossimo articolo: scene, nodi e segnali

Nel prossimo articolo della serie approfondiremo la struttura interna di un progetto Godot 4 basato su C#:

come organizzare scene riutilizzabili e caricarle dinamicamente;
come sfruttare i diversi tipi di nodi 2D (Sprite2D, Button, Control, ecc.);
come usare i segnali (signals) per far comunicare nodi e script C# in modo disaccoppiato;
come gestire transizioni semplici tra schermate per una tipica app Android (es. schermo iniziale, menu, schermata di gioco).

Partiremo dal progetto creato in questa bozza e lo estenderemo, mantenendo il focus su una struttura pulita e facilmente manutenibile per il deploy su Android.

Nota: questo contenuto deve essere salvato esclusivamente come bozza e non pubblicato.

Godot 4 Android C#: Creare il Primo Progetto 2D