HUD et Thème Godot 4 : passation de l'arbre de Control et acceptation en Play

Le HUD Godot 4 n’est pas terminé quand les PNG reposent sur des nœuds TextureRect : les StyleBox dans le Thème, les polices par défaut, la chaîne de conteneurs (MarginContainer → HBoxContainer / VBoxContainer), et les ancres / offsets décident ensemble si la mise en page tient sur toutes les résolutions. L’Auto Layout Figma peut sembler parfait alors qu’en Play on voit encore des barres inférieures qui dérivent, des boutons à min zéro, ou du texte long tronqué—généralement l’arbre de Control ou la ressource Thème ne correspondait pas à la spec de passation.

Ci-dessous, l’accent est mis sur Godot 4.x Control + Thème. Les équipes Unity peuvent appliquer la même barre via checklist moteur + MCP. Flux complet Figma → Godot : Figma vers Godot (VberAI Studio exporte l’arbre de Control). Cet article couvre uniquement le shell du HUD : Thème, nommage des nœuds, smoke test en Play—pas les étapes d’installation MCP.

Critères d’échec (un seul suffit = non validé) : contrôles principaux du HUD lisibles mais tronqués au format cible (y compris l’équivalent Safe Area DisplayServer.get_display_safe_area()) ; même bouton avec taille différente entre l’Éditeur et le build exporté sans spec écrite ; états de bouton du Thème (normal / survol / pressé / désactivé, etc.) manquants mais livrés quand même ; arbre de scène modifié pour une seule locale (conflit avec l’i18n à structure identique—voir débordement de locale) ; minimum_size non défini donc le fond de panneau nine-slice semble correct mais le texte colle aux bords.

---

Thème et nœuds : ce que la passation doit aligner

Livraison design	Atterrissage Godot
Couleur / rayon / panneaux bordés	StyleBoxFlat / StyleBoxTexture dans Theme (marges de patch selon nine-slice)
Tailles corps / titre	font_size par défaut du Thème + variations de type Label si nécessaire
États de bouton	Quatre jeux de StyleBox sur Button : normal / survol / pressé / désactivé
Icône + texte	TextureRect d’icône avec min fixe ; Label de texte dans un conteneur extensible
Racine HUD plein écran	Preset d’ancre du Control racine + MarginContainer pour la safe area

Nommage : les noms de nœuds de scène correspondent à la sémantique des composants Figma (HUD_BottomBar, Btn_Shop) pour que les chemins $ des scripts / MCP restent stables (checklist moteur + MCP).

---

Ordre d’acceptation en Play (6 étapes)

1. Verrouiller le viewport et la safe area

• Définir la largeur/hauteur de base cible dans Project Settings → Display (convention portrait de l’équipe).
• Encadrer la racine du HUD avec DisplayServer.get_display_safe_area() ou le nœud SafeArea de Godot 4.2+ ; tester un téléphone allongé (voir l’article Safe Area).

2. Le Thème comme source unique de vérité

• Le sous-arbre du HUD hérite d’une seule ressource Theme, pas de surcharges manuelles par bouton.
• Tout nœud surchargé doit être listé dans la spec, sinon un reskin les oubliera.

3. Chaîne de conteneurs et size flags

Vérification	Erreur courante
size_flags_horizontal / vertical	Un Label qui devrait grandir manque de Fill/Expand → troncature de locale
custom_minimum_size	Hauteur de bouton à 0 → cible tactile trop petite
MarginContainer imbriqué	Marges doublées → anneau vide supplémentaire

4. Smoke test des locales

• Dans Localization, basculer sur les langues stress (DE/ES, etc.) et la langue de livraison ; ne changer que le texte tr(), pas l’arbre de nœuds.
• Débordement → chemin débordement de locale (largeur min / texte / ré-export).

5. États et focus

• Focus clavier/manette (si pris en charge) : StyleBox de focus défini dans le Thème.
• Boutons désactivés qui bloquent encore les clics (mouse_filter, état disabled).

6. Retest sur build exporté

• Lancer le HUD principal 30 s en Debug et Release ; si le fallback de police change la largeur, retester sur appareil (élément 5 avant livraison Dev/Release ; élément 2 toutes locales).

---

Correspondance approximative Figma Auto Layout

Figma	Godot 4
Auto Layout vertical	VBoxContainer + séparation
Auto Layout horizontal	HBoxContainer
Padding	MarginContainer ou marge de contenu StyleBox
Remplir le conteneur	size_flags Expand + Fill
Ajuster au contenu	Enfants sans Expand ; le parent s’ajuste

Si VberAI Studio (ou votre pipeline) a déjà exporté les conteneurs, validez en Play—ne vous fiez pas uniquement aux frames statiques de l’Éditeur.

---

Routage des correctifs

Symptôme	Cause probable	Action	Responsable
Barre inférieure sous l’encoche	Pas d’encart safe area	Marge racine + API safe area	Ing
Une locale déborde	Largeur min / taille de police	Min du Thème ou du conteneur ; texte loc plus court	Design + ing
Styles erronés après reskin	Surcharges dispersées	Consolider le Thème ; ré-exporter	Ing + design
Couture nine-slice dans StyleBox	Mauvaise marge de patch	Aligner les px du design ; voir l’article nine-slice	Ing + design
MCP ne peut pas lier les nœuds	Noms ≠ export	Unifier le nommage ; ré-exporter Scene/PackedScene	Ing

---

FAQ

Un Thème par écran ou un seul pour tout le jeu ?
Schéma courant : Thème global + rare theme_override ; skins d’événement via échange de Thème reskin, pas d’éditions de teinte par nœud.

Mélanger Control avec une mise en page CanvasItem brute ?
Garder le HUD 2D sur un seul arbre de Control ; ne pas mélanger avec des coordonnées CanvasLayer placées à la main dans le même HUD.

Faut-il un style de focus séparé pour clavier/manette ?
Si le projet prend en charge le focus clavier/manette, définir un StyleBox de focus sur Button, LineEdit, etc. dans le Thème (ou un theme_override visible), et tester Tab/d-pad en Play. Un HUD tactile uniquement peut spécifier aucun style de focus requis pour que QA et ing partagent la même barre.

En quoi est-ce différent de l’acceptation d’un Prefab Unity ?
Même barre (troncature, locales, états, Release) ; remplacez les noms par StyleBox / size_flags / PackedScene.

Faut-il obligatoirement utiliser Figma ?
Non. Sans Figma, il faut quand même une spec Thème + conteneurs ; avec Figma, checklist de passation design puis Godot.