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

はじめに
VSplitContainerとは？
このノードを使うべき場面
主なプロパティと機能
もっと使いこなす：カスタマイズできるパラメータ
1. ウィンドウリサイズに追従して上ペインの高さを維持する
まとめ
シリーズ：Godot 4 ノード解説

はじめに

「上にゲーム画面、下にログコンソール」——開発ツールやデバッグUIで見かけるこの上下2分割レイアウト。Godot で手軽に実現できるのが VSplitContainer です。前回紹介した HSplitContainer の姉妹クラスで、垂直方向の分割に特化しています。

この記事では、VSplitContainer の役割・基本的な使い方・よく触るプロパティを紹介します。

VSplitContainerとは？

VSplitContainer は 2つの子ノードを上下に並べ、その境界にドラッグ可能な横の仕切りを置くUIコンテナです。ユーザーが仕切りを上下にドラッグすることで、上ペインと下ペインのサイズ比率を自由に変えられます。

机の引き出しの仕切り板をイメージしてください。仕切りを上下にスライドさせると、上の段と下の段の高さがリアルタイムで変わる——VSplitContainer はまさにその動きを UI 上で再現するノードです。

継承ツリーは VSplitContainer → SplitContainer → Container → Control → CanvasItem → Node です。SplitContainer が持つ共通プロパティ（split_offset・collapsed・dragged シグナルなど）をそのまま引き継ぎつつ、分割方向が「垂直（上下）」に固定されています。水平分割が必要なら姉妹クラスの HSplitContainer を使います。

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

ゲーム画面＋デバッグコンソール：上にゲームのビューポート、下にログやデバッグ出力を表示したいとき
マップ＋詳細パネル：上に広いマップビュー、下に選択したポイントの情報を表示するとき
エディタ風レイアウト：上にコードやスクリプト編集エリア、下に出力・エラーログを並べるとき
チャット・メッセージUI：上にメッセージ履歴一覧、下にテキスト入力エリアを配置するとき
リサイザブルな設定パネル：上にカテゴリ一覧、下にその詳細オプションをリアルタイム表示するとき

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

ユーザーにサイズを変えさせたくない（比率固定） → VBoxContainer + size_flags の組み合わせが向いています
左右2列に分けたい → HSplitContainer を使います

主なプロパティと機能

VSplitContainer 固有の追加プロパティはなく、親クラス SplitContainer のプロパティを使います。代表的なものをまとめました。

プロパティ / シグナル	役割	使用例
`split_offset`	仕切りの垂直位置をピクセル単位でオフセット指定。0 が中央、負値で上寄り、正値で下寄り	起動時に上ペインを特定の高さに固定する
`dragger_visibility`	仕切りの表示モード（VISIBLE / HIDDEN / HIDDEN_COLLAPSED）	固定レイアウトにしたいとき HIDDEN_COLLAPSED を使う
`collapsed`	true にすると下ペインを折りたたんで非表示にする	コンソールパネルの表示・非表示トグルに利用
シグナル `dragged(offset)`	仕切りがドラッグされたときに発火。引数は現在のオフセット値（int）	分割比率の変化をセーブデータや他UIに反映させる

基本的な使い方

extends Control

@onready var split := $VSplitContainer

func _ready():
    # コンテナ全体の高さの2/3を上ペインに割り当てる
    split.split_offset = -split.size.y / 2 + split.size.y * 2 / 3

dragged シグナルで仕切り位置を保存する

func _on_v_split_container_dragged(offset: int) -> void:
    # プロジェクト設定などに保存しておき、次回起動時に復元できる
    ProjectSettings.set_setting("ui/v_split_offset", offset)
    print("仕切り位置を保存: ", offset)

collapsed でコンソールパネルを開閉する

@onready var split := $VSplitContainer
@onready var toggle_btn := $ToggleButton

func _on_toggle_button_pressed() -> void:
    split.collapsed = not split.collapsed

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

パラメータ	変えると何が起きるか	設定例
`split_offset`	負値で上ペイン広め、正値で下ペイン広めになる。コンテナ高さの変化に追従させたい場合はリサイズ時に再計算が必要	`split_offset = -120` → 上が少し広め
`dragger_visibility`	VISIBLE：常に仕切りを表示 / HIDDEN：見えないがドラッグ可 / HIDDEN_COLLAPSED：完全固定	`dragger_visibility = SplitContainer.DRAGGER_HIDDEN`
`collapsed`	true で下ペインが非表示になり上ペインが全高を占める。false で元に戻る	`split.collapsed = true`
子ノードの `custom_minimum_size.y`	各ペインが縮められる最小高さを設定。これ以上は仕切りをドラッグできなくなる	`$TopPanel.custom_minimum_size.y = 100`
`theme` の `separation`	仕切り領域の高さ（px）を変更。細くするとスタイリッシュ、太くするとタッチ操作向きに	テーマエディタで separation = 6
子ノードの `size_flags_vertical`	EXPAND を設定した子は余白を積極的に使う。どちらの子に EXPAND を付けるかで伸び方が変わる	`$BottomPanel.size_flags_vertical = Control.SIZE_EXPAND_FILL`

ウィンドウリサイズに追従して上ペインの高さを維持する

extends Control

@onready var split := $VSplitContainer
const TOP_HEIGHT := 300.0  # 上ペインの固定高さ（px）

func _ready() -> void:
    get_tree().root.size_changed.connect(_on_window_resized)
    _apply_split()

func _on_window_resized() -> void:
    _apply_split()

func _apply_split() -> void:
    # split_offset は中央からのオフセットなので高さの半分を引く
    split.split_offset = -split.size.y / 2.0 + TOP_HEIGHT