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

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

はじめに

「左にファイルツリー、右にエディタ」——ゲーム開発ツールやデスクトップアプリでよく見るこの左右2分割レイアウト。Godot で手軽に実現できるのが HSplitContainer です。前回紹介した SplitContainer の子クラスで、水平方向の分割に特化しています。

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

HSplitContainerとは？

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

部屋を区切る引き戸をイメージしてください。戸を左右にスライドさせると、隣の部屋の広さがリアルタイムで変わる——HSplitContainer はまさにその動きを UI 上で再現するノードです。

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

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

ファイルブラウザ・プロジェクト管理UI：左にフォルダ・アイテム一覧、右にその詳細やプレビューを表示したいとき
コードエディタ風レイアウト：左にソースコード一覧または入力エリア、右に出力ログやプレビューを並べるとき
インスペクタ・設定パネル：左にオブジェクト選択リスト、右にプロパティ編集エリアを配置するとき
地図＋情報パネル：左にマップビュー、右に選択地点の説明や統計を表示するとき
リサイザブルなデバッグツール：左にゲーム画面、右にデバッグ情報をリアルタイム表示するとき

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

ユーザーにサイズを変えさせたくない（比率固定） → HBoxContainer + size_flags の組み合わせが向いています
上下2段に分けたい → VSplitContainer を使います

主なプロパティと機能

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

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

基本的な使い方

extends Control

@onready var split := $HSplitContainer

func _ready():
    # コンテナ全体の横幅の1/3を左ペインに割り当てる
    split.split_offset = -split.size.x / 2 + split.size.x / 3

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

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

collapsed でサイドパネルを開閉する

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

func _on_toggle_button_pressed() -> void:
    split.collapsed = not split.collapsed
    toggle_btn.text = "▶ 開く" if split.collapsed else "◀ 閉じる"

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

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

パラメータ	変えると何が起きるか	設定例
`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.x`	各ペインが縮められる最小幅を設定。これ以上は仕切りをドラッグできなくなる	`$LeftPanel.custom_minimum_size.x = 150`
`theme` の `separation`	仕切り領域の幅（px）を変更。細くするとスタイリッシュ、太くするとタッチ操作向きに	テーマエディタで separation = 6
子ノードの `size_flags_horizontal`	EXPAND を設定した子は余白を積極的に使う。どちらの子に EXPAND を付けるかで伸び方が変わる	`$RightPanel.size_flags_horizontal = Control.SIZE_EXPAND_FILL`

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

extends Control

@onready var split := $HSplitContainer
const LEFT_WIDTH := 200.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.x / 2.0 + LEFT_WIDTH