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

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

はじめに

右クリックで表示されるコンテキストメニューや、ボタンを押したときに開くメニューリスト——そういった「ポップアップで選択肢を出す」UIを作れるのが PopupMenu です。OptionButton の内部でも使われており、Godot の UI で最も汎用性の高いポップアップノードです。

この記事では、PopupMenu の仕組みと使いどころ、選択肢の追加・シグナルの使い方を紹介します。

PopupMenuとは？

PopupMenu は 任意の位置にポップアップするメニューリストを表示するノードです。マウス座標やノードの位置を指定して表示し、項目が選ばれると id_pressed シグナルで通知します。表示中は他のUI操作がブロックされ、外側をクリックすると自動で閉じます。

Windowsのデスクトップを右クリックしたときに現れる「新規作成・貼り付け・プロパティ…」のリストをイメージしてください。PopupMenu はその動きをゲーム内のどこにでも再現できるノードです。

継承ツリーは PopupMenu → Popup → Window → Viewport → Node です。Window を継承しているため、独立したウィンドウとして動作します。

PopupMenu を使ったコンテキストメニューの表示例 — 右クリックやボタン操作でメニューをポップアップ表示できる

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

右クリックコンテキストメニュー：キャラクターやオブジェクトを右クリックしてアクションを選ぶとき
ツールバーボタンのドロップダウン：「ファイル▼」ボタンを押すと「新規・開く・保存」が出るUIエディタ風メニュー
ゲーム内メニュー：アイテムアイコンを長押しして「使う・捨てる・詳細を見る」を選ぶアクション
マップのマーカーメニュー：地図上のポイントをクリックして「目的地に設定・削除」などを選ぶとき

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

常に画面に見えている選択肢リストが欲しい → OptionButton（033）や VBoxContainer + Button の方が向いている
確認ダイアログを出したい → ConfirmationDialog（039）を使う

主なプロパティと機能

プロパティ / メソッド	型	役割
`add_item(label, id)`	void	メニュー項目をコードから追加する
`add_separator(label)`	void	区切り線を追加する（label を省略するとラベルなし）
`add_check_item(label, id)`	void	チェックマーク付き項目を追加する
`set_item_disabled(index, true)`	void	特定の項目をグレーアウトして選択不可にする
`popup(rect)`	void	指定位置にメニューを表示する
`popup_on_parent(rect)`	void	親ノードを基準にした位置に表示する
`clear()`	void	すべての項目を削除する
`id_pressed`（シグナル）	Signal	項目が選ばれたとき、その項目の ID を引数として発火する

コード例：右クリックでコンテキストメニューを表示する

@onready var menu: PopupMenu = $PopupMenu

const ID_ATTACK  = 0
const ID_EXAMINE = 1
const ID_ITEM    = 2

func _ready() -> void:
    menu.clear()
    menu.add_item("攻撃する",      ID_ATTACK)
    menu.add_item("調べる",        ID_EXAMINE)
    menu.add_separator()
    menu.add_item("アイテムを使う", ID_ITEM)
    menu.id_pressed.connect(_on_menu_selected)

func _input(event: InputEvent) -> void:
    if event is InputEventMouseButton and event.button_index == MOUSE_BUTTON_RIGHT and event.pressed:
        menu.popup(Rect2(event.global_position, Vector2.ZERO))

func _on_menu_selected(id: int) -> void:
    match id:
        ID_ATTACK:  print("攻撃！")
        ID_EXAMINE: print("調べる")
        ID_ITEM:    print("アイテムを使う")

PopupMenu の区切り線・チェック項目・グレーアウト項目の構成例 — 区切り線・チェック項目・グレーアウトを組み合わせてリッチなメニューが作れる

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

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

パラメータ・テクニック	変えると何が起きるか
`add_separator()` を挟む	項目をグループ分けして見やすくできる。アクション系・設定系などのカテゴリ分けに
`set_item_disabled(index, true)`	条件を満たさない操作（MPが足りないスキルなど）をグレー表示で「存在するが使えない」と伝えられる
`set_item_icon(index, texture)`	メニュー項目の左にアイコンを表示できる。ゲームらしい見た目に仕上がる
`add_check_item()` + `set_item_checked()`	チェックマーク付きのトグル項目を作れる。設定のオン・オフ状態を表示するのに使える
サブメニューを追加する	`add_submenu_item()` で入れ子のメニューが作れる。「装備する▶」→「頭・体・武器」のような階層メニューに