godot-ui-control

Godot UI / Control ノード（4.x）

Control アンカーとContainerノードを使ってレスポンシブなUIをレイアウトし、Themeでスタイルを設定して、キーボードやゲームパッドで操作できるようにします。対象はGodot 4.7です。

使用する場面

• Control派生ノードを使ってHUD、メニュー、インベントリ、ダイアログボックス、設定画面を構築する場合、ウィンドウサイズに応じて変化するUIを配置する場合、テーマを設定する場合、またはコントローラー／キーボード向けのフォーカス移動を設定する場合に使用します。

使用しない場面： ワールド内の2Dノード（Node2D／スプライト）→ godot-nodes-scenes；UIのトランジションをアニメーションさせる場合 → godot-animation（Tween）；カードの手札などジャンル固有のUI → card-game／visual-novel。入力の完全な再割り当て → input-systems。

基本的なワークフロー

1. UIにはNode2DではなくControlノードを使います。 Controlには矩形（位置＋サイズ）、アンカーがあり、フォーカスやテーマに対応しています。
2. レスポンシブ対応にはアンカーを使います。 アンカーは、親の矩形に対する割合（0～1）で、Controlの各辺が固定される位置を示します。ピクセル単位で手動配置する代わりに、エディターのLayoutプリセット（Top-Left、Full Rect、Centerなど）を使います。
3. 子の配置はContainerに任せます。 子をVBoxContainer、HBoxContainer、GridContainer、MarginContainerなどに入れます。位置とサイズはコンテナーが設定し、配置の流れはsize_flagsで制御します。コンテナー内の子のアンカーは設定しないでください（上書きされます）。
4. Themeでスタイルを設定します。 最上位のControlにThemeリソースを割り当てると、子が継承します。必要な場合に限り、ノードごとのテーマオーバーライドを使います。
5. フォーカスを設定して、ゲームパッド／キーボードでボタン間を移動できるようにします。 デフォルトでフォーカスするControlを設定し、隣接ノードを定義するか、自動設定に任せます。
6. シグナルを接続します（pressed、toggled、text_submitted、value_changed）。

パターン

1. アンカーを使ったレスポンシブなレイアウト（コード形式）

extends Control

func _ready() -> void:
    # Stretch this panel to fill its parent (equivalent to the "Full Rect" preset).
    anchors_preset = Control.PRESET_FULL_RECT
    # Or set anchors manually: all four edges at the parent's far corners.
    # anchor_left = 0; anchor_top = 0; anchor_right = 1; anchor_bottom = 1

2. コンテナーとボタンのシグナルで構築するメニュー

extends VBoxContainer    # children stack vertically, auto-sized

func _ready() -> void:
    for child in get_children():
        if child is Button:
            child.pressed.connect(_on_button_pressed.bind(child.name))
    # Give the first button focus so a gamepad can navigate immediately.
    if get_child_count() > 0:
        (get_child(0) as Control).grab_focus()

func _on_button_pressed(which: StringName) -> void:
    match which:
        "PlayButton":  get_tree().change_scene_to_file("res://game.tscn")
        "QuitButton":  get_tree().quit()

3. サイズフラグ：子の1つを拡張して余った領域を埋める

# In a HBoxContainer: a label on the left, a spacer that eats remaining width.
func _ready() -> void:
    $Label.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
    $Spacer.size_flags_horizontal = Control.SIZE_EXPAND_FILL   # grows to fill

4. 1つのノードに対するテーマオーバーライド（Themeリソース全体を使わない方法）

func _ready() -> void:
    # Per-node overrides: use add_theme_* (type-specific setters).
    $Title.add_theme_font_size_override("font_size", 32)
    $Title.add_theme_color_override("font_color", Color.GOLD)
    $Panel.add_theme_stylebox_override("panel", preload("res://ui/panel.stylebox.tres"))

注意点

• 手動配置とContainerの併用。 Containerの子は自身の位置やアンカーを設定できません。レイアウトはコンテナーが管理します。自由に配置するには、ノードをコンテナーの外に出すか、通常のControl／PanelContainerラッパーを使います。
• アンカーとオフセットの違い。 アンカーは親に対する割合で、オフセットはアンカー位置からのピクセル単位の差分です。プリセットでアンカーを設定してから、オフセットで微調整します。アンカーが0のまま位置だけを設定すると、UIはウィンドウサイズに合わせて拡大縮小されません。
• UIにNode2Dを使う。 Node2Dの子になっているボタンやラベルは、テーマが正しく適用されず、フォーカスも適切に取得できません。UIはCanvasLayer／Controlのサブツリー内に配置してください。
• ゲームパッドでフォーカスが失われる。 何もフォーカスされていないと、方向入力は機能しません。最初のControlでgrab_focus()を呼び出し、focus_modeがFOCUS_NONEではないことを確認してください。
• Themeとテーマオーバーライドの違い。 Themeリソースはサブツリー全体にスタイルを適用し、add_theme_*は1つのノードをオーバーライドします。ノードごとのオーバーライドを多用すると、テーマの一元管理が損なわれます。
• rect_*プロパティは名前が変更されています。 Godot 3のrect_size／rect_position／rect_min_sizeは、4.xではsize／position／custom_minimum_sizeになりました。
• 全画面のControlに対するmouse_filter。 下にあるノードへのクリックを遮ることがあります。装飾専用のパネルにはMOUSE_FILTER_IGNOREを設定してください。

参考資料

• アンカー／オフセットの計算、各種Container、ThemeおよびStyleBoxリソースの作成と拡張、フォーカス隣接ノードの設定、HUD向けのCanvasLayerについては、references/layout-and-theming.mdを参照してください。

関連スキル

• game-ui-ux — エンジンを問わないUI／UX：レスポンシブな拡大縮小、安全領域、フォーカス移動、画面フロー。
• godot-animation — TweenベースのUIトランジションと演出。
• godot-signals-groups — UIイベントをゲームロジックに接続。
• input-systems — 再割り当て可能な入力と複数デバイスのフォーカス。
• card-game／visual-novel — UI中心のジャンル向けテンプレート。