Game-UI-Safe-Area und Geräte-QA: Debug-Reihenfolge und Prefab-Fixes

Der häufigste Bericht: Die Game-Ansicht sieht gut aus, aber auf einem hohen Smartphone sitzt das HUD unter der Notch, oder Buttons wirken antippbar, doch die Treffer gehen daneben. Safe Area ist nicht „den Anchor verschieben“ – es ist Root-Canvas-Policy, Full-Bleed-Hintergrund vs. eingerückter Inhalt und ob die Runtime-safeArea mit dem Kanal übereinstimmt.

Fehlerklassen, Unity-UGUI-Debug-Reihenfolge, Prefab-Fix-Regeln und Kanal-/Mini-Game-Caveats. Design-Handoff-Punkt 7 Safe-Zone-Markierungen sind unter „Was Design liefern muss“ zusammengefasst; Pre-Ship-Punkt 1 Geräteumfang wird hier erweitert – keine Wiederholung der Engine-+-MCP-Checkliste Raycast / erstes Play.

Godot / Cocos: Auf DisplayServer.get_display_safe_area() / Engine-SafeArea-Widgets abbilden; gleiche Schrittfolge wie bei Unity unten.

Fail-Kriterien (eines davon = nicht bestanden): primär lesbare UI oder erforderliche Buttons unter Systemverdeckung (Notch, Home-Indicator, abgerundete Ecken); offensichtlicher Versatz zwischen Optik und Treffer; Editor nur 16:9 ohne Ziel-Seitenverhältnis auf dem Gerät; Dev- vs. Release-Safe-Area-Verhalten weicht ohne Spec ab.

---

Zuerst klassifizieren: Clip, Offset oder nur Hintergrund

Symptom	Erster Verdacht	Debug-Schritt
Visueller Clip (Text/Icons in der Notch)	Inhalt nicht eingerückt; Root als Vollbild behandelt	safeArea vs. Content-Rects prüfen
Tap-Offset (sieht richtig aus, trifft nicht)	Canvas-Scale-Modus, mehrere Canvases, Kamera-Mismatch	EventSystem-Raycast + Canvas renderMode
Hintergrund geclippt, Buttons OK	Full-Bleed-BG by Design, Inhalt eingerückt	Kein Fail, wenn Spec es erlaubt
Falsch nach Rotation	Kein Listener für Orientierungs-/safeArea-Änderung	Inset bei Rotation neu berechnen
Nur ein Kanal-Build betroffen	SDK ändert safeArea oder Auflösung	Diesen Build smoken; nicht nur auf generisches Android verlassen

---

Unity UGUI: empfohlene Debug-Reihenfolge (6 Schritte)

1. Reproduktion fixieren

Gerät, OS, Dev/Release, Orientierung, Game-View-Auflösung festhalten. Pre-Ship-Punkt 5: Haupt-HUD auf Dev und Release laufen lassen.

2. safeArea und Referenzauflösung loggen

Nach dem Laden der Haupt-UI loggen:

• Screen.width / Screen.height
• Screen.safeArea
• Display.cutouts (Android 11+, falls genutzt)

Lesen: safeArea kleiner als Screen → Inhalt muss eingerückt werden. Im Editor ist safeArea oft gleich dem Vollbild → kein Ersatz für das Gerät.

3. Canvas-Root und Canvas Scaler

Prüfung	Typischer Fehler	Fix-Richtung
Root Render Mode	Gemischtes Screen Space / Camera UI → Ray-Offset	Ein Modus für UI
Canvas Scaler	Referenzauflösung ≠ Projekt-Portrait-Baseline	An Engine-Checkliste Punkt 1 anpassen
Match width/height	Langes Seitenverhältnis skaliert falsch; Edge-Widgets driften	Match mit Design/Prod abstimmen; Prefab fixen, nicht nur Scene
Mehrere Canvas-Sortierung	Treffer gehen an falschen Layer	sortingOrder und Raycast-Targets angleichen

4. Layer: Full-Bleed-Hintergrund vs. sicherer Inhalt

Vorgeschlagene Prefab-Hierarchie:

Canvas
├── Background_FullBleed   (voller Anchor, darf in Notch reichen, kein Input)
└── SafeRoot               (Safe-Area-Komponente oder safeArea-getriebenes Padding)
    ├── HUD_Content
    └── Popups

Unity Safe Area nutzen (oder Projektcode, der offsetMin/Max aus Screen.safeArea setzt). Interaktive Buttons nicht ohne Inset über den Vollbildschirm strecken.

Studio-Exporte mit einer flachen Ebene: siehe Nine-Slice / strukturierter Re-Export und Canvas → Prefab.

5. Geräte-Tap-Stichprobe

3–5 kritische Buttons im Hauptfluss; visuelles Zentrum mit Finger vergleichen. Offset nur bei einem Popup → verschachtelten Canvas oder doppelten Scaler prüfen.

6. Prefab im Repo committen

Pass-Kriterien liegen im versionierten Prefab, nicht in Test-Scene-Overrides (Pre-Ship-Punkt 6). Nach Anchor-Änderungen Locale-Overflow-Smoke auf Stress-Sprachen laufen lassen.

---

Kanal / Mini-Game

Szenario	Hinweis
Native App	Screen.safeArea + echte Geräte
Manche Mini-Games / Quick Apps	Container safeArea / systemInfo ≠ Editor-Sim
Android-Cutouts	Cutout vs. safeArea können abweichen
PC / Deck	safeArea oft Vollbild

Pattern: ISafeAreaProvider (oder Äquivalent); pro Plattform injizieren – #if in HUD-Prefabs vermeiden.

---

Fix-Routing

Symptom	Wahrscheinliche Ursache	Aktion	Owner
Geräte-Clip, Editor OK	Kein SafeRoot / kein safeArea-Treiber	Layer-Prefab + Safe Area; Gerät erneut testen	Engineering
Hintergrund OK, Buttons geclippt	Buttons unter Bleed-Layer	In SafeRoot verschieben; Studio-Re-Export der Layer	Engineering + Design
Tap-Offset	Multi-Canvas / Camera-UI / verschachtelter Scaler	Canvas zusammenführen oder Raycast-Kamera vereinheitlichen	Engineering
Drift bei Auflösungswechsel	Nur feste Anchors	Anchors fixen; Engine-Punkt 6	Engineering
Design hat keinen Safe-Frame	Fehlender Handoff-Punkt 7	Design ergänzt Notch-/Home-Referenzen; Re-Export	Design
Flacher Studio-Export	BG + HUD nicht getrennt	In-Place-Split, dann Re-Export	Engineering + Design

---

Was Design liefert (sekundär)

Lieferung	Nutzung im Prefab
Zielauflösung + Safe-Referenz (Notch / Home-Bar)	Reference Resolution und Inset-Erwartungen
Benannte Full-Bleed- vs. HUD-Layer	Prefab Background_* / SafeRoot
Edge-Tabs innerhalb Safe oder bewusstes Bleed	Anchor-Strategie

Designer müssen keine Skripte schreiben – klare Markierungen reduzieren geratene Inset-px.

---

Häufig gestellte Fragen

Reicht Game-View-Auflösung des iPhone?
Nur Dev-Smoke; Ship erfordert Zielgeräte (Pre-Ship-Punkt 1). Editor-safeArea weicht oft ab.

Safe-Area-Komponente vs. manueller Offset?
Team-Entscheidung; manuell muss bei safeArea-/Orientierungsänderungen aktualisieren – doppelte Logik vermeiden.

Clip allein per Canvas Scaler fixen?
Scaler skaliert; Inset ist separat. Clip ist Content-Rect; Scaler ist globale Skalierung.

Kann MCP/Cursor helfen?
Gut für Prefab-Umbenennungen, Safe Area anhängen, Play-Smoke – Zahlen kommen trotzdem aus Geräte-Logs. Engine-+-MCP-Checkliste.

Safe Area plus Locale-Overflow?
Erst SafeRoot-Layout fixen, dann Stress-Locales – Inset verkleinert die Breite.

VberAI Studio vs. Google AI Studio?
Nein. Siehe Vergleich.