Vùng An Toàn UI Game và QA Thiết Bị: Thứ Tự Debug và Sửa Prefab cho Kỹ Sư

Báo cáo kỹ thuật phổ biến nhất: Game view trông ổn, nhưng trên điện thoại màn hình dài HUD nằm dưới notch, hoặc nút trông có thể chạm nhưng lại trượt. Vùng An Toàn không phải là “đẩy nhẹ Anchor”—nó là chính sách Canvas gốc, nền full-bleed so với nội dung inset, và liệu safeArea runtime có khớp với kênh hay không.

các lớp lỗi, thứ tự debug Unity UGUI, quy tắc sửa Prefab, và lưu ý về kênh/mini-game. Dấu vùng an toàn của mục bàn giao thiết kế số 7 được tóm tắt trong phần “những gì thiết kế phải cung cấp”; phạm vi thiết bị của mục trước khi ship số 1 được mở rộng ở đây—không lặp lại checklist engine + MCP Raycast / lần Play đầu tiên.

Godot / Cocos: Ánh xạ sang DisplayServer.get_display_safe_area() / widget SafeArea của engine; cùng thứ tự bước như Unity bên dưới.

Tiêu chí không đạt (bất kỳ điều nào = không đạt): UI đọc được chính hoặc nút bắt buộc nằm dưới che khuất hệ thống (notch, home indicator, góc bo tròn); lệch rõ ràng giữa hình ảnh và điểm chạm; chỉ Editor 16:9 mà không có tỷ lệ mục tiêu trên thiết bị; hành vi Vùng An Toàn Dev so với Release khác nhau mà không có đặc tả.

---

Phân loại trước: cắt, lệch, hay chỉ nền

Triệu chứng	Nghi ngờ đầu tiên	Hành động kỹ thuật
Cắt hình ảnh (chữ/icon trong notch)	Nội dung chưa inset; gốc bị coi là toàn màn hình	Kiểm tra safeArea so với rect nội dung
Lệch điểm chạm (trông đúng, lại trượt)	Chế độ scale Canvas, nhiều Canvas, camera không khớp	Raycast EventSystem + renderMode của Canvas
Nền bị cắt, nút vẫn ổn	Nền full-bleed theo thiết kế, nội dung inset	Không phải lỗi nếu đặc tả cho phép
Sai sau khi xoay	Không có listener cho thay đổi hướng / safeArea	Tính lại inset khi xoay
Chỉ một bản build kênh	SDK thay đổi safeArea hoặc độ phân giải	Smoke bản build đó; đừng chỉ dựa vào Android chung

---

Unity UGUI: thứ tự debug đề xuất (6 bước)

1. Khóa việc tái hiện

Ghi lại thiết bị, OS, Dev/Release, hướng, độ phân giải Game view. Mục trước khi ship số 5: chạy HUD chính trên Dev và Release.

2. Log safeArea và độ phân giải tham chiếu

Sau khi UI chính tải, log:

• Screen.width / Screen.height
• Screen.safeArea
• Display.cutouts (Android 11+ nếu dùng)

Đọc: safeArea nhỏ hơn màn hình → cần inset nội dung. Trong Editor safeArea thường bằng toàn màn hình → không thay thế được thiết bị.

3. Canvas gốc và Canvas Scaler

Kiểm tra	Lỗi thường gặp	Hướng khắc phục
Render Mode gốc	Trộn Screen Space / Camera UI → lệch ray	Một chế độ cho UI
Canvas Scaler	Độ phân giải tham chiếu ≠ baseline dọc của dự án	Khớp checklist engine mục 1
Match width/height	Tỷ lệ dài scale sai; widget rìa trôi	Thống nhất Match với thiết kế/prod; sửa Prefab chứ không chỉ Scene
Sắp xếp nhiều Canvas	Điểm chạm vào sai lớp	Căn chỉnh sortingOrder và raycast target

4. Lớp: nền full-bleed so với nội dung an toàn

Gợi ý phân cấp Prefab:

Canvas
├── Background_FullBleed   (anchor đầy đủ, có thể vào notch, không nhận input)
└── SafeRoot               (component Safe Area hoặc padding dựa trên safeArea)
    ├── HUD_Content
    └── Popups

Dùng Safe Area của Unity (hoặc code dự án đặt offsetMin/Max từ Screen.safeArea). Không kéo giãn nút tương tác toàn màn hình mà không inset.

Xuất từ Studio với một lớp phẳng: xem nine-slice / tái xuất có cấu trúc và canvas → Prefab.

5. Kiểm tra điểm chạm trên thiết bị

3–5 nút quan trọng trên luồng chính; so sánh tâm hình ảnh với ngón tay. Chỉ lệch trên một popup → kiểm tra Canvas lồng nhau hoặc Scaler kép.

6. Commit Prefab vào repo

Tiêu chí đạt nằm trong Prefab có version, không phải override Scene test (mục trước khi ship số 6). Sau khi đổi Anchor, chạy smoke tràn văn bản đa ngôn ngữ trên các ngôn ngữ stress.

---

Kênh / mini-game (kỹ thuật)

Tình huống	Lưu ý
Ứng dụng native	Screen.safeArea + thiết bị thật
Một số mini-game / ứng dụng nhanh	safeArea / systemInfo của container ≠ mô phỏng Editor
Cutout Android	cutout so với safeArea có thể khác
PC / deck	safeArea thường toàn màn hình

Mẫu: ISafeAreaProvider (hoặc tương đương); inject theo nền tảng—tránh #if trong Prefab HUD.

---

Định tuyến khắc phục

Triệu chứng	Nguyên nhân khả năng	Hành động	Chủ sở hữu
Cắt trên thiết bị, Editor ổn	Không có SafeRoot / không có driver safeArea	Phân lớp Prefab + Safe Area; test lại thiết bị	Kỹ thuật
Nền ổn, nút bị cắt	Nút nằm dưới lớp tràn	Chuyển sang SafeRoot; Studio tái xuất lớp	Kỹ thuật + Thiết kế
Lệch điểm chạm	Nhiều Canvas / camera UI / Scaler lồng nhau	Gộp Canvas hoặc thống nhất camera raycast	Kỹ thuật
Trôi khi đổi độ phân giải	Chỉ dùng anchor cố định	Sửa anchor; mục engine số 6	Kỹ thuật
Thiết kế không có khung an toàn	Thiếu mục bàn giao số 7	Thiết kế thêm tham chiếu notch/home; tái xuất	Thiết kế
Xuất Studio phẳng	BG + HUD chưa tách	Tách tại chỗ rồi tái xuất	Kỹ thuật + Thiết kế

---

Những gì thiết kế cung cấp (thứ yếu)

Bàn giao	Kỹ thuật dùng
Độ phân giải mục tiêu + tham chiếu an toàn (notch / home bar)	Reference Resolution và kỳ vọng inset
Lớp full-bleed so với HUD được đặt tên	Prefab Background_* / SafeRoot
Tab rìa nằm trong vùng an toàn hay tràn có chủ đích	Chiến lược Anchor

Nhà thiết kế không cần viết script—dấu rõ ràng giảm việc đoán px inset.

---

Câu hỏi thường gặp

Độ phân giải Game view iPhone có đủ không?
Chỉ smoke Dev; ship cần thiết bị mục tiêu (mục trước khi ship số 1). safeArea trong Editor thường khác.

Component Safe Area so với offset thủ công?
Lựa chọn của nhóm; thủ công phải làm mới khi safeArea/hướng thay đổi—tránh logic trùng lặp.

Chỉ sửa cắt bằng Canvas Scaler?
Scaler scale; inset là riêng biệt. Cắt là rect nội dung; Scaler là scale toàn cục.

MCP/Cursor có giúp được không?
Tốt cho đổi tên Prefab, gắn Safe Area, smoke Play—số liệu vẫn từ log thiết bị. Checklist engine + MCP.

Vùng An Toàn cộng với tràn ngôn ngữ?
Sửa layout SafeRoot trước, rồi ngôn ngữ stress—inset làm hẹp chiều rộng.

VberAI Studio so với Google AI Studio?
Không. Xem so sánh.