Godot 4 HUD e Theme: passaggio dell'albero Control e accettazione in Play

Un HUD in Godot 4 non è finito quando i PNG stanno su nodi TextureRect: StyleBox nel Theme, font di default, la catena di container (MarginContainer → HBoxContainer / VBoxContainer) e anchor / offset insieme decidono se il layout regge su tutte le risoluzioni. L’Auto Layout di Figma può sembrare perfetto mentre in Play si vedono ancora barre inferiori che si spostano, pulsanti con min a zero o testi lunghi tagliati—di solito l’albero Control o la risorsa Theme non corrispondono alla specifica di handoff.

Qui ci concentriamo su Godot 4.x Control + Theme. I team Unity possono applicare la stessa barra tramite la checklist engine + MCP. Flusso completo Figma → Godot: Figma to Godot (VberAI Studio esporta l’albero Control). Questo articolo copre solo la shell dell’HUD: Theme, naming dei nodi, smoke in Play—non i passi di installazione MCP.

Criteri di fallimento (uno solo = non superato): controlli principali dell’HUD leggibili ma tagliati all’aspect target (incluso l’equivalente di Safe Area DisplayServer.get_display_safe_area()); stesso pulsante con dimensione diversa tra Editor e build esportata senza specifica scritta; stati del pulsante nel Theme (normal / hover / pressed / disabled, ecc.) mancanti ma comunque rilasciati; albero della scena modificato per una sola lingua (in conflitto con i18n a struttura identica—vedi overflow delle lingue); minimum_size non impostato così il pannello nine-slice sembra a posto ma il testo tocca i bordi.

---

Theme e nodi: cosa deve allineare l’handoff

Consegna del design	Atterraggio in Godot
Colore / raggio / pannelli con bordo	StyleBoxFlat / StyleBoxTexture nel Theme (patch margins secondo nine-slice)
Dimensioni body / titolo	font_size di default del Theme + type variations di Label se necessario
Stati del pulsante	Quattro set di StyleBox su Button: normal / hover / pressed / disabled
Icona + testo	TextureRect dell’icona con min fisso; Label del testo in un container espandibile
Root HUD a schermo intero	Preset anchor del Control root + MarginContainer per la safe area

Naming: i nomi dei nodi della scena corrispondono alla semantica dei componenti Figma (HUD_BottomBar, Btn_Shop) così i percorsi $ di MCP / script restano stabili (checklist engine + MCP).

---

Ordine di accettazione in Play (6 passi)

1. Blocca viewport e safe area

• Imposta larghezza/altezza base target in Project Settings → Display (convenzione portrait del team).
• Insetta il root dell’HUD con DisplayServer.get_display_safe_area() o il nodo SafeArea di Godot 4.2+; fai smoke su un telefono alto (vedi il post su Safe Area).

2. Theme come unica fonte di verità

• Il sottoalbero dell’HUD eredita una sola risorsa Theme, non override manuali per ogni Button.
• Eventuali nodi con override devono essere elencati nella specifica, altrimenti un reskin li salterà.

3. Catena di container e size flags

Verifica	Errore comune
size_flags_horizontal / vertical	Label che dovrebbe crescere senza Fill/Expand → testo tagliato in locale
custom_minimum_size	Altezza del pulsante a 0 → touch target troppo piccolo
MarginContainer annidati	Margini doppi → anello vuoto extra

4. Smoke delle lingue

• In Localization, passa alle lingue di stress (DE/ES, ecc.) e alla lingua di rilascio; cambia solo il testo tr(), non l’albero dei nodi.
• Overflow → percorso overflow delle lingue (larghezza minima / testo / ri-esportazione).

5. Stati e focus

• Focus da tastiera/gamepad (se supportato): StyleBox di focus definito nel Theme.
• Pulsanti disabilitati che bloccano ancora i click (mouse_filter, stato disabled).

6. Retest sulla build esportata

• Esegui l’HUD principale per 30s in Debug e Release; se il fallback del font cambia la larghezza, ritesta su dispositivo (voce 5 pre-rilascio Dev/Release; voce 2 tutte le lingue).

---

Mappatura approssimativa dell’Auto Layout di Figma

Figma	Godot 4
Auto Layout verticale	VBoxContainer + separation
Auto Layout orizzontale	HBoxContainer
Padding	MarginContainer o content margin dello StyleBox
Fill container	size_flags Expand + Fill
Hug contents	Figli senza Expand; il genitore si adatta

Se VberAI Studio (o la tua pipeline) ha già esportato i container, accetta in Play—non valutare solo a occhio i frame statici dell’Editor.

---

Routing delle correzioni

Sintomo	Causa probabile	Azione	Owner
Barra inferiore sotto il notch	Nessun inset di safe area	Margine del root + API safe area	Eng
Una lingua va in overflow	Larghezza minima / dimensione font	Min del Theme o del container; testo loc più corto	Design + eng
Stili sbagliati dopo il reskin	Override sparsi	Consolida il Theme; ri-esporta	Eng + design
Cucitura nine-slice nello StyleBox	Patch margin errato	Allinea ai px del design; vedi il post nine-slice	Eng + design
MCP non riesce a collegare i nodi	Nomi ≠ export	Unifica il naming; ri-esporta Scene/PackedScene	Eng

---

FAQ

Un Theme per schermata o uno per tutto il gioco?
Pattern comune: Theme globale + rari theme_override; skin degli eventi tramite swap di Theme per reskin, non modifiche di tinta per nodo.

Mescolare Control con layout CanvasItem grezzo?
Tieni l’HUD 2D su un solo albero Control; non mischiarlo con coordinate CanvasLayer posizionate a mano nello stesso HUD.

Serve uno stile di focus separato per tastiera/gamepad?
Se il progetto supporta il focus da tastiera/gamepad, definisci lo StyleBox di focus su Button, LineEdit, ecc. nel Theme (o un theme_override visibile), e fai smoke con Tab/d-pad in Play. Un HUD solo touch può specificare nessuno stile di focus richiesto così QA ed eng condividono un’unica barra.

In cosa è diverso dall’accettazione di un Prefab Unity?
Stessa barra (clip, lingue, stati, Release); cambiano i nomi in StyleBox / size_flags / PackedScene.

Dobbiamo per forza usare Figma?
No. Senza Figma serve comunque una specifica di Theme + container; con Figma, checklist di handoff del design e poi Godot.