Safe Area dell'interfaccia di gioco e QA su dispositivo: ordine di debug e correzioni Prefab

Il report più comune: la Game view sembra corretta, ma su un telefono allungato l’HUD finisce sotto il notch, o i pulsanti sembrano cliccabili ma i tap falliscono. La Safe Area non è «spostare l’Anchor» — riguarda la policy del Canvas radice, sfondo full-bleed vs contenuto in inset, e se il safeArea runtime corrisponde al canale.

classi di fallimento, ordine di debug Unity UGUI, regole di correzione Prefab, e caveat canale/mini-giochi. Le marcature di zona sicura dell’item 7 del handoff design sono riassunte in «cosa deve fornire il design»; la portata dispositivo dell’item 1 pre-lancio è sviluppata qui — non ripete Raycast / primo Play della checklist motore + MCP.

Godot / Cocos: allineare a DisplayServer.get_display_safe_area() / widget SafeArea del motore; stesso ordine di passi di Unity sotto.

Criteri di fallimento (uno solo = non superato): UI principale leggibile o pulsanti obbligatori sotto occlusione di sistema (notch, home indicator, angoli arrotondati); offset visivo vs hit evidente; solo Editor 16:9 senza aspect target su dispositivo; comportamento Safe Area Dev vs Release diverso senza spec.

---

Classificare prima: clip, offset o solo sfondo

Sintomo	Sospetto principale	Azione ingegneria
Clip visivo (testo/icone nel notch)	Contenuto non in inset; radice trattata come full screen	Verificare safeArea vs rect di contenuto
Offset tap (sembra giusto, manca)	Modalità scala Canvas, Canvas multipli, camera disallineata	Raycast EventSystem + Canvas renderMode
Sfondo clippato, pulsanti OK	Sfondo full-bleed by design, contenuto in inset	Non è un fallimento se la spec lo consente
Sbagliato dopo rotazione	Nessun listener per orientamento / cambio safeArea	Ricalcolare inset alla rotazione
Solo build di un canale	SDK modifica safeArea o risoluzione	Smoke su quella build; non affidarsi solo ad Android generico

---

Unity UGUI: ordine di debug consigliato (6 passi)

1. Bloccare la riproduzione

Registrare dispositivo, OS, Dev/Release, orientamento, risoluzione Game view. Item 5 pre-lancio: eseguire HUD principale su Dev e Release.

2. Loggare safeArea e risoluzione di riferimento

Dopo il caricamento dell’UI principale, loggare:

• Screen.width / Screen.height
• Screen.safeArea
• Display.cutouts (Android 11+ se usato)

Lettura: safeArea più piccolo dello schermo → inset del contenuto obbligatorio. In Editor safeArea spesso uguale al full screen → non sostituisce il dispositivo.

3. Radice Canvas e Canvas Scaler

Controllo	Errore tipico	Direzione correzione
Render Mode radice	Screen Space / Camera UI misti → offset ray	Un solo mode per l’UI
Canvas Scaler	Reference resolution ≠ baseline portrait del progetto	Allineare checklist motore item 1
Match width/height	Aspect lungo scala male; widget ai bordi derivano	Concordare Match con design/prod; correggere Prefab non solo Scene
Ordinamento Canvas multipli	Hit sulla layer sbagliata	Allineare sortingOrder e target raycast

4. Layer: sfondo full-bleed vs contenuto safe

Gerarchia Prefab suggerita:

Canvas
├── Background_FullBleed   (anchor pieno, può entrare nel notch, no input)
└── SafeRoot               (componente Safe Area o padding da safeArea)
    ├── HUD_Content
    └── Popups

Usare Safe Area di Unity (o codice progetto che imposta offsetMin/Max da Screen.safeArea). Non estendere pulsanti interattivi a full screen senza inset.

Export Studio con un solo layer piatto: vedere nine-slice / re-export strutturato e canvas → Prefab.

5. Spot-check tap su dispositivo

3–5 pulsanti critici sul flusso principale; confrontare centro visivo con il dito. Offset solo su un popup → controllare Canvas annidato o doppio Scaler.

6. Committare il Prefab nel repo

I criteri di passaggio vivono nel Prefab versionato, non in override di Scene di test (item 6 pre-lancio). Dopo cambi Anchor, eseguire smoke overflow locale sulle lingue stress.

---

Canale / mini-gioco (ingegneria)

Scenario	Nota
App nativa	Screen.safeArea + dispositivi reali
Alcuni mini-giochi / quick app	safeArea / systemInfo del container ≠ sim Editor
Cutout Android	cutout vs safeArea possono differire
PC / deck	safeArea spesso full screen

Pattern: ISafeAreaProvider (o equivalente); iniettare per piattaforma — evitare #if nei Prefab HUD.

---

Routing delle correzioni

Sintomo	Causa probabile	Azione	Responsabile
Clip su dispositivo, Editor OK	Nessun SafeRoot / nessun driver safeArea	Layer Prefab + Safe Area; ritest dispositivo	Ingegneria
Sfondo OK, pulsanti clippati	Pulsanti sotto layer bleed	Spostare in SafeRoot; re-export layer Studio	Ingegneria + Design
Offset tap	Canvas multipli / camera UI / Scaler annidato	Unificare Canvas o camera raycast	Ingegneria
Deriva al cambio risoluzione	Solo anchor fissi	Correggere anchor; item 6 motore	Ingegneria
Design senza frame safe	Manca item 7 handoff	Design aggiunge ref notch/home; re-export	Design
Export Studio piatto	BG + HUD non separati	Split in-place poi re-export	Ingegneria + Design

---

Cosa fornisce il design

Consegna	Uso ingegneria
Risoluzione target + riferimento safe (notch / barra home)	Reference Resolution e aspettative di inset
Layer nominati full-bleed vs HUD	Prefab Background_* / SafeRoot
Tab ai bordi dentro safe o bleed intenzionale	Strategia anchor

I designer non devono scrivere script — marcature chiare riducono i px di inset indovinati.

---

Domande frequenti

Basta la risoluzione iPhone della Game view?
Solo smoke Dev; il rilascio richiede dispositivi target (item 1 pre-lancio). Il safeArea in Editor spesso differisce.

Componente Safe Area vs offset manuale?
Scelta di team; il manuale deve aggiornarsi ai cambi safeArea/orientamento — evitare logica duplicata.

Correggere il clip solo con Canvas Scaler?
Lo Scaler scala; l’inset è separato. Il clip è il rect di contenuto; lo Scaler è la scala globale.

MCP/Cursor possono aiutare?
Utili per rename Prefab, attaccare Safe Area, smoke Play — i numeri vengono sempre dai log dispositivo. Checklist motore + MCP.

Safe Area più overflow locale?
Correggere prima il layout SafeRoot, poi locale stress — l’inset riduce la larghezza.

VberAI Studio vs Google AI Studio?
No. Vedi confronto.