Godot 4 HUD と Theme：Control ツリー引き渡しと Play 受け入れ

Godot 4 の HUD は PNG を TextureRect に載せた時点では完成しません。Theme 内の StyleBox、デフォルトフォント、コンテナチェーン（MarginContainer → HBoxContainer / VBoxContainer）、アンカー / offset がセットで、解像度を変えてもレイアウトが保てるか決まります。Figma の Auto Layout が揃っていても Play では 底バーのずれ、min 高さ 0 のボタン、長文クリップ が出ることが多く、Control ツリーまたは Theme リソースが引き渡し仕様とズレている典型です。

以下は Godot 4.x Control + Theme が主題です。Unity チームは エンジン+MCPチェックリスト で同型の基準を当てられます。Figma → Godot の全体は Figma to Godot（VberAI Studio が Control ツリーをエクスポート）。本稿は HUD シェル：Theme、ノード命名、Play スモーク のみ—MCP インストール手順は繰り返しません。

不合格基準（いずれか1つ）： 目標アスペクトで主 HUD の 可読コントロールがクリップ（Safe Area 相当の DisplayServer.get_display_safe_area() を含む）；同一ボタンが Editor とエクスポートビルド でサイズ不一致かつ仕様なし；Theme ボタン状態（normal / hover / pressed / disabled 等）の欠落のまま出荷；一言語だけ Scene ツリー構造を変更（同構造 i18n と矛盾—多言語オーバーフロー）；minimum_size 未設定 で ナインスライス 背景は良いが文字が端に張り付く。

---

Theme とノード：引き渡しで揃えるもの

デザイン交付	Godot 側
色 / 角丸 / 枠付きパネル	Theme 内 StyleBoxFlat / StyleBoxTexture（patch margin は ナインスライス）
本文 / 見出しサイズ	Theme デフォルト font_size + 必要なら Label 型バリエーション
ボタン状態	Button の normal/hover/pressed/disabled の StyleBox 4 セット
アイコン + 文案	アイコン TextureRect 固定 min、文案 Label は拡張可能なコンテナ内
全画面 HUD 根	根 Control アンカー preset + safe area 用 MarginContainer

命名： Scene ノード名と Figma コンポーネント名を 意味で一致（HUD_BottomBar、Btn_Shop）—MCP / スクリプト $ パス安定（エンジン+MCPチェックリスト）。

---

Play 受け入れ順（6 ステップ）

1. ビューポートと safe area を固定

• Project Settings → Display で目標基準解像度（チームの縦画面規約）。
• DisplayServer.get_display_safe_area() または Godot 4.2+ SafeArea ノードで HUD 根を inset；縦長端末を 1 台スモーク（Safe Area 記事参照）。

2. Theme が唯一の真実源か

• HUD サブツリーが 1 つの Theme リソースを継承し、Button ごとの手 override ばかりでないか。
• override ノードは仕様に列挙—列挙なしはリスキン漏れ。

3. コンテナチェーンと size flags

確認	よくあるミス
size_flags_horizontal / vertical	伸びる Label に Fill/Expand なし → 多言語クリップ
custom_minimum_size	ボタン高さ 0 → タッチ領域不足
ネスト MarginContainer	margin 二重 → 余白リング

4. 多言語スモーク

• Localization で ストレス言語（DE/ES 等）と主発売言語；変更は tr() テキストのみ、ツリーは触らない。
• オーバーフロー → 多言語オーバーフロー（min 幅 / 文案 / 再エクスポート）。

5. 状態とフォーカス

• キーボード/パッド対応時：focus StyleBox が 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（またはパイプライン）がコンテナ付きで出していれば Play で受け入れ—Editor 静止フレームだけ見ない。

---

修正ルーティング

症状	想定原因	対応	担当
底バーがノッチ内	safe inset なし	根 margin + safe area API	エンジニア
単一言語だけオーバーフロー	min 幅 / フォントサイズ	Theme またはコンテナ min；短い loc	デザイン+エンジニア
リスキン後スタイル崩れ	override 散乱	Theme に集約；再エクスポート	エンジニア+デザイン
StyleBox ナインスライス継ぎ目	patch margin 誤り	稿 px 合わせ；ナインスライス記事	エンジニア+デザイン
MCP がノードにバインド不可	命名≠ export	命名統一；Scene/PackedScene 再エクスポート	エンジニア

---

よくある質問

Theme は画面ごと？ゲーム全体で一つ？
一般的：グローバル Theme + 稀な theme_override；イベント皮は リスキン で Theme 差し替え—ノード単位の色塗りではない。

Control と CanvasItem レイアウト混在？
2D HUD は Control ツリーに統一；同じ HUD で CanvasLayer 手座標と混ぜない。

キーボード/パッド用 focus スタイルは別途？
対応するなら Theme で Button、LineEdit 等に focus StyleBox（または目立つ theme_override）を定義し Play で Tab/方向キーをスモーク。タッチ専 HUD は仕様に focus スタイル不要 と書き QA とエンジニアの基準を揃える。

Unity Prefab 受け入れと違う？
基準は同じ（クリップ、多言語、状態、Release）；名前が StyleBox / size_flags / PackedScene になるだけ。

Figma 必須？
いいえ。Figma なしでも Theme + コンテナ仕様 必須；Figma ありなら デザインハンドオフチェックリスト の後 Godot。