게임 UI Safe Area와 디바이스 QA: 디버그 순서와 Prefab 수정

가장 흔한 보고: Game view는 멀쩡한데, 세로로 긴 폰에서는 HUD가 노치 아래에 깔리거나, 버튼이 눌릴 것처럼 보이지만 히트가 빗나간다. Safe Area는 “Anchor를 살짝 밀어주는” 문제가 아니다—루트 Canvas 정책, 풀블리드 배경 vs 인셋 콘텐츠, 그리고 런타임 safeArea가 채널과 일치하는지의 문제다.

실패 클래스, Unity UGUI 디버그 순서, Prefab 수정 규칙, 채널/미니게임 주의사항. 디자인 핸드오프 항목 7의 안전 영역 표시는 “디자인이 제공해야 하는 것”에서 요약한다; 출시 전 항목 1의 디바이스 범위는 여기서 확장한다—엔진 + MCP 체크리스트의 Raycast / 첫 Play를 반복하는 것이 아니다.

Godot / Cocos: DisplayServer.get_display_safe_area() / 엔진 SafeArea 위젯에 매핑한다; 아래 Unity와 동일한 단계 순서를 따른다.

실패 기준 (하나라도 해당 = 미통과): 주요 가독 UI 또는 필수 버튼이 시스템 가림(노치, 홈 인디케이터, 둥근 모서리) 아래에 있음; 시각과 히트의 명백한 오프셋; Editor 16:9만 확인하고 디바이스에서 대상 화면비 미확인; 스펙 없이 Dev와 Release의 Safe Area 동작이 다름.

---

먼저 분류: 클립, 오프셋, 아니면 배경만

증상	우선 의심	디버그 단계
시각적 클립 (노치에 텍스트/아이콘)	콘텐츠가 인셋되지 않음; 루트를 전체 화면으로 취급	safeArea vs 콘텐츠 rect 확인
탭 오프셋 (보기엔 맞는데 빗나감)	Canvas scale mode, 다중 Canvas, 카메라 불일치	EventSystem raycast + Canvas renderMode
배경은 잘림, 버튼은 정상	설계상 풀블리드 bg, 콘텐츠는 인셋	스펙이 허용하면 실패 아님
회전 후 잘못됨	orientation / safeArea 변경 리스너 없음	회전 시 인셋 재계산
한 채널 빌드에서만	SDK가 safeArea나 해상도를 변경	해당 빌드 스모크; 일반 Android만 신뢰하지 말 것

---

Unity UGUI: 권장 디버그 순서 (6단계)

1. 재현 고정

디바이스, OS, Dev/Release, orientation, Game view 해상도를 기록한다. 출시 전 항목 5: 메인 HUD를 Dev와 Release에서 실행한다.

2. safeArea와 레퍼런스 해상도 로그

메인 UI 로드 후 다음을 로그한다:

• Screen.width / Screen.height
• Screen.safeArea
• Display.cutouts (사용 시 Android 11+)

해석: safeArea가 화면보다 작으면 → 콘텐츠 인셋 필요. Editor에서는 safeArea가 전체 화면과 같은 경우가 많음 → 디바이스 대체물이 아니다.

3. Canvas 루트와 Canvas Scaler

확인	흔한 실수	수정 방향
루트 Render Mode	Screen Space / Camera UI 혼용 → ray 오프셋	UI는 하나의 모드로
Canvas Scaler	레퍼런스 해상도 ≠ 프로젝트 세로 기준	엔진 체크리스트 항목 1과 일치
Match width/height	긴 화면비에서 잘못 스케일; 가장자리 위젯 드리프트	Match를 디자인/프로덕션과 합의; Scene 전용이 아닌 Prefab 수정
다중 Canvas 정렬	히트가 잘못된 레이어로	sortingOrder와 raycast 대상 정렬

4. 레이어: 풀블리드 배경 vs 안전 콘텐츠

권장 Prefab 계층:

Canvas
├── Background_FullBleed   (전체 anchor, 노치 진입 가능, 입력 없음)
└── SafeRoot               (Safe Area 컴포넌트 또는 safeArea 기반 패딩)
    ├── HUD_Content
    └── Popups

Unity Safe Area 사용(또는 프로젝트 코드에서 Screen.safeArea로 offsetMin/Max 설정). 인터랙티브 버튼을 인셋 없이 전체 화면으로 늘리지 말 것.

단일 평면 레이어로 내보낸 Studio: 나인슬라이스 / 구조화 재내보내기와 canvas → Prefab 참조.

5. 디바이스 탭 스팟 체크

메인 플로우의 핵심 버튼 3–5개; 시각적 중심과 손가락을 비교. 한 팝업에서만 오프셋 → 중첩 Canvas나 이중 Scaler 확인.

6. 리포지토리에 Prefab 커밋

통과 기준은 테스트 Scene 오버라이드가 아니라 버전 관리되는 Prefab에 있다 (출시 전 항목 6). Anchor 변경 후 스트레스 언어에서 로케일 오버플로 스모크를 실행한다.

---

채널 / 미니게임

시나리오	참고
네이티브 앱	Screen.safeArea + 실제 디바이스
일부 미니게임 / 퀵 앱	컨테이너 safeArea / systemInfo ≠ Editor 시뮬
Android 컷아웃	cutout과 safeArea가 다를 수 있음
PC / deck	safeArea가 전체 화면인 경우 많음

패턴: ISafeAreaProvider (또는 동등물); 플랫폼별 주입—HUD Prefab에 #if 지양.

---

수정 라우팅

증상	유력 원인	조치	담당
디바이스 클립, Editor 정상	SafeRoot / safeArea 드라이버 없음	레이어 Prefab + Safe Area; 디바이스 재테스트	엔지니어링
배경 정상, 버튼 잘림	버튼이 블리드 레이어 아래	SafeRoot로 이동; Studio 레이어 재내보내기	엔지니어링 + 디자인
탭 오프셋	다중 Canvas / 카메라 UI / 중첩 Scaler	Canvas 병합 또는 raycast 카메라 통일	엔지니어링
해상도 변경 시 드리프트	고정 anchor만 사용	anchor 수정; 엔진 항목 6	엔지니어링
디자인에 안전 프레임 없음	핸드오프 항목 7 누락	디자인이 노치/홈 레퍼런스 추가; 재내보내기	디자인
평면 Studio 내보내기	BG + HUD 미분리	인플레이스 분할 후 재내보내기	엔지니어링 + 디자인

---

디자인이 제공하는 것 (부차적)

산출물	엔지니어링 활용
대상 해상도 + 안전 레퍼런스 (노치 / 홈 바)	Reference Resolution과 인셋 기대치
이름 붙은 풀블리드 vs HUD 레이어	Prefab Background_* / SafeRoot
안전 영역 내 가장자리 탭 또는 의도적 블리드	Anchor 전략

디자이너가 스크립트를 작성할 필요는 없다—명확한 표시가 추측 인셋 px를 줄인다.

---

자주 묻는 질문

Game view iPhone 해상도로 충분한가?
Dev 스모크 전용; 출시에는 대상 디바이스가 필요하다 (출시 전 항목 1). Editor safeArea는 다른 경우가 많다.

Safe Area 컴포넌트 vs 수동 오프셋?
팀 선택; 수동은 safeArea/orientation 변경 시 갱신해야 함—중복 로직 지양.

Canvas Scaler만으로 클립을 고칠 수 있나?
Scaler는 스케일; 인셋은 별개. 클립은 콘텐츠 rect; Scaler는 전역 스케일.

MCP/Cursor가 도움이 되나?
Prefab 이름 변경, Safe Area 부착, Play 스모크에 유용—숫자는 여전히 디바이스 로그에서. 엔진 + MCP 체크리스트.

Safe Area와 로케일 오버플로?
SafeRoot 레이아웃을 먼저 수정한 뒤 스트레스 로케일—인셋이 너비를 줄인다.

VberAI Studio vs Google AI Studio?
아니다. 비교 참조.