Godot 4 HUD dan Tema: Penyerahan Control Tree dan Penerimaan Play

Godot 4 HUD tidak selesai apabila PNG diletakkan pada nod TextureRect: StyleBox dalam Tema, fon lalai, rantaian kontena (MarginContainer → HBoxContainer / VBoxContainer), dan anchor / offset bersama-sama menentukan sama ada susun atur kekal merentas resolusi. Auto Layout Figma boleh kelihatan sempurna manakala Play masih menunjukkan bar bawah yang hanyut, butang min sifar, atau teks panjang terpotong—biasanya Control tree atau sumber Tema tidak sepadan dengan spesifikasi penyerahan.

Di bawah memberi tumpuan kepada Godot 4.x Control + Theme. Pasukan Unity boleh menggunakan bar yang sama melalui senarai semak enjin + MCP. Aliran penuh Figma → Godot: Figma ke Godot (VberAI Studio mengeksport Control tree). Catatan ini merangkumi cangkerang HUD sahaja: Theme, penamaan nod, Play smoke—bukan langkah pemasangan MCP.

Kriteria gagal (mana-mana satu = tidak lulus): kawalan HUD utama terpotong pada nisbah sasaran (termasuk Safe Area setara DisplayServer.get_display_safe_area()); saiz butang yang sama Editor vs binaan dieksport tidak sepadan tanpa spesifikasi bertulis; keadaan butang Tema (normal / hover / pressed / disabled, dsb.) keadaan yang hilang masih dihantar; Scene tree diubah untuk satu lokasi sahaja (berkonflik dengan i18n struktur sama—lihat limpahan lokasi); minimum_size tidak ditetapkan supaya panel latar nine-slice kelihatan baik tetapi teks melekat pada tepi.

---

Tema dan nod: apa yang penyerahan mesti selaraskan

Penghantaran reka bentuk	Pendaratan Godot
Warna / radius / panel bersempadan	StyleBoxFlat / StyleBoxTexture dalam Theme (margin patch mengikut nine-slice)
Saiz badan / tajuk	font_size lalai Tema + variasi jenis Label jika perlu
Keadaan butang	Empat set StyleBox pada Button: normal / hover / pressed / disabled
Ikon + teks	TextureRect ikon dengan min tetap; Label teks dalam kontena boleh kembang
Akar HUD skrin penuh	Preset anchor Control akar + MarginContainer untuk kawasan selamat

Penamaan: Nama nod Scene sepadan dengan semantik komponen Figma (HUD_BottomBar, Btn_Shop) supaya laluan $ MCP / skrip kekal stabil (senarai semak enjin + MCP).

---

Urutan penerimaan Play (6 langkah)

1. Kunci viewport dan kawasan selamat

• Tetapkan lebar/tinggi asas sasaran dalam Project Settings → Display (konvensyen potret pasukan).
• Inset akar HUD dengan DisplayServer.get_display_safe_area() atau nod SafeArea Godot 4.2+; uji satu telefon tinggi (lihat catatan Safe Area).

2. Tema sebagai satu-satunya sumber kebenaran

• Subtree HUD mewarisi satu sumber Theme, bukan gantian manual setiap Butang.
• Mana-mana nod gantian mesti disenaraikan dalam spesifikasi atau reskin akan terlepas pandang.

3. Rantaian kontena dan bendera saiz

Semak	Kesilapan biasa
size_flags_horizontal / vertical	Label yang sepatutnya membesar tidak mempunyai Fill/Expand → teks lokasi terpotong
custom_minimum_size	Tinggi butang 0 → sasaran sentuh terlalu kecil
MarginContainer bersarang	Margin berganda → cincin kosong tambahan

4. Ujian lokasi

• Dalam Localization, tukar bahasa tekanan (DE/ES, dsb.) dan bahasa penghantaran; ubah hanya teks tr(), bukan node tree.
• Limpahan → laluan limpahan lokasi (lebar min / teks / eksport semula).

5. Keadaan dan fokus

• Fokus papan kekunci/gamepad (jika disokong): StyleBox fokus ditakrifkan dalam Tema.
• Butang dilumpuhkan masih menyekat klik (mouse_filter, keadaan disabled).

6. Ujian semula binaan dieksport

• Jalankan HUD utama 30s dalam Debug dan Release; jika fallback fon mengubah lebar, uji semula pada peranti (item pra-penghantaran 5 Dev/Release; semua lokasi item 2).

---

Pemetaan kasar Auto Layout Figma

Figma	Godot 4
Auto Layout Menegak	VBoxContainer + pemisahan
Auto Layout Melintang	HBoxContainer
Padding	MarginContainer atau margin kandungan StyleBox
Isi kontena	size_flags Expand + Fill
Peluk kandungan	Anak tidak Expand; induk memeluk

Jika VberAI Studio (atau pipeline anda) sudah mengeksport kontena, terima dalam Play—jangan hanya menilai bingkai Editor statik dengan mata.

---

Penghalaan pembetulan

Gejala	Punca berkemungkinan	Tindakan	Pemilik
Bar bawah di bawah notch	Tiada inset selamat	Margin akar + API kawasan selamat	Eng
Satu lokasi melimpah	Lebar min / saiz fon	Min Tema atau kontena; teks lokasi lebih pendek	Reka bentuk + eng
Gaya salah selepas reskin	Gantian bertaburan	Satukan Tema; eksport semula	Eng + reka bentuk
Jahitan nine-slice dalam StyleBox	Margin patch salah	Padankan px reka bentuk; lihat catatan nine-slice	Eng + reka bentuk
MCP tidak dapat mengikat nod	Nama ≠ eksport	Satukan penamaan; eksport semula Scene/PackedScene	Eng

---

Soalan Lazim

Satu Tema setiap skrin atau satu untuk keseluruhan permainan?
Corak biasa: Tema global + theme_override jarang; kulit acara melalui pertukaran Tema reskin, bukan pengeditan warna setiap nod.

Campurkan Control dengan susun atur CanvasItem mentah?
Kekalkan HUD 2D pada satu Control tree; jangan campur dengan koordinat CanvasLayer yang diletakkan secara manual dalam HUD yang sama.

Perlukan gaya fokus berasingan untuk papan kekunci/gamepad?
Jika projek menyokong fokus papan kekunci/gamepad, takrifkan StyleBox fokus pada Button, LineEdit, dsb. dalam Tema (atau theme_override yang kelihatan), dan uji Tab/d-pad dalam Play. HUD sentuh sahaja boleh menetapkan tiada gaya fokus diperlukan supaya QA dan eng berkongsi satu bar.

Bagaimana ini berbeza daripada penerimaan Prefab Unity?
Bar yang sama (klip, lokasi, keadaan, Release); tukar nama kepada StyleBox / size_flags / PackedScene.

Mesti kita guna Figma?
Tidak. Tanpa Figma anda masih perlukan spesifikasi Tema + kontena; dengan Figma, senarai semak penyerahan reka bentuk kemudian Godot.