Safe Area UI Permainan dan QA Peranti: Susunan Debug dan Pembaikan Prefab

Laporan kejuruteraan paling biasa: Pandangan permainan nampak elok, tetapi pada telefon tinggi HUD berada di bawah takuk, atau butang nampak boleh diketuk tetapi ketikan tersasar. Safe Area bukan “tolak Anchor”—ia adalah dasar Canvas akar, latar belakang penuh-bleed vs kandungan inset, dan sama ada safeArea masa jalan sepadan dengan saluran.

kelas kegagalan, susunan debug Unity UGUI, peraturan pembaikan Prefab, dan kaveat saluran/mini-permainan. Item serahan reka bentuk 7 tanda zon selamat diringkaskan di bawah “apa yang reka bentuk mesti bekalkan”; item pra-hantar 1 skop peranti dikembangkan di sini—bukan ulangan senarai semak enjin + MCP Raycast / Play pertama.

Godot / Cocos: Petakan kepada DisplayServer.get_display_safe_area() / widget SafeArea enjin; susunan langkah sama seperti Unity di bawah.

Kriteria gagal (mana-mana satu = tidak lulus): UI boleh baca utama atau butang diperlukan di bawah okulasi sistem (takuk, penunjuk home, sudut bulat); offset visual vs ketikan yang jelas; Editor 16:9 sahaja tanpa nisbah sasaran pada peranti; tingkah laku Safe Area Dev vs Release berbeza tanpa spesifikasi.

---

Klasifikasikan dahulu: klip, offset, atau latar belakang sahaja

Gejala	Syak dahulu	Tindakan kejuruteraan
Klip visual (teks/ikon dalam takuk)	Kandungan tidak inset; akar dianggap skrin penuh	Semak safeArea vs segi empat kandungan
Offset ketikan (nampak betul, tersasar)	Mod skala Canvas, berbilang Canvas, kamera tidak sepadan	Raycast EventSystem + Canvas renderMode
Latar belakang diklip, butang OK	Latar penuh-bleed mengikut reka bentuk, kandungan inset	Bukan gagal jika spesifikasi benarkan
Salah selepas putaran	Tiada pendengar untuk orientasi / perubahan safeArea	Kira semula inset semasa putar
Hanya satu binaan saluran	SDK ubah safeArea atau resolusi	Uji asap binaan itu; jangan bergantung pada Android generik sahaja

---

Unity UGUI: susunan debug disyorkan (6 langkah)

1. Kunci pembiakan

Rekod peranti, OS, Dev/Release, orientasi, resolusi pandangan Game. Item pra-hantar 5: jalankan HUD utama pada Dev dan Release.

2. Log safeArea dan resolusi rujukan

Selepas UI utama dimuatkan, log:

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

Baca: safeArea lebih kecil daripada skrin → kandungan inset diperlukan. Dalam Editor safeArea selalunya sama dengan skrin penuh → bukan pengganti peranti.

3. Akar Canvas dan Canvas Scaler

Semak	Kesilapan biasa	Arah pembaikan
Render Mode akar	Campuran Screen Space / Camera UI → offset sinar	Satu mod untuk UI
Canvas Scaler	Resolusi rujukan ≠ garis dasar potret projek	Padan senarai semak enjin item 1
Padan lebar/tinggi	Nisbah panjang skala salah; widget tepi hanyut	Sepakati Match dengan reka bentuk/prod; baiki Prefab bukan Scene sahaja
Susunan berbilang Canvas	Ketikan pergi ke lapisan salah	Selaraskan sortingOrder dan sasaran raycast

4. Lapisan: latar belakang penuh-bleed vs kandungan selamat

Hierarki Prefab dicadangkan:

Canvas
├── Background_FullBleed   (anchor penuh, boleh masuk takuk, tiada input)
└── SafeRoot               (komponen Safe Area atau padding dipacu safeArea)
    ├── HUD_Content
    └── Popups

Guna Safe Area Unity (atau kod projek menetapkan offsetMin/Max daripada Screen.safeArea). Jangan regangkan butang interaktif skrin penuh tanpa inset.

Eksport Studio dengan satu lapisan rata: lihat nine-slice / eksport semula berstruktur dan canvas → Prefab.

5. Semakan titik ketikan peranti

3–5 butang kritikal pada aliran utama; bandingkan pusat visual dengan jari. Offset hanya pada satu popup → semak Canvas bersarang atau Scaler berganda.

6. Commit Prefab dalam repo

Kriteria lulus berada dalam Prefab berversi, bukan ganti ganti Scene ujian (item pra-hantar 6). Selepas perubahan Anchor, jalankan asap limpahan lokasi pada bahasa tekanan.

---

Saluran / mini-permainan (kejuruteraan)

Senario	Nota
Aplikasi asli	Screen.safeArea + peranti sebenar
Sesetengah mini-permainan / aplikasi pantas	safeArea / systemInfo kontena ≠ simulasi Editor
Cutout Android	cutout vs safeArea mungkin berbeza
PC / deck	safeArea selalunya skrin penuh

Corak: ISafeAreaProvider (atau setara); suntik mengikut platform—elak #if dalam Prefab HUD.

---

Penghalaan pembaikan

Gejala	Punca berkemungkinan	Tindakan	Pemilik
Klip peranti, Editor OK	Tiada SafeRoot / tiada pemacu safeArea	Lapisan Prefab + Safe Area; uji semula peranti	Kejuruteraan
Latar belakang OK, butang diklip	Butang di bawah lapisan bleed	Pindah ke SafeRoot; eksport semula lapisan Studio	Kejuruteraan + Reka Bentuk
Offset ketikan	Berbilang Canvas / kamera UI / Scaler bersarang	Gabung Canvas atau satukan kamera raycast	Kejuruteraan
Hanyut pada perubahan resolusi	Anchor tetap sahaja	Baiki anchor; item enjin 6	Kejuruteraan
Reka bentuk tiada bingkai selamat	Tiada item serahan 7	Reka bentuk tambah rujukan takuk/home; eksport semula	Reka Bentuk
Eksport Studio rata	BG + HUD tidak dipisahkan	Pisah di tempat kemudian eksport semula	Kejuruteraan + Reka Bentuk

---

Apa yang reka bentuk bekalkan

Serahan	Kegunaan kejuruteraan
Resolusi sasaran + rujukan selamat (takuk / bar home)	Resolusi Rujukan dan jangkaan inset
Lapisan penuh-bleed vs HUD bernama	Prefab Background_* / SafeRoot
Tab tepi dalam selamat atau bleed yang disengajakan	Strategi Anchor

Pereka bentuk tidak perlu tulis skrip—tanda jelas kurangkan px inset yang diagak.

---

Soalan Lazim

Adakah resolusi iPhone pandangan Game mencukupi?
Asap Dev sahaja; penghantaran memerlukan peranti sasaran (item pra-hantar 1). safeArea Editor selalunya berbeza.

Komponen Safe Area vs offset manual?
Pilihan pasukan; manual mesti muat semula pada perubahan safeArea/orientasi—elak logik berganda.

Baiki klip dengan Canvas Scaler sahaja?
Scaler menskalakan; inset berasingan. Klip ialah segi empat kandungan; Scaler ialah skala global.

Bolehkah MCP/Cursor membantu?
Bagus untuk penamaan semula Prefab, melampirkan Safe Area, asap Play—nombor tetap daripada log peranti. Senarai semak enjin + MCP.

Safe Area campur limpahan lokasi?
Baiki susun atur SafeRoot dahulu, kemudian lokasi tekanan—inset mengecilkan lebar.

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