HUD y Theme en Godot 4: Traspaso del árbol de Control y aceptación en Play

El HUD en Godot 4 no está terminado cuando los PNG están sobre nodos TextureRect: StyleBox en el Theme, las fuentes por defecto, la cadena de contenedores (MarginContainer → HBoxContainer / VBoxContainer) y las anclas / offsets deciden en conjunto si el layout se mantiene en todas las resoluciones. El Auto Layout de Figma puede verse perfecto mientras Play aún muestra barras inferiores que se desplazan, botones con mínimo cero o texto largo recortado—normalmente el árbol de Control o el recurso Theme no coincidían con la especificación de traspaso.

A continuación nos centramos en Godot 4.x Control + Theme. Los equipos de Unity pueden aplicar la misma barra mediante el checklist de motor + MCP. Flujo completo Figma → Godot: Figma a Godot (VberAI Studio exporta el árbol de Control). Este artículo cubre solo el armazón del HUD: Theme, nombres de nodos y smoke en Play—no los pasos de instalación de MCP.

Criterios de fallo (cualquiera = no aprobado): controles legibles del HUD principal recortados en la relación de aspecto objetivo (incluido el equivalente a Safe Area DisplayServer.get_display_safe_area()); el mismo botón con tamaño distinto entre Editor y build exportado sin especificación escrita; estados de botón del Theme (normal / hover / pressed / disabled, etc.) faltantes y aún enviados; árbol de escena cambiado solo para una localización (entra en conflicto con i18n de misma estructura—ver desbordamiento de localización); minimum_size sin definir de modo que el fondo del panel nine-slice se ve bien pero el texto queda pegado a los bordes.

---

Theme y nodos: qué debe alinear el traspaso

Entrega de diseño	Aterrizaje en Godot
Color / radio / paneles con borde	StyleBoxFlat / StyleBoxTexture en Theme (márgenes de parche según nine-slice)
Tamaños de cuerpo / título	font_size por defecto del Theme + variaciones de tipo Label si hacen falta
Estados de botón	Cuatro conjuntos de StyleBox en Button: normal / hover / pressed / disabled
Icono + texto	TextureRect del icono con mínimo fijo; Label del texto en contenedor expandible
Raíz del HUD a pantalla completa	Preset de ancla del Control raíz + MarginContainer para el área segura

Nombres: los nombres de nodos de la escena coinciden con la semántica de componentes de Figma (HUD_BottomBar, Btn_Shop) para que las rutas $ de MCP / scripts se mantengan estables (checklist de motor + MCP).

---

Orden de aceptación en Play (6 pasos)

1. Fijar viewport y área segura

• Define el ancho/alto base objetivo en Project Settings → Display (convención de retrato del equipo).
• Aplica un inset a la raíz del HUD con DisplayServer.get_display_safe_area() o el nodo SafeArea de Godot 4.2+; haz smoke en un teléfono alto (ver el artículo de Safe Area).

2. Theme como única fuente de verdad

• El subárbol del HUD hereda un único recurso Theme, no overrides manuales por Button.
• Cualquier nodo con override debe estar listado en la especificación o el reskin los pasará por alto.

3. Cadena de contenedores y size flags

Comprobación	Error común
size_flags_horizontal / vertical	Un Label que debería crecer no tiene Fill/Expand → recorte de localización
custom_minimum_size	Altura de botón 0 → objetivo táctil demasiado pequeño
MarginContainer anidado	Márgenes dobles → anillo en blanco extra

4. Smoke de localización

• En Localization, cambia a idiomas de estrés (DE/ES, etc.) y al idioma de envío; cambia solo el texto de tr(), no el árbol de nodos.
• Desbordamiento → ruta de desbordamiento de localización (ancho mínimo / texto / reexportación).

5. Estados y foco

• Foco de teclado/gamepad (si se admite): focus StyleBox definido en el Theme.
• Botones deshabilitados que aún bloquean clics (mouse_filter, estado disabled).

6. Retest del build exportado

• Ejecuta el HUD principal 30 s en Debug y Release; si el fallback de fuente cambia el ancho, vuelve a probar en dispositivo (ítem 5 previo al envío Dev/Release; ítem 2 de todas las localizaciones).

---

Mapeo aproximado de Figma Auto Layout

Figma	Godot 4
Auto Layout vertical	VBoxContainer + separación
Auto Layout horizontal	HBoxContainer
Padding	MarginContainer o margen de contenido del StyleBox
Fill container	size_flags Expand + Fill
Hug contents	Hijos sin Expand; el padre abraza

Si VberAI Studio (o tu pipeline) ya exportó los contenedores, acepta en Play—no evalúes solo a ojo los frames estáticos del Editor.

---

Enrutamiento de arreglos

Síntoma	Causa probable	Acción	Responsable
Barra inferior bajo el notch	Sin inset seguro	Margen raíz + API de área segura	Ing
Una localización se desborda	Ancho mínimo / tamaño de fuente	Mínimo de Theme o contenedor; texto de loc más corto	Diseño + ing
Estilos incorrectos tras el reskin	Overrides dispersos	Consolidar Theme; reexportar	Ing + diseño
Costura de nine-slice en StyleBox	Margen de parche incorrecto	Igualar px del diseño; ver artículo de nine-slice	Ing + diseño
MCP no puede enlazar nodos	Nombres ≠ exportación	Unificar nombres; reexportar Scene/PackedScene	Ing

---

FAQ

¿Un Theme por pantalla o uno para todo el juego?
Patrón común: Theme global + theme_override poco frecuente; skins de eventos mediante cambio de Theme de reskin, no ediciones de tinte por nodo.

¿Mezclar Control con layout crudo de CanvasItem?
Mantén el HUD 2D en un solo árbol de Control; no lo mezcles con coordenadas de CanvasLayer colocadas a mano en el mismo HUD.

¿Hace falta un estilo de foco aparte para teclado/gamepad?
Si el proyecto admite foco de teclado/gamepad, define el StyleBox de focus en Button, LineEdit, etc. dentro del Theme (o un theme_override visible), y haz smoke con Tab/d-pad en Play. Un HUD solo táctil puede especificar sin estilo de foco requerido para que QA e ing compartan un mismo criterio.

¿En qué se diferencia de la aceptación de Prefabs en Unity?
Misma barra (recorte, localizaciones, estados, Release); cambia los nombres a StyleBox / size_flags / PackedScene.

¿Es obligatorio usar Figma?
No. Sin Figma igual necesitas especificación de Theme + contenedores; con Figma, checklist de traspaso de diseño y luego Godot.