Godot 4 HUD và Theme: Bàn giao Control Tree và Nghiệm thu Play

Godot 4 HUD chưa xong khi PNG chỉ nằm trên các node TextureRect: StyleBox trong Theme, font mặc định, chuỗi container (MarginContainer → HBoxContainer / VBoxContainer), và anchors / offsets cùng nhau quyết định liệu layout có giữ vững qua các độ phân giải hay không. Auto Layout của Figma có thể trông hoàn hảo trong khi Play vẫn hiển thị thanh dưới trôi dạt, nút zero-min, hoặc copy dài bị cắt—thường là do Control tree hoặc Theme resource không khớp với spec bàn giao.

Dưới đây tập trung vào Godot 4.x Control + Theme. Các team Unity có thể áp dụng cùng thanh tiêu chuẩn qua engine + MCP checklist. Toàn bộ luồng Figma → Godot: Figma to Godot (VberAI Studio xuất Control tree). Bài này chỉ bao gồm HUD shell: Theme, đặt tên node, Play smoke—không phải các bước cài MCP.

Tiêu chí fail (bất kỳ một cái = không đạt): HUD chính có control dễ đọc bị cắt ở tỉ lệ mục tiêu (bao gồm tương đương Safe Area DisplayServer.get_display_safe_area()); cùng một button có kích thước Editor vs bản build xuất khác nhau mà không có spec bằng văn bản; các trạng thái button trong Theme (normal / hover / pressed / disabled, v.v.) thiếu trạng thái vẫn được ship; Scene tree bị thay đổi chỉ cho một locale (xung đột với i18n cùng cấu trúc—xem locale overflow); minimum_size chưa đặt nên panel bg nine-slice trông ổn nhưng chữ dính sát mép.

---

Theme và node: bàn giao phải khớp những gì

Bàn giao thiết kế	Đáp xuống Godot
Màu / bo góc / panel có viền	StyleBoxFlat / StyleBoxTexture trong Theme (patch margins theo nine-slice)
Cỡ body / title	font_size mặc định của Theme + type variations cho Label nếu cần
Trạng thái button	Bốn bộ StyleBox trên Button: normal / hover / pressed / disabled
Icon + copy	Icon TextureRect với min cố định; copy Label trong container có thể giãn
Root HUD toàn màn hình	Root Control anchor preset + MarginContainer cho safe area

Đặt tên: Tên node trong Scene khớp ngữ nghĩa component Figma (HUD_BottomBar, Btn_Shop) để đường dẫn $ của MCP / script luôn ổn định (engine + MCP checklist).

---

Thứ tự nghiệm thu Play (6 bước)

1. Khóa viewport và safe area

• Đặt chiều rộng/cao cơ sở mục tiêu trong Project Settings → Display (quy ước portrait của team).
• Chèn inset cho root HUD bằng DisplayServer.get_display_safe_area() hoặc node SafeArea từ Godot 4.2+; smoke một điện thoại cao (xem bài Safe Area).

2. Theme là nguồn chân lý duy nhất

• Subtree HUD kế thừa một Theme resource, không override thủ công từng Button.
• Mọi node override phải được liệt kê trong spec, nếu không reskin sẽ bỏ sót chúng.

3. Chuỗi container và size flags

Kiểm tra	Lỗi thường gặp
size_flags_horizontal / vertical	Label lẽ ra phải giãn lại thiếu Fill/Expand → cắt locale
custom_minimum_size	Chiều cao button bằng 0 → touch target quá nhỏ
MarginContainer lồng nhau	Margin gấp đôi → thêm viền trắng thừa

4. Smoke locale

• Trong Localization, chuyển sang ngôn ngữ stress (DE/ES, v.v.) và ngôn ngữ ship; chỉ đổi text tr(), không đổi node tree.
• Tràn → theo hướng locale overflow (min width / copy / xuất lại).

5. Trạng thái và focus

• Focus bàn phím/gamepad (nếu được hỗ trợ): focus StyleBox được định nghĩa trong Theme.
• Button disabled vẫn chặn click (mouse_filter, trạng thái disabled).

6. Kiểm thử lại trên bản build xuất

• Chạy HUD chính 30 giây trong Debug và Release; nếu font fallback thay đổi chiều rộng, kiểm thử lại trên thiết bị (mục 5 trước khi ship Dev/Release; mục 2 cho mọi locale).

---

Ánh xạ sơ bộ Figma Auto Layout

Figma	Godot 4
Vertical Auto Layout	VBoxContainer + separation
Horizontal Auto Layout	HBoxContainer
Padding	MarginContainer hoặc content margin của StyleBox
Fill container	size_flags Expand + Fill
Hug contents	Các con không Expand; cha hug

Nếu VberAI Studio (hoặc pipeline của bạn) đã xuất container, nghiệm thu trong Play—đừng chỉ nhìn bằng mắt các frame tĩnh trong Editor.

---

Định tuyến sửa lỗi

Triệu chứng	Nguyên nhân khả dĩ	Hành động	Chủ sở hữu
Thanh dưới nằm dưới notch	Không có safe inset	Margin root + API safe area	Eng
Một locale bị tràn	Min width / font size	Min của Theme hoặc container; copy loc ngắn hơn	Design + eng
Style sai sau reskin	Override rải rác	Hợp nhất Theme; xuất lại	Eng + design
Đường nối nine-slice trong StyleBox	Patch margin sai	Khớp px thiết kế; xem bài nine-slice	Eng + design
MCP không bind được node	Tên ≠ bản xuất	Thống nhất đặt tên; xuất lại Scene/PackedScene	Eng

---

FAQ

Một Theme cho mỗi màn hình hay một cho toàn game?
Mẫu phổ biến: Theme toàn cục + theme_override hiếm khi dùng; skin sự kiện qua hoán đổi Theme reskin, không chỉnh tint từng node.

Trộn Control với layout CanvasItem thô?
Giữ HUD 2D trên một Control tree; không trộn với tọa độ CanvasLayer đặt tay trong cùng HUD.

Cần style focus riêng cho bàn phím/gamepad?
Nếu dự án hỗ trợ focus bàn phím/gamepad, định nghĩa StyleBox focus trên Button, LineEdit, v.v. trong Theme (hoặc theme_override hiển thị), và smoke Tab/d-pad trong Play. HUD chỉ cảm ứng có thể ghi spec không yêu cầu style focus để QA và eng dùng chung một thanh tiêu chuẩn.

Điều này khác gì nghiệm thu Unity Prefab?
Cùng thanh tiêu chuẩn (clip, locale, trạng thái, Release); chỉ đổi tên thành StyleBox / size_flags / PackedScene.

Có bắt buộc dùng Figma không?
Không. Không có Figma bạn vẫn cần spec Theme + container; có Figma thì theo design handoff checklist rồi sang Godot.