HUD e Theme no Godot 4: Handoff da Árvore de Controles e Aceite no Play

O HUD no Godot 4 não está pronto quando os PNGs ficam em nós TextureRect: StyleBox no Theme, fontes padrão, a cadeia de containers (MarginContainer → HBoxContainer / VBoxContainer) e âncoras / offsets juntos decidem se o layout se mantém em todas as resoluções. O Auto Layout do Figma pode parecer perfeito enquanto o Play ainda mostra barras inferiores deslocando, botões com mínimo zero ou textos longos cortados—geralmente a árvore de Controls ou o recurso de Theme não correspondia à especificação de handoff.

Abaixo o foco é Godot 4.x Control + Theme. Equipes Unity podem aplicar a mesma barra via checklist de engine + MCP. Fluxo completo Figma → Godot: Figma para Godot (VberAI Studio exporta a árvore de Controls). Este post cobre apenas o shell do HUD: Theme, nomenclatura de nós, smoke no Play—não passos de instalação do MCP.

Critérios de falha (qualquer um = não aprovado): controles legíveis do HUD principal cortados na proporção alvo (incluindo equivalente a Safe Area DisplayServer.get_display_safe_area()); mesmo botão com tamanho divergente entre Editor e build exportado sem spec escrita; estados de botão do Theme (normal / hover / pressed / disabled, etc.) ausentes ainda enviados; árvore de cena alterada para apenas um idioma (conflita com i18n de mesma estrutura—veja overflow de locale); minimum_size não definido então o fundo do painel em nine-slice parece bom mas o texto cola nas bordas.

---

Theme e nós: o que o handoff precisa alinhar

Entrega de design	Chegada no Godot
Cor / raio / painéis com borda	StyleBoxFlat / StyleBoxTexture no Theme (patch margins conforme nine-slice)
Tamanhos de corpo / título	font_size padrão do Theme + variações de tipo de Label se necessário
Estados de botão	Quatro conjuntos de StyleBox no Button: normal / hover / pressed / disabled
Ícone + texto	TextureRect do ícone com mínimo fixo; Label de texto em container expansível
Raiz do HUD em tela cheia	Preset de âncora do Control raiz + MarginContainer para safe area

Nomenclatura: nomes de nós da cena correspondem à semântica dos componentes do Figma (HUD_BottomBar, Btn_Shop) para que caminhos $ de MCP / script permaneçam estáveis (checklist de engine + MCP).

---

Ordem de aceite no Play (6 passos)

1. Travar viewport e safe area

• Defina largura/altura base alvo em Project Settings → Display (convenção de retrato da equipe).
• Faça inset da raiz do HUD com DisplayServer.get_display_safe_area() ou nó SafeArea do Godot 4.2+; faça smoke em um celular alto (veja o post de Safe Area).

2. Theme como fonte única de verdade

• Subárvore do HUD herda um único recurso Theme, não overrides manuais por Button.
• Quaisquer nós com override devem estar listados na spec ou o reskin vai ignorá-los.

3. Cadeia de containers e size flags

Verificação	Erro comum
size_flags_horizontal / vertical	Label que deveria crescer sem Fill/Expand → corte de locale
custom_minimum_size	Altura do botão 0 → alvo de toque pequeno demais
MarginContainer aninhado	Margens duplicadas → anel em branco extra

4. Smoke de locale

• Em Localization, alterne idiomas de estresse (DE/ES, etc.) e o idioma de envio; mude apenas o texto de tr(), não a árvore de nós.
• Overflow → caminho de overflow de locale (largura mínima / texto / reexportação).

5. Estados e foco

• Foco de teclado/gamepad (se suportado): StyleBox de focus definido no Theme.
• Botões desabilitados ainda bloqueando cliques (mouse_filter, estado disabled).

6. Reteste em build exportado

• Rode o HUD principal por 30s em Debug e Release; se o fallback de fonte mudar a largura, reteste no dispositivo (item 5 do pré-envio Dev/Release; item 2 de todos os idiomas).

---

Mapeamento aproximado do Auto Layout do Figma

Figma	Godot 4
Auto Layout vertical	VBoxContainer + separation
Auto Layout horizontal	HBoxContainer
Padding	MarginContainer ou content margin do StyleBox
Preencher container	size_flags Expand + Fill
Abraçar conteúdo	Filhos sem Expand; pai abraça

Se o VberAI Studio (ou seu pipeline) já exportou os containers, aceite no Play—não avalie apenas quadros estáticos do Editor no olho.

---

Roteamento de correções

Sintoma	Causa provável	Ação	Responsável
Barra inferior sob o notch	Sem inset de safe area	Margem na raiz + API de safe area	Eng
Um idioma transborda	Largura mínima / tamanho de fonte	Mínimo do Theme ou container; texto de loc mais curto	Design + eng
Estilos errados após reskin	Overrides espalhados	Consolidar Theme; reexportar	Eng + design
Costura de nine-slice no StyleBox	Patch margin errado	Igualar px do design; veja o post de nine-slice	Eng + design
MCP não consegue vincular nós	Nomes ≠ exportação	Unificar nomenclatura; reexportar Scene/PackedScene	Eng

---

FAQ

Um Theme por tela ou um para o jogo inteiro?
Padrão comum: Theme global + theme_override raro; skins de evento via troca de Theme de reskin, não edições de tint por nó.

Misturar Control com layout bruto de CanvasItem?
Mantenha o HUD 2D em uma única árvore de Controls; não misture com coordenadas de CanvasLayer posicionadas à mão no mesmo HUD.

Precisa de estilo de foco separado para teclado/gamepad?
Se o projeto suporta foco de teclado/gamepad, defina StyleBox de focus em Button, LineEdit, etc. no Theme (ou theme_override visível), e faça smoke de Tab/d-pad no Play. HUD apenas de toque pode especificar nenhum estilo de foco necessário para que QA e eng compartilhem a mesma barra.

Como isso difere do aceite de Prefab no Unity?
Mesma barra (corte, idiomas, estados, Release); troque os nomes para StyleBox / size_flags / PackedScene.

Precisamos usar Figma?
Não. Sem Figma você ainda precisa de spec de Theme + containers; com Figma, checklist de handoff de design e depois Godot.