Godot 4 HUD dan Theme: Serah Terima Control Tree dan Acceptance Play

Godot 4 HUD belum selesai saat PNG sudah duduk di node TextureRect: StyleBox di Theme, font default, rantai container (MarginContainer → HBoxContainer / VBoxContainer), dan anchor / offset bersama-sama menentukan apakah layout bertahan di berbagai resolusi. Auto Layout Figma bisa terlihat sempurna sementara Play masih menampilkan bottom bar yang bergeser, tombol ber-min nol, atau teks panjang terpotong—biasanya Control tree atau resource Theme tidak sesuai spesifikasi handoff.

Di bawah ini fokus pada Godot 4.x Control + Theme. Tim Unity dapat menerapkan bar yang sama lewat checklist engine + MCP. Alur lengkap Figma → Godot: Figma to Godot (VberAI Studio mengekspor Control tree). Posting ini hanya membahas shell HUD: Theme, penamaan node, Play smoke—bukan langkah instalasi MCP.

Kriteria gagal (salah satu saja = tidak lulus): kontrol HUD utama terpotong pada aspect target (termasuk padanan Safe Area DisplayServer.get_display_safe_area()); ukuran tombol yang sama berbeda antara Editor dan build yang diekspor tanpa spec tertulis; state tombol Theme (normal / hover / pressed / disabled, dsb.) yang hilang tetap dikirim; Scene tree diubah hanya untuk satu locale (bertentangan dengan i18n struktur sama—lihat locale overflow); minimum_size tidak diatur sehingga background panel nine-slice terlihat bagus tetapi teks menempel ke tepi.

---

Theme dan node: apa yang harus selaras saat handoff

Delivery desain	Pendaratan di Godot
Warna / radius / panel berbingkai	StyleBoxFlat / StyleBoxTexture di Theme (patch margin sesuai nine-slice)
Ukuran body / judul	font_size default Theme + variasi tipe Label jika perlu
State tombol	Empat set StyleBox pada Button: normal / hover / pressed / disabled
Ikon + teks	TextureRect ikon dengan min tetap; teks Label di container yang bisa melebar
Root HUD layar penuh	Preset anchor Control root + MarginContainer untuk safe area

Penamaan: Nama node Scene sesuai semantik komponen Figma (HUD_BottomBar, Btn_Shop) agar path $ MCP / script tetap stabil (checklist engine + MCP).

---

Urutan acceptance Play (6 langkah)

1. Kunci viewport dan safe area

• Atur lebar/tinggi dasar target di Project Settings → Display (konvensi portrait tim).
• Inset root HUD dengan DisplayServer.get_display_safe_area() atau node SafeArea Godot 4.2+; smoke satu ponsel tinggi (lihat posting Safe Area).

2. Theme sebagai satu-satunya sumber kebenaran

• Subtree HUD mewarisi satu resource Theme, bukan override manual per-Button.
• Node override apa pun harus terdaftar di spec atau reskin akan melewatkannya.

3. Rantai container dan size flags

Periksa	Kesalahan umum
size_flags_horizontal / vertical	Label yang seharusnya melebar tidak punya Fill/Expand → locale terpotong
custom_minimum_size	Tinggi tombol 0 → target sentuh terlalu kecil
MarginContainer bersarang	Margin ganda → cincin kosong ekstra

4. Smoke locale

• Di Localization, ganti bahasa stress (DE/ES, dsb.) dan bahasa rilis; ubah hanya teks tr(), bukan node tree.
• Overflow → jalur locale overflow (min width / teks / ekspor ulang).

5. State dan focus

• Focus keyboard/gamepad (jika didukung): StyleBox focus didefinisikan di Theme.
• Tombol disabled masih memblokir klik (mouse_filter, state disabled).

6. Retest build yang diekspor

• Jalankan HUD utama 30 detik di Debug dan Release; jika fallback font mengubah lebar, retest di perangkat (item pra-rilis 5 Dev/Release; semua locale item 2).

---

Pemetaan kasar Figma Auto Layout

Figma	Godot 4
Auto Layout vertikal	VBoxContainer + separation
Auto Layout horizontal	HBoxContainer
Padding	MarginContainer atau content margin StyleBox
Fill container	size_flags Expand + Fill
Hug contents	Anak tidak Expand; induk hug

Jika VberAI Studio (atau pipeline Anda) sudah mengekspor container, accept di Play—jangan hanya menilai frame Editor statis dengan mata.

---

Routing perbaikan

Gejala	Kemungkinan penyebab	Tindakan	Penanggung jawab
Bottom bar di bawah notch	Tidak ada inset safe	Margin root + API safe area	Eng
Satu locale overflow	Min width / ukuran font	Min Theme atau container; teks loc lebih pendek	Design + eng
Style salah setelah reskin	Override tersebar	Konsolidasikan Theme; ekspor ulang	Eng + design
Seam nine-slice di StyleBox	Patch margin salah	Sesuaikan px desain; lihat posting nine-slice	Eng + design
MCP tidak bisa bind node	Nama ≠ ekspor	Satukan penamaan; ekspor ulang Scene/PackedScene	Eng

---

FAQ

Satu Theme per layar atau satu untuk seluruh game?
Pola umum: Theme global + theme_override yang jarang; skin event lewat swap Theme reskin, bukan edit tint per-node.

Mencampur Control dengan layout CanvasItem mentah?
Pertahankan HUD 2D pada satu Control tree; jangan campur dengan koordinat CanvasLayer yang ditempatkan manual di HUD yang sama.

Perlu style focus terpisah untuk keyboard/gamepad?
Jika proyek mendukung focus keyboard/gamepad, definisikan StyleBox focus pada Button, LineEdit, dsb. di Theme (atau theme_override yang terlihat), dan smoke Tab/d-pad di Play. HUD khusus sentuh bisa menspesifikasikan tidak perlu styling focus agar QA dan eng berbagi satu bar yang sama.

Apa bedanya dengan acceptance Prefab Unity?
Bar yang sama (clip, locale, state, Release); ganti nama menjadi StyleBox / size_flags / PackedScene.

Haruskah kami memakai Figma?
Tidak. Tanpa Figma Anda tetap butuh spec Theme + container; dengan Figma, checklist handoff desain lalu Godot.