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 / 脚本 $ 路径稳定（见 Godot 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。