Godot 4 HUD 與 Theme：Control 樹交接與 Play 驗收

Godot 4 的 HUD 不是「把 PNG 掛到 TextureRect」就結束：Theme 裡的 StyleBox、預設字體、容器鏈（MarginContainer → HBoxContainer / VBoxContainer）和 錨點 / offset 一起決定多解析度下是否對齊。Figma 裡 Auto Layout 對齊了，Play 裡仍可能 底欄漂移、按鈕 min 高度不夠、長文案擠爆——多半是 Control 樹或 Theme 資源沒按交接規格落地。

下文以 Godot 4.x Control + Theme 為主；Unity 團隊可對照 進引擎 MCP 清單 做同構驗收。Figma 進 Godot 的總流程見 Figma → Godot（VberAI Studio 匯出 Control 樹）；本文只展開 HUD 殼層：Theme、節點命名、Play 抽測，不重複 MCP 安裝說明。

失敗判據（任一即未通過）： 主 HUD 在目標長寬比下 可讀控件被裁切（含 Safe Area 等價的 DisplayServer.get_display_safe_area()）；同一按鈕在 Editor 與 匯出包 尺寸不一致且無規格；Theme 按鈕態（normal / hover / pressed / disabled 等）缺態仍上線；為某一語言單獨改 Scene 樹結構（與同結構多語言目標衝突，見 多語言爆框）；minimum_size 未設導致 九宮格 底圖 OK 但內文貼邊。

---

Theme 與節點：交接時要對齊什麼

設計交付	Godot 側落地
顏色 / 圓角 / 邊框面板	Theme 內 StyleBoxFlat / StyleBoxTexture（patch margin 對照 九宮格）
正文字號、標題字號	Theme 預設 font_size + 必要時 Label 主題類型變體
按鈕多態	Button 的 normal/hover/pressed/disabled 四套 StyleBox
圖示 + 文案	圖示 TextureRect 固定 min，文案 Label 在獨立容器內可擴展
全螢幕 HUD 根	根 Control 錨點 preset + MarginContainer 吃 safe area

命名： Scene 中節點名與 Figma 元件名 語義一致（HUD_BottomBar、Btn_Shop），便於 MCP / 腳本 $ 路徑穩定（見 進引擎 MCP 清單）。

---

Play 驗收順序（6 步）

1. 固定視埠與 safe area

• 在 Project Settings → Display 設目標基準寬高（與團隊豎屏約定一致）。
• 用 DisplayServer.get_display_safe_area() 或 Godot 4.2+ 的 SafeArea 節點對 HUD 根做 inset；長螢幕真機抽一條（對照 Safe Area 文）。

2. Theme 資源是否唯一來源

• HUD 子樹是否 inherit 同一 Theme 資源，而非每個 Button 手填 override。
• 手填 override 的節點清單應寫入規格，否則換皮時漏改。

3. 容器鏈與 size flags

檢查	常見錯誤
size_flags_horizontal / vertical	該擴展的 Label 未 Fill/Expand，導致多語言截斷
custom_minimum_size	按鈕高度為 0，觸控熱區不足
嵌套 MarginContainer	重複 margin 導致「多出一圈空白」

4. 多語言 smoke

• 在 Localization 切換 壓力語言（DE/ES 等）與主發行語；僅改 tr() 文本，不改節點樹。
• 溢出則回 多語言爆框 路徑（改 min 寬 / 文案 / 重匯）。

5. 狀態與焦點

• 鍵盤/手柄焦點（若支援）：Focus 樣式是否在 Theme 中定義。
• Disabled 按鈕是否仍擋點擊（mouse_filter、disabled 狀態）。

6. 匯出包復測

• Debug 與 Release 各跑主 HUD 30s；字體 fallback 導致寬度變化時在真機復測（對照 發布前第 5 項 Dev/Release；多語言見該清單第 2 項）。

---

與 Figma Auto Layout 的粗略對應

Figma	Godot 4
Auto Layout 垂直	VBoxContainer + separation
Auto Layout 水平	HBoxContainer
Padding	MarginContainer 或 StyleBox content margin
Fill container	size_flags = Expand + Fill
Hug contents	子節點不設 Expand；父容器 hug

VberAI Studio（或專案約定工具）匯出的 Control 樹若已帶容器，驗收以 Play 為準，不在 Editor 靜態幀裡 eyeball。

---

回修路徑表

現象	最可能原因	建議動作	負責
底欄進 notch	未 inset safe area	根 Margin + safe area API	程式
僅某語爆框	min 寬 / 字號	Theme 或容器 min；本地化改短	設計 + 程式
換皮後樣式亂	override 散落	收回 Theme 資源；重匯	程式 + 設計
StyleBox 九宮格縫	patch margin 錯	對齊稿面 px；見九宮格文	程式 + 設計
MCP 綁不上節點	命名與匯出不一致	統一命名；重匯 Scene/PackedScene	程式

---

常見問題

Theme 按 UI 屏一個還是全遊戲一個？
常見：全域 Theme + 少數屏 theme_override；活動皮可用 換皮 換 Theme 資源，而非逐節點改色。

Control 與 CanvasItem 混用？
2D HUD 應統一 Control 樹；勿與舊 CanvasLayer 手擺座標混一套 HUD。

鍵盤/手柄導航要單獨做 Focus 樣式嗎？
若專案支援鍵鼠/手柄切焦點，須在 Theme 裡為 Button、LineEdit 等定義 focus 態 StyleBox（或與 normal 區分明顯的 theme_override），並在 Play 裡走一遍 Tab/方向鍵；純觸屏 HUD 可寫進規格「不要求 focus 樣式」，避免 QA 與程式標準不一致。

和 Unity Prefab 驗收有何不同？
判據相同（裁切、多語、狀態、Release）；元件名換成 StyleBox / size_flags / PackedScene。

必須用 Figma 嗎？
否。無 Figma 時仍須 Theme + 容器規格；有 Figma 時按 交稿自查 交付再進 Godot。