Godot 4 HUD와 테마: Control 트리 핸드오프와 Play 승인

Godot 4 HUD는 PNG가 TextureRect 노드 위에 올라갔다고 끝나는 것이 아니다: Theme의 StyleBox, 기본 폰트, 컨테이너 체인(MarginContainer → HBoxContainer / VBoxContainer), 그리고 앵커 / 오프셋이 함께 해상도 전반에서 레이아웃이 유지되는지를 결정한다. Figma Auto Layout은 완벽해 보여도 Play에서는 여전히 하단 바가 흘러내리거나, 최소 크기가 0인 버튼, 또는 긴 문구가 잘리는 모습이 나올 수 있다—보통 Control 트리나 Theme 리소스가 핸드오프 스펙과 맞지 않기 때문이다.

아래 내용은 Godot 4.x Control + Theme에 초점을 맞춘다. Unity 팀은 엔진 + MCP 체크리스트를 통해 동일한 기준을 적용할 수 있다. 전체 Figma → Godot 흐름: Figma to Godot (VberAI Studio가 Control 트리를 내보낸다). 이 글은 HUD 셸에 한정: Theme, 노드 네이밍, Play 스모크를 다루며 MCP 설치 단계는 다루지 않는다.

실패 기준 (하나라도 해당 = 미통과): 주요 HUD의 읽어야 하는 컨트롤이 목표 화면비에서 잘림 (Safe Area에 해당하는 DisplayServer.get_display_safe_area() 포함); 동일 버튼이 에디터와 내보낸 빌드에서 크기가 다른데 문서화된 스펙이 없음; Theme 버튼 상태(normal / hover / pressed / disabled 등)가 누락된 채 출시됨; 한 로케일만을 위해 씬 트리가 변경됨(동일 구조 i18n과 충돌—로케일 오버플로 참고); minimum_size 미설정으로 나인슬라이스 패널 배경은 괜찮아 보이지만 텍스트가 가장자리에 붙음.

---

Theme와 노드: 핸드오프가 맞춰야 할 것

디자인 전달물	Godot 적용
색상 / 반경 / 테두리 패널	Theme의 StyleBoxFlat / StyleBoxTexture (나인슬라이스에 따른 패치 마진)
본문 / 제목 크기	Theme 기본 font_size + 필요 시 Label 타입 변형
버튼 상태	Button의 네 가지 StyleBox 세트: normal / hover / pressed / disabled
아이콘 + 문구	아이콘 TextureRect에 고정 최소 크기; 문구 Label은 확장 가능한 컨테이너에
전체 화면 HUD 루트	루트 Control 앵커 프리셋 + 안전 영역용 MarginContainer

네이밍: 씬 노드 이름은 Figma 컴포넌트 의미와 일치시켜(HUD_BottomBar, Btn_Shop) MCP / 스크립트 $ 경로가 안정적으로 유지되게 한다(엔진 + MCP 체크리스트).

---

Play 승인 순서 (6단계)

1. 뷰포트와 안전 영역 고정

• Project Settings → Display에서 목표 기준 너비/높이 설정(팀 세로 모드 관례).
• DisplayServer.get_display_safe_area() 또는 Godot 4.2+ SafeArea 노드로 HUD 루트를 인셋; 세로로 긴 폰 하나로 스모크(Safe Area 글 참고).

2. Theme를 단일 진실 공급원으로

• HUD 서브트리는 하나의 Theme 리소스를 상속하며, 버튼별 수동 오버라이드가 아니다.
• 오버라이드 노드가 있다면 스펙에 명시해야 리스킨 시 누락되지 않는다.

3. 컨테이너 체인과 크기 플래그

확인	흔한 실수
size_flags_horizontal / vertical	커져야 할 Label에 Fill/Expand가 없음 → 로케일 잘림
custom_minimum_size	버튼 높이 0 → 터치 타깃이 너무 작음
중첩 MarginContainer	이중 마진 → 여분의 빈 링

4. 로케일 스모크

• Localization에서 스트레스 언어(DE/ES 등)와 출시 언어를 전환하고, tr() 텍스트만 바꾸며 노드 트리는 바꾸지 않는다.
• 오버플로 → 로케일 오버플로 경로(최소 너비 / 문구 / 재내보내기).

5. 상태와 포커스

• 키보드/게임패드 포커스(지원 시): Theme에 focus StyleBox 정의.
• 비활성 버튼이 여전히 클릭을 막는지(mouse_filter, disabled 상태).

6. 내보낸 빌드 재테스트

• 주요 HUD를 Debug와 Release에서 30초 실행; 폰트 폴백이 너비를 바꾸면 기기에서 재테스트(출시 전 항목 5 Dev/Release; 모든 로케일 항목 2).

---

Figma Auto Layout 대략적 매핑

Figma	Godot 4
세로 Auto Layout	VBoxContainer + separation
가로 Auto Layout	HBoxContainer
패딩	MarginContainer 또는 StyleBox content margin
컨테이너 채우기	size_flags Expand + Fill
콘텐츠에 맞추기	자식은 Expand 안 함; 부모가 맞춤

VberAI Studio(또는 파이프라인)가 이미 컨테이너를 내보냈다면, Play에서 승인하라—정적인 에디터 프레임만 눈으로 확인하지 말 것.

---

수정 라우팅

증상	유력 원인	조치	담당
노치 아래로 하단 바	안전 인셋 없음	루트 마진 + 안전 영역 API	엔지니어
한 로케일만 오버플로	최소 너비 / 폰트 크기	Theme 또는 컨테이너 최소값; 더 짧은 로케일 문구	디자인 + 엔지니어
리스킨 후 스타일 잘못됨	오버라이드가 흩어짐	Theme 통합; 재내보내기	엔지니어 + 디자인
StyleBox의 나인슬라이스 이음새	잘못된 패치 마진	디자인 px와 일치; 나인슬라이스 글 참고	엔지니어 + 디자인
MCP가 노드를 바인딩 못 함	이름 ≠ 내보내기	네이밍 통일; Scene/PackedScene 재내보내기	엔지니어

---

FAQ

화면당 하나의 Theme인가, 게임 전체에 하나인가?
흔한 패턴: 전역 Theme + 드문 theme_override; 이벤트 스킨은 노드별 틴트 편집이 아니라 리스킨 Theme 교체로.

Control과 원시 CanvasItem 레이아웃을 섞어도 되나?
2D HUD는 하나의 Control 트리에 유지하라; 같은 HUD에서 수동 배치한 CanvasLayer 좌표와 섞지 말 것.

키보드/게임패드용 별도 포커스 스타일이 필요한가?
프로젝트가 키보드/게임패드 포커스를 지원하면 Theme에서 Button, LineEdit 등에 focus StyleBox를 정의하고(또는 가시적 theme_override), Play에서 Tab/d-pad를 스모크하라. 터치 전용 HUD는 포커스 스타일 불필요로 스펙해 QA와 엔지니어가 같은 기준을 공유하게 할 수 있다.

Unity Prefab 승인과 어떻게 다른가?
같은 기준(잘림, 로케일, 상태, Release); 이름만 StyleBox / size_flags / PackedScene으로 바꾸면 된다.

Figma를 반드시 써야 하나?
아니다. Figma 없이도 Theme + 컨테이너 스펙은 필요하다; Figma가 있다면 디자인 핸드오프 체크리스트 후 Godot으로.