Godot入門：OptionButtonの使い方と活用法

はじめに
OptionButtonとは？
このノードを使うべき場面
主なプロパティと機能
もっと使いこなす：カスタマイズできるパラメータ
まとめ
シリーズ：Godot 4 ノード解説

はじめに

「難易度をかんたん・ふつう・むずかしいから選んでください」——こういった複数の選択肢からひとつを選ばせるドロップダウンUIを作るときに使うのが OptionButton です。ボタン1つでリストを開閉できるので、限られた画面スペースを効率よく使えます。

この記事では、OptionButton の仕組み・選択肢の追加方法・よく触るプロパティを紹介します。

OptionButtonとは？

OptionButton は クリックするとドロップダウンリストが開き、選択肢のひとつを選べるUIノードです。選択中の項目がボタン上に表示され、リストを開かずとも現在の設定が一目でわかります。

紙のアンケートの「いずれかに○をつけてください」欄をイメージしてください。OptionButton は、その選択肢一覧をボタン1つの中に折りたたんで収納してくれます。

継承ツリーは OptionButton → Button → BaseButton → Control → CanvasItem → Node です。内部的には PopupMenu を保持しており、ボタンクリック時にそれを表示します。

OptionButton の閉じた状態と開いたドロップダウン — ボタンをクリックするとドロップダウンリストが開き、選択後に閉じる

このノードを使うべき場面

難易度選択：かんたん・ふつう・むずかしいなどの難易度をドロップダウンで選ばせるとき
言語・地域選択：ゲームの表示言語を一覧から選ばせるとき
解像度・画質設定：グラフィック設定の選択肢をコンパクトに収めたいとき
キャラクタークラス選択：職業や種族などの選択肢が多い場合に一覧表示するとき
ソート・フィルター：「新着順」「評価順」などのソート方法を切り替えるとき

別のノードが適切な場面：

選択肢が2〜3個で常に全部見せたい → Button をラジオグループにした方が直感的
ユーザーが自由にテキストを入力＋候補から選ぶ → LineEdit + カスタムドロップダウンで対応する

主なプロパティと機能

プロパティ / メソッド	型	役割
`selected`	int	現在選択されている項目のインデックス（0始まり）。-1 は未選択
`get_selected_id()`	int	選択中の項目に割り当てたカスタムIDを返す
`get_selected_metadata()`	Variant	選択中の項目に紐付けたメタデータを返す
`add_item(label, id)`	void	選択肢をコードから追加する
`clear()`	void	すべての選択肢を削除する
`item_selected`（シグナル）	Signal	選択肢が変更されたとき、選択インデックスを引数として発火する

コード例：難易度選択ドロップダウンを作る

@onready var difficulty: OptionButton = $DifficultyOption

func _ready() -> void:
    difficulty.clear()
    difficulty.add_item("かんたん", 0)
    difficulty.add_item("ふつう",   1)
    difficulty.add_item("むずかしい", 2)

    # 保存済みの設定を反映
    difficulty.selected = SaveData.difficulty_index

    difficulty.item_selected.connect(_on_difficulty_selected)

func _on_difficulty_selected(index: int) -> void:
    SaveData.difficulty_index = index
    print("難易度:", difficulty.get_item_text(index))

コード例：メタデータを使って設定値と選択肢を紐付ける

func _ready() -> void:
    var resolutions = [
        {"label": "1280 x 720",  "size": Vector2i(1280, 720)},
        {"label": "1920 x 1080", "size": Vector2i(1920, 1080)},
        {"label": "2560 x 1440", "size": Vector2i(2560, 1440)},
    ]

    for i in resolutions.size():
        difficulty.add_item(resolutions[i]["label"], i)
        difficulty.set_item_metadata(i, resolutions[i]["size"])

func _on_item_selected(index: int) -> void:
    var size: Vector2i = difficulty.get_item_metadata(index)
    DisplayServer.window_set_size(size)

インスペクターから OptionButton の選択肢を追加する — インスペクターの「Items」からGUIで選択肢を追加することもできる

もっと使いこなす：カスタマイズできるパラメータ

まずは基本を動かしてみてから、余裕が出たら試してみてください。

パラメータ・テクニック	変えると何が起きるか
`set_item_metadata()` を使う	インデックスではなく任意の値（Vector2i・Stringなど）を選択肢に紐付けられる。解像度や設定値の管理に便利
`set_item_disabled(index, true)`	特定の選択肢をグレーアウトして選べなくできる。未解放コンテンツの表示に
`add_separator()`	リストに区切り線を追加できる。選択肢をグループ分けしたいときに
`set_item_icon(index, texture)`	選択肢の左にアイコン画像を表示できる。言語選択に国旗を添えるなど
`selected` をコードから変更する	保存済み設定をUIに反映するときに必須。起動時の初期化で使う