Godot 4 HUD und Theme: Control-Tree-Übergabe und Play-Abnahme

Godot 4 HUD ist nicht fertig, wenn PNGs auf TextureRect-Nodes liegen: StyleBox im Theme, Standard-Fonts, die Container-Kette (MarginContainer → HBoxContainer / VBoxContainer) und Anchors / Offsets entscheiden gemeinsam, ob das Layout über alle Auflösungen hält. Figma Auto Layout kann perfekt aussehen, während Play trotzdem wandernde Bottom Bars, Buttons ohne Mindestgröße oder abgeschnittenen langen Text zeigt – meist passten Control-Tree oder Theme-Ressource nicht zur Übergabe-Spezifikation.

Der Fokus liegt unten auf Godot 4.x Control + Theme. Unity-Teams können dieselbe Messlatte über die Engine-+-MCP-Checkliste anwenden. Der vollständige Figma → Godot-Flow: Figma to Godot (VberAI Studio exportiert den Control-Tree). Dieser Beitrag behandelt nur die HUD-Hülle: Theme, Node-Naming, Play-Smoke – nicht die MCP-Installationsschritte.

Fail-Kriterien (eines davon = nicht bestanden): primäre HUD-bedienbare Controls abgeschnitten beim Ziel-Seitenverhältnis (inklusive Safe Area-Äquivalent DisplayServer.get_display_safe_area()); derselbe Button mit Größen-Mismatch zwischen Editor und exportiertem Build ohne schriftliche Spezifikation; Theme-Button-States (normal / hover / pressed / disabled usw.) fehlen, werden aber trotzdem ausgeliefert; Scene-Tree nur für ein Locale geändert (Konflikt mit gleichstrukturierter i18n – siehe Locale-Overflow); minimum_size nicht gesetzt, sodass Nine-Slice-Panel-Hintergrund gut aussieht, aber Text an den Rändern klebt.

---

Theme und Nodes: Was die Übergabe abgleichen muss

Design-Lieferung	Godot-Landung
Farbe / Radius / umrandete Panels	StyleBoxFlat / StyleBoxTexture im Theme (Patch-Margins gemäß Nine-Slice)
Body- / Titel-Größen	Theme-Standard-font_size + Label-Type-Variations bei Bedarf
Button-States	Vier StyleBox-Sets auf Button: normal / hover / pressed / disabled
Icon + Copy	Icon-TextureRect mit fester Mindestgröße; Copy-Label in expandierendem Container
Full-Screen-HUD-Root	Root-Control-Anchor-Preset + MarginContainer für Safe Area

Naming: Scene-Node-Namen entsprechen der Figma-Komponenten-Semantik (HUD_BottomBar, Btn_Shop), damit MCP- / Skript-$-Pfade stabil bleiben (Engine-+-MCP-Checkliste).

---

Play-Abnahme-Reihenfolge (6 Schritte)

1. Viewport und Safe Area fixieren

• Ziel-Basisbreite/-höhe in Project Settings → Display festlegen (Portrait-Konvention des Teams).
• HUD-Root mit DisplayServer.get_display_safe_area() oder Godot 4.2+ SafeArea-Node einbetten; ein hohes Smartphone als Smoke testen (siehe Safe-Area-Beitrag).

2. Theme als Single Source of Truth

• HUD-Subtree erbt eine Theme-Ressource, keine manuellen Overrides pro Button.
• Alle Override-Nodes müssen in der Spezifikation aufgeführt sein, sonst verpasst ein Reskin sie.

3. Container-Kette und Size Flags

Prüfung	Häufiger Fehler
size_flags_horizontal / vertical	Label, das wachsen soll, hat kein Fill/Expand → Locale-Clipping
custom_minimum_size	Button-Höhe 0 → Touch-Target zu klein
Verschachtelter MarginContainer	Doppelte Margins → zusätzlicher Leerraum-Ring

4. Locale-Smoke

• In Localization Stress-Sprachen (DE/ES usw.) und Auslieferungssprache umschalten; nur tr()-Text ändern, nicht den Node-Tree.
• Overflow → Locale-Overflow-Pfad (Mindestbreite / Copy / Re-Export).

5. States und Fokus

• Tastatur-/Gamepad-Fokus (falls unterstützt): Focus-StyleBox im Theme definiert.
• Deaktivierte Buttons blockieren weiterhin Klicks (mouse_filter, disabled-State).

6. Exportierten Build erneut testen

• Haupt-HUD 30 s in Debug und Release laufen lassen; wenn Font-Fallback die Breite ändert, auf dem Gerät erneut testen (Pre-Ship-Punkt 5 Dev/Release; alle Locales Punkt 2).

---

Grobe Figma-Auto-Layout-Zuordnung

Figma	Godot 4
Vertikales Auto Layout	VBoxContainer + Separation
Horizontales Auto Layout	HBoxContainer
Padding	MarginContainer oder StyleBox-Content-Margin
Container füllen	size_flags Expand + Fill
Inhalte umschließen	Kinder nicht Expand; Parent umschließt

Wenn VberAI Studio (oder die eigene Pipeline) Container bereits exportiert hat, in Play abnehmen – nicht nur statische Editor-Frames mit dem Auge prüfen.

---

Fix-Routing

Symptom	Wahrscheinliche Ursache	Aktion	Owner
Bottom Bar unter der Notch	Kein Safe Inset	Root-Margin + Safe-Area-API	Eng
Ein Locale läuft über	Mindestbreite / Font-Größe	Theme- oder Container-Min; kürzere Loc-Copy	Design + Eng
Styles nach Reskin falsch	Overrides verstreut	Theme konsolidieren; Re-Export	Eng + Design
Nine-Slice-Naht in StyleBox	Falsche Patch-Margin	Design-px angleichen; siehe Nine-Slice-Beitrag	Eng + Design
MCP kann Nodes nicht binden	Namen ≠ Export	Naming vereinheitlichen; Scene/PackedScene re-exportieren	Eng

---

FAQ

Ein Theme pro Screen oder eines für das ganze Spiel?
Häufiges Muster: globales Theme + seltene theme_override; Event-Skins über Reskin-Theme-Swap, nicht über Tint-Edits pro Node.

Control mit rohem CanvasItem-Layout mischen?
2D-HUD auf einem Control-Tree halten; nicht mit handplatzierten CanvasLayer-Koordinaten im selben HUD vermischen.

Braucht man einen separaten Fokus-Style für Tastatur/Gamepad?
Wenn das Projekt Tastatur-/Gamepad-Fokus unterstützt, Focus-StyleBox auf Button, LineEdit usw. im Theme definieren (oder sichtbares theme_override) und Tab/D-Pad in Play als Smoke testen. Ein reines Touch-HUD kann kein Fokus-Styling erforderlich spezifizieren, damit QA und Eng dieselbe Messlatte teilen.

Wie unterscheidet sich das von Unity-Prefab-Abnahme?
Dieselbe Messlatte (Clipping, Locales, States, Release); nur die Namen wechseln zu StyleBox / size_flags / PackedScene.

Muss man Figma verwenden?
Nein. Ohne Figma braucht man trotzdem eine Theme-+-Container-Spezifikation; mit Figma zuerst die Design-Handoff-Checkliste, dann Godot.