Godot 4 HUD и Theme: передача Control-дерева и приёмка в Play

Godot 4 HUD не готов, когда PNG просто лежат на узлах TextureRect: StyleBox в Theme, шрифты по умолчанию, цепочка контейнеров (MarginContainer → HBoxContainer / VBoxContainer) и якоря / offsets вместе решают, удержится ли раскладка на разных разрешениях. Auto Layout из Figma может выглядеть идеально, но в Play всё ещё будут уползающие нижние панели, кнопки с нулевым минимумом или обрезанный длинный текст — обычно потому, что 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()); у одной и той же кнопки размер в редакторе и в экспортированной сборке не совпадает без письменной спецификации; состояния кнопок в Theme (normal / hover / pressed / disabled и т. д.) отсутствуют, но всё равно выпускаются; дерево сцены изменено только для одной локали (конфликтует с i18n одинаковой структуры — см. переполнение локалей); minimum_size не задан, поэтому фон панели с nine-slice выглядит нормально, но текст прилипает к краям.

---

Theme и узлы: что должна согласовать передача

Дизайн-поставка	Приземление в Godot
Цвет / радиус / панели с рамкой	StyleBoxFlat / StyleBoxTexture в Theme (patch margins по nine-slice)
Размеры основного / заголовочного текста	font_size по умолчанию в Theme + вариации типа Label при необходимости
Состояния кнопок	Четыре набора StyleBox на Button: normal / hover / pressed / disabled
Иконка + текст	Иконка TextureRect с фиксированным минимумом; текст Label в растягиваемом контейнере
Корень полноэкранного HUD	Пресет якоря корневого Control + MarginContainer для safe area

Именование: имена узлов сцены совпадают с семантикой компонентов Figma (HUD_BottomBar, Btn_Shop), чтобы пути MCP / скриптов $ оставались стабильными (чек-лист движка + MCP).

---

Порядок приёмки в Play (6 шагов)

1. Зафиксировать viewport и safe area

• Задайте целевую базовую ширину/высоту в Project Settings → Display (командное соглашение для портрета).
• Отступите корень HUD через DisplayServer.get_display_safe_area() или узел SafeArea в Godot 4.2+; проверьте на одном высоком телефоне (см. пост про Safe Area).

2. Theme как единственный источник истины

• Поддерево HUD наследует один ресурс Theme, а не ручные переопределения на каждой кнопке.
• Любые узлы с переопределениями должны быть перечислены в спецификации, иначе рескин их пропустит.

3. Цепочка контейнеров и флаги размера

Проверка	Частая ошибка
size_flags_horizontal / vertical	У Label, который должен расти, нет Fill/Expand → обрезка локали
custom_minimum_size	Высота кнопки 0 → цель касания слишком мала
Вложенный MarginContainer	Двойные отступы → лишнее пустое кольцо

4. Дымовой тест локалей

• В Localization переключите стресс-языки (DE/ES и т. д.) и язык выпуска; меняйте только текст tr(), не дерево узлов.
• Переполнение → путь переполнения локалей (мин. ширина / текст / повторный экспорт).

5. Состояния и фокус

• Фокус клавиатуры/геймпада (если поддерживается): StyleBox focus, заданный в Theme.
• Отключённые кнопки всё ещё перехватывают клики (mouse_filter, состояние disabled).

6. Повторный тест экспортированной сборки

• Запустите основной HUD 30 секунд в Debug и Release; если fallback шрифта меняет ширину, повторите тест на устройстве (пункт 5 предрелизного чек-листа Dev/Release; все локали — пункт 2).

---

Приблизительное сопоставление с Figma Auto Layout

Figma	Godot 4
Вертикальный Auto Layout	VBoxContainer + separation
Горизонтальный Auto Layout	HBoxContainer
Padding	MarginContainer или content margin в StyleBox
Fill container	size_flags Expand + Fill
Hug contents	Дочерние без Expand; родитель обжимает

Если VberAI Studio (или ваш пайплайн) уже экспортировал контейнеры, принимайте в Play — не оценивайте только статичные кадры в редакторе.

---

Маршрутизация правок

Симптом	Вероятная причина	Действие	Владелец
Нижняя панель под вырезом	Нет safe inset	Отступ корня + API safe area	Инж.
Одна локаль переполняется	Мин. ширина / размер шрифта	Минимум Theme или контейнера; сократить текст локали	Дизайн + инж.
Стили неверны после рескина	Переопределения разбросаны	Консолидировать Theme; повторный экспорт	Инж. + дизайн
Шов nine-slice в StyleBox	Неверный patch margin	Совместить с px дизайна; см. пост про nine-slice	Инж. + дизайн
MCP не может привязать узлы	Имена ≠ экспорт	Унифицировать именование; повторно экспортировать Scene/PackedScene	Инж.

---

FAQ

Один Theme на экран или один на всю игру?
Частый паттерн: глобальный Theme + редкий theme_override; скины событий через замену Theme при рескине, а не ручную правку тона на каждом узле.

Смешивать Control с ручной раскладкой CanvasItem?
Держите 2D HUD на одном Control-дереве; не смешивайте с вручную расставленными координатами CanvasLayer в одном HUD.

Нужен отдельный стиль фокуса для клавиатуры/геймпада?
Если проект поддерживает фокус клавиатуры/геймпада, задайте StyleBox focus на Button, LineEdit и т. д. в Theme (или видимый theme_override) и проверьте Tab/d-pad в Play. HUD только для касаний может указать в спецификации стиль фокуса не требуется, чтобы QA и инженеры делили одну планку.

Чем это отличается от приёмки Prefab в Unity?
Та же планка (обрезка, локали, состояния, Release); замените имена на StyleBox / size_flags / PackedScene.

Обязательно ли использовать Figma?
Нет. Без Figma вам всё равно нужна спецификация Theme + контейнеров; с Figma — чек-лист передачи дизайна, затем Godot.