Safe Area UI Game dan QA Perangkat: Urutan Debug dan Perbaikan Prefab

Laporan paling umum: Tampilan Game view terlihat baik, tetapi di ponsel tinggi HUD berada di bawah notch, atau tombol tampak bisa di-tap tetapi hit meleset. Safe Area bukan sekadar “geser Anchor”—ini adalah kebijakan root Canvas, background full-bleed vs konten inset, dan apakah safeArea runtime sesuai dengan channel.

kelas kegagalan, urutan debug Unity UGUI, aturan perbaikan Prefab, dan catatan channel/mini-game. Item handoff desain 7 tanda safe-zone dirangkum di bagian “apa yang harus disediakan desain”; item pra-rilis 1 cakupan perangkat diperluas di sini—bukan pengulangan dari checklist engine + MCP Raycast / Play pertama.

Godot / Cocos: Petakan ke DisplayServer.get_display_safe_area() / widget SafeArea engine; urutan langkah sama dengan Unity di bawah.

Kriteria gagal (salah satu = tidak lulus): UI utama yang dapat dibaca atau tombol wajib berada di bawah oklusi sistem (notch, home indicator, sudut membulat); offset visual vs hit yang jelas; Editor hanya 16:9 tanpa aspek target di perangkat; perilaku Safe Area Dev vs Release berbeda tanpa spesifikasi.

---

Klasifikasikan dulu: clip, offset, atau background saja

Gejala	Tersangka pertama	Tindakan engineering
Clip visual (teks/ikon di notch)	Konten tidak inset; root diperlakukan sebagai layar penuh	Periksa safeArea vs rect konten
Offset tap (tampak benar, meleset)	Mode skala Canvas, beberapa Canvas, kamera tidak cocok	Raycast EventSystem + renderMode Canvas
Background terpotong, tombol OK	Bg full-bleed sesuai desain, konten inset	Bukan kegagalan jika spesifikasi mengizinkan
Salah setelah rotasi	Tidak ada listener untuk orientasi / perubahan safeArea	Hitung ulang inset saat rotasi
Hanya build satu channel	SDK mengubah safeArea atau resolusi	Smoke build tersebut; jangan hanya mengandalkan Android generik

---

Unity UGUI: urutan debug yang disarankan (6 langkah)

1. Kunci reproduksi

Catat perangkat, OS, Dev/Release, orientasi, resolusi Game view. Item pra-rilis 5: jalankan HUD utama di Dev dan Release.

2. Log safeArea dan resolusi referensi

Setelah UI utama dimuat, log:

• Screen.width / Screen.height
• Screen.safeArea
• Display.cutouts (Android 11+ jika digunakan)

Baca: safeArea lebih kecil dari layar → konten perlu inset. Di Editor safeArea sering sama dengan layar penuh → bukan pengganti perangkat.

3. Root Canvas dan Canvas Scaler

Periksa	Kesalahan umum	Arah perbaikan
Render Mode root	Campuran Screen Space / Camera UI → offset ray	Satu mode untuk UI
Canvas Scaler	Resolusi referensi ≠ baseline portrait proyek	Cocokkan checklist engine item 1
Match width/height	Aspek panjang skala salah; widget tepi bergeser	Sepakati Match dengan desain/produksi; perbaiki Prefab bukan hanya Scene
Urutan sortir Canvas ganda	Hit menuju layer salah	Selaraskan sortingOrder dan target raycast

4. Layer: background full-bleed vs konten aman

Hierarki Prefab yang disarankan:

Canvas
├── Background_FullBleed   (anchor penuh, boleh masuk notch, tanpa input)
└── SafeRoot               (komponen Safe Area atau padding yang digerakkan safeArea)
    ├── HUD_Content
    └── Popups

Gunakan Safe Area Unity (atau kode proyek yang mengatur offsetMin/Max dari Screen.safeArea). Jangan regangkan tombol interaktif ke layar penuh tanpa inset.

Ekspor Studio dengan satu layer datar: lihat nine-slice / ekspor ulang terstruktur dan canvas → Prefab.

5. Spot-check tap perangkat

3–5 tombol kritis pada alur utama; bandingkan pusat visual dengan jari. Offset hanya pada satu popup → periksa Canvas bersarang atau Scaler ganda.

6. Commit Prefab di repo

Kriteria lulus berada di Prefab berversi, bukan override Scene uji (item pra-rilis 6). Setelah perubahan Anchor, jalankan smoke locale overflow pada bahasa stres.

---

Channel / mini-game

Skenario	Catatan
Aplikasi native	Screen.safeArea + perangkat nyata
Beberapa mini-game / quick app	safeArea / systemInfo kontainer ≠ simulasi Editor
Cutout Android	cutout vs safeArea bisa berbeda
PC / deck	safeArea sering layar penuh

Pola: ISafeAreaProvider (atau setara); suntikkan per platform—hindari #if di Prefab HUD.

---

Routing perbaikan

Gejala	Kemungkinan penyebab	Tindakan	Pemilik
Clip perangkat, Editor OK	Tidak ada SafeRoot / driver safeArea	Layer Prefab + Safe Area; uji ulang perangkat	Engineering
Background OK, tombol terpotong	Tombol di bawah layer bleed	Pindahkan ke SafeRoot; ekspor ulang layer Studio	Engineering + Design
Offset tap	Multi Canvas / kamera UI / Scaler bersarang	Gabungkan Canvas atau satukan kamera raycast	Engineering
Pergeseran saat resolusi berubah	Hanya anchor tetap	Perbaiki anchor; item engine 6	Engineering
Desain tidak punya safe frame	Item handoff 7 hilang	Desain menambahkan referensi notch/home; ekspor ulang	Design
Ekspor Studio datar	BG + HUD tidak dipisah	Pemisahan in-place lalu ekspor ulang	Engineering + Design

---

Apa yang disediakan desain

Pengiriman	Penggunaan engineering
Resolusi target + referensi aman (notch / home bar)	Reference Resolution dan ekspektasi inset
Layer full-bleed vs HUD yang dinamai	Prefab Background_* / SafeRoot
Tab tepi di dalam area aman atau bleed yang disengaja	Strategi Anchor

Desainer tidak perlu menulis skrip—tanda yang jelas mengurangi tebakan inset px.

---

Pertanyaan umum

Apakah resolusi iPhone Game view cukup?
Hanya smoke Dev; rilis memerlukan perangkat target (item pra-rilis 1). safeArea Editor sering berbeda.

Komponen Safe Area vs offset manual?
Pilihan tim; manual harus menyegarkan saat safeArea/orientasi berubah—hindari logika duplikat.

Perbaiki clip hanya dengan Canvas Scaler?
Scaler menskalakan; inset terpisah. Clip adalah rect konten; Scaler adalah skala global.

Bisakah MCP/Cursor membantu?
Bagus untuk rename Prefab, melampirkan Safe Area, smoke Play—angka tetap dari log perangkat. Checklist engine + MCP.

Safe Area plus locale overflow?
Perbaiki tata letak SafeRoot dulu, lalu locale stres—inset menyusutkan lebar.

VberAI Studio vs Google AI Studio?
Tidak. Lihat perbandingan.