Godot 4 per Android con C# – Guida 5: interfacce touch, HUD e layout responsive

In questa quinta guida della serie su Godot 4 per Android con C# creiamo un'interfaccia utente completa: pulsanti touch, etichette (Label), pannelli e un semplice HUD di gioco con punteggio e comandi virtuali. Imparerai a usare i nodi Control e Container, configurare ancoraggi e margini per adattare l'interfaccia a diversi schermi Android e collegare i segnali dei pulsanti a uno script C#. Concluderemo con un piccolo progetto pratico e la procedura per testarlo sia su emulatore sia su dispositivo reale.

Prerequisiti e obiettivi della guida

Questa guida è pensata sia per chi sta iniziando con Godot 4 e C#, sia per sviluppatori con esperienza su altre piattaforme (ad esempio Android Java/Kotlin) che vogliono capire rapidamente come strutturare un'interfaccia touch in Godot.

Prima di iniziare dovresti avere:

Godot 4.x installato con supporto C# (Mono).
SDK Android e toolchain configurati in Godot (per export su Android).
Almeno un progetto Godot 4 creato con una scena base 2D o 3D.
Conoscenze di base di C# (classi, metodi, eventi/delegati).

Alla fine della guida sarai in grado di:

Capire la differenza tra nodi Control e nodi grafici (Sprite, Node2D, ecc.).
Usare Container per allineare e distribuire elementi UI.
Impostare ancoraggi, margini e dimensioni minime per diversi schermi Android.
Creare un HUD di gioco con punteggio e pulsanti virtuali.
Collegare segnali dei pulsanti a script C# e gestire gli eventi touch.
Testare e ottimizzare l'interfaccia su emulatore e dispositivo.

Concetti chiave: Control, Container, HUD e layout

Nodi Control: la base dell'interfaccia in Godot

I nodi Control sono la base per tutte le interfacce in Godot. Qualsiasi elemento UI che può ricevere input (pulsanti, slider, text field) o visualizzare informazioni (Label, TextureRect, pannelli) deriva da Control. A differenza dei nodi 2D/3D, i Control lavorano in coordinate di interfaccia e gestiscono automaticamente ridimensionamento, allineamento e ancoraggi rispetto alla finestra o al genitore.

Alcuni Control fondamentali per un HUD touch Android:

Label: mostra testo (punteggio, tempo, messaggi).
Button: pulsante classico, anche per touch.
TextureButton: pulsante con icona o grafica personalizzata.
Panel: riquadro di sfondo per raggruppare elementi HUD.
MarginContainer: aggiunge margini interni a un gruppo di controlli.
HBoxContainer / VBoxContainer: distribuiscono automaticamente gli elementi in riga o colonna.

Ancoraggi e margini: adattare la UI agli schermi Android

Su Android i dispositivi hanno risoluzioni e proporzioni molto diverse. In Godot 4, i nodi Control usano:

Anchor (anchor_left, anchor_right, anchor_top, anchor_bottom): definiscono a quale lato o porzione del contenitore il nodo è “ancorato” (es. in alto a sinistra, a tutta larghezza, centrato).
Offset / Margini (offset_left, offset_top, ecc.): la distanza, in pixel, dall'ancoraggio.

Per un HUD che deve stare sempre in alto, ad esempio, userai tipicamente:

Anchor Top/Left/Right fissati ai bordi superiori/laterali.
Margini piccoli per non far toccare il bordo dello schermo.

Container: layout automatici e responsive

I Container sono nodi Control speciali che ridimensionano e posizionano automaticamente i figli, molto utili per evitare calcoli manuali di posizioni e per ottenere un layout che si adatta a risoluzioni diverse.

I più usati in un HUD Android sono:

HBoxContainer: distribuisce i controlli orizzontalmente (ideale per una barra dei pulsanti).
VBoxContainer: distribuisce i controlli verticalmente (menu, colonne di pulsanti).
MarginContainer: applica padding interno a un gruppo di controlli (utile per pannelli HUD).
CenterContainer: centra i controlli al suo interno (es. messaggio “Pausa”).

In questa guida userai soprattutto MarginContainer e HBoxContainer per creare una barra HUD in alto e pulsanti virtuali in basso.

Creare la base dell'HUD: scena, nodi e struttura

1. Creare una nuova scena HUD

Per mantenere il progetto ordinato, conviene creare una scena separata dedicata all'HUD.

In Godot 4, crea una nuova scena.
Come nodo radice scegli CanvasLayer (così l'HUD resta in primo piano rispetto alla scena di gioco).
Rinomina il nodo radice in HUD.

Il CanvasLayer è ideale per HUD e overlay, perché non è influenzato dal movimento della camera 2D o 3D.

2. Aggiungere un pannello superiore con punteggio

Ora aggiungiamo un pannello in alto con una Label per il punteggio:

Aggiungi come figlio di HUD un nodo Control, rinominalo in TopBar.
Nell'Inspector imposta Anchors Preset su Top Wide (in Godot 4 puoi usare il menu contestuale degli ancoraggi).
Imposta un'altezza fissa (es. Custom Minimum Height = 64 o un valore adatto al tuo progetto).
Come figlio di TopBar aggiungi un MarginContainer, rinominalo in TopMargin.
Dentro TopMargin aggiungi un HBoxContainer, rinominalo in TopContent.
Come figlio di TopContent aggiungi una Label, rinominala in ScoreLabel.

Imposta il testo iniziale di ScoreLabel a Score: 0 e, se vuoi, un allineamento a sinistra. Il MarginContainer si occuperà del padding, l'HBoxContainer allineerà correttamente elementi aggiuntivi (es. vite, timer) senza dover riposizionare tutto a mano.

3. Aggiungere pulsanti virtuali per i controlli touch

Creiamo ora una barra inferiore con pulsanti virtuali (es. Sinistra, Destra, Azione):

Come figlio di HUD aggiungi un Control e rinominalo in BottomBar.
Imposta gli ancoraggi di BottomBar a Bottom Wide e una Custom Minimum Height simile a TopBar.
Dentro BottomBar aggiungi un MarginContainer (BottomMargin).
Dentro BottomMargin aggiungi un HBoxContainer (BottomButtons).
Dentro BottomButtons aggiungi tre Button o TextureButton:

BtnLeft – testo: «<» (o un'icona freccia sinistra).
BtnRight – testo: «>».
BtnAction – testo: «Action» o un'icona.

Nel HBoxContainer puoi regolare la proprietà Separation per aumentare la distanza tra i pulsanti, e usare Size Flags dei pulsanti (es. Expand) per farli riempire lo spazio orizzontale in modo uniforme su tutti gli schermi.

Collegare i segnali dei pulsanti a uno script C#

1. Creare lo script C# dell'HUD

Ora creiamo uno script C# per gestire punteggio e input dai pulsanti virtuali.

Seleziona il nodo radice HUD.
Crea un nuovo script C# (es. HUD.cs) e allegalo al nodo.

Un esempio di script di base potrebbe essere:

using Godot; using System; public partial class HUD : CanvasLayer { private Label _scoreLabel; private int _score = 0; public override void _Ready() { // Recupero dei riferimenti ai nodi UI _scoreLabel = GetNode<Label>("TopBar/TopMargin/TopContent/ScoreLabel"); // Inizializzo il testo del punteggio UpdateScoreLabel(); // Collego i segnali dei pulsanti var btnLeft = GetNode<Button>("BottomBar/BottomMargin/BottomButtons/BtnLeft"); var btnRight = GetNode<Button>("BottomBar/BottomMargin/BottomButtons/BtnRight"); var btnAction = GetNode<Button>("BottomBar/BottomMargin/BottomButtons/BtnAction"); btnLeft.Pressed += OnLeftPressed; btnRight.Pressed += OnRightPressed; btnAction.Pressed += OnActionPressed; } private void UpdateScoreLabel() { _scoreLabel.Text = $"Score: {_score}"; } // Esempio: incrementa il punteggio quando viene premuto il pulsante Azione private void OnActionPressed() { _score += 10; UpdateScoreLabel(); } // Qui potresti notificare il tuo Player o GameController private void OnLeftPressed() { GD.Print("Move Left"); } private void OnRightPressed() { GD.Print("Move Right"); } }

In questo esempio colleghiamo i segnali in C# usando gli eventi Pressed dei pulsanti. Non è necessario passare dal pannello "Node" dell'editor, anche se puoi farlo se preferisci un workflow più visuale.

2. Collegare i pulsanti al Player o al GameController

Nella maggior parte dei giochi, l'HUD non dovrebbe contenere la logica di movimento del personaggio, ma inviare comandi a un nodo dedicato (es. Player o GameController).

Una soluzione pratica è esporre eventi pubblici nello script HUD, che altri nodi possono sottoscrivere:

public partial class HUD : CanvasLayer { public event Action LeftPressed; public event Action RightPressed; public event Action ActionPressed; // ... _Ready e altre parti come prima ... private void OnLeftPressed() { LeftPressed?.Invoke(); } private void OnRightPressed() { RightPressed?.Invoke(); } private void OnActionPressed() { ActionPressed?.Invoke(); _score += 10; UpdateScoreLabel(); } }

Nel tuo GameController o Player, puoi collegarti agli eventi HUD nel metodo _Ready():

public override void _Ready() { var hud = GetNode<HUD>("/root/Main/HUD"); // Adatta il path al tuo progetto hud.LeftPressed += () => MoveLeft(); hud.RightPressed += () => MoveRight(); hud.ActionPressed += () => JumpOrShoot(); }

In questo modo separi la logica di input dalla logica di gioco, mantenendo il codice più modulare e manutenibile.

Esempio completo: piccolo HUD con punteggio e pulsanti virtuali

Ricapitoliamo con un esempio predisposto per essere integrato in un semplice gioco 2D: l'HUD mostra il punteggio in alto e tre pulsanti virtuali in basso (Sinistra, Destra, Azione). Ogni pressione di "Azione" aumenta il punteggio, mentre Sinistra/Destra stampano un log (che potrai sostituire con la logica di movimento).

1. Struttura dei nodi HUD

La struttura finale della scena HUD sarà simile a questa:

HUD (CanvasLayer) ├── TopBar (Control) │ └── TopMargin (MarginContainer) │ └── TopContent (HBoxContainer) │ └── ScoreLabel (Label) └── BottomBar (Control) └── BottomMargin (MarginContainer) └── BottomButtons (HBoxContainer) ├── BtnLeft (Button) ├── BtnRight (Button) └── BtnAction (Button)

2. Script C# completo dell'HUD

Ecco uno script HUD completo e commentato, pronto da usare:

using Godot; using System; public partial class HUD : CanvasLayer { // Eventi pubblici per collegare l'HUD alla logica di gioco public event Action LeftPressed; public event Action RightPressed; public event Action ActionPressed; private Label _scoreLabel; private int _score = 0; public override void _Ready() { // Recupero dei riferimenti ai nodi UI tramite il loro percorso nella scena _scoreLabel = GetNode<Label>("TopBar/TopMargin/TopContent/ScoreLabel"); var btnLeft = GetNode<Button>("BottomBar/BottomMargin/BottomButtons/BtnLeft"); var btnRight = GetNode<Button>("BottomBar/BottomMargin/BottomButtons/BtnRight"); var btnAction = GetNode<Button>("BottomBar/BottomMargin/BottomButtons/BtnAction"); // Collego gli eventi C# ai segnali Godot btnLeft.Pressed += OnLeftPressedInternal; btnRight.Pressed += OnRightPressedInternal; btnAction.Pressed += OnActionPressedInternal; UpdateScoreLabel(); } private void UpdateScoreLabel() { _scoreLabel.Text = $"Score: {_score}"; } private void OnLeftPressedInternal() { // Notifico eventuali listener esterni LeftPressed?.Invoke(); GD.Print("HUD: Left button pressed"); } private void OnRightPressedInternal() { RightPressed?.Invoke(); GD.Print("HUD: Right button pressed"); } private void OnActionPressedInternal() { ActionPressed?.Invoke(); // Esempio: incrementa il punteggio _score += 10; UpdateScoreLabel(); GD.Print("HUD: Action button pressed, score = " + _score); } // Metodo pubblico per aggiornare il punteggio dall'esterno (es. GameController) public void SetScore(int value) { _score = value; UpdateScoreLabel(); } }

Assicurati che i nomi dei nodi nella scena coincidano con i percorsi usati in GetNode<T>. In caso di dubbi, copia i Node Path direttamente dall'Inspector di Godot.

3. Integrazione dell'HUD nella scena principale

Per usare l'HUD nel tuo gioco:

Aggiungi la scena HUD.tscn come figlio della scena principale (es. Main).
Assicurati che HUD sia un CanvasLayer separato dalla logica di gioco.
Nel tuo script di gioco principale, recupera il riferimento a HUD e collegati ai suoi eventi.

Esempio di script C# per la scena principale:

using Godot; public partial class Main : Node { private HUD _hud; public override void _Ready() { _hud = GetNode<HUD>("HUD"); // Collegamento ai comandi dell'HUD _hud.LeftPressed += OnLeft; _hud.RightPressed += OnRight; _hud.ActionPressed += OnAction; } private void OnLeft() { GD.Print("Main: Left command"); // TODO: chiama qui i metodi del Player } private void OnRight() { GD.Print("Main: Right command"); } private void OnAction() { GD.Print("Main: Action command"); } }

Adattare l'interfaccia a diversi schermi Android

1. Impostare la risoluzione di riferimento (Viewport)

Prima di rifinire ancoraggi e layout, definisci una risoluzione di riferimento nel progetto:

Apri Project > Project Settings.
Vai alla sezione Display > Window.
Imposta Viewport Width e Height (ad esempio 1080×1920 o 720×1280 per un layout verticale, 1920×1080 per orizzontale).
Verifica le modalità di ridimensionamento (stretch mode/scale) in base al tipo di gioco.

Questi valori rappresentano la base su cui progetterai l'interfaccia; Godot si occuperà di scalare la UI sui vari dispositivi.

2. Uso pratico di ancoraggi e container

Per un HUD robusto su Android, segui queste linee guida:

Evita posizionamenti assoluti: usa Anchors Preset (Top, Bottom, Full Rect) invece di modificare a mano solo gli offset.
Usa Container quando possibile: HBox/VBox distribuiscono meglio spazio e margini, soprattutto per pulsanti multipli.
Testa in orizzontale e verticale se il tuo gioco supporta entrambe le orientazioni.
Imposta Size Flags adeguati: per i pulsanti principali, Expand + Fill sugli assi rilevanti aiuta a occupare correttamente lo spazio.

3. Ridimensionamento touch-friendly

Su dispositivi touch, i controlli devono essere abbastanza grandi da essere premuti comodamente con il dito. Qualche riferimento pratico:

Mira ad almeno 48–56 dp di dimensione minima per i pulsanti (adatta in base alla risoluzione di riferimento).
Evita di posizionare pulsanti critici troppo vicini ai bordi estremi per non confliggere con gesture di sistema.
Usa icone e testo chiari, con contrasto sufficiente rispetto allo sfondo del gioco.

Testare l'HUD su emulatore e dispositivo Android

1. Test rapido con l'emulatore Android

Per un ciclo di sviluppo veloce puoi usare un emulatore Android (Android Studio o altri):

Avvia l'emulatore con la risoluzione/forma desiderata (phone, tablet, vari DPI).
In Godot apri Project > Export e assicurati di avere un profilo Android configurato.
Usa Debug > Deploy with Remote Debug (o l'equivalente nel tuo setup Godot 4) per lanciare l'app direttamente sull'emulatore.
Verifica che il punteggio sia leggibile e che i pulsanti virtuali siano facilmente cliccabili con il mouse (simula il tocco).

Prova a ridimensionare la finestra dell'emulatore o usare dispositivi diversi per vedere come si comporta l'HUD.

2. Test su dispositivo reale

Nessun test di interfaccia Android è completo senza prova su dispositivo reale:

Abilita le Opzioni sviluppatore e il Debug USB sul telefono.
Collega il dispositivo via USB (o usa ADB wireless se supportato).
Verifica che Godot veda il dispositivo (se necessario, controlla adb devices da terminale).
Lancia il deploy del progetto su Android come fatto per l'emulatore.
Prova l'HUD in situazioni reali: presa a una mano, gioco orizzontale/verticale, luce intensa, ecc.

Durante il test, presta attenzione a:

Dimensione e distanza dei pulsanti (errori di tocco).
Leggibilità del testo su diversi DPI e luminanze.
Eventuali tagli dell'HUD dovuti a notch, barre di sistema o gesture.

Consigli pratici ed errori comuni

Consigli pratici

Separa HUD e logica di gioco: mantieni l'HUD come scena e script dedicati che emettono eventi verso il resto del gioco.
Usa i container per tutto ciò che è ripetitivo: barre di pulsanti, liste, menu.
Commenta il codice C#: soprattutto nei punti in cui colleghi eventi e segnali, per aiutare il te stesso del futuro o il tuo team.
Versiona le scene: prima di grossi cambi di layout, salva copie della scena HUD per poter tornare indietro.

Errori comuni da evitare

Posizionare i controlli con coordinate assolute e dimenticare gli ancoraggi: l'HUD sembrerà corretto nella risoluzione di sviluppo ma si romperà su altri dispositivi.
Usare nomi generici (es. Label, Button) che rendono difficile scrivere GetNode leggibili.
Mischiare logica di input e logica di gioco nello stesso script: rende più complesso il riuso dell'HUD in altre scene.
Dimenticare il CanvasLayer per l'HUD: la UI finirà per muoversi con la camera di gioco, creando artefatti.

FAQ – Domande frequenti

Posso usare lo stesso HUD sia per desktop sia per Android?

Sì, a patto di progettarlo pensando al touch. Su desktop potresti disattivare i pulsanti virtuali e usare input da tastiera o gamepad, mantenendo però la stessa scena HUD con alcune parti abilitate/disabilitate in base alla piattaforma.

È meglio collegare i segnali dei pulsanti dall'editor o da C#?

Entrambi i metodi sono validi. Collegare i segnali da C# (come in questa guida) rende il comportamento più esplicito nel codice e facilita il refactoring. Collegarli dall'editor può essere più rapido per prototipi veloci. Scegli in base alle dimensioni del progetto e alle abitudini del team.

Come gestisco layout diversi per telefono e tablet?

Per progetti complessi puoi creare varianti di HUD diverse (scene o sottoscene) e caricare quella più adatta in base alla risoluzione/DPI rilevati in fase di avvio. In alternativa, puoi usare container più sofisticati (GridContainer, SplitContainer) e logica di layout dinamica in C# per spostare o ridimensionare elementi quando cambia la risoluzione.

Come faccio a evitare che l'HUD venga coperto dalla barra di sistema o dal notch?

Controlla le impostazioni di Stretch e le opzioni specifiche per Android nelle impostazioni di export (ad esempio, immersive mode). In aggiunta, lascia sempre un po' di margine superiore per il pannello HUD e testa su più dispositivi con notch e forme di schermo diverse.

Riepilogo e prossimi passi

In questa guida hai visto come costruire un HUD completo in Godot 4 per Android usando C#: partendo dai nodi Control e Container, hai creato una barra superiore con punteggio, una barra inferiore con pulsanti virtuali, impostato ancoraggi e layout per adattarti ai vari schermi e collegato i pulsanti a uno script C# tramite eventi, mantenendo la logica di gioco separata dall'interfaccia. Hai anche imparato a testare l'HUD su emulatore e dispositivo reale, evitando gli errori più comuni nei layout touch.

Nella prossima guida della serie vedremo come gestire input misti (touch, accelerometro e gamepad) in Godot 4 per Android con C#, integrando i pulsanti virtuali dell'HUD con l'input fisico dei controller e le gesture del dispositivo, per offrire un'esperienza di gioco flessibile e moderna.

Godot 4 per Android con C#: Interfaccia, Pulsanti e HUD